This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perl 3.0 patch #1 (combined patch)
[perl5.git] / perl.man.4
1 ''' Beginning of part 4
2 ''' $Header: perl.man.4,v 3.0.1.1 89/10/26 23:18:43 lwall Locked $
3 '''
4 ''' $Log:       perl.man.4,v $
5 ''' Revision 3.0.1.1  89/10/26  23:18:43  lwall
6 ''' patch1: documented the desirability of unnecessary parentheses
7 ''' 
8 ''' Revision 3.0  89/10/18  15:21:55  lwall
9 ''' 3.0 baseline
10 ''' 
11 .Sh "Precedence"
12 .I Perl
13 operators have the following associativity and precedence:
14 .nf
15
16 nonassoc\h'|1i'print printf exec system sort reverse
17 \h'1.5i'chmod chown kill unlink utime die return
18 left\h'|1i',
19 right\h'|1i'= += \-= *= etc.
20 right\h'|1i'?:
21 nonassoc\h'|1i'.\|.
22 left\h'|1i'||
23 left\h'|1i'&&
24 left\h'|1i'| ^
25 left\h'|1i'&
26 nonassoc\h'|1i'== != eq ne
27 nonassoc\h'|1i'< > <= >= lt gt le ge
28 nonassoc\h'|1i'chdir exit eval reset sleep rand umask
29 nonassoc\h'|1i'\-r \-w \-x etc.
30 left\h'|1i'<< >>
31 left\h'|1i'+ \- .
32 left\h'|1i'* / % x
33 left\h'|1i'=~ !~ 
34 right\h'|1i'! ~ and unary minus
35 right\h'|1i'**
36 nonassoc\h'|1i'++ \-\|\-
37 left\h'|1i'\*(L'(\*(R'
38
39 .fi
40 As mentioned earlier, if any list operator (print, etc.) or
41 any unary operator (chdir, etc.)
42 is followed by a left parenthesis as the next token on the same line,
43 the operator and arguments within parentheses are taken to
44 be of highest precedence, just like a normal function call.
45 Examples:
46 .nf
47
48         chdir $foo || die;      # (chdir $foo) || die
49         chdir($foo) || die;     # (chdir $foo) || die
50         chdir ($foo) || die;    # (chdir $foo) || die
51         chdir +($foo) || die;   # (chdir $foo) || die
52
53 but, because * is higher precedence than ||:
54
55         chdir $foo * 20;        # chdir ($foo * 20)
56         chdir($foo) * 20;       # (chdir $foo) * 20
57         chdir ($foo) * 20;      # (chdir $foo) * 20
58         chdir +($foo) * 20;     # chdir ($foo * 20)
59
60         rand 10 * 20;           # rand (10 * 20)
61         rand(10) * 20;          # (rand 10) * 20
62         rand (10) * 20;         # (rand 10) * 20
63         rand +(10) * 20;        # rand (10 * 20)
64
65 .fi
66 In the absence of parentheses,
67 the precedence of list operators such as print, sort or chmod is
68 either very high or very low depending on whether you look at the left
69 side of operator or the right side of it.
70 For example, in
71 .nf
72
73         @ary = (1, 3, sort 4, 2);
74         print @ary;             # prints 1324
75
76 .fi
77 the commas on the right of the sort are evaluated before the sort, but
78 the commas on the left are evaluated after.
79 In other words, list operators tend to gobble up all the arguments that
80 follow them, and then act like a simple term with regard to the preceding
81 expression.
82 Note that you have to be careful with parens:
83 .nf
84
85 .ne 3
86         # These evaluate exit before doing the print:
87         print($foo, exit);      # Obviously not what you want.
88         print $foo, exit;       # Nor is this.
89
90 .ne 4
91         # These do the print before evaluating exit:
92         (print $foo), exit;     # This is what you want.
93         print($foo), exit;      # Or this.
94         print ($foo), exit;     # Or even this.
95
96 Also note that
97
98         print ($foo & 255) + 1, "\en";
99
100 .fi
101 probably doesn't do what you expect at first glance.
102 .Sh "Subroutines"
103 A subroutine may be declared as follows:
104 .nf
105
106     sub NAME BLOCK
107
108 .fi
109 .PP
110 Any arguments passed to the routine come in as array @_,
111 that is ($_[0], $_[1], .\|.\|.).
112 The array @_ is a local array, but its values are references to the
113 actual scalar parameters.
114 The return value of the subroutine is the value of the last expression
115 evaluated, and can be either an array value or a scalar value.
116 Alternately, a return statement may be used to specify the returned value and
117 exit the subroutine.
118 To create local variables see the
119 .I local
120 operator.
121 .PP
122 A subroutine is called using the
123 .I do
124 operator or the & operator.
125 .nf
126
127 .ne 12
128 Example:
129
130         sub MAX {
131                 local($max) = pop(@_);
132                 foreach $foo (@_) {
133                         $max = $foo \|if \|$max < $foo;
134                 }
135                 $max;
136         }
137
138         .\|.\|.
139         $bestday = &MAX($mon,$tue,$wed,$thu,$fri);
140
141 .ne 21
142 Example:
143
144         # get a line, combining continuation lines
145         #  that start with whitespace
146         sub get_line {
147                 $thisline = $lookahead;
148                 line: while ($lookahead = <STDIN>) {
149                         if ($lookahead \|=~ \|/\|^[ \^\e\|t]\|/\|) {
150                                 $thisline \|.= \|$lookahead;
151                         }
152                         else {
153                                 last line;
154                         }
155                 }
156                 $thisline;
157         }
158
159         $lookahead = <STDIN>;   # get first line
160         while ($_ = do get_line(\|)) {
161                 .\|.\|.
162         }
163
164 .fi
165 .nf
166 .ne 6
167 Use array assignment to a local list to name your formal arguments:
168
169         sub maybeset {
170                 local($key, $value) = @_;
171                 $foo{$key} = $value unless $foo{$key};
172         }
173
174 .fi
175 This also has the effect of turning call-by-reference into call-by-value,
176 since the assignment copies the values.
177 .Sp
178 Subroutines may be called recursively.
179 If a subroutine is called using the & form, the argument list is optional.
180 If omitted, no @_ array is set up for the subroutine; the @_ array at the
181 time of the call is visible to subroutine instead.
182 .nf
183
184         do foo(1,2,3);          # pass three arguments
185         &foo(1,2,3);            # the same
186
187         do foo();               # pass a null list
188         &foo();                 # the same
189         &foo;                   # pass no arguments--more efficient
190
191 .fi
192 .Sh "Passing By Reference"
193 Sometimes you don't want to pass the value of an array to a subroutine but
194 rather the name of it, so that the subroutine can modify the global copy
195 of it rather than working with a local copy.
196 In perl you can refer to all the objects of a particular name by prefixing
197 the name with a star: *foo.
198 When evaluated, it produces a scalar value that represents all the objects
199 of that name.
200 When assigned to within a local() operation, it causes the name mentioned
201 to refer to whatever * value was assigned to it.
202 Example:
203 .nf
204
205         sub doubleary {
206             local(*someary) = @_;
207             foreach $elem (@someary) {
208                 $elem *= 2;
209             }
210         }
211         do doubleary(*foo);
212         do doubleary(*bar);
213
214 .fi
215 Assignment to *name is currently recommended only inside a local().
216 You can actually assign to *name anywhere, but the previous referent of
217 *name may be stranded forever.
218 This may or may not bother you.
219 .Sp
220 Note that scalars are already passed by reference, so you can modify scalar
221 arguments without using this mechanism by refering explicitly to the $_[nnn]
222 in question.
223 You can modify all the elements of an array by passing all the elements
224 as scalars, but you have to use the * mechanism to push, pop or change the
225 size of an array.
226 The * mechanism will probably be more efficient in any case.
227 .Sp
228 Since a *name value contains unprintable binary data, if it is used as
229 an argument in a print, or as a %s argument in a printf or sprintf, it
230 then has the value '*name', just so it prints out pretty.
231 .Sh "Regular Expressions"
232 The patterns used in pattern matching are regular expressions such as
233 those supplied in the Version 8 regexp routines.
234 (In fact, the routines are derived from Henry Spencer's freely redistributable
235 reimplementation of the V8 routines.)
236 In addition, \ew matches an alphanumeric character (including \*(L"_\*(R") and \eW a nonalphanumeric.
237 Word boundaries may be matched by \eb, and non-boundaries by \eB.
238 A whitespace character is matched by \es, non-whitespace by \eS.
239 A numeric character is matched by \ed, non-numeric by \eD.
240 You may use \ew, \es and \ed within character classes.
241 Also, \en, \er, \ef, \et and \eNNN have their normal interpretations.
242 Within character classes \eb represents backspace rather than a word boundary.
243 Alternatives may be separated by |.
244 The bracketing construct \|(\ .\|.\|.\ \|) may also be used, in which case \e<digit>
245 matches the digit'th substring, where digit can range from 1 to 9.
246 (Outside of the pattern, always use $ instead of \e in front of the digit.
247 The scope of $<digit> (and $\`, $& and $\')
248 extends to the end of the enclosing BLOCK or eval string, or to
249 the next pattern match with subexpressions.
250 The \e<digit> notation sometimes works outside the current pattern, but should
251 not be relied upon.)
252 $+ returns whatever the last bracket match matched.
253 $& returns the entire matched string.
254 ($0 normally returns the same thing, but don't depend on it.)
255 $\` returns everything before the matched string.
256 $\' returns everything after the matched string.
257 Examples:
258 .nf
259     
260         s/\|^\|([^ \|]*\|) \|*([^ \|]*\|)\|/\|$2 $1\|/; # swap first two words
261
262 .ne 5
263         if (/\|Time: \|(.\|.\|):\|(.\|.\|):\|(.\|.\|)\|/\|) {
264                 $hours = $1;
265                 $minutes = $2;
266                 $seconds = $3;
267         }
268
269 .fi
270 By default, the ^ character matches only the beginning of the string,
271 the $ character matches only at the end (or before the newline at the end)
272 and
273 .I perl
274 does certain optimizations with the assumption that the string contains
275 only one line.
276 You may, however, wish to treat a string as a multi-line buffer, such that
277 the ^ will match after any newline within the string, and $ will match
278 before any newline.
279 At the cost of a little more overhead, you can do this by setting the variable
280 $* to 1.
281 Setting it back to 0 makes
282 .I perl
283 revert to its old behavior.
284 .PP
285 To facilitate multi-line substitutions, the . character never matches a newline
286 (even when $* is 0).
287 In particular, the following leaves a newline on the $_ string:
288 .nf
289
290         $_ = <STDIN>;
291         s/.*(some_string).*/$1/;
292
293 If the newline is unwanted, try one of
294
295         s/.*(some_string).*\en/$1/;
296         s/.*(some_string)[^\e000]*/$1/;
297         s/.*(some_string)(.|\en)*/$1/;
298         chop; s/.*(some_string).*/$1/;
299         /(some_string)/ && ($_ = $1);
300
301 .fi
302 Any item of a regular expression may be followed with digits in curly brackets
303 of the form {n,m}, where n gives the minimum number of times to match the item
304 and m gives the maximum.
305 The form {n} is equivalent to {n,n} and matches exactly n times.
306 The form {n,} matches n or more times.
307 (If a curly bracket occurs in any other context, it is treated as a regular
308 character.)
309 The * modifier is equivalent to {0,}, the + modifier to {1,} and the ? modifier
310 to {0,1}.
311 There is no limit to the size of n or m, but large numbers will chew up
312 more memory.
313 .Sp
314 You will note that all backslashed metacharacters in
315 .I perl
316 are alphanumeric,
317 such as \eb, \ew, \en.
318 Unlike some other regular expression languages, there are no backslashed
319 symbols that aren't alphanumeric.
320 So anything that looks like \e\e, \e(, \e), \e<, \e>, \e{, or \e} is always
321 interpreted as a literal character, not a metacharacter.
322 This makes it simple to quote a string that you want to use for a pattern
323 but that you are afraid might contain metacharacters.
324 Simply quote all the non-alphanumeric characters:
325 .nf
326
327         $pattern =~ s/(\eW)/\e\e$1/g;
328
329 .fi
330 .Sh "Formats"
331 Output record formats for use with the
332 .I write
333 operator may declared as follows:
334 .nf
335
336 .ne 3
337     format NAME =
338     FORMLIST
339     .
340
341 .fi
342 If name is omitted, format \*(L"STDOUT\*(R" is defined.
343 FORMLIST consists of a sequence of lines, each of which may be of one of three
344 types:
345 .Ip 1. 4
346 A comment.
347 .Ip 2. 4
348 A \*(L"picture\*(R" line giving the format for one output line.
349 .Ip 3. 4
350 An argument line supplying values to plug into a picture line.
351 .PP
352 Picture lines are printed exactly as they look, except for certain fields
353 that substitute values into the line.
354 Each picture field starts with either @ or ^.
355 The @ field (not to be confused with the array marker @) is the normal
356 case; ^ fields are used
357 to do rudimentary multi-line text block filling.
358 The length of the field is supplied by padding out the field
359 with multiple <, >, or | characters to specify, respectively, left justification,
360 right justification, or centering.
361 If any of the values supplied for these fields contains a newline, only
362 the text up to the newline is printed.
363 The special field @* can be used for printing multi-line values.
364 It should appear by itself on a line.
365 .PP
366 The values are specified on the following line, in the same order as
367 the picture fields.
368 The values should be separated by commas.
369 .PP
370 Picture fields that begin with ^ rather than @ are treated specially.
371 The value supplied must be a scalar variable name which contains a text
372 string.
373 .I Perl
374 puts as much text as it can into the field, and then chops off the front
375 of the string so that the next time the variable is referenced,
376 more of the text can be printed.
377 Normally you would use a sequence of fields in a vertical stack to print
378 out a block of text.
379 If you like, you can end the final field with .\|.\|., which will appear in the
380 output if the text was too long to appear in its entirety.
381 You can change which characters are legal to break on by changing the
382 variable $: to a list of the desired characters.
383 .PP
384 Since use of ^ fields can produce variable length records if the text to be
385 formatted is short, you can suppress blank lines by putting the tilde (~)
386 character anywhere in the line.
387 (Normally you should put it in the front if possible, for visibility.)
388 The tilde will be translated to a space upon output.
389 If you put a second tilde contiguous to the first, the line will be repeated
390 until all the fields on the line are exhausted.
391 (If you use a field of the @ variety, the expression you supply had better
392 not give the same value every time forever!)
393 .PP
394 Examples:
395 .nf
396 .lg 0
397 .cs R 25
398 .ft C
399
400 .ne 10
401 # a report on the /etc/passwd file
402 format top =
403 \&                        Passwd File
404 Name                Login    Office   Uid   Gid Home
405 ------------------------------------------------------------------
406 \&.
407 format STDOUT =
408 @<<<<<<<<<<<<<<<<<< @||||||| @<<<<<<@>>>> @>>>> @<<<<<<<<<<<<<<<<<
409 $name,              $login,  $office,$uid,$gid, $home
410 \&.
411
412 .ne 29
413 # a report from a bug report form
414 format top =
415 \&                        Bug Reports
416 @<<<<<<<<<<<<<<<<<<<<<<<     @|||         @>>>>>>>>>>>>>>>>>>>>>>>
417 $system,                      $%,         $date
418 ------------------------------------------------------------------
419 \&.
420 format STDOUT =
421 Subject: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
422 \&         $subject
423 Index: @<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
424 \&       $index,                       $description
425 Priority: @<<<<<<<<<< Date: @<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
426 \&          $priority,        $date,   $description
427 From: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
428 \&      $from,                         $description
429 Assigned to: @<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
430 \&             $programmer,            $description
431 \&~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
432 \&                                     $description
433 \&~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
434 \&                                     $description
435 \&~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
436 \&                                     $description
437 \&~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
438 \&                                     $description
439 \&~                                    ^<<<<<<<<<<<<<<<<<<<<<<<...
440 \&                                     $description
441 \&.
442
443 .ft R
444 .cs R
445 .lg
446 .fi
447 It is possible to intermix prints with writes on the same output channel,
448 but you'll have to handle $\- (lines left on the page) yourself.
449 .PP
450 If you are printing lots of fields that are usually blank, you should consider
451 using the reset operator between records.
452 Not only is it more efficient, but it can prevent the bug of adding another
453 field and forgetting to zero it.
454 .Sh "Interprocess Communication"
455 The IPC facilities of perl are built on the Berkeley socket mechanism.
456 If you don't have sockets, you can ignore this section.
457 The calls have the same names as the corresponding system calls,
458 but the arguments tend to differ, for two reasons.
459 First, perl file handles work differently than C file descriptors.
460 Second, perl already knows the length of its strings, so you don't need
461 to pass that information.
462 Here is a sample client (untested):
463 .nf
464
465         ($them,$port) = @ARGV;
466         $port = 2345 unless $port;
467         $them = 'localhost' unless $them;
468
469         $SIG{'INT'} = 'dokill';
470         sub dokill { kill 9,$child if $child; }
471
472         do 'sys/socket.h' || die "Can't do sys/socket.h: $@";
473
474         $sockaddr = 'S n a4 x8';
475         chop($hostname = `hostname`);
476
477         ($name, $aliases, $proto) = getprotobyname('tcp');
478         ($name, $aliases, $port) = getservbyname($port, 'tcp')
479                 unless $port =~ /^\ed+$/;;
480         ($name, $aliases, $type, $len, $thisaddr) = gethostbyname($hostname);
481         ($name, $aliases, $type, $len, $thataddr) = gethostbyname($them);
482
483         $this = pack($sockaddr, &AF_INET, 0, $thisaddr);
484         $that = pack($sockaddr, &AF_INET, $port, $thataddr);
485
486         socket(S, &PF_INET, &SOCK_STREAM, $proto) || die "socket: $!";
487         bind(S, $this) || die "bind: $!";
488         connect(S, $that) || die "connect: $!";
489
490         select(S); $| = 1; select(stdout);
491
492         if ($child = fork) {
493                 while (<>) {
494                         print S;
495                 }
496                 sleep 3;
497                 do dokill();
498         }
499         else {
500                 while (<S>) {
501                         print;
502                 }
503         }
504
505 .fi
506 And here's a server:
507 .nf
508
509         ($port) = @ARGV;
510         $port = 2345 unless $port;
511
512         do 'sys/socket.h' || die "Can't do sys/socket.h: $@";
513
514         $sockaddr = 'S n a4 x8';
515
516         ($name, $aliases, $proto) = getprotobyname('tcp');
517         ($name, $aliases, $port) = getservbyname($port, 'tcp')
518                 unless $port =~ /^\ed+$/;;
519
520         $this = pack($sockaddr, &AF_INET, $port, "\e0\e0\e0\e0");
521
522         select(NS); $| = 1; select(stdout);
523
524         socket(S, &PF_INET, &SOCK_STREAM, $proto) || die "socket: $!";
525         bind(S, $this) || die "bind: $!";
526         listen(S, 5) || die "connect: $!";
527
528         select(S); $| = 1; select(stdout);
529
530         for (;;) {
531                 print "Listening again\en";
532                 ($addr = accept(NS,S)) || die $!;
533                 print "accept ok\en";
534
535                 ($af,$port,$inetaddr) = unpack($pat,$addr);
536                 @inetaddr = unpack('C4',$inetaddr);
537                 print "$af $port @inetaddr\en";
538
539                 while (<NS>) {
540                         print;
541                         print NS;
542                 }
543         }
544
545 .fi
546 .Sh "Predefined Names"
547 The following names have special meaning to
548 .IR perl .
549 I could have used alphabetic symbols for some of these, but I didn't want
550 to take the chance that someone would say reset \*(L"a\-zA\-Z\*(R" and wipe them all
551 out.
552 You'll just have to suffer along with these silly symbols.
553 Most of them have reasonable mnemonics, or analogues in one of the shells.
554 .Ip $_ 8
555 The default input and pattern-searching space.
556 The following pairs are equivalent:
557 .nf
558
559 .ne 2
560         while (<>) {\|.\|.\|.   # only equivalent in while!
561         while ($_ = <>) {\|.\|.\|.
562
563 .ne 2
564         /\|^Subject:/
565         $_ \|=~ \|/\|^Subject:/
566
567 .ne 2
568         y/a\-z/A\-Z/
569         $_ =~ y/a\-z/A\-Z/
570
571 .ne 2
572         chop
573         chop($_)
574
575 .fi 
576 (Mnemonic: underline is understood in certain operations.)
577 .Ip $. 8
578 The current input line number of the last filehandle that was read.
579 Readonly.
580 Remember that only an explicit close on the filehandle resets the line number.
581 Since <> never does an explicit close, line numbers increase across ARGV files
582 (but see examples under eof).
583 (Mnemonic: many programs use . to mean the current line number.)
584 .Ip $/ 8
585 The input record separator, newline by default.
586 Works like
587 .IR awk 's
588 RS variable, including treating blank lines as delimiters
589 if set to the null string.
590 If set to a value longer than one character, only the first character is used.
591 (Mnemonic: / is used to delimit line boundaries when quoting poetry.)
592 .Ip $, 8
593 The output field separator for the print operator.
594 Ordinarily the print operator simply prints out the comma separated fields
595 you specify.
596 In order to get behavior more like
597 .IR awk ,
598 set this variable as you would set
599 .IR awk 's
600 OFS variable to specify what is printed between fields.
601 (Mnemonic: what is printed when there is a , in your print statement.)
602 .Ip $"" 8
603 This is like $, except that it applies to array values interpolated into
604 a double-quoted string (or similar interpreted string).
605 Default is a space.
606 (Mnemonic: obvious, I think.)
607 .Ip $\e 8
608 The output record separator for the print operator.
609 Ordinarily the print operator simply prints out the comma separated fields
610 you specify, with no trailing newline or record separator assumed.
611 In order to get behavior more like
612 .IR awk ,
613 set this variable as you would set
614 .IR awk 's
615 ORS variable to specify what is printed at the end of the print.
616 (Mnemonic: you set $\e instead of adding \en at the end of the print.
617 Also, it's just like /, but it's what you get \*(L"back\*(R" from
618 .IR perl .)
619 .Ip $# 8
620 The output format for printed numbers.
621 This variable is a half-hearted attempt to emulate
622 .IR awk 's
623 OFMT variable.
624 There are times, however, when
625 .I awk
626 and
627 .I perl
628 have differing notions of what
629 is in fact numeric.
630 Also, the initial value is %.20g rather than %.6g, so you need to set $#
631 explicitly to get
632 .IR awk 's
633 value.
634 (Mnemonic: # is the number sign.)
635 .Ip $% 8
636 The current page number of the currently selected output channel.
637 (Mnemonic: % is page number in nroff.)
638 .Ip $= 8
639 The current page length (printable lines) of the currently selected output
640 channel.
641 Default is 60.
642 (Mnemonic: = has horizontal lines.)
643 .Ip $\- 8
644 The number of lines left on the page of the currently selected output channel.
645 (Mnemonic: lines_on_page \- lines_printed.)
646 .Ip $~ 8
647 The name of the current report format for the currently selected output
648 channel.
649 (Mnemonic: brother to $^.)
650 .Ip $^ 8
651 The name of the current top-of-page format for the currently selected output
652 channel.
653 (Mnemonic: points to top of page.)
654 .Ip $| 8
655 If set to nonzero, forces a flush after every write or print on the currently
656 selected output channel.
657 Default is 0.
658 Note that
659 .I STDOUT
660 will typically be line buffered if output is to the
661 terminal and block buffered otherwise.
662 Setting this variable is useful primarily when you are outputting to a pipe,
663 such as when you are running a
664 .I perl
665 script under rsh and want to see the
666 output as it's happening.
667 (Mnemonic: when you want your pipes to be piping hot.)
668 .Ip $$ 8
669 The process number of the
670 .I perl
671 running this script.
672 (Mnemonic: same as shells.)
673 .Ip $? 8
674 The status returned by the last pipe close, backtick (\`\`) command or
675 .I system
676 operator.
677 Note that this is the status word returned by the wait() system
678 call, so the exit value of the subprocess is actually ($? >> 8).
679 $? & 255 gives which signal, if any, the process died from, and whether
680 there was a core dump.
681 (Mnemonic: similar to sh and ksh.)
682 .Ip $& 8 4
683 The string matched by the last pattern match (not counting any matches hidden
684 within a BLOCK or eval enclosed by the current BLOCK).
685 (Mnemonic: like & in some editors.)
686 .Ip $\` 8 4
687 The string preceding whatever was matched by the last pattern match
688 (not counting any matches hidden within a BLOCK or eval enclosed by the current
689 BLOCK).
690 (Mnemonic: \` often precedes a quoted string.)
691 .Ip $\' 8 4
692 The string following whatever was matched by the last pattern match
693 (not counting any matches hidden within a BLOCK or eval enclosed by the current
694 BLOCK).
695 (Mnemonic: \' often follows a quoted string.)
696 Example:
697 .nf
698
699 .ne 3
700         $_ = \'abcdefghi\';
701         /def/;
702         print "$\`:$&:$\'\en";          # prints abc:def:ghi
703
704 .fi
705 .Ip $+ 8 4
706 The last bracket matched by the last search pattern.
707 This is useful if you don't know which of a set of alternative patterns
708 matched.
709 For example:
710 .nf
711
712     /Version: \|(.*\|)|Revision: \|(.*\|)\|/ \|&& \|($rev = $+);
713
714 .fi
715 (Mnemonic: be positive and forward looking.)
716 .Ip $* 8 2
717 Set to 1 to do multiline matching within a string, 0 to tell
718 .I perl
719 that it can assume that strings contain a single line, for the purpose
720 of optimizing pattern matches.
721 Pattern matches on strings containing multiple newlines can produce confusing
722 results when $* is 0.
723 Default is 0.
724 (Mnemonic: * matches multiple things.)
725 .Ip $0 8
726 Contains the name of the file containing the
727 .I perl
728 script being executed.
729 The value should be copied elsewhere before any pattern matching happens, which
730 clobbers $0.
731 (Mnemonic: same as sh and ksh.)
732 .Ip $<digit> 8
733 Contains the subpattern from the corresponding set of parentheses in the last
734 pattern matched, not counting patterns matched in nested blocks that have
735 been exited already.
736 (Mnemonic: like \edigit.)
737 .Ip $[ 8 2
738 The index of the first element in an array, and of the first character in
739 a substring.
740 Default is 0, but you could set it to 1 to make
741 .I perl
742 behave more like
743 .I awk
744 (or Fortran)
745 when subscripting and when evaluating the index() and substr() functions.
746 (Mnemonic: [ begins subscripts.)
747 .Ip $] 8 2
748 The string printed out when you say \*(L"perl -v\*(R".
749 It can be used to determine at the beginning of a script whether the perl
750 interpreter executing the script is in the right range of versions.
751 Example:
752 .nf
753
754 .ne 5
755         # see if getc is available
756         ($version,$patchlevel) =
757                  $] =~ /(\ed+\e.\ed+).*\enPatch level: (\ed+)/;
758         print STDERR "(No filename completion available.)\en"
759                  if $version * 1000 + $patchlevel < 2016;
760
761 .fi
762 (Mnemonic: Is this version of perl in the right bracket?)
763 .Ip $; 8 2
764 The subscript separator for multi-dimensional array emulation.
765 If you refer to an associative array element as
766 .nf
767         $foo{$a,$b,$c}
768
769 it really means
770
771         $foo{join($;, $a, $b, $c)}
772
773 But don't put
774
775         @foo{$a,$b,$c}          # a slice--note the @
776
777 which means
778
779         ($foo{$a},$foo{$b},$foo{$c})
780
781 .fi
782 Default is "\e034", the same as SUBSEP in
783 .IR awk .
784 Note that if your keys contain binary data there might not be any safe
785 value for $;.
786 (Mnemonic: comma (the syntactic subscript separator) is a semi-semicolon.
787 Yeah, I know, it's pretty lame, but $, is already taken for something more
788 important.)
789 .Ip $! 8 2
790 If used in a numeric context, yields the current value of errno, with all the
791 usual caveats.
792 If used in a string context, yields the corresponding system error string.
793 You can assign to $! in order to set errno
794 if, for instance, you want $! to return the string for error n, or you want
795 to set the exit value for the die operator.
796 (Mnemonic: What just went bang?)
797 .Ip $@ 8 2
798 The error message from the last eval command.
799 If null, the last eval parsed and executed correctly.
800 (Mnemonic: Where was the syntax error \*(L"at\*(R"?)
801 .Ip $< 8 2
802 The real uid of this process.
803 (Mnemonic: it's the uid you came FROM, if you're running setuid.)
804 .Ip $> 8 2
805 The effective uid of this process.
806 Example:
807 .nf
808
809 .ne 2
810         $< = $>;        # set real uid to the effective uid
811         ($<,$>) = ($>,$<);      # swap real and effective uid
812
813 .fi
814 (Mnemonic: it's the uid you went TO, if you're running setuid.)
815 Note: $< and $> can only be swapped on machines supporting setreuid().
816 .Ip $( 8 2
817 The real gid of this process.
818 If you are on a machine that supports membership in multiple groups
819 simultaneously, gives a space separated list of groups you are in.
820 The first number is the one returned by getgid(), and the subsequent ones
821 by getgroups(), one of which may be the same as the first number.
822 (Mnemonic: parentheses are used to GROUP things.
823 The real gid is the group you LEFT, if you're running setgid.)
824 .Ip $) 8 2
825 The effective gid of this process.
826 If you are on a machine that supports membership in multiple groups
827 simultaneously, gives a space separated list of groups you are in.
828 The first number is the one returned by getegid(), and the subsequent ones
829 by getgroups(), one of which may be the same as the first number.
830 (Mnemonic: parentheses are used to GROUP things.
831 The effective gid is the group that's RIGHT for you, if you're running setgid.)
832 .Sp
833 Note: $<, $>, $( and $) can only be set on machines that support the
834 corresponding set[re][ug]id() routine.
835 $( and $) can only be swapped on machines supporting setregid().
836 .Ip $: 8 2
837 The current set of characters after which a string may be broken to
838 fill continuation fields (starting with ^) in a format.
839 Default is "\ \en-", to break on whitespace or hyphens.
840 (Mnemonic: a \*(L"colon\*(R" in poetry is a part of a line.)
841 .Ip @ARGV 8 3
842 The array ARGV contains the command line arguments intended for the script.
843 Note that $#ARGV is the generally number of arguments minus one, since
844 $ARGV[0] is the first argument, NOT the command name.
845 See $0 for the command name.
846 .Ip @INC 8 3
847 The array INC contains the list of places to look for
848 .I perl
849 scripts to be
850 evaluated by the \*(L"do EXPR\*(R" command.
851 It initially consists of the arguments to any
852 .B \-I
853 command line switches, followed
854 by the default
855 .I perl
856 library, probably \*(L"/usr/local/lib/perl\*(R".
857 .Ip $ENV{expr} 8 2
858 The associative array ENV contains your current environment.
859 Setting a value in ENV changes the environment for child processes.
860 .Ip $SIG{expr} 8 2
861 The associative array SIG is used to set signal handlers for various signals.
862 Example:
863 .nf
864
865 .ne 12
866         sub handler {   # 1st argument is signal name
867                 local($sig) = @_;
868                 print "Caught a SIG$sig\-\|\-shutting down\en";
869                 close(LOG);
870                 exit(0);
871         }
872
873         $SIG{\'INT\'} = \'handler\';
874         $SIG{\'QUIT\'} = \'handler\';
875         .\|.\|.
876         $SIG{\'INT\'} = \'DEFAULT\';    # restore default action
877         $SIG{\'QUIT\'} = \'IGNORE\';    # ignore SIGQUIT
878
879 .fi
880 The SIG array only contains values for the signals actually set within
881 the perl script.
882 .Sh "Packages"
883 Perl provides a mechanism for alternate namespaces to protect packages from
884 stomping on each others variables.
885 By default, a perl script starts compiling into the package known as \*(L"main\*(R".
886 By use of the
887 .I package
888 declaration, you can switch namespaces.
889 The scope of the package declaration is from the declaration itself to the end
890 of the enclosing block (the same scope as the local() operator).
891 Typically it would be the first declaration in a file to be included by
892 the \*(L"do FILE\*(R" operator.
893 You can switch into a package in more than one place; it merely influences
894 which symbol table is used by the compiler for the rest of that block.
895 You can refer to variables in other packages by prefixing the name with
896 the package name and a single quote.
897 If the package name is null, the \*(L"main\*(R" package as assumed.
898 Eval'ed strings are compiled in the package in which the eval was compiled
899 in.
900 (Assignments to $SIG{}, however, assume the signal handler specified is in the
901 main package.
902 Qualify the signal handler name if you wish to have a signal handler in
903 a package.)
904 For an example, examine perldb.pl in the perl library.
905 It initially switches to the DB package so that the debugger doesn't interfere
906 with variables in the script you are trying to debug.
907 At various points, however, it temporarily switches back to the main package
908 to evaluate various expressions in the context of the main package.
909 .PP
910 The symbol table for a package happens to be stored in the associative array
911 of that name prepended with an underscore.
912 The value in each entry of the associative array is
913 what you are referring to when you use the *name notation.
914 In fact, the following have the same effect (in package main, anyway),
915 though the first is more
916 efficient because it does the symbol table lookups at compile time:
917 .nf
918
919 .ne 2
920         local(*foo) = *bar;
921         local($_main{'foo'}) = $_main{'bar'};
922
923 .fi
924 You can use this to print out all the variables in a package, for instance.
925 Here is dumpvar.pl from the perl library:
926 .nf
927 .ne 11
928         package dumpvar;
929
930         sub main'dumpvar {
931         \&    ($package) = @_;
932         \&    local(*stab) = eval("*_$package");
933         \&    while (($key,$val) = each(%stab)) {
934         \&        {
935         \&            local(*entry) = $val;
936         \&            if (defined $entry) {
937         \&                print "\e$$key = '$entry'\en";
938         \&            }
939 .ne 7
940         \&            if (defined @entry) {
941         \&                print "\e@$key = (\en";
942         \&                foreach $num ($[ .. $#entry) {
943         \&                    print "  $num\et'",$entry[$num],"'\en";
944         \&                }
945         \&                print ")\en";
946         \&            }
947 .ne 10
948         \&            if ($key ne "_$package" && defined %entry) {
949         \&                print "\e%$key = (\en";
950         \&                foreach $key (sort keys(%entry)) {
951         \&                    print "  $key\et'",$entry{$key},"'\en";
952         \&                }
953         \&                print ")\en";
954         \&            }
955         \&        }
956         \&    }
957         }
958
959 .fi
960 Note that, even though the subroutine is compiled in package dumpvar, the
961 name of the subroutine is qualified so that it's name is inserted into package
962 \*(L"main\*(R".
963 .Sh "Style"
964 Each programmer will, of course, have his or her own preferences in regards
965 to formatting, but there are some general guidelines that will make your
966 programs easier to read.
967 .Ip 1. 4 4
968 Just because you CAN do something a particular way doesn't mean that
969 you SHOULD do it that way.
970 .I Perl
971 is designed to give you several ways to do anything, so consider picking
972 the most readable one.
973 For instance
974
975         open(FOO,$foo) || die "Can't open $foo: $!";
976
977 is better than
978
979         die "Can't open $foo: $!" unless open(FOO,$foo);
980
981 because the second way hides the main point of the statement in a
982 modifier.
983 On the other hand
984
985         print "Starting analysis\en" if $verbose;
986
987 is better than
988
989         $verbose && print "Starting analysis\en";
990
991 since the main point isn't whether the user typed -v or not.
992 .Sp
993 Similarly, just because an operator lets you assume default arguments
994 doesn't mean that you have to make use of the defaults.
995 The defaults are there for lazy systems programmers writing one-shot
996 programs.
997 If you want your program to be readable, consider supplying the argument.
998 .Sp
999 Along the same lines, just because you
1000 .I can
1001 omit parentheses in many places doesn't mean that you ought to:
1002 .nf
1003
1004         return print reverse sort num values array;
1005         return print(reverse(sort num (values(%array))));
1006
1007 .fi
1008 When in doubt, parenthesize.
1009 At the very least it will let some poor schmuck bounce on the % key in vi.
1010 .Ip 2. 4 4
1011 Don't go through silly contortions to exit a loop at the top or the
1012 bottom, when
1013 .I perl
1014 provides the "last" operator so you can exit in the middle.
1015 Just outdent it a little to make it more visible:
1016 .nf
1017
1018 .ne 7
1019     line:
1020         for (;;) {
1021             statements;
1022         last line if $foo;
1023             next line if /^#/;
1024             statements;
1025         }
1026
1027 .fi
1028 .Ip 3. 4 4
1029 Don't be afraid to use loop labels\*(--they're there to enhance readability as
1030 well as to allow multi-level loop breaks.
1031 See last example.
1032 .Ip 6. 4 4
1033 For portability, when using features that may not be implemented on every
1034 machine, test the construct in an eval to see if it fails.
1035 If you know what version or patchlevel a particular feature was implemented,
1036 you can test $] to see if it will be there.
1037 .Ip 4. 4 4
1038 Choose mnemonic indentifiers.
1039 .Ip 5. 4 4
1040 Be consistent.
1041 .Sh "Debugging"
1042 If you invoke
1043 .I perl
1044 with a
1045 .B \-d
1046 switch, your script will be run under a debugging monitor.
1047 It will halt before the first executable statement and ask you for a
1048 command, such as:
1049 .Ip "h" 12 4
1050 Prints out a help message.
1051 .Ip "s" 12 4
1052 Single step.
1053 Executes until it reaches the beginning of another statement.
1054 .Ip "c" 12 4
1055 Continue.
1056 Executes until the next breakpoint is reached.
1057 .Ip "<CR>" 12 4
1058 Repeat last s or c.
1059 .Ip "n" 12 4
1060 Single step around subroutine call.
1061 .Ip "l min+incr" 12 4
1062 List incr+1 lines starting at min.
1063 If min is omitted, starts where last listing left off.
1064 If incr is omitted, previous value of incr is used.
1065 .Ip "l min-max" 12 4
1066 List lines in the indicated range.
1067 .Ip "l line" 12 4
1068 List just the indicated line.
1069 .Ip "l" 12 4
1070 List incr+1 more lines after last printed line.
1071 .Ip "l subname" 12 4
1072 List subroutine.
1073 If it's a long subroutine it just lists the beginning.
1074 Use \*(L"l\*(R" to list more.
1075 .Ip "L" 12 4
1076 List lines that have breakpoints or actions.
1077 .Ip "t" 12 4
1078 Toggle trace mode on or off.
1079 .Ip "b line" 12 4
1080 Set a breakpoint.
1081 If line is omitted, sets a breakpoint on the current line
1082 line that is about to be executed.
1083 Breakpoints may only be set on lines that begin an executable statement.
1084 .Ip "b subname" 12 4
1085 Set breakpoint at first executable line of subroutine.
1086 .Ip "S" 12 4
1087 Lists the names of all subroutines.
1088 .Ip "d line" 12 4
1089 Delete breakpoint.
1090 If line is omitted, deletes the breakpoint on the current line
1091 line that is about to be executed.
1092 .Ip "D" 12 4
1093 Delete all breakpoints.
1094 .Ip "A" 12 4
1095 Delete all line actions.
1096 .Ip "V package" 12 4
1097 List all variables in package.
1098 Default is main package.
1099 .Ip "a line command" 12 4
1100 Set an action for line.
1101 A multi-line command may be entered by backslashing the newlines.
1102 .Ip "< command" 12 4
1103 Set an action to happen before every debugger prompt.
1104 A multi-line command may be entered by backslashing the newlines.
1105 .Ip "> command" 12 4
1106 Set an action to happen after the prompt when you've just given a command
1107 to return to executing the script.
1108 A multi-line command may be entered by backslashing the newlines.
1109 .Ip "! number" 12 4
1110 Redo a debugging command.
1111 If number is omitted, redoes the previous command.
1112 .Ip "! -number" 12 4
1113 Redo the command that was that many commands ago.
1114 .Ip "H -number" 12 4
1115 Display last n commands.
1116 Only commands longer than one character are listed.
1117 If number is omitted, lists them all.
1118 .Ip "q or ^D" 12 4
1119 Quit.
1120 .Ip "command" 12 4
1121 Execute command as a perl statement.
1122 A missing semicolon will be supplied.
1123 .Ip "p expr" 12 4
1124 Same as \*(L"print DB'OUT expr\*(R".
1125 The DB'OUT filehandle is opened to /dev/tty, regardless of where STDOUT
1126 may be redirected to.
1127 .PP
1128 If you want to modify the debugger, copy perldb.pl from the perl library
1129 to your current directory and modify it as necessary.
1130 You can do some customization by setting up a .perldb file which contains
1131 initialization code.
1132 For instance, you could make aliases like these:
1133 .nf
1134
1135     $DBalias{'len'} = 's/^len(.*)/p length(\e$1)/';
1136     $DBalias{'stop'} = 's/^stop (at|in)/b/';
1137     $DBalias{'.'} =
1138       's/^./p "\e$DBsub(\e$DBline):\et\e$DBline[\e$DBline]"/';
1139
1140 .fi
1141 .Sh "Setuid Scripts"
1142 .I Perl
1143 is designed to make it easy to write secure setuid and setgid scripts.
1144 Unlike shells, which are based on multiple substitution passes on each line
1145 of the script,
1146 .I perl
1147 uses a more conventional evaluation scheme with fewer hidden \*(L"gotchas\*(R".
1148 Additionally, since the language has more built-in functionality, it
1149 has to rely less upon external (and possibly untrustworthy) programs to
1150 accomplish its purposes.
1151 .PP
1152 In an unpatched 4.2 or 4.3bsd kernel, setuid scripts are intrinsically
1153 insecure, but this kernel feature can be disabled.
1154 If it is,
1155 .I perl
1156 can emulate the setuid and setgid mechanism when it notices the otherwise
1157 useless setuid/gid bits on perl scripts.
1158 If the kernel feature isn't disabled,
1159 .I perl
1160 will complain loudly that your setuid script is insecure.
1161 You'll need to either disable the kernel setuid script feature, or put
1162 a C wrapper around the script.
1163 .PP
1164 When perl is executing a setuid script, it takes special precautions to
1165 prevent you from falling into any obvious traps.
1166 (In some ways, a perl script is more secure than the corresponding
1167 C program.)
1168 Any command line argument, environment variable, or input is marked as
1169 \*(L"tainted\*(R", and may not be used, directly or indirectly, in any
1170 command that invokes a subshell, or in any command that modifies files,
1171 directories or processes.
1172 Any variable that is set within an expression that has previously referenced
1173 a tainted value also becomes tainted (even if it is logically impossible
1174 for the tainted value to influence the variable).
1175 For example:
1176 .nf
1177
1178 .ne 5
1179         $foo = shift;                   # $foo is tainted
1180         $bar = $foo,\'bar\';            # $bar is also tainted
1181         $xxx = <>;                      # Tainted
1182         $path = $ENV{\'PATH\'}; # Tainted, but see below
1183         $abc = \'abc\';                 # Not tainted
1184
1185 .ne 4
1186         system "echo $foo";             # Insecure
1187         system "echo", $foo;    # Secure (doesn't use sh)
1188         system "echo $bar";             # Insecure
1189         system "echo $abc";             # Insecure until PATH set
1190
1191 .ne 5
1192         $ENV{\'PATH\'} = \'/bin:/usr/bin\';
1193         $ENV{\'IFS\'} = \'\' if $ENV{\'IFS\'} ne \'\';
1194
1195         $path = $ENV{\'PATH\'}; # Not tainted
1196         system "echo $abc";             # Is secure now!
1197
1198 .ne 5
1199         open(FOO,"$foo");               # OK
1200         open(FOO,">$foo");              # Not OK
1201
1202         open(FOO,"echo $foo|"); # Not OK, but...
1203         open(FOO,"-|") || exec \'echo\', $foo;  # OK
1204
1205         $zzz = `echo $foo`;             # Insecure, zzz tainted
1206
1207         unlink $abc,$foo;               # Insecure
1208         umask $foo;                     # Insecure
1209
1210 .ne 3
1211         exec "echo $foo";               # Insecure
1212         exec "echo", $foo;              # Secure (doesn't use sh)
1213         exec "sh", \'-c\', $foo;        # Considered secure, alas
1214
1215 .fi
1216 The taintedness is associated with each scalar value, so some elements
1217 of an array can be tainted, and others not.
1218 .PP
1219 If you try to do something insecure, you will get a fatal error saying 
1220 something like \*(L"Insecure dependency\*(R" or \*(L"Insecure PATH\*(R".
1221 Note that you can still write an insecure system call or exec,
1222 but only by explicity doing something like the last example above.
1223 You can also bypass the tainting mechanism by referencing
1224 subpatterns\*(--\c
1225 .I perl
1226 presumes that if you reference a substring using $1, $2, etc, you knew
1227 what you were doing when you wrote the pattern:
1228 .nf
1229
1230         $ARGV[0] =~ /^\-P(\ew+)$/;
1231         $printer = $1;          # Not tainted
1232
1233 .fi
1234 This is fairly secure since \ew+ doesn't match shell metacharacters.
1235 Use of .+ would have been insecure, but
1236 .I perl
1237 doesn't check for that, so you must be careful with your patterns.
1238 This is the ONLY mechanism for untainting user supplied filenames if you
1239 want to do file operations on them (unless you make $> equal to $<).
1240 .PP
1241 It's also possible to get into trouble with other operations that don't care
1242 whether they use tainted values.
1243 Make judicious use of the file tests in dealing with any user-supplied
1244 filenames.
1245 When possible, do opens and such after setting $> = $<.
1246 .I Perl
1247 doesn't prevent you from opening tainted filenames for reading, so be
1248 careful what you print out.
1249 The tainting mechanism is intended to prevent stupid mistakes, not to remove
1250 the need for thought.
1251 .SH ENVIRONMENT
1252 .I Perl
1253 uses PATH in executing subprocesses, and in finding the script if \-S
1254 is used.
1255 HOME or LOGDIR are used if chdir has no argument.
1256 .PP
1257 Apart from these,
1258 .I perl
1259 uses no environment variables, except to make them available
1260 to the script being executed, and to child processes.
1261 However, scripts running setuid would do well to execute the following lines
1262 before doing anything else, just to keep people honest:
1263 .nf
1264
1265 .ne 3
1266     $ENV{\'PATH\'} = \'/bin:/usr/bin\';    # or whatever you need
1267     $ENV{\'SHELL\'} = \'/bin/sh\' if $ENV{\'SHELL\'} ne \'\';
1268     $ENV{\'IFS\'} = \'\' if $ENV{\'IFS\'} ne \'\';
1269
1270 .fi
1271 .SH AUTHOR
1272 Larry Wall <lwall@jpl-devvax.Jpl.Nasa.Gov>
1273 .SH FILES
1274 /tmp/perl\-eXXXXXX      temporary file for
1275 .B \-e
1276 commands.
1277 .SH SEE ALSO
1278 a2p     awk to perl translator
1279 .br
1280 s2p     sed to perl translator
1281 .SH DIAGNOSTICS
1282 Compilation errors will tell you the line number of the error, with an
1283 indication of the next token or token type that was to be examined.
1284 (In the case of a script passed to
1285 .I perl
1286 via
1287 .B \-e
1288 switches, each
1289 .B \-e
1290 is counted as one line.)
1291 .PP
1292 Setuid scripts have additional constraints that can produce error messages
1293 such as \*(L"Insecure dependency\*(R".
1294 See the section on setuid scripts.
1295 .SH TRAPS
1296 Accustomed
1297 .IR awk
1298 users should take special note of the following:
1299 .Ip * 4 2
1300 Semicolons are required after all simple statements in
1301 .IR perl .
1302 Newline
1303 is not a statement delimiter.
1304 .Ip * 4 2
1305 Curly brackets are required on ifs and whiles.
1306 .Ip * 4 2
1307 Variables begin with $ or @ in
1308 .IR perl .
1309 .Ip * 4 2
1310 Arrays index from 0 unless you set $[.
1311 Likewise string positions in substr() and index().
1312 .Ip * 4 2
1313 You have to decide whether your array has numeric or string indices.
1314 .Ip * 4 2
1315 Associative array values do not spring into existence upon mere reference.
1316 .Ip * 4 2
1317 You have to decide whether you want to use string or numeric comparisons.
1318 .Ip * 4 2
1319 Reading an input line does not split it for you.  You get to split it yourself
1320 to an array.
1321 And the
1322 .I split
1323 operator has different arguments.
1324 .Ip * 4 2
1325 The current input line is normally in $_, not $0.
1326 It generally does not have the newline stripped.
1327 ($0 is initially the name of the program executed, then the last matched
1328 string.)
1329 .Ip * 4 2
1330 $<digit> does not refer to fields\*(--it refers to substrings matched by the last
1331 match pattern.
1332 .Ip * 4 2
1333 The
1334 .I print
1335 statement does not add field and record separators unless you set
1336 $, and $\e.
1337 .Ip * 4 2
1338 You must open your files before you print to them.
1339 .Ip * 4 2
1340 The range operator is \*(L".\|.\*(R", not comma.
1341 (The comma operator works as in C.)
1342 .Ip * 4 2
1343 The match operator is \*(L"=~\*(R", not \*(L"~\*(R".
1344 (\*(L"~\*(R" is the one's complement operator, as in C.)
1345 .Ip * 4 2
1346 The exponentiation operator is \*(L"**\*(R", not \*(L"^\*(R".
1347 (\*(L"^\*(R" is the XOR operator, as in C.)
1348 .Ip * 4 2
1349 The concatenation operator is \*(L".\*(R", not the null string.
1350 (Using the null string would render \*(L"/pat/ /pat/\*(R" unparsable,
1351 since the third slash would be interpreted as a division operator\*(--the
1352 tokener is in fact slightly context sensitive for operators like /, ?, and <.
1353 And in fact, . itself can be the beginning of a number.)
1354 .Ip * 4 2
1355 .IR Next ,
1356 .I exit
1357 and
1358 .I continue
1359 work differently.
1360 .Ip * 4 2
1361 The following variables work differently
1362 .nf
1363
1364           Awk   \h'|2.5i'Perl
1365           ARGC  \h'|2.5i'$#ARGV
1366           ARGV[0]       \h'|2.5i'$0
1367           FILENAME\h'|2.5i'$ARGV
1368           FNR   \h'|2.5i'$. \- something
1369           FS    \h'|2.5i'(whatever you like)
1370           NF    \h'|2.5i'$#Fld, or some such
1371           NR    \h'|2.5i'$.
1372           OFMT  \h'|2.5i'$#
1373           OFS   \h'|2.5i'$,
1374           ORS   \h'|2.5i'$\e
1375           RLENGTH       \h'|2.5i'length($&)
1376           RS    \h'|2.5i'$/
1377           RSTART        \h'|2.5i'length($\`)
1378           SUBSEP        \h'|2.5i'$;
1379
1380 .fi
1381 .Ip * 4 2
1382 When in doubt, run the
1383 .I awk
1384 construct through a2p and see what it gives you.
1385 .PP
1386 Cerebral C programmers should take note of the following:
1387 .Ip * 4 2
1388 Curly brackets are required on ifs and whiles.
1389 .Ip * 4 2
1390 You should use \*(L"elsif\*(R" rather than \*(L"else if\*(R"
1391 .Ip * 4 2
1392 .I Break
1393 and
1394 .I continue
1395 become
1396 .I last
1397 and
1398 .IR next ,
1399 respectively.
1400 .Ip * 4 2
1401 There's no switch statement.
1402 .Ip * 4 2
1403 Variables begin with $ or @ in
1404 .IR perl .
1405 .Ip * 4 2
1406 Printf does not implement *.
1407 .Ip * 4 2
1408 Comments begin with #, not /*.
1409 .Ip * 4 2
1410 You can't take the address of anything.
1411 .Ip * 4 2
1412 ARGV must be capitalized.
1413 .Ip * 4 2
1414 The \*(L"system\*(R" calls link, unlink, rename, etc. return nonzero for success, not 0.
1415 .Ip * 4 2
1416 Signal handlers deal with signal names, not numbers.
1417 .Ip * 4 2
1418 You can't subscript array values, only arrays (no $x = (1,2,3)[2];).
1419 .PP
1420 Seasoned
1421 .I sed
1422 programmers should take note of the following:
1423 .Ip * 4 2
1424 Backreferences in substitutions use $ rather than \e.
1425 .Ip * 4 2
1426 The pattern matching metacharacters (, ), and | do not have backslashes in front.
1427 .Ip * 4 2
1428 The range operator is .\|. rather than comma.
1429 .PP
1430 Sharp shell programmers should take note of the following:
1431 .Ip * 4 2
1432 The backtick operator does variable interpretation without regard to the
1433 presence of single quotes in the command.
1434 .Ip * 4 2
1435 The backtick operator does no translation of the return value, unlike csh.
1436 .Ip * 4 2
1437 Shells (especially csh) do several levels of substitution on each command line.
1438 .I Perl
1439 does substitution only in certain constructs such as double quotes,
1440 backticks, angle brackets and search patterns.
1441 .Ip * 4 2
1442 Shells interpret scripts a little bit at a time.
1443 .I Perl
1444 compiles the whole program before executing it.
1445 .Ip * 4 2
1446 The arguments are available via @ARGV, not $1, $2, etc.
1447 .Ip * 4 2
1448 The environment is not automatically made available as variables.
1449 .SH BUGS
1450 .PP
1451 .I Perl
1452 is at the mercy of your machine's definitions of various operations
1453 such as type casting, atof() and sprintf().
1454 .PP
1455 If your stdio requires an seek or eof between reads and writes on a particular
1456 stream, so does
1457 .IR perl .
1458 .PP
1459 While none of the built-in data types have any arbitrary size limits (apart
1460 from memory size), there are still a few arbitrary limits:
1461 a given identifier may not be longer than 255 characters;
1462 sprintf is limited on many machines to 128 characters per field (unless the format
1463 specifier is exactly %s);
1464 and no component of your PATH may be longer than 255 if you use \-S.
1465 .PP
1466 .I Perl
1467 actually stands for Pathologically Eclectic Rubbish Lister, but don't tell
1468 anyone I said that.
1469 .rn }` ''