Beefy Boxes and Bandwidth Generously Provided by pair Networks
We don't bite newbies here... much
 
PerlMonks  

Comment on

( #3333=superdoc: print w/ replies, xml ) Need Help??

And chmod and chown look weird, just specifying a list. For example:

chmod LIST

when the detail says the first element must be the mode. This is better written as:

chmod MODE, LIST

Actually, the terse syntax examples given in the Perl documentation convey subtle meaning to those who are aware of the conventions being used and changing "chmod LIST" to "chmod MODE,LIST" would convey incorrect information to such people. (To become such a person, in part, one just needs to read, understand, and remember the 2nd paragraph of perlfunc.)

$ say "prototype('CORE::chmod')" @

I don't mind being told "mkdir FILENAME" because it hints at this possibility:

$ perl -e'mkdir("$ENV{HOME}/.bashrc") or die $!,$/' File exists

I started down the road of proposing that one of those conventions might actually be involved in the choice of "FILENAME" over "DIRNAME", because I noticed this:

$ perldoc perlfunc | grep FILENAME | egrep '^ *[a-z]+ [A-Z]' chroot FILENAME mkdir FILENAME,MASK mkdir FILENAME rmdir FILENAME sysopen FILEHANDLE,FILENAME,MODE sysopen FILEHANDLE,FILENAME,MODE,PERMS $ say 'map prototype("CORE::$_"), qw/ chroot mkdir rmdir sysopen /' _ _;$ _ *$$;$

But that doesn't make sense for a lot of reasons.

I also noticed:

$ perldoc perlfunc | grep DIRNAME $ perldoc perlfunc | grep FILENAME | wc -l 16

So, how does opendir describe its argument?

$ perldoc -f opendir | head -1 opendir DIRHANDLE,EXPR

Now, that needs to say "DIRHANDLE" and not "FILEHANDLE", because you can't use a Perl DIRHANDLE as a Perl FILEHANDLE so that distinction is rather important. There is no such distinction between a FILENAME and a DIRNAME for Perl (nor for Unix, nor for Windows).

But why is that "EXPR" and not "FILENAME"? Well, it is a common choice:

$ perldoc perlfunc | egrep '^ {7}readlink [A-Z]' readlink EXPR $ perldoc perlfunc | egrep '^ {7}lstat [A-Z]' lstat EXPR $ perldoc perlfunc | egrep '^ {7}do [A-Z]' do BLOCK do SUBROUTINE(LIST) do EXPR Uses the value of EXPR as a filename and executes the c +ontents

One could argue that "do EXPR" helps to convey the point that "any (other) expression gets interpretted as a file name" as opposed to possibly implying that Perl does something like looking at the value to see if it looks like a file name.

[ I was surprised to (re)learn this:

$ perl -we "do findModule(); sub findModule{'nonesuch.pl'}" Use of "do" to call subroutines is deprecated at -e line 1.

]

And that might explain the choice of "EXPR" for these cases as well:

$ perldoc perlfunc | egrep '^ {7}truncate [A-Z]' truncate FILEHANDLE,LENGTH truncate EXPR,LENGTH $ perldoc perlfunc | egrep '^ {7}stat [A-Z]' stat FILEHANDLE stat EXPR stat DIRHANDLE

Though, I think the case of noticing FILEHANDLE and DIRHANDLE exceptions really is about examining the value not about different syntax, so I find the "EXPR" choice less valuable here. But changing "stat EXPR" to "stat FILENAME" draws too much attention to the distinction between "FILE" and "DIR" in:

stat FILEHANDLE stat FILENAME stat DIRHANDLE

While I think changing "DBNAME" to "FILENAME" would significantly improve the clarity here:

$ perldoc perlfunc | egrep '^ {7}dbmopen [A-Z]' dbmopen HASH,DBNAME,MASK

(Because "DBNAME" isn't a "FILENAME" in most contexts I deal with -- though, perhaps "FILENAME" was avoided since suffixes likely get appended.)

How about places that don't use "EXPR"?

$ perldoc perlfunc | egrep '^ {7}link ' link OLDFILE,NEWFILE $ perldoc perlfunc | egrep '^ {7}rename ' rename OLDNAME,NEWNAME

I find "OLDNAME" a much better choice than "OLDFILE". Similar to the starting complaint, "OLDFILE" could be the name of a directory. But more important, for me, is that "OLDFILE" doesn't as clearly convey that what is given is the name of a file not some handle or other representation. I also wouldn't go more explicit like these:

link OLDFILENAME,NEWFILENAME rename OLDFILENAME,NEWFILENAME

because I would worry about implying that these can't be used on directories [which isn't something I worry about implying for mkdir() or rmdir()]. One could argue for:

link OLDNAME,NEWLINKNAME

but I'd probably depart even further and go with:

link DESTNAME,NEWNAME

(I've long found the argument order for link,3 and ln quite confusing, I must admit.)

After considering the broader context, I think most of the uses of "FILENAME" really should be changed to "DIRNAME". Not because I find those uses of "FILENAME" confusing or inappropriate, but because they are cases where the distinction doesn't matter and so "DIRNAME" is just slightly clearer. (I find many cases that are a lot more in need of improvement than the one that started this thread.)

Contrast that with changing "lstat EXPR" to "lstat FILENAME". I don't like "lstat FILENAME" as it sounds like it might be trying to imply that you can't use it on directories or links, but only on plain files. But I also see no reason to use "EXPR" for that case. I think I prefer "lstat PATHNAME".

So my updates would only be as follows:

-X FILEHANDLE -X PATHNAME -X DIRHANDLE caller DEPTH caller chdir DIRNAME chdir FILEHANDLE chdir DIRHANDLE chdir chroot DIRNAME chroot connect SOCKET,DEST cos RADIANS cos dbmopen HASH,FILENAME,MASK eof FILEHANDLE eof() # Just changed spacing eof exit VALUE exp VALUE gmtime EPOCHSECONDS gmtime int VALUE int link DESTNAME,NEWNAME localtime EPOCHSECONDS localtime log VALUE log lstat PATHNAME lstat mkdir DIRNAME,MASK mkdir DIRNAME mkdir opendir DIRHANDLE,DIRNAME rand MAX rand readlink FILENAME readlink readpipe COMMANDLINE readpipe return EXPRESSIONS return rmdir DIRNAME rmdir symlink DESTNAME,NEWNAME sin VALUE sin sleep SECONDS sleep sqrt VALUE sqrt srand VALUE srand stat FILEHANDLE stat PATHNAME stat DIRHANDLE stat truncate FILEHANDLE,LENGTH truncate FILENAME,LENGTH

So I'd explicitly leave these unchanged:

chmod LIST chown LIST do BLOCK do SUBROUTINE(LIST) do EXPR rename OLDNAME,NEWNAME sysopen FILEHANDLE,FILENAME,MODE sysopen FILEHANDLE,FILENAME,MODE,PERMS

- tye        


In reply to Re^3: mkdir in perldoc (prototypes) by tye
in thread mkdir in perldoc by QM

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • Outside of code tags, you may need to use entities for some characters:
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?
    Username:
    Password:

    What's my password?
    Create A New User
    Chatterbox?
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others cooling their heels in the Monastery: (9)
    As of 2014-09-20 16:32 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      How do you remember the number of days in each month?











      Results (160 votes), past polls