diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/pods/perlsyn.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/pods/perlsyn.pod | 1213 |
1 files changed, 0 insertions, 1213 deletions
diff --git a/Master/tlpkg/tlperl/lib/pods/perlsyn.pod b/Master/tlpkg/tlperl/lib/pods/perlsyn.pod deleted file mode 100644 index 3bebeec7adb..00000000000 --- a/Master/tlpkg/tlperl/lib/pods/perlsyn.pod +++ /dev/null @@ -1,1213 +0,0 @@ -=head1 NAME -X<syntax> - -perlsyn - Perl syntax - -=head1 DESCRIPTION - -A Perl program consists of a sequence of declarations and statements -which run from the top to the bottom. Loops, subroutines, and other -control structures allow you to jump around within the code. - -Perl is a B<free-form> language: you can format and indent it however -you like. Whitespace serves mostly to separate tokens, unlike -languages like Python where it is an important part of the syntax, -or Fortran where it is immaterial. - -Many of Perl's syntactic elements are B<optional>. Rather than -requiring you to put parentheses around every function call and -declare every variable, you can often leave such explicit elements off -and Perl will figure out what you meant. This is known as B<Do What I -Mean>, abbreviated B<DWIM>. It allows programmers to be B<lazy> and to -code in a style with which they are comfortable. - -Perl B<borrows syntax> and concepts from many languages: awk, sed, C, -Bourne Shell, Smalltalk, Lisp and even English. Other -languages have borrowed syntax from Perl, particularly its regular -expression extensions. So if you have programmed in another language -you will see familiar pieces in Perl. They often work the same, but -see L<perltrap> for information about how they differ. - -=head2 Declarations -X<declaration> X<undef> X<undefined> X<uninitialized> - -The only things you need to declare in Perl are report formats and -subroutines (and sometimes not even subroutines). A scalar 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: - - if ($a) {} - -are exempt from warnings (because they care about truth rather than -definedness). Operators such as C<++>, C<-->, C<+=>, -C<-=>, and C<.=>, that operate on undefined variables such as: - - undef $a; - $a++; - -are also always exempt from such warnings. - -A declaration can be put anywhere a statement can, but has no effect on -the execution of the primary sequence of statements: declarations all -take effect at compile time. All declarations are typically put at -the beginning or the end of the script. However, if you're using -lexically-scoped private variables created with C<my()>, -C<state()>, or C<our()>, you'll have to make sure -your format or subroutine definition is within the same block scope -as the my if you expect to be able to access those private variables. - -Declaring a subroutine allows a subroutine name to be used as if it were a -list operator from that point forward in the program. You can declare a -subroutine without defining it by saying C<sub name>, thus: -X<subroutine, declaration> - - sub myname; - $me = myname $0 or die "can't get myname"; - -A bare declaration like that declares the function to be a list operator, -not a unary operator, so you have to be careful to use parentheses (or -C<or> instead of C<||>.) The C<||> operator binds too tightly to use after -list operators; it becomes part of the last element. You can always use -parentheses around the list operators arguments to turn the list operator -back into something that behaves more like a function call. Alternatively, -you can use the prototype C<($)> to turn the subroutine into a unary -operator: - - sub myname ($); - $me = myname $0 || die "can't get myname"; - -That now parses as you'd expect, but you still ought to get in the habit of -using parentheses in that situation. For more on prototypes, see -L<perlsub> - -Subroutines declarations can also be loaded up with the C<require> statement -or both loaded and imported into your namespace with a C<use> statement. -See L<perlmod> for details on this. - -A statement sequence may contain declarations of lexically-scoped -variables, but apart from declaring a variable name, the declaration acts -like an ordinary statement, and is elaborated within the sequence of -statements as if it were an ordinary statement. That means it actually -has both compile-time and run-time effects. - -=head2 Comments -X<comment> X<#> - -Text from a C<"#"> character until the end of the line is a comment, -and is ignored. Exceptions include C<"#"> inside a string or regular -expression. - -=head2 Simple Statements -X<statement> X<semicolon> X<expression> X<;> - -The only kind of simple statement is an expression evaluated for its -side-effects. Every simple statement must be terminated with a -semicolon, unless it is the final statement in a block, in which case -the semicolon is optional. But put the semicolon in anyway if the -block takes up more than one line, because you may eventually add -another line. Note that there are operators like C<eval {}>, C<sub {}>, and -C<do {}> that I<look> like compound statements, but aren't--they're just -TERMs in an expression--and thus need an explicit termination when used -as the last item in a statement. - -=head2 Truth and Falsehood -X<truth> X<falsehood> X<true> X<false> X<!> X<not> X<negation> X<0> - -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. -Negation of a true value by C<!> or C<not> returns a special false value. -When evaluated as a string it is treated as C<"">, but as a number, it -is treated as 0. Most Perl operators -that return true or false behave this way. - -=head2 Statement Modifiers -X<statement modifier> X<modifier> X<if> X<unless> X<while> -X<until> X<when> X<foreach> X<for> - -Any simple statement may optionally be followed by a I<SINGLE> modifier, -just before the terminating semicolon (or block ending). The possible -modifiers are: - - if EXPR - unless EXPR - while EXPR - until EXPR - for LIST - foreach LIST - when EXPR - -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 (that is, if the condition is false). - - print "Basset hounds got long ears" if length $ear >= 10; - go_outside() and play() unless $is_raining; - -The C<for(each)> 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" for 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 Perl4 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>; - ... - } until !defined($line) || $line eq ".\n" - -See L<perlfunc/do>. Note also that the loop control statements described -later will I<NOT> work in this construct, because modifiers don't take -loop labels. Sorry. You can always put another block inside of it -(for C<next>) or around it (for C<last>) to do that sort of thing. -For C<next>, just double the braces: -X<next> X<last> X<redo> - - do {{ - next if $x == $y; - # do something here - }} until $x++ > $z; - -For C<last>, you have to be more elaborate: -X<last> - - LOOP: { - do { - last if $x = $y**2; - # do something here - } while $x++ <= $z; - } - -B<NOTE:> The behaviour of a C<my>, C<state>, or -C<our> modified with a statement modifier conditional -or loop construct (for example, C<my $x if ...>) is -B<undefined>. The value of the C<my> variable may be C<undef>, any -previously assigned value, or possibly anything else. Don't rely on -it. Future versions of perl might do something different from the -version of perl you try it out on. Here be dragons. -X<my> - -The C<when> modifier is an experimental feature that first appeared in Perl -5.14. To use it, you should include a C<use v5.14> declaration. -(Technically, it requires only the C<switch> feature, but that aspect of it -was not available before 5.14.) Operative only from within a C<foreach> -loop or a C<given> block, it executes the statement only if the smartmatch -C<< $_ ~~ I<EXPR> >> is true. If the statement executes, it is followed by -a C<next> from inside a C<foreach> and C<break> from inside a C<given>. - -Under the current implementation, the C<foreach> loop can be -anywhere within the C<when> modifier's dynamic scope, but must be -within the C<given> block's lexical scope. This restricted may -be relaxed in a future release. See L<"Switch Statements"> below. - -=head2 Compound Statements -X<statement, compound> X<block> X<bracket, curly> X<curly bracket> X<brace> -X<{> X<}> X<if> X<unless> X<given> X<while> X<until> X<foreach> X<for> X<continue> - -In Perl, a sequence of statements that defines a scope is called a block. -Sometimes a block is delimited by the file containing it (in the case -of a required file, or the program as a whole), and sometimes a block -is delimited by the extent of a string (in the case of an eval). - -But generally, a block is delimited by curly brackets, also known as braces. -We will call this syntactic construct a BLOCK. - -The following compound statements may be used to control flow: - - if (EXPR) BLOCK - if (EXPR) BLOCK else BLOCK - if (EXPR) BLOCK elsif (EXPR) BLOCK ... - if (EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK - - unless (EXPR) BLOCK - unless (EXPR) BLOCK else BLOCK - unless (EXPR) BLOCK elsif (EXPR) BLOCK ... - unless (EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK - - given (EXPR) BLOCK - - LABEL while (EXPR) BLOCK - LABEL while (EXPR) BLOCK continue BLOCK - - LABEL until (EXPR) BLOCK - LABEL until (EXPR) BLOCK continue BLOCK - - LABEL for (EXPR; EXPR; EXPR) BLOCK - LABEL for VAR (LIST) BLOCK - LABEL for VAR (LIST) BLOCK continue BLOCK - - LABEL foreach (EXPR; EXPR; EXPR) BLOCK - LABEL foreach VAR (LIST) BLOCK - LABEL foreach VAR (LIST) BLOCK continue BLOCK - - LABEL BLOCK - LABEL BLOCK continue BLOCK - - PHASE BLOCK - -The experimental C<given> statement is I<not automatically enabled>; see -L</"Switch Statements"> below for how to do so, and the attendant caveats. - -Unlike in C and Pascal, in Perl these are all defined in terms of BLOCKs, -not statements. This means that the curly brackets are I<required>--no -dangling statements allowed. If you want to write conditionals without -curly brackets, there are several other ways to do it. The following -all do the same thing: - - if (!open(FOO)) { die "Can't open $FOO: $!" } - die "Can't open $FOO: $!" unless open(FOO); - open(FOO) || die "Can't open $FOO: $!"; - open(FOO) ? () : die "Can't open $FOO: $!"; - # a bit exotic, that last one - -The C<if> statement is straightforward. Because BLOCKs are always -bounded by curly brackets, there is never any ambiguity about which -C<if> an C<else> goes with. If you use C<unless> in place of C<if>, -the sense of the test is reversed. Like C<if>, C<unless> can be followed -by C<else>. C<unless> can even be followed by one or more C<elsif> -statements, though you may want to think twice before using that particular -language construct, as everyone reading your code will have to think at least -twice before they can understand what's going on. - -The C<while> statement executes the block as long as the expression is -L<true|/"Truth and Falsehood">. -The C<until> statement executes the block as long as the expression is -false. -The LABEL is optional, and if present, consists of an identifier followed -by a colon. The LABEL identifies the loop for the loop control -statements C<next>, C<last>, and C<redo>. -If the LABEL is omitted, the loop control statement -refers to the innermost enclosing loop. This may include dynamically -looking back your call-stack at run time to find the LABEL. Such -desperate behavior triggers a warning if you use the C<use warnings> -pragma or the B<-w> flag. - -If there is a C<continue> BLOCK, it is always executed just before the -conditional is about to be evaluated again. Thus it can be used to -increment a loop variable, even when the loop has been continued via -the C<next> statement. - -When a block is preceding by a compilation phase keyword such as C<BEGIN>, -C<END>, C<INIT>, C<CHECK>, or C<UNITCHECK>, then the block will run only -during the corresponding phase of execution. See L<perlmod> for more details. - -Extension modules can also hook into the Perl parser to define new -kinds of compound statements. These are introduced by a keyword which -the extension recognizes, and the syntax following the keyword is -defined entirely by the extension. If you are an implementor, see -L<perlapi/PL_keyword_plugin> for the mechanism. If you are using such -a module, see the module's documentation for details of the syntax that -it defines. - -=head2 Loop Control -X<loop control> X<loop, control> X<next> X<last> X<redo> X<continue> - -The C<next> command starts the next iteration of the loop: - - LINE: while (<STDIN>) { - next LINE if /^#/; # discard comments - ... - } - -The C<last> command immediately exits the loop in question. The -C<continue> block, if any, is not executed: - - LINE: while (<STDIN>) { - last LINE if /^$/; # exit when done with header - ... - } - -The C<redo> command restarts the loop block without evaluating the -conditional again. The C<continue> block, if any, is I<not> executed. -This command is normally used by programs that want to lie to themselves -about what was just input. - -For example, when processing a file like F</etc/termcap>. -If your input lines might end in backslashes to indicate continuation, you -want to skip ahead and get the next record. - - while (<>) { - chomp; - if (s/\\$//) { - $_ .= <>; - redo unless eof(); - } - # now process $_ - } - -which is Perl shorthand for the more explicitly written version: - - LINE: while (defined($line = <ARGV>)) { - chomp($line); - if ($line =~ s/\\$//) { - $line .= <ARGV>; - redo LINE unless eof(); # not eof(ARGV)! - } - # now process $line - } - -Note that if there were a C<continue> block on the above code, it would -get executed only on lines discarded by the regex (since redo skips the -continue block). A continue block is often used to reset line counters -or C<m?pat?> one-time matches: - - # inspired by :1,$g/fred/s//WILMA/ - while (<>) { - m?(fred)? && s//WILMA $1 WILMA/; - m?(barney)? && s//BETTY $1 BETTY/; - m?(homer)? && s//MARGE $1 MARGE/; - } continue { - print "$ARGV $.: $_"; - close ARGV if eof; # reset $. - reset if eof; # reset ?pat? - } - -If the word C<while> is replaced by the word C<until>, the sense of the -test is reversed, but the conditional is still tested before the first -iteration. - -Loop control statements don't work in an C<if> or C<unless>, since -they aren't loops. You can double the braces to make them such, though. - - if (/pattern/) {{ - last if /fred/; - next if /barney/; # same effect as "last", - # but doesn't document as well - # do something here - }} - -This is caused by the fact that a block by itself acts as a loop that -executes once, see L<"Basic BLOCKs">. - -The form C<while/if BLOCK BLOCK>, available in Perl 4, is no longer -available. Replace any occurrence of C<if BLOCK> by C<if (do BLOCK)>. - -=head2 For Loops -X<for> X<foreach> - -Perl's C-style C<for> loop works like the corresponding C<while> loop; -that means that this: - - for ($i = 1; $i < 10; $i++) { - ... - } - -is the same as this: - - $i = 1; - while ($i < 10) { - ... - } continue { - $i++; - } - -There is one minor difference: if variables are declared with C<my> -in the initialization section of the C<for>, the lexical scope of -those variables is exactly the C<for> loop (the body of the loop -and the control sections). -X<my> - -Besides the normal array index looping, C<for> can lend itself -to many other interesting applications. Here's one that avoids the -problem you get into if you explicitly test for end-of-file on -an interactive file descriptor causing your program to appear to -hang. -X<eof> X<end-of-file> X<end of file> - - $on_a_tty = -t STDIN && -t STDOUT; - sub prompt { print "yes? " if $on_a_tty } - for ( prompt(); <STDIN>; prompt() ) { - # do something - } - -Using C<readline> (or the operator form, C<< <EXPR> >>) as the -conditional of a C<for> loop is shorthand for the following. This -behaviour is the same as a C<while> loop conditional. -X<readline> X<< <> >> - - for ( prompt(); defined( $_ = <STDIN> ); prompt() ) { - # do something - } - -=head2 Foreach Loops -X<for> X<foreach> - -The C<foreach> loop iterates over a normal list value and sets the -variable VAR to be each element of the list in turn. If the variable -is preceded with the keyword C<my>, then it is lexically scoped, and -is therefore visible only within the loop. Otherwise, the variable is -implicitly local to the loop and regains its former value upon exiting -the loop. If the variable was previously declared with C<my>, it uses -that variable instead of the global one, but it's still localized to -the loop. This implicit localization occurs I<only> in a C<foreach> -loop. -X<my> X<local> - -The C<foreach> keyword is actually a synonym for the C<for> keyword, so -you can use either. If VAR is omitted, C<$_> is set to each value. -X<$_> - -If any element of LIST is an lvalue, you can modify it by modifying -VAR inside the loop. Conversely, if any element of LIST is NOT an -lvalue, any attempt to modify that element will fail. In other words, -the C<foreach> loop index variable is an implicit alias for each item -in the list that you're looping over. -X<alias> - -If any part of LIST is an array, C<foreach> will get very confused if -you add or remove elements within the loop body, for example with -C<splice>. So don't do that. -X<splice> - -C<foreach> probably won't do what you expect if VAR is a tied or other -special variable. Don't do that either. - -Examples: - - for (@ary) { s/foo/bar/ } - - for my $elem (@elements) { - $elem *= 2; - } - - for $count (reverse(1..10), "BOOM") { - print $count, "\n"; - sleep(1); - } - - for (1..15) { print "Merry Christmas\n"; } - - foreach $item (split(/:[\\\n:]*/, $ENV{TERMCAP})) { - print "Item: $item\n"; - } - -Here's how a C programmer might code up a particular algorithm in Perl: - - for (my $i = 0; $i < @ary1; $i++) { - for (my $j = 0; $j < @ary2; $j++) { - if ($ary1[$i] > $ary2[$j]) { - last; # can't go to outer :-( - } - $ary1[$i] += $ary2[$j]; - } - # this is where that last takes me - } - -Whereas here's how a Perl programmer more comfortable with the idiom might -do it: - - OUTER: for my $wid (@ary1) { - INNER: for my $jet (@ary2) { - next OUTER if $wid > $jet; - $wid += $jet; - } - } - -See how much easier this is? It's cleaner, safer, and faster. It's -cleaner because it's less noisy. It's safer because if code gets added -between the inner and outer loops later on, the new code won't be -accidentally executed. The C<next> explicitly iterates the other loop -rather than merely terminating the inner one. And it's faster because -Perl executes a C<foreach> statement more rapidly than it would the -equivalent C<for> loop. - -=head2 Basic BLOCKs -X<block> - -A BLOCK by itself (labeled or not) is semantically equivalent to a -loop that executes once. Thus you can use any of the loop control -statements in it to leave or restart the block. (Note that this is -I<NOT> true in C<eval{}>, C<sub{}>, or contrary to popular belief -C<do{}> blocks, which do I<NOT> count as loops.) The C<continue> -block is optional. - -The BLOCK construct can be used to emulate case structures. - - SWITCH: { - if (/^abc/) { $abc = 1; last SWITCH; } - if (/^def/) { $def = 1; last SWITCH; } - if (/^xyz/) { $xyz = 1; last SWITCH; } - $nothing = 1; - } - -You'll also find that C<foreach> loop used to create a topicalizer -and a switch: - - SWITCH: - for ($var) { - if (/^abc/) { $abc = 1; last SWITCH; } - if (/^def/) { $def = 1; last SWITCH; } - if (/^xyz/) { $xyz = 1; last SWITCH; } - $nothing = 1; - } - -Such constructs are quite frequently used, both because older versions of -Perl had no official C<switch> statement, and also because the new version -described immediately below remains experimental and can sometimes be confusing. - -=head2 Switch Statements - -X<switch> X<case> X<given> X<when> X<default> - -Starting from Perl 5.10.1 (well, 5.10.0, but it didn't work -right), you can say - - use feature "switch"; - -to enable an experimental switch feature. This is loosely based on an -old version of a Perl 6 proposal, but it no longer resembles the Perl 6 -construct. You also get the switch feature whenever you declare that your -code prefers to run under a version of Perl that is 5.10 or later. For -example: - - use v5.14; - -Under the "switch" feature, Perl gains the experimental keywords -C<given>, C<when>, C<default>, C<continue>, and C<break>. -Starting from Perl 5.16, one can prefix the switch -keywords with C<CORE::> to access the feature without a C<use feature> -statement. The keywords C<given> and -C<when> are analogous to C<switch> and -C<case> in other languages, so the code in the previous section could be -rewritten as - - use v5.10.1; - for ($var) { - when (/^abc/) { $abc = 1 } - when (/^def/) { $def = 1 } - when (/^xyz/) { $xyz = 1 } - default { $nothing = 1 } - } - -The C<foreach> is the non-experimental way to set a topicalizer. -If you wish to use the highly experimental C<given>, that could be -written like this: - - use v5.10.1; - given ($var) { - when (/^abc/) { $abc = 1 } - when (/^def/) { $def = 1 } - when (/^xyz/) { $xyz = 1 } - default { $nothing = 1 } - } - -As of 5.14, that can also be written this way: - - use v5.14; - for ($var) { - $abc = 1 when /^abc/; - $def = 1 when /^def/; - $xyz = 1 when /^xyz/; - default { $nothing = 1 } - } - -Or if you don't care to play it safe, like this: - - use v5.14; - given ($var) { - $abc = 1 when /^abc/; - $def = 1 when /^def/; - $xyz = 1 when /^xyz/; - default { $nothing = 1 } - } - -The arguments to C<given> and C<when> are in scalar context, -and C<given> assigns the C<$_> variable its topic value. - -Exactly what the I<EXPR> argument to C<when> does is hard to describe -precisely, but in general, it tries to guess what you want done. Sometimes -it is interpreted as C<< $_ ~~ I<EXPR> >>, and sometimes it does not. It -also behaves differently when lexically enclosed by a C<given> block than -it does when dynamically enclosed by a C<foreach> loop. The rules are far -too difficult to understand to be described here. See L</"Experimental Details -on given and when"> later on. - -Due to an unfortunate bug in how C<given> was implemented between Perl 5.10 -and 5.14, under those implementations the version of C<$_> governed by -C<given> is merely a lexically scoped copy of the original, not a -dynamically scoped alias to the original, as it would be if it were a -C<foreach> or under both the original and the current Perl 6 language -specification. This bug is expected to be addressed in a future release of -Perl. For forwards compatibility, if you really want a lexical C<$_>, -specify that explicitly: - - given(my $_ = EXPR) { ... } - -In the meanwhile, stick to C<foreach> for your topicalizer and -you will be less unhappy. - -=head2 Goto -X<goto> - -Although not for the faint of heart, Perl does support a C<goto> -statement. There are three forms: C<goto>-LABEL, C<goto>-EXPR, and -C<goto>-&NAME. A loop's LABEL is not actually a valid target for -a C<goto>; it's just the name of the loop. - -The C<goto>-LABEL form finds the statement labeled with LABEL and resumes -execution there. It may not be used to go into any construct that -requires initialization, such as a subroutine or a C<foreach> loop. It -also can't be used to go into a construct that is optimized away. It -can be used to go almost anywhere else within the dynamic scope, -including out of subroutines, but it's usually better to use some other -construct such as C<last> or C<die>. The author of Perl has never felt the -need to use this form of C<goto> (in Perl, that is--C is another matter). - -The C<goto>-EXPR form expects a label name, whose scope will be resolved -dynamically. This allows for computed C<goto>s per FORTRAN, but isn't -necessarily recommended if you're optimizing for maintainability: - - goto(("FOO", "BAR", "GLARCH")[$i]); - -The C<goto>-&NAME form is highly magical, and substitutes a call to the -named subroutine for the currently running subroutine. This is used by -C<AUTOLOAD()> subroutines that wish to load another subroutine and then -pretend that the other subroutine had been called in the first place -(except that any modifications to C<@_> in the current subroutine are -propagated to the other subroutine.) After the C<goto>, not even C<caller()> -will be able to tell that this routine was called first. - -In almost all cases like this, it's usually a far, far better idea to use the -structured control flow mechanisms of C<next>, C<last>, or C<redo> instead of -resorting to a C<goto>. For certain applications, the catch and throw pair of -C<eval{}> and die() for exception processing can also be a prudent approach. - -=head2 The Ellipsis Statement -X<...> -X<... statement> -X<ellipsis operator> -X<elliptical statement> -X<unimplemented statement> -X<unimplemented operator> -X<yada-yada> -X<yada-yada operator> -X<... operator> -X<whatever operator> -X<triple-dot operator> - -Beginning in Perl 5.12, Perl accepts an ellipsis, "C<...>", as a -placeholder for code that you haven't implemented yet. This form of -ellipsis, the unimplemented statement, should not be confused with the -binary flip-flop C<...> operator. One is a statement and the other an -operator. (Perl doesn't usually confuse them because usually Perl can tell -whether it wants an operator or a statement, but see below for exceptions.) - -When Perl 5.12 or later encounters an ellipsis statement, it parses this -without error, but if and when you should actually try to execute it, Perl -throws an exception with the text C<Unimplemented>: - - use v5.12; - sub unimplemented { ... } - eval { unimplemented() }; - if ($@ =~ /^Unimplemented at /) { - say "I found an ellipsis!"; - } - -You can only use the elliptical statement to stand in for a -complete statement. These examples of how the ellipsis works: - - use v5.12; - { ... } - sub foo { ... } - ...; - eval { ... }; - sub somemeth { - my $self = shift; - ...; - } - $x = do { - my $n; - ...; - say "Hurrah!"; - $n; - }; - -The elliptical statement cannot stand in for an expression that -is part of a larger statement, since the C<...> is also the three-dot -version of the flip-flop operator (see L<perlop/"Range Operators">). - -These examples of attempts to use an ellipsis are syntax errors: - - use v5.12; - - print ...; - open(my $fh, ">", "/dev/passwd") or ...; - if ($condition && ... ) { say "Howdy" }; - -There are some cases where Perl can't immediately tell the difference -between an expression and a statement. For instance, the syntax for a -block and an anonymous hash reference constructor look the same unless -there's something in the braces to give Perl a hint. The ellipsis is a -syntax error if Perl doesn't guess that the C<{ ... }> is a block. In that -case, it doesn't think the C<...> is an ellipsis because it's expecting an -expression instead of a statement: - - @transformed = map { ... } @input; # syntax error - -You can use a C<;> inside your block to denote that the C<{ ... }> is a -block and not a hash reference constructor. Now the ellipsis works: - - @transformed = map {; ... } @input; # ; disambiguates - - @transformed = map { ...; } @input; # ; disambiguates - -Note: Some folks colloquially refer to this bit of punctuation as a -"yada-yada" or "triple-dot", but its true name -is actually an ellipsis. Perl does not yet -accept the Unicode version, U+2026 HORIZONTAL ELLIPSIS, as an alias for -C<...>, but someday it may. - -=head2 PODs: Embedded Documentation -X<POD> X<documentation> - -Perl has a mechanism for intermixing documentation with source code. -While it's expecting the beginning of a new statement, if the compiler -encounters a line that begins with an equal sign and a word, like this - - =head1 Here There Be Pods! - -Then that text and all remaining text up through and including a line -beginning with C<=cut> will be ignored. The format of the intervening -text is described in L<perlpod>. - -This allows you to intermix your source code -and your documentation text freely, as in - - =item snazzle($) - - The snazzle() function will behave in the most spectacular - form that you can possibly imagine, not even excepting - cybernetic pyrotechnics. - - =cut back to the compiler, nuff of this pod stuff! - - sub snazzle($) { - my $thingie = shift; - ......... - } - -Note that pod translators should look at only paragraphs beginning -with a pod directive (it makes parsing easier), whereas the compiler -actually knows to look for pod escapes even in the middle of a -paragraph. This means that the following secret stuff will be -ignored by both the compiler and the translators. - - $a=3; - =secret stuff - warn "Neither POD nor CODE!?" - =cut back - print "got $a\n"; - -You probably shouldn't rely upon the C<warn()> being podded out forever. -Not all pod translators are well-behaved in this regard, and perhaps -the compiler will become pickier. - -One may also use pod directives to quickly comment out a section -of code. - -=head2 Plain Old Comments (Not!) -X<comment> X<line> X<#> X<preprocessor> X<eval> - -Perl can process line directives, much like the C preprocessor. Using -this, one can control Perl's idea of filenames and line numbers in -error or warning messages (especially for strings that are processed -with C<eval()>). The syntax for this mechanism is almost the same as for -most C preprocessors: it matches the regular expression - - # example: '# line 42 "new_filename.plx"' - /^\# \s* - line \s+ (\d+) \s* - (?:\s("?)([^"]+)\g2)? \s* - $/x - -with C<$1> being the line number for the next line, and C<$3> being -the optional filename (specified with or without quotes). Note that -no whitespace may precede the C<< # >>, unlike modern C preprocessors. - -There is a fairly obvious gotcha included with the line directive: -Debuggers and profilers will only show the last source line to appear -at a particular line number in a given file. Care should be taken not -to cause line number collisions in code you'd like to debug later. - -Here are some examples that you should be able to type into your command -shell: - - % perl - # line 200 "bzzzt" - # the '#' on the previous line must be the first char on line - die 'foo'; - __END__ - foo at bzzzt line 201. - - % perl - # line 200 "bzzzt" - eval qq[\n#line 2001 ""\ndie 'foo']; print $@; - __END__ - foo at - line 2001. - - % perl - eval qq[\n#line 200 "foo bar"\ndie 'foo']; print $@; - __END__ - foo at foo bar line 200. - - % perl - # line 345 "goop" - eval "\n#line " . __LINE__ . ' "' . __FILE__ ."\"\ndie 'foo'"; - print $@; - __END__ - foo at goop line 345. - -=head2 Experimental Details on given and when - -As previously mentioned, the "switch" feature is considered highly -experimental; it is subject to change with little notice. In particular, -both C<given> and C<when> have tricky behaviours that are expected to -change to become less tricky in the future. Do not rely upon their -current (mis)implementations. - -Here is a longer example of C<given>: - - use feature ":5.10"; - given ($foo) { - when (undef) { - say '$foo is undefined'; - } - when ("foo") { - say '$foo is the string "foo"'; - } - when ([1,3,5,7,9]) { - say '$foo is an odd digit'; - continue; # Fall through - } - when ($_ < 100) { - say '$foo is numerically less than 100'; - } - when (\&complicated_check) { - say 'a complicated check for $foo is true'; - } - default { - die q(I don't know what to do with $foo); - } - } - -As currently implemented, C<given(EXPR)> assign the value of I<EXPR> to -merely a lexically scoped I<B<copy>> (!) of C<$_>, not a dynamically -scoped alias the way C<foreach> does. That makes it similar to - - do { my $_ = EXPR; ... } - -except that the block is automatically broken out of by a -successful C<when> or an explicit C<break>. Because it is only a -copy, and because it is only lexically scoped, not dynamically -scoped, you cannot do the things with it that you are used to in -a C<foreach> loop. In particular, you probably cannot use -arbitrary function calls. Best stick to C<foreach> for that. - -Most of the power comes from the implicit smartmatching that can -sometimes apply. Most of the time, C<when(EXPR)> is treated as an -implicit smartmatch of C<$_>, that is, C<$_ ~~ EXPR>. (See -L<perlop/"Smartmatch Operator"> for more information on smartmatching.) -But when I<EXPR> is one of the 10 exceptional cases (or things like them) -listed below, it is used directly as a boolean. - -=over 4 - -=item 1. - -A user-defined subroutine call or a method invocation. - -=item 2. - -A regular expression match in the form of C</REGEX/>, C<$foo =~ /REGEX/>, -or C<$foo =~ EXPR>. Also, a negated regular expression match in -the form C<!/REGEX/>, C<$foo !~ /REGEX/>, or C<$foo !~ EXPR>. - -=item 3. - -A smart match that uses an explicit C<~~> operator, such as C<EXPR ~~ EXPR>. - -=item 4. - -A boolean comparison operator such as C<$_ E<lt> 10> or C<$x eq "abc"> The -relational operators that this applies to are the six numeric comparisons -(C<< < >>, C<< > >>, C<< <= >>, C<< >= >>, C<< == >>, and C<< != >>), and -the six string comparisons (C<lt>, C<gt>, C<le>, C<ge>, C<eq>, and C<ne>). - -B<NOTE:> You will often have to use C<$c ~~ $_> because -the default case uses C<$_ ~~ $c> , which is frequently -the opposite of what you want. - -=item 5. - -At least the three builtin functions C<defined(...)>, C<exists(...)>, and -C<eof(...)>. We might someday add more of these later if we think of them. - -=item 6. - -A negated expression, whether C<!(EXPR)> or C<not(EXPR)>, or a logical -exclusive-or, C<(EXPR1) xor (EXPR2)>. The bitwise versions (C<~> and C<^>) -are not included. - -=item 7. - -A filetest operator, with exactly 4 exceptions: C<-s>, C<-M>, C<-A>, and -C<-C>, as these return numerical values, not boolean ones. The C<-z> -filetest operator is not included in the exception list. - -=item 8. - -The C<..> and C<...> flip-flop operators. Note that the C<...> flip-flop -operator is completely different from the C<...> elliptical statement -just described. - -=back - -In those 8 cases above, the value of EXPR is used directly as a boolean, so -no smartmatching is done. You may think of C<when> as a smartsmartmatch. - -Furthermore, Perl inspects the operands of logical operators to -decide whether to use smartmatching for each one by applying the -above test to the operands: - -=over 4 - -=item 9. - -If EXPR is C<EXPR1 && EXPR2> or C<EXPR1 and EXPR2>, the test is applied -I<recursively> to both EXPR1 and EXPR2. -Only if I<both> operands also pass the -test, I<recursively>, will the expression be treated as boolean. Otherwise, -smartmatching is used. - -=item 10. - -If EXPR is C<EXPR1 || EXPR2>, C<EXPR1 // EXPR2>, or C<EXPR1 or EXPR2>, the -test is applied I<recursively> to EXPR1 only (which might itself be a -higher-precedence AND operator, for example, and thus subject to the -previous rule), not to EXPR2. If EXPR1 is to use smartmatching, then EXPR2 -also does so, no matter what EXPR2 contains. But if EXPR2 does not get to -use smartmatching, then the second argument will not be either. This is -quite different from the C<&&> case just described, so be careful. - -=back - -These rules are complicated, but the goal is for them to do what you want -(even if you don't quite understand why they are doing it). For example: - - when (/^\d+$/ && $_ < 75) { ... } - -will be treated as a boolean match because the rules say both -a regex match and an explicit test on C<$_> will be treated -as boolean. - -Also: - - when ([qw(foo bar)] && /baz/) { ... } - -will use smartmatching because only I<one> of the operands is a boolean: -the other uses smartmatching, and that wins. - -Further: - - when ([qw(foo bar)] || /^baz/) { ... } - -will use smart matching (only the first operand is considered), whereas - - when (/^baz/ || [qw(foo bar)]) { ... } - -will test only the regex, which causes both operands to be -treated as boolean. Watch out for this one, then, because an -arrayref is always a true value, which makes it effectively -redundant. Not a good idea. - -Tautologous boolean operators are still going to be optimized -away. Don't be tempted to write - - when ("foo" or "bar") { ... } - -This will optimize down to C<"foo">, so C<"bar"> will never be considered (even -though the rules say to use a smartmatch -on C<"foo">). For an alternation like -this, an array ref will work, because this will instigate smartmatching: - - when ([qw(foo bar)] { ... } - -This is somewhat equivalent to the C-style switch statement's fallthrough -functionality (not to be confused with I<Perl's> fallthrough -functionality--see below), wherein the same block is used for several -C<case> statements. - -Another useful shortcut is that, if you use a literal array or hash as the -argument to C<given>, it is turned into a reference. So C<given(@foo)> is -the same as C<given(\@foo)>, for example. - -C<default> behaves exactly like C<when(1 == 1)>, which is -to say that it always matches. - -=head3 Breaking out - -You can use the C<break> keyword to break out of the enclosing -C<given> block. Every C<when> block is implicitly ended with -a C<break>. - -=head3 Fall-through - -You can use the C<continue> keyword to fall through from one -case to the next: - - given($foo) { - when (/x/) { say '$foo contains an x'; continue } - when (/y/) { say '$foo contains a y' } - default { say '$foo does not contain a y' } - } - -=head3 Return value - -When a C<given> statement is also a valid expression (for example, -when it's the last statement of a block), it evaluates to: - -=over 4 - -=item * - -An empty list as soon as an explicit C<break> is encountered. - -=item * - -The value of the last evaluated expression of the successful -C<when>/C<default> clause, if there happens to be one. - -=item * - -The value of the last evaluated expression of the C<given> block if no -condition is true. - -=back - -In both last cases, the last expression is evaluated in the context that -was applied to the C<given> block. - -Note that, unlike C<if> and C<unless>, failed C<when> statements always -evaluate to an empty list. - - my $price = do { - given ($item) { - when (["pear", "apple"]) { 1 } - break when "vote"; # My vote cannot be bought - 1e10 when /Mona Lisa/; - "unknown"; - } - }; - -Currently, C<given> blocks can't always -be used as proper expressions. This -may be addressed in a future version of Perl. - -=head3 Switching in a loop - -Instead of using C<given()>, you can use a C<foreach()> loop. -For example, here's one way to count how many times a particular -string occurs in an array: - - use v5.10.1; - my $count = 0; - for (@array) { - when ("foo") { ++$count } - } - print "\@array contains $count copies of 'foo'\n"; - -Or in a more recent version: - - use v5.14; - my $count = 0; - for (@array) { - ++$count when "foo"; - } - print "\@array contains $count copies of 'foo'\n"; - -At the end of all C<when> blocks, there is an implicit C<next>. -You can override that with an explicit C<last> if you're -interested in only the first match alone. - -This doesn't work if you explicitly specify a loop variable, as -in C<for $item (@array)>. You have to use the default variable C<$_>. - -=head3 Differences from Perl 6 - -The Perl 5 smartmatch and C<given>/C<when> constructs are not compatible -with their Perl 6 analogues. The most visible difference and least -important difference is that, in Perl 5, parentheses are required around -the argument to C<given()> and C<when()> (except when this last one is used -as a statement modifier). Parentheses in Perl 6 are always optional in a -control construct such as C<if()>, C<while()>, or C<when()>; they can't be -made optional in Perl 5 without a great deal of potential confusion, -because Perl 5 would parse the expression - - given $foo { - ... - } - -as though the argument to C<given> were an element of the hash -C<%foo>, interpreting the braces as hash-element syntax. - -However, their are many, many other differences. For example, -this works in Perl 5: - - use v5.12; - my @primary = ("red", "blue", "green"); - - if (@primary ~~ "red") { - say "primary smartmatches red"; - } - - if ("red" ~~ @primary) { - say "red smartmatches primary"; - } - - say "that's all, folks!"; - -But it doesn't work at all in Perl 6. Instead, you should -use the (parallelizable) C<any> operator instead: - - if any(@primary) eq "red" { - say "primary smartmatches red"; - } - - if "red" eq any(@primary) { - say "red smartmatches primary"; - } - -The table of smartmatches in L<perlop/"Smartmatch Operator"> is not -identical to that proposed by the Perl 6 specification, mainly due to -differences between Perl 6's and Perl 5's data models, but also because -the Perl 6 spec has changed since Perl 5 rushed into early adoption. - -In Perl 6, C<when()> will always do an implicit smartmatch with its -argument, while in Perl 5 it is convenient (albeit potentially confusing) to -suppress this implicit smartmatch in various rather loosely-defined -situations, as roughly outlined above. (The difference is largely because -Perl 5 does not have, even internally, a boolean type.) - -=cut |