Re: Announcing the Perl 5 Documentation Team

On Fri, Jul 2, 2010 at 08:57, David Golden <[email protected]> wrote:
> On Fri, Jul 2, 2010 at 8:22 AM, Chas. Owens <[email protected]> wrote:
>> It isn't just that say wasn't added until 5.10, it is that say doesn't
>> even work without a "use 5.010;" or similar statement.  This means
>> that the person coming to the Perl for the first time will encounter
>> one of three scenarios:
>
> You're missing my point, or I'm not being sufficiently clear.
>
> The vast majority of the time, the documentation is being read by
> people who are *NOT* "coming to Perl for the first time" and thus I
> don't think that *all* documentation should be written for the
> absolute beginner.
>
> Intro-level documentation ("intro", "tutorial", "quick start",
> possibly "faq") should.  Reference documentation should not.  IMO,
> that includes things that would come from perldoc -f, etc.
>
> Yes, we want to make Perl easier to learn for the novice, but not at
> the cost of bloating the documentation for the average user.
>
> -- David
>

Lets take a quick look at what it would really look like.  I chose
substr at random and updated it to fit scenario 3.  It took four
version statements and a rewrite of the last example.  I am not
satisfied with the last example, it is still very confusing. there
must be a better example of when you would use this feature of substr.
 Also, and this shows my ignorance of the newer features, why doesn't
given work with that example?  I thought it was supposed to alias $_
to its argument like for does.

Proposed style:

=item substr EXPR,OFFSET

Extracts a substring out of EXPR and returns it.  First character is at
offset C<0>, or whatever you've set C<$[> to (but don't do that).
If OFFSET is negative (or more precisely, less than C<$[>), starts
that far from the end of the string.  If LENGTH is omitted, returns
everything to the end of the string.  If LENGTH is negative, leaves that
many characters off the end of the string.

    use 5.005;
    my $s = "The black cat climbed the green tree";
    my $color  = substr $s, 4, 5;      # black
    my $middle = substr $s, 4, -11;    # black cat climbed the
    my $end    = substr $s, 14;        # climbed the green tree
    my $tail   = substr $s, -4;        # tree
    my $z      = substr $s, -4, 2;     # tr

You can use the substr() function as an lvalue, in which case EXPR
must itself be an lvalue.  If you assign something shorter than LENGTH,
the string will shrink, and if you assign something longer than LENGTH,
the string will grow to accommodate it.  To keep the string the same
length, you may need to pad or chop your value using C<sprintf>.

If OFFSET and LENGTH specify a substring that is partly outside the
string, only the part within the string is returned.  If the substring
is beyond either end of the string, substr() returns the undefined
value and produces a warning.  When used as an lvalue, specifying a
substring that is entirely outside the string raises an exception.
Here's an example showing the behavior for boundary cases:

    use 5.005;
    my $name = 'fred';
    substr($name, 4) = 'dy';         # $name is now 'freddy'
    my $null = substr $name, 6, 2;   # returns "" (no warning)
    my $oops = substr $name, 7;      # returns undef, with warning
    substr($name, 7) = 'gap';        # raises an exception

An alternative to using substr() as an lvalue is to specify the
replacement string as the 4th argument.  This allows you to replace
parts of the EXPR and return what was there before in one operation,
just as you can with splice().

    use 5.005;
    my $s = "The black cat climbed the green tree";
    my $z = substr $s, 14, 7, "jumped from";    # climbed
    # $s is now "The black cat jumped from the green tree"

Note that the lvalue returned by the 3-arg version of substr() acts as
a 'magic bullet'; each time it is assigned to, it remembers which part
of the original string is being modified; for example:

    use 5.010;
    my $x = '1234';
    for my $temp (substr($x,1,2)) {
        $temp = 'a';   say $x;    # prints 1a4
        $temp = 'xyz'; say $x;    # prints 1xyz4
        $x    = '56789';
        $temp = 'pq';  say $x;    # prints 5pq9
    }

Prior to Perl version 5.9.1, the result of using an lvalue multiple times was
unspecified.

Versus the original

=over 8

=item substr EXPR,OFFSET,LENGTH,REPLACEMENT
X<substr> X<substring> X<mid> X<left> X<right>

=item substr EXPR,OFFSET,LENGTH

=item substr EXPR,OFFSET

Extracts a substring out of EXPR and returns it.  First character is at
offset C<0>, or whatever you've set C<$[> to (but don't do that).
If OFFSET is negative (or more precisely, less than C<$[>), starts
that far from the end of the string.  If LENGTH is omitted, returns
everything to the end of the string.  If LENGTH is negative, leaves that
many characters off the end of the string.

    my $s = "The black cat climbed the green tree";
    my $color  = substr $s, 4, 5;      # black
    my $middle = substr $s, 4, -11;    # black cat climbed the
    my $end    = substr $s, 14;        # climbed the green tree
    my $tail   = substr $s, -4;        # tree
    my $z      = substr $s, -4, 2;     # tr

You can use the substr() function as an lvalue, in which case EXPR
must itself be an lvalue.  If you assign something shorter than LENGTH,
the string will shrink, and if you assign something longer than LENGTH,
the string will grow to accommodate it.  To keep the string the same
length, you may need to pad or chop your value using C<sprintf>.

If OFFSET and LENGTH specify a substring that is partly outside the
string, only the part within the string is returned.  If the substring
is beyond either end of the string, substr() returns the undefined
value and produces a warning.  When used as an lvalue, specifying a
substring that is entirely outside the string raises an exception.
Here's an example showing the behavior for boundary cases:

    my $name = 'fred';
    substr($name, 4) = 'dy';         # $name is now 'freddy'
    my $null = substr $name, 6, 2;   # returns "" (no warning)
    my $oops = substr $name, 7;      # returns undef, with warning
    substr($name, 7) = 'gap';        # raises an exception

An alternative to using substr() as an lvalue is to specify the
replacement string as the 4th argument.  This allows you to replace
parts of the EXPR and return what was there before in one operation,
just as you can with splice().

    my $s = "The black cat climbed the green tree";
    my $z = substr $s, 14, 7, "jumped from";    # climbed
    # $s is now "The black cat jumped from the green tree"

Note that the lvalue returned by the 3-arg version of substr() acts as
a 'magic bullet'; each time it is assigned to, it remembers which part
of the original string is being modified; for example:

    $x = '1234';
    for (substr($x,1,2)) {
        $_ = 'a';   print $x,"\n";    # prints 1a4
        $_ = 'xyz'; print $x,"\n";    # prints 1xyz4
        $x = '56789';
        $_ = 'pq';  print $x,"\n";    # prints 5pq9
    }

Prior to Perl version 5.9.1, the result of using an lvalue multiple times was
unspecified.

=back


-- 
Chas. Owens
wonkden.net
The most important skill a programmer can have is the ability to read.