Received: by 10.66.77.3 with SMTP id o3mr1308214paw.13.1348770603044;
        Thu, 27 Sep 2012 11:30:03 -0700 (PDT)
Newsgroups: perl.perl6.language
Path: g9ni397pbh.1!nntp.google.com!border1.nntp.dca.giganews.com!nntp.giganews.com!news.snarked.org!nntp.develooper.com!nntp.perl.org
Return-Path: <a...@ajs.com>
Mailing-List: contact perl6-language-h...@perl.org; run by ezmlm
Delivered-To: mailing list perl6-langu...@perl.org
Received: (qmail 32714 invoked from network); 27 Sep 2012 18:18:27 -0000
Received: from x1.develooper.com (207.171.7.70)
  by x6.develooper.com with SMTP; 27 Sep 2012 18:18:27 -0000
Received: (qmail 12425 invoked by uid 225); 27 Sep 2012 18:18:27 -0000
Delivered-To: perl6-langu...@perl.org
Received: (qmail 12421 invoked by alias); 27 Sep 2012 18:18:27 -0000
X-Spam-Status: No, hits=-2.6 required=8.0
	tests=BAYES_00,HTML_MESSAGE,RCVD_IN_DNSWL_LOW
X-Spam-Check-By: la.mx.develooper.com
Received: from mail-vb0-f41.google.com (HELO mail-vb0-f41.google.com) (209.85.212.41)
    by la.mx.develooper.com (qpsmtpd/0.28) with ESMTP; Thu, 27 Sep 2012 11:18:23 -0700
Received: by vbkv13 with SMTP id v13so2843413vbk.14
        for <perl6-langu...@perl.org>; Thu, 27 Sep 2012 11:18:19 -0700 (PDT)
        d=google.com; s=20120113;
        h=mime-version:date:message-id:subject:from:to:content-type
         :x-gm-message-state;
        bh=PVLKVunKY0SYNHGuhf1ygvBjnQVfvuasyH9C6jvz0UI=;
        b=LD19okuCYSY8P4T03SOM/lRS68nayp9KAyYTYy4vm1gLkh+/O1aXe0211BbjoRQBi6
         ukKeFmqwUAs1z/qGvsp+gJf/vOYxfouNkIaUJKg3Y9VchpUsWPc7Kj9HinRjFucHvizG
         PsX3XpdBU0TGYkGQ7N8M0ud8ujfOF5IZaoudgey936YB2fGQX5lnpqNZSFkhFYx7j+YT
         CFMT4Xxp+d8vMR2gcuZiex14jKoOekzF6+DBmetF+q7dd2QmHndTqsYNEW7+FAR4VRQS
         LL+8Gxegg+30RkVCcnTU98aF/Q75AVl4IK01u9/00DhaO+FnOP2MkCnuXo53lPlyCAVH
         Ftag==
MIME-Version: 1.0
Received: by 10.52.90.83 with SMTP id bu19mr2130521vdb.64.1348769898845; Thu,
 27 Sep 2012 11:18:18 -0700 (PDT)
Received: by 10.58.58.41 with HTTP; Thu, 27 Sep 2012 11:18:18 -0700 (PDT)
Date: Thu, 27 Sep 2012 14:18:18 -0400
Message-ID: <CAN=dS7SnNQFNCoyff1YKd-bVmSh=ok4SWs3aHTEPCuxstOD...@mail.gmail.com>
Subject: Update for S32::Str and musings on sprintf
To: Perl6 Language List <perl6-langu...@perl.org>
X-Gm-Message-State: ALoCoQmtI8UecvwMTo13r8XUUeqm+OSmpRvqvYSMxbmS49my69n0pn9ks4eVbphApLnd1V2/luMd
X-Virus-Checked: Checked
Approved: n...@nntp.perl.org
From: a...@ajs.com (Aaron Sherman)
Bytes: 5639
Lines: 84
Content-Type: text/plain; charset=UTF-8

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.