Beefy Boxes and Bandwidth Generously Provided by pair Networks
No such thing as a small change

Comment on

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

There are a lot of Perl functions that expect a string. And yet there is only one pair that document this in these usage lines:

$ perldoc perlfunc | egrep '^ {7}[a-z]+ STR' index STR,SUBSTR,POSITION index STR,SUBSTR rindex STR,SUBSTR,POSITION rindex STR,SUBSTR

I refrained from proposing that a ton of cases of "EXPR" be changed to "STRING" (no, not to "STR", thank you) because there are a lot of cases where the ARGUMENT part is describing a type of syntax rather than a type of data. And, for example, "chop STRING" might convey that you can only write chop('string literal') not chop($variable) (when the opposite is the case).

That is also why I didn't label any arguments as things like "INT" or "NUMBER" (and note that nobody else before me did either).

Now, if we can come up with a name that conveys "an expression that will be interpreted as a string" that is hard to interpret as meaning "just a string literal", then I'd change a bunch more "EXPR" items. That would be similar to how I copied the precedent of "abs VALUE" to a lot of cases where a numeric expression is expected. But I, like you, preferred even better names like "rand MAX", "caller DEPTH", and "cos RADIANS".

I also never used "VARIABLE" as there are two quite different cases that such might imply. One might be tempted to write "chop VARIABLE" to convey that chop expects to be able to modify what it is given in-place (it needs to be an "lvalue"). But there are a lot of lvalues in Perl that are not just "VARIABLE".

The other case is when nothing more complex than a simple scalar variable is allowed (such as for "FILEHANDLE" in "print FILEHANDLE LIST"). One such is where I was strongly tempted to use "VARIABLE":

$ perldoc perlfunc | egrep '^ {7}sort ' sort SUBNAME LIST sort BLOCK LIST sort LIST

Because the "sort SUBNAME LIST" case actually includes the possibility of using a reference to a subroutine, not just a SUBNAME. I'd almost rather it was more specific like:


But that would be a significant departure from the rest of the entries. And I actually don't think that \&SUBNAME is allowed. The documentation strongly implies that sort $compare_by{$type} LIST is not allowed (while the examples very much don't clarify that point). But part of this is due to sort just having some of the worst syntax quirks of any Perl function.

I think a better route is, for the few complex cases, throw in just the shortest canonical syntax examples much earlier:

sort SUBNAME LIST sort BLOCK LIST sort LIST In list context, this sorts the LIST and returns the sorted list value. In scalar context, the behaviour of "sort()" is undefined. If SUBNAME and BLOCK are omitted, "sort"s in standard string comparison order. Otherwise, SUBNAME or BLOCK provides a subroutine that returns an integer less than, equal to, or greater than 0, depending on how the elements of the list are to be ordered. (The "<=>" and "cmp" operators are extremely useful in such routines.) SUBNAME should be the bareword name of a subroutine or a simple scalar variable (unsubscripted) containing either a subroutine name or a reference to a subroutine. BLOCK is just an anonymous, in-line subroutine. @names = sort @names; @numbers = sort { $a <=> $b } @numbers; sub hi2lo { $b <=> $a } @numbers = sort hi2lo @numbers; my $comparison = \&hi2lo; @numbers = sort $comparison @numbers; # Syntax error: my %comparisons = get_compare_functions(); @numbers = sort $comparisons{hi2lo} @numbers; # Not allowed ^^^^^^^ Beware when trying to sort the list returned from a function call, as the obvious syntax does not do that: @sorted = sort foo($x,$y); # same as: @sorted = sort foo $x,$y; # or as: my @list = ($x,$y); @sorted = sort foo @list; # Put just $x and $y into @sorted, # using foo() to compare the values. You must instead use something like: @sorted = sort( foo($x,$y) ); @sorted = sort { $a cmp $b } foo $x,$y; @sorted = sort +foo($x,$y); @sorted = sort &foo($x,$y); ...describe more esoteric details... ...don't include more examples until later... (so the examples of just syntax stand out)

- tye        

In reply to Re^5: mkdir in perldoc (STRING) by tye
in thread mkdir in perldoc by QM

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!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • 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
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            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?

    What's my password?
    Create A New User
    and all is quiet...

    How do I use this? | Other CB clients
    Other Users?
    Others scrutinizing the Monastery: (7)
    As of 2017-01-20 02:54 GMT
    Find Nodes?
      Voting Booth?
      Do you watch meteor showers?

      Results (173 votes). Check out past polls.