CGI/Perl Guide | Learning Center | Forums | Advertise | Login
Site Search: in

  Main Index MAIN
INDEX
Search Posts SEARCH
POSTS
Who's Online WHO'S
ONLINE
Log in LOG
IN

Home: General Discussions: General Questions:
Documentation Misses in Scalar::Util

 



vikas.deep
User

May 31, 2009, 10:03 PM

Post #1 of 4 (3808 views)
Documentation Misses in Scalar::Util Can't Post

 Somebody please do tell me why the following statement that appears in documentation
(synopsis section) of Scalar::Util module misses
out the "openhandle" subroutine. Even as (all) other
subroutines (11 in number out of 12 in total) are
enlisted in this statement.


Code
# 
SYNOPSIS
use Scalar::Util qw(blessed dualvar isweak readonly refaddr reftype tainted weaken isvstring looks_like_number set_prototype);

This (past) saturday I was playing (learning) this module , I copy-pasted above statement from synopsis
section and every time I tried to use "openhandle" I got the following error


Code
#Undefined subroutine &main::openhandle called at  
larr.pl line 28.


Even though the "Description" section of this module
says that

Quote
#By default "Scalar::Util" does not export any
subroutines.

is there any valid reason to enlist 11 subroutines in
qw() statement in the synopsis and leave out one.

Is this not a typing error in the documentation ??

or is there something more to it that I am missing ??

Any idea--

Quote
-For all my suggestions " I am sure someone else can do it in a better or elegant manner!"


KevinR
Veteran


May 31, 2009, 10:56 PM

Post #2 of 4 (3806 views)
Re: [vikas.deep] Documentation Misses in Scalar::Util [In reply to] Can't Post

This what the synopsis also says:


Quote
# and other useful utils appearing below


The author, for whatever reason, just did not include the openhandle function/method in the synopsis part of the documentation but he did note that there are more "utils".

If you want to use the openhandle function you will have to import it:


Code
use Scalar::Util qw(openhandle)


The author of a module also writes the documentation (usually). Some authors are better than others at documenting the module and sometimes there are errors in the documentation. If you look on CPAN and read the annotated version of a modules documentation you will often find corrections posted by other people or just comments. Scala::Util has one comment in the annoted version.
-------------------------------------------------


vikas.deep
User

Jun 1, 2009, 2:13 AM

Post #3 of 4 (3803 views)
Re: [KevinR] Documentation Misses in Scalar::Util [In reply to] Can't Post

I am surprised

Code
# and other useful utils appearing below

This line never appeared in my system when I used

Code
perldoc Scalar::Util

This is what I was seeing when using
perldoc Scalar::Util

Code
NAME 
Scalar::Util - A selection of general-utility scalar subroutines

SYNOPSIS
use Scalar::Util qw(blessed dualvar isweak readonly refaddr reftype tainted
weaken isvstring looks_like_number set_prototype);

DESCRIPTION
"Scalar::Util" contains a selection of subroutines that people have
expressed would be nice to have in the perl core, but the usage would
not really be high enough to warrant the use of a keyword, and the size
so small such that being individual extensions would be wasteful.

By default "Scalar::Util" does not export any subroutines. The
subroutines defined are

If the "# and other useful utils appearing below"
line had ever appeared on my system I would have thought/reflected for a while before posting this message
Still more surprisingly this means

Quote

The documentation at CPAN is different from what perldoc gives in my system

-For all my suggestions " I am sure someone else can do it in a better or elegant manner!"


KevinR
Veteran


Jun 1, 2009, 9:58 AM

Post #4 of 4 (3799 views)
Re: [vikas.deep] Documentation Misses in Scalar::Util [In reply to] Can't Post

Scalar::Util is a core module and the documentation on perldoc does not have the extra line I posted in the synopsis nor is it in the documentation of my local install of activeperl 5.8, but it is in the documentation posted on CPAN. I don't know why the documentation on CPAN has it and perldoc doesn't. I can only assume the author (or module maintainer) recently updated the documentation.
-------------------------------------------------

 
 


Search for (options) Powered by Gossamer Forum v.1.2.0

Web Applications & Managed Hosting Powered by Gossamer Threads
Visit our Mailing List Archives