[ 21385]
Subject: [PATCH 5.8.1] pod/perlrun.pod: no space after -i allowed
From: Brendan O'Dea <bod@debian.org>
Date: Sun, 28 Sep 2003 23:23:34 +1000
Message-ID: <
20030928132334.GA29499@londo.c47.org>
[ 21386]
Subject: [PATCH 5.8.1] Fix broken splitpod program
From: Steve Hay <steve.hay@uk.radan.com>
Date: Mon, 29 Sep 2003 11:50:23 +0100
Message-ID: <
3F780E6F.3020704@uk.radan.com>
[ 21388]
Subject: [PATCH] Re: [perl #24071] Typo in description of binmode
From: Yitzchak Scott-Thoennes <sthoenna@efn.org>
Date: Tue, 30 Sep 2003 04:53:02 -0700
Message-ID: <
20030930115302.GA3200@efn.org>
[ 21392]
Revamp the section on local() in perlsub.
- avoid using the word "declare" in conjunction with local()
- less archaelogical references
- more about localization of lvalues
- removes examples of localization of tied hashes that don't work
- give titles to subsections
- explain localization of magic values
- explain localization of globs
- fix link to perldelta
[ 21398]
build perlapi.pod in deterministic order even when functions differ
only in case; regen perlapi.pod
[ 21403]
Subject: Re: [PATCH] [perl #24113] mistake in perlretut
From: Robert Spier <rspier@pobox.com>
Date: Sun, 05 Oct 2003 21:34:30 -0700
Message-Id: <m3vfr39e7d.wl_rspier@pobox.com>
[ 21405]
Subject: Re: [PATCH] perlsyn.pod Revision - Resend
From: Shlomi Fish <shlomif@vipe.technion.ac.il>
Date: Fri, 3 Oct 2003 12:34:46 +0200 (IST)
Message-Id: <Pine.LNX.4.56.
0310031233580.28640@vipe.technion.ac.il>
(Applied with minor tweaks.)
[ 21409]
Subject: [PATCH pod/perlfunc.pod] ref can return false on references
From: Abigail <abigail@abigail.nl>
Date: Mon, 6 Oct 2003 05:55:21 -0700
Message-ID: <
20031006125521.GA26446@ucan.foad.org>
[ 21412]
Fix broken link in perltodo.pod.
[ 21417]
Update perlfunc/require to describe NXDOMAIN caching... er, you
know what I mean.
[ 21431]
Document the behaviour of filetest operators regarding parentheses.
This fixes bug #24127 (by documenting it as a feature.)
[ 21435]
Make everyone stop posting to p5p about 0e0.
[ 21437]
Minor nit in perlrun, spotted by Art Haas.
p4raw-link: @21437 on //depot/perl:
47427c4eeabaf71bb2382593c8e760e49bdf9070
p4raw-link: @21435 on //depot/perl:
835f270a3e4bae7616085b997e93ab587be224b4
p4raw-link: @21431 on //depot/perl:
568e6d8bd7657b48163f7ab2d0c13229c0263323
p4raw-link: @21417 on //depot/perl:
209071589ddd827372bd46e1358d1d13f6b4dbcb
p4raw-link: @21412 on //depot/perl:
d085b7b6c4d00879b2363f00bf97b5f398fbae7d
p4raw-link: @21409 on //depot/perl:
8a2e08044eac72c17425ec10bbb958834013a72b
p4raw-link: @21405 on //depot/perl:
cf48932e9c614884be015feecb615c4d42f6f135
p4raw-link: @21403 on //depot/perl:
865c4c6f6836f5d201ca85b078e35d1e47de908b
p4raw-link: @21398 on //depot/perl:
6a477168226f5506df9ce7c01de57e2808b61d82
p4raw-link: @21392 on //depot/perl:
325192b1501ec5e5c61fcc775e645f404027aa64
p4raw-link: @21388 on //depot/perl:
749683d21f35ef8611124597a119da951072e5fa
p4raw-link: @21386 on //depot/perl:
279b5f1a612874b608bbd09f6635e256c67090a7
p4raw-link: @21385 on //depot/perl:
ddffceb7d688de00c74f6c81d16019f39be53dc8
p4raw-id: //depot/maint-5.8/perl@21479
p4raw-integrated: from //depot/perl@21478 'copy in' autodoc.pl
(@18851..) pod/splitpod (@19140..) pod/perlretut.pod (@19873..)
pod/perltodo.pod (@21198..) 'edit in' pod/perlfunc.pod
(@21409..) 'merge in' pod/perlsub.pod (@21007..) pod/perlop.pod
(@21421..)
p4raw-edited: from //depot/perl@21405 'edit in' pod/perlsyn.pod
(@20161..)
p4raw-integrated: from //depot/perl@21398 'merge in' pod/perlapi.pod
(@21198..)
p4raw-edited: from //depot/perl@21385 'edit in' pod/perlrun.pod
(@21139..)
_EOB_
my $key;
-for $key (sort { uc($a) cmp uc($b); } keys %apidocs) { # case insensitive sort
+# case insensitive sort, with fallback for determinacy
+for $key (sort { uc($a) cmp uc($b) || $a cmp $b } keys %apidocs) {
my $section = $apidocs{$key};
print DOC "\n=head1 $key\n\n=over 8\n\n";
for my $key (sort { uc($a) cmp uc($b); } keys %$section) {
=for hackers
Found in file sv.h
-=item SvIVX
+=item SvIVx
-Returns the raw value in the SV's IV slot, without checks or conversions.
-Only use when you are sure SvIOK is true. See also C<SvIV()>.
+Coerces the given SV to an integer and returns it. Guarantees to evaluate
+sv only once. Use the more efficient C<SvIV> otherwise.
- IV SvIVX(SV* sv)
+ IV SvIVx(SV* sv)
=for hackers
Found in file sv.h
-=item SvIVx
+=item SvIVX
-Coerces the given SV to an integer and returns it. Guarantees to evaluate
-sv only once. Use the more efficient C<SvIV> otherwise.
+Returns the raw value in the SV's IV slot, without checks or conversions.
+Only use when you are sure SvIOK is true. See also C<SvIV()>.
- IV SvIVx(SV* sv)
+ IV SvIVX(SV* sv)
=for hackers
Found in file sv.h
=for hackers
Found in file sv.h
-=item SvNVx
+=item SvNVX
-Coerces the given SV to a double and returns it. Guarantees to evaluate
-sv only once. Use the more efficient C<SvNV> otherwise.
+Returns the raw value in the SV's NV slot, without checks or conversions.
+Only use when you are sure SvNOK is true. See also C<SvNV()>.
- NV SvNVx(SV* sv)
+ NV SvNVX(SV* sv)
=for hackers
Found in file sv.h
-=item SvNVX
+=item SvNVx
-Returns the raw value in the SV's NV slot, without checks or conversions.
-Only use when you are sure SvNOK is true. See also C<SvNV()>.
+Coerces the given SV to a double and returns it. Guarantees to evaluate
+sv only once. Use the more efficient C<SvNV> otherwise.
- NV SvNVX(SV* sv)
+ NV SvNVx(SV* sv)
=for hackers
Found in file sv.h
=for hackers
Found in file sv.h
-=item SvPVX
+=item SvPVx
-Returns a pointer to the physical string in the SV. The SV must contain a
-string.
+A version of C<SvPV> which guarantees to evaluate sv only once.
- char* SvPVX(SV* sv)
+ char* SvPVx(SV* sv, STRLEN len)
=for hackers
Found in file sv.h
-=item SvPVx
+=item SvPVX
-A version of C<SvPV> which guarantees to evaluate sv only once.
+Returns a pointer to the physical string in the SV. The SV must contain a
+string.
- char* SvPVx(SV* sv, STRLEN len)
+ char* SvPVX(SV* sv)
=for hackers
Found in file sv.h
If LAYER is omitted or specified as C<:raw> the filehandle is made
suitable for passing binary data. This includes turning off possible CRLF
translation and marking it as bytes (as opposed to Unicode characters).
-Note that as despite what may be implied in I<"Programming Perl">
-(the Camel) or elsewhere C<:raw> is I<not> the simply inverse of C<:crlf>
+Note that, despite what may be implied in I<"Programming Perl"> (the
+Camel) or elsewhere, C<:raw> is I<not> the simply inverse of C<:crlf>
-- other layers which would affect binary nature of the stream are
I<also> disabled. See L<PerlIO>, L<perlrun> and the discussion about the
PERLIO environment variable.
=item ref
-Returns a true value if EXPR is a reference, false otherwise. If EXPR
+Returns a non-empty string if EXPR is a reference, the empty
+string otherwise. If EXPR
is not specified, C<$_> will be used. The value returned depends on the
type of thing the reference is a reference to.
Builtin types include:
Otherwise, demands that a library file be included if it hasn't already
been included. The file is included via the do-FILE mechanism, which is
-essentially just a variety of C<eval>. Has semantics similar to the following
-subroutine:
+essentially just a variety of C<eval>. Has semantics similar to the
+following subroutine:
sub require {
- my($filename) = @_;
- return 1 if $INC{$filename};
- my($realfilename,$result);
- ITER: {
- foreach $prefix (@INC) {
- $realfilename = "$prefix/$filename";
- if (-f $realfilename) {
- $INC{$filename} = $realfilename;
- $result = do $realfilename;
- last ITER;
- }
- }
- die "Can't find $filename in \@INC";
- }
- delete $INC{$filename} if $@ || !$result;
- die $@ if $@;
- die "$filename did not return true value" unless $result;
- return $result;
+ my ($filename) = @_;
+ if (exists $INC{$filename}) {
+ return 1 if $INC{$filename};
+ die "Compilation failed in require";
+ }
+ my ($realfilename,$result);
+ ITER: {
+ foreach $prefix (@INC) {
+ $realfilename = "$prefix/$filename";
+ if (-f $realfilename) {
+ $INC{$filename} = $realfilename;
+ $result = do $realfilename;
+ last ITER;
+ }
+ }
+ die "Can't find $filename in \@INC";
+ }
+ if ($@) {
+ $INC{$filename} = undef;
+ die $@;
+ } elsif (!$result) {
+ delete $INC{$filename};
+ die "$filename did not return true value";
+ } else {
+ return $result;
+ }
}
Note that the file will not be included twice under the same specified
=head2 Named Unary Operators
The various named unary operators are treated as functions with one
-argument, with optional parentheses. These include the filetest
-operators, like C<-f>, C<-M>, etc. See L<perlfunc>.
+argument, with optional parentheses.
If any list operator (print(), etc.) or any unary operator (chdir(), etc.)
is followed by a left parenthesis as the next token, the operator and
rand (10) * 20; # (rand 10) * 20
rand +(10) * 20; # rand (10 * 20)
+Regarding precedence, the filetest operators, like C<-f>, C<-M>, etc. are
+treated like named unary operators, but they don't follow this functional
+parenthesis rule. That means, for example, that C<-f($file).".bak"> is
+equivalent to C<-f "$file.bak">.
+
See also L<"Terms and List Operators (Leftward)">.
=head2 Relational Operators
"2+2=4" =~ /2\+2/; # matches, \+ is treated like an ordinary +
"The interval is [0,1)." =~ /[0,1)./ # is a syntax error!
"The interval is [0,1)." =~ /\[0,1\)\./ # matches
- "/usr/bin/perl" =~ /\/usr\/local\/bin\/perl/; # matches
+ "/usr/bin/perl" =~ /\/usr\/bin\/perl/; # matches
In the last regexp, the forward slash C<'/'> is also backslashed,
because it is used to delimit the regexp. This can lead to LTS
(leaning toothpick syndrome), however, and it is often more readable
to change delimiters.
+ "/usr/bin/perl" =~ m!/usr/bin/perl!; # easier to read
The backslash character C<'\'> is a metacharacter itself and needs to
be backslashed:
streams as usual.
C<-C> on its own (not followed by any number or option list), or the
-empty string C<""> for the C<$ENV{PERL_UNICODE}, has the same effect
-as <-CSDL>. In other words, the standard I/O handles and the default
-C<open()> layer are UTF-8-fied B<but> only if the locale environment
-variables indicate a UTF-8 locale. This behaviour follows the
-I<implicit> (and problematic) UTF-8 behaviour of Perl 5.8.0.
+empty string C<""> for the C<PERL_UNICODE> environment variable, has the
+same effect as C<-CSDL>. In other words, the standard I/O handles and
+the default C<open()> layer are UTF-8-fied B<but> only if the locale
+environment variables indicate a UTF-8 locale. This behaviour follows
+the I<implicit> (and problematic) UTF-8 behaviour of Perl 5.8.0.
-You can use C<-C0> (or C<"0"> for $ENV{PERL_UNICODE}) to explicitly
+You can use C<-C0> (or C<"0"> for C<PERL_UNICODE>) to explicitly
disable all the above Unicode features.
The read-only magic variable C<${^UNICODE}> reflects the numeric value
This allows you to add a prefix to the backup file, instead of (or in
addition to) a suffix:
- $ perl -pi 'orig_*' -e 's/bar/baz/' fileA # backup to 'orig_fileA'
+ $ perl -pi'orig_*' -e 's/bar/baz/' fileA # backup to 'orig_fileA'
Or even to place backup copies of the original files into another
directory (provided the directory already exists):
- $ perl -pi 'old/*.orig' -e 's/bar/baz/' fileA # backup to 'old/fileA.orig'
+ $ perl -pi'old/*.orig' -e 's/bar/baz/' fileA # backup to 'old/fileA.orig'
These sets of one-liners are equivalent:
$ perl -pi -e 's/bar/baz/' fileA # overwrite current file
- $ perl -pi '*' -e 's/bar/baz/' fileA # overwrite current file
+ $ perl -pi'*' -e 's/bar/baz/' fileA # overwrite current file
- $ perl -pi '.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
- $ perl -pi '*.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
+ $ perl -pi'.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
+ $ perl -pi'*.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
From the shell, saying
or C<do/require/use>'d file. If more than one value is listed, the
list must be placed in parentheses. All listed elements must be
legal lvalues. Only alphanumeric identifiers may be lexically
-scoped--magical built-ins like C<$/> must currently be C<local>ize
+scoped--magical built-ins like C<$/> must currently be C<local>ized
with C<local> instead.
Unlike dynamic variables created by the C<local> operator, lexical
B<WARNING>: In general, you should be using C<my> instead of C<local>, because
it's faster and safer. Exceptions to this include the global punctuation
-variables, filehandles and formats, and direct manipulation of the Perl
-symbol table itself. Format variables often use C<local> though, as do
-other variables whose current value must be visible to called
-subroutines.
+variables, global filehandles and formats, and direct manipulation of the
+Perl symbol table itself. C<local> is mostly used when the current value
+of a variable must be visible to called subroutines.
Synopsis:
- local $foo; # declare $foo dynamically local
- local (@wid, %get); # declare list of variables local
- local $foo = "flurp"; # declare $foo dynamic, and init it
- local @oof = @bar; # declare @oof dynamic, and init it
+ # localization of values
+
+ local $foo; # make $foo dynamically local
+ local (@wid, %get); # make list of variables local
+ local $foo = "flurp"; # make $foo dynamic, and init it
+ local @oof = @bar; # make @oof dynamic, and init it
+
+ local $hash{key} = "val"; # sets a local value for this hash entry
+ local ($cond ? $v1 : $v2); # several types of lvalues support
+ # localization
+
+ # localization of symbols
local *FH; # localize $FH, @FH, %FH, &FH ...
local *merlyn = *randal; # now $merlyn is really $randal, plus
a local variable. This is known as dynamic scoping. Lexical scoping
is done with C<my>, which works more like C's auto declarations.
-If more than one variable is given to C<local>, they must be placed in
-parentheses. All listed elements must be legal lvalues. This operator works
+Some types of lvalues can be localized as well : hash and array elements
+and slices, conditionals (provided that their result is always
+localizable), and symbolic references. As for simple variables, this
+creates new, dynamically scoped values.
+
+If more than one variable or expression is given to C<local>, they must be
+placed in parentheses. This operator works
by saving the current values of those variables in its argument list on a
hidden stack and restoring them upon exiting the block, subroutine, or
eval. This means that called subroutines can also reference the local
variable, but not the global one. The argument list may be assigned to if
desired, which allows you to initialize your local variables. (If no
initializer is given for a particular variable, it is created with an
-undefined value.) Commonly this is used to name the parameters to a
-subroutine. Examples:
-
- for $i ( 0 .. 9 ) {
- $digits{$i} = $i;
- }
- # assume this function uses global %digits hash
- parse_num();
-
- # now temporarily add to %digits hash
- if ($base12) {
- # (NOTE: not claiming this is efficient!)
- local %digits = (%digits, 't' => 10, 'e' => 11);
- parse_num(); # parse_num gets this new %digits!
- }
- # old %digits restored here
+undefined value.)
Because C<local> is a run-time operator, it gets executed each time
-through a loop. In releases of Perl previous to 5.0, this used more stack
-storage each time until the loop was exited. Perl now reclaims the space
-each time through, but it's still more efficient to declare your variables
-outside the loop.
+through a loop. Consequently, it's more efficient to localize your
+variables outside the loop.
+
+=head3 Grammatical note on local()
A C<local> is simply a modifier on an lvalue expression. When you assign to
a C<local>ized variable, the C<local> doesn't change whether its list is viewed
supplies a scalar context.
-A note about C<local()> and composite types is in order. Something
-like C<local(%foo)> works by temporarily placing a brand new hash in
-the symbol table. The old hash is left alone, but is hidden "behind"
-the new one.
+=head3 Localization of special variables
-This means the old variable is completely invisible via the symbol
-table (i.e. the hash entry in the C<*foo> typeglob) for the duration
-of the dynamic scope within which the C<local()> was seen. This
-has the effect of allowing one to temporarily occlude any magic on
-composite types. For instance, this will briefly alter a tied
-hash to some other implementation:
+If you localize a special variable, you'll be giving a new value to it,
+but its magic won't go away. That means that all side-effects related
+to this magic still work with the localized value.
- tie %ahash, 'APackage';
- [...]
- {
- local %ahash;
- tie %ahash, 'BPackage';
- [..called code will see %ahash tied to 'BPackage'..]
- {
- local %ahash;
- [..%ahash is a normal (untied) hash here..]
- }
+This feature allows code like this to work :
+
+ # Read the whole contents of FILE in $slurp
+ { local $/ = undef; $slurp = <FILE>; }
+
+Note, however, that this restricts localization of some values ; for
+example, the following statement dies, as of perl 5.9.0, with an error
+I<Modification of a read-only value attempted>, because the $1 variable is
+magical and read-only :
+
+ local $1 = 2;
+
+Similarly, but in a way more difficult to spot, the following snippet will
+die in perl 5.9.0 :
+
+ sub f { local $_ = "foo"; print }
+ for ($1) {
+ # now $_ is aliased to $1, thus is magic and readonly
+ f();
}
- [..%ahash back to its initial tied self again..]
-B<WARNING> The code example above does not currently work as described.
+See next section for an alternative to this situation.
+
+B<WARNING>: Localization of tied arrays and hashes does not currently
+work as described.
This will be fixed in a future release of Perl; in the meantime, avoid
code that relies on any particular behaviour of localising tied arrays
or hashes (localising individual elements is still okay).
-See L<perldelta/"Localising Tied Arrays and Hashes Is Broken"> for more
+See L<perl58delta/"Localising Tied Arrays and Hashes Is Broken"> for more
details.
-As another example, a custom implementation of C<%ENV> might look
-like this:
+=head3 Localization of globs
- {
- local %ENV;
- tie %ENV, 'MyOwnEnv';
- [..do your own fancy %ENV manipulation here..]
- }
- [..normal %ENV behavior here..]
+The construct
+
+ local *name;
+
+creates a whole new symbol table entry for the glob C<name> in the
+current package. That means that all variables in its glob slot ($name,
+@name, %name, &name, and the C<name> filehandle) are dynamically reset.
+
+This implies, among other things, that any magic eventually carried by
+those variables is locally lost. In other words, saying C<local */>
+will not have any effect on the internal value of the input record
+separator.
+
+Notably, if you want to work with a brand new value of the default scalar
+$_, and avoid the potential problem listed above about $_ previously
+carrying a magic value, you should use C<local *_> instead of C<local $_>.
+
+=head3 Localization of elements of composite types
It's also worth taking a moment to explain what happens when you
C<local>ize a member of a composite type (i.e. an array or hash element).
=head2 Declarations
-The only things you need to declare in Perl are report formats
-and subroutines--and even undefined subroutines can be handled
-through AUTOLOAD. A variable holds the undefined value (C<undef>)
-until it has been assigned a defined value, which is anything
-other than C<undef>. When used as a number, C<undef> is treated
-as C<0>; when used as a string, it is treated the empty string,
-C<"">; and when used as a reference that isn't being assigned
-to, it is treated as an error. If you enable warnings, you'll
-be notified of an uninitialized value whenever you treat C<undef>
-as a string or a number. Well, usually. Boolean contexts, such as:
+The only things you need to declare in Perl are report formats and
+subroutines (and sometimes not even subroutines). A variable holds
+the undefined value (C<undef>) until it has been assigned a defined
+value, which is anything other than C<undef>. When used as a number,
+C<undef> is treated as C<0>; when used as a string, it is treated as
+the empty string, C<"">; and when used as a reference that isn't being
+assigned to, it is treated as an error. If you enable warnings,
+you'll be notified of an uninitialized value whenever you treat
+C<undef> as a string or a number. Well, usually. Boolean contexts,
+such as:
my $a;
if ($a) {}
The number 0, the strings C<'0'> and C<''>, the empty list C<()>, and
C<undef> are all false in a boolean context. All other values are true.
-Note that while 0, 0.0 and C<'0'> are false, C<'0.0'> and C<'0e0'> are
-true, but evaluate to 0 in a numeric context.
+=head2 Statement Modifiers
Any simple statement may optionally be followed by a I<SINGLE> modifier,
just before the terminating semicolon (or block ending). The possible
unless EXPR
while EXPR
until EXPR
- foreach EXPR
-
-The C<if> and C<unless> modifiers have the expected semantics,
-presuming you're a speaker of English. The C<foreach> modifier is an
-iterator: For each value in EXPR, it aliases C<$_> to the value and
-executes the statement. The C<while> and C<until> modifiers have the
-usual "C<while> loop" semantics (conditional evaluated first), except
-when applied to a C<do>-BLOCK (or to the deprecated C<do>-SUBROUTINE
-statement), in which case the block executes once before the
-conditional is evaluated. This is so that you can write loops like:
+ foreach LIST
+
+The C<EXPR> following the modifier is referred to as the "condition".
+Its truth or falsehood determines how the modifier will behave.
+
+C<if> executes the statement once I<if> and only if the condition is
+true. C<unless> is the opposite, it executes the statement I<unless>
+the condition is true (i.e., if the condition is false).
+
+ print "Basset hounds got long ears" if length $ear >= 10;
+ go_outside() and play() unless $is_raining;
+
+The C<foreach> modifier is an iterator: it executes the statement once
+for each item in the LIST (with C<$_> aliased to each item in turn).
+
+ print "Hello $_!\n" foreach qw(world Dolly nurse);
+
+C<while> repeats the statement I<while> the condition is true.
+C<until> does the opposite, it repeats the statement I<until> the
+condition is true (or while the condition is false):
+
+ # Both of these count from 0 to 10.
+ print $i++ while $i <= 10;
+ print $j++ until $j > 10;
+
+The C<while> and C<until> modifiers have the usual "C<while> loop"
+semantics (conditional evaluated first), except when applied to a
+C<do>-BLOCK (or to the deprecated C<do>-SUBROUTINE statement), in
+which case the block executes once before the conditional is
+evaluated. This is so that you can write loops like:
do {
$line = <STDIN>;
Locales and Unicode interact with each other in unpleasant ways.
One possible solution would be to adopt/support ICU:
- http://oss.software.ibm.com/developerworks/opensource/icu/project/
+ http://oss.software.ibm.com/icu/index.html
=head2 Arithmetic on non-Arabic numerals
next unless /^=(?!cut)/ .. /^=cut/;
if (/=item (\S+)/ and $1 ne '*') {
+ my $item = $1;
s/=item //;
- #$cur = "POSIX::" . $1;
- $next{$cur} = $1;
- $cur = $1;
+ $next{$cur} = $item;
+ $cur = $item;
$syn{$cur} .= $_;
next;
} else {
- #s,L</,L<POSIX/,g;
s,L</,L<perlfunc/,g;
push @{$pod{$cur}}, $_ if $cur;
}
https://perl5.git.perl.org / perl5.git / commitdiff