In the documentation for sprintf (
http://perlcabal.org/syn/S32/Str.html#sprintf) I suggest changing:
The $format is scanned for % characters. Any % introduces a format token.
> Format tokens have the following grammar:
to:
The $format is scanned for % characters. Any % introduces a format token.
> The simplest format tokens are a % followed by a letter which is called a
> "directive". Directives guide the use (if any) of the rest of sprintf's
> arguments. Between the % and the directive, a number of controls such as
> precision and width formatting can be introduced.
> In detail, format tokens have the following grammar:
... and remove the two sentences that follow the grammar itself.
It's a bit harsh to drop the casual reader right into the grammar for
format tokens without explaining what the grammar is for.
As for the grammar itself, can we remove the commit after the initial %? Is
it required for the documentation?
On "index" modifiers: Do we need a string variant for named parameters in
P6? E.g.:
sprintf('%(time)$s: %(msg)$s', :$msg, :$time);
as an alternative to:
sprintf('%2$s: %1$s', $msg, $time);
Python has something like this (
http://docs.python.org/library/stdtypes.html#string-formatting), but they
drop the $ and just use "%(name)d" where d is the directive... it's not
clear to me if the presence of the $ in P6 helps (because it maintains
visual compatibility with numeric indexes) or hinders (because it's not
required and therefore just makes the format longer for no reason)...
Also documenting each part of the grammar is, of course, required. For
example, here's a description of the "index" portion of the grammar:
The index modifies the default behavior of pulling needed values from
> sprintf's remaining arguments, in order. Instead, the given index number
> addresses the positional argument list to sprintf, with the format string
> itself being index zero and subsequent positional parameters being one and
> so-forth.
In that description, I'm implicitly allowing for a format string which
includes itself ("%0$s"), which is not part of the previous standards, but
I think it doesn't hurt, and avoids arbitrarily disallowing it the way P5
and POSIX do...
The vector flag should probably go. Its only primary use is unpacking raw
IPv4 addresses, and that can be done in a dozen other trivial ways in Perl
6. TMTOWTDI, but this is a particularly archaic way that I can't imagine
any new code wanting to use...
For the rest, I think we can copy the documentation for precision and flags
from:
http://perldoc.perl.org/functions/sprintf.html
Also, a review of the POSIX documentation might reveal additional items
that should be documented:
http://pubs.opengroup.org/onlinepubs/9699919799/functions/sprintf.html
--
Aaron Sherman <a...@ajs.com>
P: 617-440-4332 Google Talk: a...@ajs.com / aaronjsher...@gmail.com
"Toolsmith" and developer. Player of games. Buyer of gadgets.
