develooper Front page | perl.perl5.porters | Postings from August 1999

Re: perlfunc annonations or OOB enhancements?

Thread Previous | Thread Next
Adam Turoff
August 27, 1999 17:02
Re: perlfunc annonations or OOB enhancements?
Message ID:
Tom Christiansen wrote:
> For example, that summary for substr() doesn't say that it's got an
> assignable return value, nor does it indicate what should go in EXPR (a
> string, not a number or an object reference), nor that the REPLACEMENT is
> also a string.

Hrm.  I'm not following the discussion of my Dog $spot, but it seems like
everyone is agreeing on the syntax even if the implementation is months

If that's the case, how about something like:

    substr(str $EXPR, int $OFFSET [, int $LEN [, str $REPLACEMENT]])

That's machine parsable, and makes it obvious which bits are optional.
That doesn't address the fact that substr can be an lvalue expression...

I suppose you can extend this syntax for documentation to include things
like +int and +num to denote non-negative numeric values.  Or just ignore 
the distinction entirely and describe them in prose.

> localtime(), on the other hand, does not therein by its perlfunc header
> alone indicate both a list and scalar return value, nor does it say
> what should go in EXPR (a non-negative integer, not a string nor an
> object reference), nor does it explain what the various list return
> value elements mean semantically, including their valid ranges?

I think that requires two descriptions:

	str $ctime = localtime([+int $seconds | time() ])

	(int $sec, int $min, int $hour, int $mday, int $mon, int $year, 
		int $wday, int $yday, int $isdst) 
			= localtime ([+int $secs | time()])

Yes, it's verbose and ugly, but no more than it needs to be.  The verbosity
and ugliness here makes a good case for out of band descriptions.  It
also describes the default values.  (Using = instead of | might be
a better choice.)

The good news is that if you introduce =function (for example), you need 
no extra markup to infer the rest of the descriptions.  In that case, it 
might be more desirable to have this in-band.

This is assuming that the int/str/num/CGI/DB_File etc. bits are acceptable
Perl (FSDO acceptable).

Handling constructor functions which take named parameters is the
next step...

> I'm not sure how much support for those efforts should be in perlfunc, or
> perhaps even in the distribution at all (personally, I use and
> the source code).  Can anyone supply some non-commercial motivation for
> doing anything in this arena?  And if so, what is your proposed syntax?

Better documentation.  These descriptions must be highly regular, so
deriving a reference card or better preambles for HTML/manpages shouldn't
be too difficult.

-- Adam

Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About