a "replacement" for awk and sed
[perl.git] / perl.man.2
1 ''' Beginning of part 2
2 ''' $Header: perl.man.2,v 1.0 87/12/18 16:18:41 root Exp $
3 '''
4 ''' $Log:       perl.man.2,v $
5 ''' Revision 1.0  87/12/18  16:18:41  root
6 ''' Initial revision
7 ''' 
8 '''
9 .Ip "goto LABEL" 8 6
10 Finds the statement labeled with LABEL and resumes execution there.
11 Currently you may only go to statements in the main body of the program
12 that are not nested inside a do {} construct.
13 This statement is not implemented very efficiently, and is here only to make
14 the sed-to-perl translator easier.
15 Use at your own risk.
16 .Ip "hex(EXPR)" 8 2
17 Returns the decimal value of EXPR interpreted as an hex string.
18 (To interpret strings that might start with 0 or 0x see oct().)
19 .Ip "index(STR,SUBSTR)" 8 4
20 Returns the position of SUBSTR in STR, based at 0, or whatever you've
21 set the $[ variable to.
22 If the substring is not found, returns one less than the base, ordinarily -1.
23 .Ip "int(EXPR)" 8 3
24 Returns the integer portion of EXPR.
25 .Ip "join(EXPR,LIST)" 8 8
26 .Ip "join(EXPR,ARRAY)" 8
27 Joins the separate strings of LIST or ARRAY into a single string with fields
28 separated by the value of EXPR, and returns the string.
29 Example:
30 .nf
31     
32     $_ = join(\|':', $login,$passwd,$uid,$gid,$gcos,$home,$shell);
33
34 .fi
35 See
36 .IR split .
37 .Ip "keys(ASSOC_ARRAY)" 8 6
38 Returns a normal array consisting of all the keys of the named associative
39 array.
40 The keys are returned in an apparently random order, but it is the same order
41 as either the values() or each() function produces (given that the associative array
42 has not been modified).
43 Here is yet another way to print your environment:
44 .nf
45
46 .ne 5
47         @keys = keys(ENV);
48         @values = values(ENV);
49         while ($#keys >= 0) {
50                 print pop(keys),'=',pop(values),"\n";
51         }
52
53 .fi
54 .Ip "kill LIST" 8 2
55 Sends a signal to a list of processes.
56 The first element of the list must be the (numerical) signal to send.
57 LIST may be an array, in which case you may wish to use the unshift
58 command to put the signal on the front of the array.
59 Returns the number of processes successfully signaled.
60 Note: in order to use the value you must put the whole thing in parentheses:
61 .nf
62
63         $cnt = (kill 9,$child1,$child2);
64
65 .fi
66 .Ip "last LABEL" 8 8
67 .Ip "last" 8
68 The
69 .I last
70 command is like the
71 .I break
72 statement in C (as used in loops); it immediately exits the loop in question.
73 If the LABEL is omitted, the command refers to the innermost enclosing loop.
74 The
75 .I continue
76 block, if any, is not executed:
77 .nf
78
79 .ne 4
80         line: while (<stdin>) {
81                 last line if /\|^$/;    # exit when done with header
82                 .\|.\|.
83         }
84
85 .fi
86 .Ip "localtime(EXPR)" 8 4
87 Converts a time as returned by the time function to a 9-element array with
88 the time analyzed for the local timezone.
89 Typically used as follows:
90 .nf
91
92 .ne 3
93     ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst)
94        = localtime(time);
95
96 .fi
97 All array elements are numeric.
98 .Ip "log(EXPR)" 8 3
99 Returns logarithm (base e) of EXPR.
100 .Ip "next LABEL" 8 8
101 .Ip "next" 8
102 The
103 .I next
104 command is like the
105 .I continue
106 statement in C; it starts the next iteration of the loop:
107 .nf
108
109 .ne 4
110         line: while (<stdin>) {
111                 next line if /\|^#/;    # discard comments
112                 .\|.\|.
113         }
114
115 .fi
116 Note that if there were a
117 .I continue
118 block on the above, it would get executed even on discarded lines.
119 If the LABEL is omitted, the command refers to the innermost enclosing loop.
120 .Ip "length(EXPR)" 8 2
121 Returns the length in characters of the value of EXPR.
122 .Ip "link(OLDFILE,NEWFILE)" 8 2
123 Creates a new filename linked to the old filename.
124 Returns 1 for success, 0 otherwise.
125 .Ip "oct(EXPR)" 8 2
126 Returns the decimal value of EXPR interpreted as an octal string.
127 (If EXPR happens to start off with 0x, interprets it as a hex string instead.)
128 The following will handle decimal, octal and hex in the standard notation:
129 .nf
130
131         $val = oct($val) if $val =~ /^0/;
132
133 .fi
134 .Ip "open(FILEHANDLE,EXPR)" 8 8
135 .Ip "open(FILEHANDLE)" 8
136 .Ip "open FILEHANDLE" 8
137 Opens the file whose filename is given by EXPR, and associates it with
138 FILEHANDLE.
139 If EXPR is omitted, the string variable of the same name as the FILEHANDLE
140 contains the filename.
141 If the filename begins with \*(L">\*(R", the file is opened for output.
142 If the filename begins with \*(L">>\*(R", the file is opened for appending.
143 If the filename begins with \*(L"|\*(R", the filename is interpreted
144 as a command to which output is to be piped, and if the filename ends
145 with a \*(L"|\*(R", the filename is interpreted as command which pipes
146 input to us.
147 (You may not have a command that pipes both in and out.)
148 On non-pipe opens, the filename '\-' represents either stdin or stdout, as
149 appropriate.
150 Open returns 1 upon success, '' otherwise.
151 Examples:
152 .nf
153     
154 .ne 3
155     $article = 100;
156     open article || die "Can't find article $article";
157     while (<article>) {\|.\|.\|.
158
159     open(log, '>>/usr/spool/news/twitlog'\|);
160
161     open(article, "caeser <$article |"\|);              # decrypt article
162
163     open(extract, "|sort >/tmp/Tmp$$"\|);               # $$ is our process#
164
165 .fi
166 .Ip "ord(EXPR)" 8 3
167 Returns the ascii value of the first character of EXPR.
168 .Ip "pop ARRAY" 8 6
169 .Ip "pop(ARRAY)" 8
170 Pops and returns the last value of the array, shortening the array by 1.
171 ''' $tmp = $ARRAY[$#ARRAY--]
172 .Ip "print FILEHANDLE LIST" 8 9
173 .Ip "print LIST" 8
174 .Ip "print" 8
175 Prints a string or comma-separated list of strings.
176 If FILEHANDLE is omitted, prints by default to standard output (or to the
177 last selected output channel\*(--see select()).
178 If LIST is also omitted, prints $_ to stdout.
179 LIST may also be an array value.
180 To set the default output channel to something other than stdout use the select operation.
181 .Ip "printf FILEHANDLE LIST" 8 9
182 .Ip "printf LIST" 8
183 Equivalent to a "print FILEHANDLE sprintf(LIST)".
184 .Ip "push(ARRAY,EXPR)" 8 7
185 Treats ARRAY (@ is optional) as a stack, and pushes the value of EXPR
186 onto the end of ARRAY.
187 The length of ARRAY increases by 1.
188 Has the same effect as
189 .nf
190
191     $ARRAY[$#ARRAY+1] = EXPR;
192
193 .fi
194 but is more efficient.
195 .Ip "redo LABEL" 8 8
196 .Ip "redo" 8
197 The
198 .I redo
199 command restarts the loop block without evaluating the conditional again.
200 The
201 .I continue
202 block, if any, is not executed.
203 If the LABEL is omitted, the command refers to the innermost enclosing loop.
204 This command is normally used by programs that want to lie to themselves
205 about what was just input:
206 .nf
207
208 .ne 16
209         # a simpleminded Pascal comment stripper
210         # (warning: assumes no { or } in strings)
211         line: while (<stdin>) {
212                 while (s|\|({.*}.*\|){.*}|$1 \||) {}
213                 s|{.*}| \||;
214                 if (s|{.*| \||) {
215                         $front = $_;
216                         while (<stdin>) {
217                                 if (\|/\|}/\|) {        # end of comment?
218                                         s|^|$front{|;
219                                         redo line;
220                                 }
221                         }
222                 }
223                 print;
224         }
225
226 .fi
227 .Ip "rename(OLDNAME,NEWNAME)" 8 2
228 Changes the name of a file.
229 Returns 1 for success, 0 otherwise.
230 .Ip "reset EXPR" 8 3
231 Generally used in a
232 .I continue
233 block at the end of a loop to clear variables and reset ?? searches
234 so that they work again.
235 The expression is interpreted as a list of single characters (hyphens allowed
236 for ranges).
237 All string variables beginning with one of those letters are set to the null
238 string.
239 If the expression is omitted, one-match searches (?pattern?) are reset to
240 match again.
241 Always returns 1.
242 Examples:
243 .nf
244
245 .ne 3
246     reset 'X';  \h'|2i'# reset all X variables
247     reset 'a-z';\h'|2i'# reset lower case variables
248     reset;      \h'|2i'# just reset ?? searches
249
250 .fi
251 .Ip "s/PATTERN/REPLACEMENT/g" 8 3
252 Searches a string for a pattern, and if found, replaces that pattern with the
253 replacement text and returns the number of substitutions made.
254 Otherwise it returns false (0).
255 The \*(L"g\*(R" is optional, and if present, indicates that all occurences
256 of the pattern are to be replaced.
257 Any delimiter may replace the slashes; if single quotes are used, no
258 interpretation is done on the replacement string.
259 If no string is specified via the =~ or !~ operator,
260 the $_ string is searched and modified.
261 (The string specified with =~ must be a string variable or array element,
262 i.e. an lvalue.)
263 If the pattern contains a $ that looks like a variable rather than an
264 end-of-string test, the variable will be interpolated into the pattern at
265 run-time.
266 See also the section on regular expressions.
267 Examples:
268 .nf
269
270     s/\|\e\|bgreen\e\|b/mauve/g;                # don't change wintergreen
271
272     $path \|=~ \|s|\|/usr/bin|\|/usr/local/bin|;
273
274     s/Login: $foo/Login: $bar/; # run-time pattern
275
276     s/\|([^ \|]*\|) *\|([^ \|]*\|)\|/\|$2 $1/;  # reverse 1st two fields
277
278 .fi
279 (Note the use of $ instead of \|\e\| in the last example.  See section
280 on regular expressions.)
281 .Ip "seek(FILEHANDLE,POSITION,WHENCE)" 8 3
282 Randomly positions the file pointer for FILEHANDLE, just like the fseek()
283 call of stdio.
284 Returns 1 upon success, 0 otherwise.
285 .Ip "select(FILEHANDLE)" 8 3
286 Sets the current default filehandle for output.
287 This has two effects: first, a
288 .I write
289 or a
290 .I print
291 without a filehandle will default to this FILEHANDLE.
292 Second, references to variables related to output will refer to this output
293 channel.
294 For example, if you have to set the top of form format for more than
295 one output channel, you might do the following:
296 .nf
297
298 .ne 4
299     select(report1);
300     $^ = 'report1_top';
301     select(report2);
302     $^ = 'report2_top';
303
304 .fi
305 Select happens to return TRUE if the file is currently open and FALSE otherwise,
306 but this has no effect on its operation.
307 .Ip "shift(ARRAY)" 8 6
308 .Ip "shift ARRAY" 8
309 .Ip "shift" 8
310 Shifts the first value of the array off, shortening the array by 1 and
311 moving everything down.
312 If ARRAY is omitted, shifts the ARGV array.
313 See also unshift().
314 .Ip "sleep EXPR" 8 6
315 .Ip "sleep" 8
316 Causes the script to sleep for EXPR seconds, or forever if no EXPR.
317 May be interrupted by sending the process a SIGALARM.
318 Returns the number of seconds actually slept.
319 .Ip "split(/PATTERN/,EXPR)" 8 8
320 .Ip "split(/PATTERN/)" 8
321 .Ip "split" 8
322 Splits a string into an array of strings, and returns it.
323 If EXPR is omitted, splits the $_ string.
324 If PATTERN is also omitted, splits on whitespace (/[\ \et\en]+/).
325 Anything matching PATTERN is taken to be a delimiter separating the fields.
326 (Note that the delimiter may be longer than one character.)
327 Trailing null fields are stripped, which potential users of pop() would
328 do well to remember.
329 A pattern matching the null string will split into separate characters.
330 .sp
331 Example:
332 .nf
333
334 .ne 5
335         open(passwd, '/etc/passwd');
336         while (<passwd>) {
337 .ie t \{\
338                 ($login, $passwd, $uid, $gid, $gcos, $home, $shell) = split(\|/\|:\|/\|);
339 'br\}
340 .el \{\
341                 ($login, $passwd, $uid, $gid, $gcos, $home, $shell)
342                         = split(\|/\|:\|/\|);
343 'br\}
344                 .\|.\|.
345         }
346
347 .fi
348 (Note that $shell above will still have a newline on it.  See chop().)
349 See also
350 .IR join .
351 .Ip "sprintf(FORMAT,LIST)" 8 4
352 Returns a string formatted by the usual printf conventions.
353 The * character is not supported.
354 .Ip "sqrt(EXPR)" 8 3
355 Return the square root of EXPR.
356 .Ip "stat(FILEHANDLE)" 8 6
357 .Ip "stat(EXPR)" 8
358 Returns a 13-element array giving the statistics for a file, either the file
359 opened via FILEHANDLE, or named by EXPR.
360 Typically used as follows:
361 .nf
362
363 .ne 3
364     ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
365        $atime,$mtime,$ctime,$blksize,$blocks)
366            = stat($filename);
367
368 .fi
369 .Ip "substr(EXPR,OFFSET,LEN)" 8 2
370 Extracts a substring out of EXPR and returns it.
371 First character is at offset 0, or whatever you've set $[ to.
372 .Ip "system LIST" 8 6
373 Does exactly the same thing as \*(L"exec LIST\*(R" except that a fork
374 is done first, and the parent process waits for the child process to complete.
375 Note that argument processing varies depending on the number of arguments.
376 See exec.
377 .Ip "tell(FILEHANDLE)" 8 6
378 .Ip "tell" 8
379 Returns the current file position for FILEHANDLE.
380 If FILEHANDLE is omitted, assumes the file last read.
381 .Ip "time" 8 4
382 Returns the number of seconds since January 1, 1970.
383 Suitable for feeding to gmtime() and localtime().
384 .Ip "times" 8 4
385 Returns a four-element array giving the user and system times, in seconds, for this
386 process and the children of this process.
387 .sp
388     ($user,$system,$cuser,$csystem) = times;
389 .sp
390 .Ip "tr/SEARCHLIST/REPLACEMENTLIST/" 8 5
391 .Ip "y/SEARCHLIST/REPLACEMENTLIST/" 8
392 Translates all occurences of the characters found in the search list with
393 the corresponding character in the replacement list.
394 It returns the number of characters replaced.
395 If no string is specified via the =~ or !~ operator,
396 the $_ string is translated.
397 (The string specified with =~ must be a string variable or array element,
398 i.e. an lvalue.)
399 For
400 .I sed
401 devotees,
402 .I y
403 is provided as a synonym for
404 .IR tr .
405 Examples:
406 .nf
407
408     $ARGV[1] \|=~ \|y/A-Z/a-z/; \h'|3i'# canonicalize to lower case
409
410     $cnt = tr/*/*/;             \h'|3i'# count the stars in $_
411
412 .fi
413 .Ip "umask(EXPR)" 8 3
414 Sets the umask for the process and returns the old one.
415 .Ip "unlink LIST" 8 2
416 Deletes a list of files.
417 LIST may be an array.
418 Returns the number of files successfully deleted.
419 Note: in order to use the value you must put the whole thing in parentheses:
420 .nf
421
422         $cnt = (unlink 'a','b','c');
423
424 .fi
425 .Ip "unshift(ARRAY,LIST)" 8 4
426 Does the opposite of a shift.
427 Prepends list to the front of the array, and returns the number of elements
428 in the new array.
429 .nf
430
431         unshift(ARGV,'-e') unless $ARGV[0] =~ /^-/;
432
433 .fi
434 .Ip "values(ASSOC_ARRAY)" 8 6
435 Returns a normal array consisting of all the values of the named associative
436 array.
437 The values are returned in an apparently random order, but it is the same order
438 as either the keys() or each() function produces (given that the associative array
439 has not been modified).
440 See also keys() and each().
441 .Ip "write(FILEHANDLE)" 8 6
442 .Ip "write(EXPR)" 8
443 .Ip "write(\|)" 8
444 Writes a formatted record (possibly multi-line) to the specified file,
445 using the format associated with that file.
446 By default the format for a file is the one having the same name is the
447 filehandle, but the format for the current output channel (see
448 .IR select )
449 may be set explicitly
450 by assigning the name of the format to the $~ variable.
451 .sp
452 Top of form processing is handled automatically:
453 if there is insufficient room on the current page for the formatted 
454 record, the page is advanced, a special top-of-page format is used
455 to format the new page header, and then the record is written.
456 By default the top-of-page format is \*(L"top\*(R", but it
457 may be set to the
458 format of your choice by assigning the name to the $^ variable.
459 .sp
460 If FILEHANDLE is unspecified, output goes to the current default output channel,
461 which starts out as stdout but may be changed by the
462 .I select
463 operator.
464 If the FILEHANDLE is an EXPR, then the expression is evaluated and the
465 resulting string is used to look up the name of the FILEHANDLE at run time.
466 For more on formats, see the section on formats later on.
467 .Sh "Subroutines"
468 A subroutine may be declared as follows:
469 .nf
470
471     sub NAME BLOCK
472
473 .fi
474 .PP
475 Any arguments passed to the routine come in as array @_,
476 that is ($_[0], $_[1], .\|.\|.).
477 The return value of the subroutine is the value of the last expression
478 evaluated.
479 There are no local variables\*(--everything is a global variable.
480 .PP
481 A subroutine is called using the
482 .I do
483 operator.
484 (CAVEAT: For efficiency reasons recursive subroutine calls are not currently
485 supported.
486 This restriction may go away in the future.  Then again, it may not.)
487 .nf
488
489 .ne 12
490 Example:
491
492         sub MAX {
493                 $max = pop(@_);
494                 while ($foo = pop(@_)) {
495                         $max = $foo \|if \|$max < $foo;
496                 }
497                 $max;
498         }
499
500         .\|.\|.
501         $bestday = do MAX($mon,$tue,$wed,$thu,$fri);
502
503 .ne 21
504 Example:
505
506         # get a line, combining continuation lines
507         #  that start with whitespace
508         sub get_line {
509                 $thisline = $lookahead;
510                 line: while ($lookahead = <stdin>) {
511                         if ($lookahead \|=~ \|/\|^[ \^\e\|t]\|/\|) {
512                                 $thisline \|.= \|$lookahead;
513                         }
514                         else {
515                                 last line;
516                         }
517                 }
518                 $thisline;
519         }
520
521         $lookahead = <stdin>;   # get first line
522         while ($_ = get_line(\|)) {
523                 .\|.\|.
524         }
525
526 .fi
527 .nf
528 .ne 6
529 Use array assignment to name your formal arguments:
530
531         sub maybeset {
532                 ($key,$value) = @_;
533                 $foo{$key} = $value unless $foo{$key};
534         }
535
536 .fi
537 .Sh "Regular Expressions"
538 The patterns used in pattern matching are regular expressions such as
539 those used by
540 .IR egrep (1).
541 In addition, \ew matches an alphanumeric character and \eW a nonalphanumeric.
542 Word boundaries may be matched by \eb, and non-boundaries by \eB.
543 The bracketing construct \|(\ .\|.\|.\ \|) may also be used, $<digit>
544 matches the digit'th substring, where digit can range from 1 to 9.
545 (You can also use the old standby \e<digit> in search patterns,
546 but $<digit> also works in replacement patterns and in the block controlled
547 by the current conditional.)
548 $+ returns whatever the last bracket match matched.
549 $& returns the entire matched string.
550 Up to 10 alternatives may given in a pattern, separated by |, with the
551 caveat that \|(\ .\|.\|.\ |\ .\|.\|.\ \|) is illegal.
552 Examples:
553 .nf
554     
555         s/\|^\|([^ \|]*\|) \|*([^ \|]*\|)\|/\|$2 $1\|/; # swap first two words
556
557 .ne 5
558         if (/\|Time: \|(.\|.\|):\|(.\|.\|):\|(.\|.\|)\|/\|) {
559                 $hours = $1;
560                 $minutes = $2;
561                 $seconds = $3;
562         }
563
564 .fi
565 By default, the ^ character matches only the beginning of the string, and
566 .I perl
567 does certain optimizations with the assumption that the string contains
568 only one line.
569 You may, however, wish to treat a string as a multi-line buffer, such that
570 the ^ will match after any newline within the string.
571 At the cost of a little more overhead, you can do this by setting the variable
572 $* to 1.
573 Setting it back to 0 makes
574 .I perl
575 revert to its old behavior.
576 .Sh "Formats"
577 Output record formats for use with the
578 .I write
579 operator may declared as follows:
580 .nf
581
582 .ne 3
583     format NAME =
584     FORMLIST
585     .
586
587 .fi
588 If name is omitted, format \*(L"stdout\*(R" is defined.
589 FORMLIST consists of a sequence of lines, each of which may be of one of three
590 types:
591 .Ip 1. 4
592 A comment.
593 .Ip 2. 4
594 A \*(L"picture\*(R" line giving the format for one output line.
595 .Ip 3. 4
596 An argument line supplying values to plug into a picture line.
597 .PP
598 Picture lines are printed exactly as they look, except for certain fields
599 that substitute values into the line.
600 Each picture field starts with either @ or ^.
601 The @ field (not to be confused with the array marker @) is the normal
602 case; ^ fields are used
603 to do rudimentary multi-line text block filling.
604 The length of the field is supplied by padding out the field
605 with multiple <, >, or | characters to specify, respectively, left justfication,
606 right justification, or centering.
607 If any of the values supplied for these fields contains a newline, only
608 the text up to the newline is printed.
609 The special field @* can be used for printing multi-line values.
610 It should appear by itself on a line.
611 .PP
612 The values are specified on the following line, in the same order as
613 the picture fields.
614 They must currently be either string variable names or string literals (or
615 pseudo-literals).
616 Currently you can separate values with spaces, but commas may be placed
617 between values to prepare for possible future versions in which full expressions
618 are allowed as values.
619 .PP
620 Picture fields that begin with ^ rather than @ are treated specially.
621 The value supplied must be a string variable name which contains a text
622 string.
623 .I Perl
624 puts as much text as it can into the field, and then chops off the front
625 of the string so that the next time the string variable is referenced,
626 more of the text can be printed.
627 Normally you would use a sequence of fields in a vertical stack to print
628 out a block of text.
629 If you like, you can end the final field with .\|.\|., which will appear in the
630 output if the text was too long to appear in its entirety.
631 .PP
632 Since use of ^ fields can produce variable length records if the text to be
633 formatted is short, you can suppress blank lines by putting the tilde (~)
634 character anywhere in the line.
635 (Normally you should put it in the front if possible.)
636 The tilde will be translated to a space upon output.
637 .PP
638 Examples:
639 .nf
640 .lg 0
641 .cs R 25
642
643 .ne 10
644 # a report on the /etc/passwd file
645 format top =
646 \&                        Passwd File
647 Name                Login    Office   Uid   Gid Home
648 ------------------------------------------------------------------
649 \&.
650 format stdout =
651 @<<<<<<<<<<<<<<<<<< @||||||| @<<<<<<@>>>> @>>>> @<<<<<<<<<<<<<<<<<
652 $name               $login   $office $uid $gid  $home
653 \&.
654
655 .ne 29
656 # a report from a bug report form
657 format top =
658 \&                        Bug Reports
659 @<<<<<<<<<<<<<<<<<<<<<<<     @|||         @>>>>>>>>>>>>>>>>>>>>>>>
660 $system;                      $%;         $date
661 ------------------------------------------------------------------
662 \&.
663 format stdout =
664 Subject: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
665 \&         $subject
666 Index: @<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
667 \&       $index                        $description
668 Priority: @<<<<<<<<<< Date: @<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
669 \&          $priority         $date    $description
670 From: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
671 \&      $from                          $description
672 Assigned to: @<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
673 \&             $programmer             $description
674 \&~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
675 \&                                     $description
676 \&~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
677 \&                                     $description
678 \&~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
679 \&                                     $description
680 \&~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
681 \&                                     $description
682 \&~                                    ^<<<<<<<<<<<<<<<<<<<<<<<...
683 \&                                     $description
684 \&.
685
686 .cs R
687 .lg
688 It is possible to intermix prints with writes on the same output channel,
689 but you'll have to handle $\- (lines left on the page) yourself.
690 .fi
691 .PP
692 If you are printing lots of fields that are usually blank, you should consider
693 using the reset operator between records.
694 Not only is it more efficient, but it can prevent the bug of adding another
695 field and forgetting to zero it.
696 .Sh "Predefined Names"
697 The following names have special meaning to
698 .IR perl .
699 I could have used alphabetic symbols for some of these, but I didn't want
700 to take the chance that someone would say reset "a-zA-Z" and wipe them all
701 out.
702 You'll just have to suffer along with these silly symbols.
703 Most of them have reasonable mnemonics, or analogues in one of the shells.
704 .Ip $_ 8
705 The default input and pattern-searching space.
706 The following pairs are equivalent:
707 .nf
708
709 .ne 2
710         while (<>) {\|.\|.\|.   # only equivalent in while!
711         while ($_ = <>) {\|.\|.\|.
712
713 .ne 2
714         /\|^Subject:/
715         $_ \|=~ \|/\|^Subject:/
716
717 .ne 2
718         y/a-z/A-Z/
719         $_ =~ y/a-z/A-Z/
720
721 .ne 2
722         chop
723         chop($_)
724
725 .fi 
726 (Mnemonic: underline is understood in certain operations.)
727 .Ip $. 8
728 The current input line number of the last file that was read.
729 Readonly.
730 (Mnemonic: many programs use . to mean the current line number.)
731 .Ip $/ 8
732 The input record separator, newline by default.
733 Works like awk's RS variable, including treating blank lines as delimiters
734 if set to the null string.
735 If set to a value longer than one character, only the first character is used.
736 (Mnemonic: / is used to delimit line boundaries when quoting poetry.)
737 .Ip $, 8
738 The output field separator for the print operator.
739 Ordinarily the print operator simply prints out the comma separated fields
740 you specify.
741 In order to get behavior more like awk, set this variable as you would set
742 awk's OFS variable to specify what is printed between fields.
743 (Mnemonic: what is printed when there is a , in your print statement.)
744 .Ip $\e 8
745 The output record separator for the print operator.
746 Ordinarily the print operator simply prints out the comma separated fields
747 you specify, with no trailing newline or record separator assumed.
748 In order to get behavior more like awk, set this variable as you would set
749 awk's ORS variable to specify what is printed at the end of the print.
750 (Mnemonic: you set $\e instead of adding \en at the end of the print.
751 Also, it's just like /, but it's what you get \*(L"back\*(R" from perl.)
752 .Ip $# 8
753 The output format for printed numbers.
754 This variable is a half-hearted attempt to emulate awk's OFMT variable.
755 There are times, however, when awk and perl have differing notions of what
756 is in fact numeric.
757 Also, the initial value is %.20g rather than %.6g, so you need to set $#
758 explicitly to get awk's value.
759 (Mnemonic: # is the number sign.)
760 .Ip $% 8
761 The current page number of the currently selected output channel.
762 (Mnemonic: % is page number in nroff.)
763 .Ip $= 8
764 The current page length (printable lines) of the currently selected output
765 channel.
766 Default is 60.
767 (Mnemonic: = has horizontal lines.)
768 .Ip $\- 8
769 The number of lines left on the page of the currently selected output channel.
770 (Mnemonic: lines_on_page - lines_printed.)
771 .Ip $~ 8
772 The name of the current report format for the currently selected output
773 channel.
774 (Mnemonic: brother to $^.)
775 .Ip $^ 8
776 The name of the current top-of-page format for the currently selected output
777 channel.
778 (Mnemonic: points to top of page.)
779 .Ip $| 8
780 If set to nonzero, forces a flush after every write or print on the currently
781 selected output channel.
782 Default is 0.
783 Note that stdout will typically be line buffered if output is to the
784 terminal and block buffered otherwise.
785 Setting this variable is useful primarily when you are outputting to a pipe,
786 such as when you are running a perl script under rsh and want to see the
787 output as it's happening.
788 (Mnemonic: when you want your pipes to be piping hot.)
789 .Ip $$ 8
790 The process number of the
791 .I perl
792 running this script.
793 (Mnemonic: same as shells.)
794 .Ip $? 8
795 The status returned by the last backtick (``) command.
796 (Mnemonic: same as sh and ksh.)
797 .Ip $+ 8 4
798 The last bracket matched by the last search pattern.
799 This is useful if you don't know which of a set of alternative patterns
800 matched.
801 For example:
802 .nf
803
804     /Version: \|(.*\|)|Revision: \|(.*\|)\|/ \|&& \|($rev = $+);
805
806 .fi
807 (Mnemonic: be positive and forward looking.)
808 .Ip $* 8 2
809 Set to 1 to do multiline matching within a string, 0 to assume strings contain
810 a single line.
811 Default is 0.
812 (Mnemonic: * matches multiple things.)
813 .Ip $0 8
814 Contains the name of the file containing the
815 .I perl
816 script being executed.
817 The value should be copied elsewhere before any pattern matching happens, which
818 clobbers $0.
819 (Mnemonic: same as sh and ksh.)
820 .Ip $[ 8 2
821 The index of the first element in an array, and of the first character in
822 a substring.
823 Default is 0, but you could set it to 1 to make
824 .I perl
825 behave more like
826 .I awk
827 (or Fortran)
828 when subscripting and when evaluating the index() and substr() functions.
829 (Mnemonic: [ begins subscripts.)
830 .Ip $! 8 2
831 The current value of errno, with all the usual caveats.
832 (Mnemonic: What just went bang?)
833 .Ip @ARGV 8 3
834 The array ARGV contains the command line arguments intended for the script.
835 Note that $#ARGV is the generally number of arguments minus one, since
836 $ARGV[0] is the first argument, NOT the command name.
837 See $0 for the command name.
838 .Ip $ENV{expr} 8 2
839 The associative array ENV contains your current environment.
840 Setting a value in ENV changes the environment for child processes.
841 .Ip $SIG{expr} 8 2
842 The associative array SIG is used to set signal handlers for various signals.
843 Example:
844 .nf
845
846 .ne 12
847         sub handler {   # 1st argument is signal name
848                 ($sig) = @_;
849                 print "Caught a SIG$sig--shutting down\n";
850                 close(log);
851                 exit(0);
852         }
853
854         $SIG{'INT'} = 'handler';
855         $SIG{'QUIT'} = 'handler';
856         ...
857         $SIG{'INT'} = 'DEFAULT';        # restore default action
858         $SIG{'QUIT'} = 'IGNORE';        # ignore SIGQUIT
859
860 .fi
861 .SH ENVIRONMENT
862 .I Perl
863 currently uses no environment variables, except to make them available
864 to the script being executed, and to child processes.
865 However, scripts running setuid would do well to execute the following lines
866 before doing anything else, just to keep people honest:
867 .nf
868
869 .ne 3
870     $ENV{'PATH'} = '/bin:/usr/bin';    # or whatever you need
871     $ENV{'SHELL'} = '/bin/sh' if $ENV{'SHELL'};
872     $ENV{'IFS'} = '' if $ENV{'IFS'};
873
874 .fi
875 .SH AUTHOR
876 Larry Wall <lwall@jpl-devvax.Jpl.Nasa.Gov>
877 .SH FILES
878 /tmp/perl\-eXXXXXX      temporary file for
879 .B \-e
880 commands.
881 .SH SEE ALSO
882 a2p     awk to perl translator
883 .br
884 s2p     sed to perl translator
885 .SH DIAGNOSTICS
886 Compilation errors will tell you the line number of the error, with an
887 indication of the next token or token type that was to be examined.
888 (In the case of a script passed to
889 .I perl
890 via
891 .B \-e
892 switches, each
893 .B \-e
894 is counted as one line.)
895 .SH TRAPS
896 Accustomed awk users should take special note of the following:
897 .Ip * 4 2
898 Semicolons are required after all simple statements in perl.  Newline
899 is not a statement delimiter.
900 .Ip * 4 2
901 Curly brackets are required on ifs and whiles.
902 .Ip * 4 2
903 Variables begin with $ or @ in perl.
904 .Ip * 4 2
905 Arrays index from 0 unless you set $[.
906 Likewise string positions in substr() and index().
907 .Ip * 4 2
908 You have to decide whether your array has numeric or string indices.
909 .Ip * 4 2
910 You have to decide whether you want to use string or numeric comparisons.
911 .Ip * 4 2
912 Reading an input line does not split it for you.  You get to split it yourself
913 to an array.
914 And split has different arguments.
915 .Ip * 4 2
916 The current input line is normally in $_, not $0.
917 It generally does not have the newline stripped.
918 ($0 is initially the name of the program executed, then the last matched
919 string.)
920 .Ip * 4 2
921 The current filename is $ARGV, not $FILENAME.
922 NR, RS, ORS, OFS, and OFMT have equivalents with other symbols.
923 FS doesn't have an equivalent, since you have to be explicit about
924 split statements.
925 .Ip * 4 2
926 $<digit> does not refer to fields--it refers to substrings matched by the last
927 match pattern.
928 .Ip * 4 2
929 The print statement does not add field and record separators unless you set
930 $, and $\e.
931 .Ip * 4 2
932 You must open your files before you print to them.
933 .Ip * 4 2
934 The range operator is \*(L"..\*(R", not comma.
935 (The comma operator works as in C.)
936 .Ip * 4 2
937 The match operator is \*(L"=~\*(R", not \*(L"~\*(R".
938 (\*(L"~\*(R" is the one's complement operator.)
939 .Ip * 4 2
940 The concatenation operator is \*(L".\*(R", not the null string.
941 (Using the null string would render \*(L"/pat/ /pat/\*(R" unparseable,
942 since the third slash would be interpreted as a division operator\*(--the
943 tokener is in fact slightly context sensitive for operators like /, ?, and <.
944 And in fact, . itself can be the beginning of a number.)
945 .Ip * 4 2
946 The \ennn construct in patterns must be given as [\ennn] to avoid interpretation
947 as a backreference.
948 .Ip * 4 2
949 Next, exit, and continue work differently.
950 .Ip * 4 2
951 When in doubt, run the awk construct through a2p and see what it gives you.
952 .PP
953 Cerebral C programmers should take note of the following:
954 .Ip * 4 2
955 Curly brackets are required on ifs and whiles.
956 .Ip * 4 2
957 You should use \*(L"elsif\*(R" rather than \*(L"else if\*(R"
958 .Ip * 4 2
959 Break and continue become last and next, respectively.
960 .Ip * 4 2
961 There's no switch statement.
962 .Ip * 4 2
963 Variables begin with $ or @ in perl.
964 .Ip * 4 2
965 Printf does not implement *.
966 .Ip * 4 2
967 Comments begin with #, not /*.
968 .Ip * 4 2
969 You can't take the address of anything.
970 .Ip * 4 2
971 Subroutines are not reentrant.
972 .Ip * 4 2
973 ARGV must be capitalized.
974 .Ip * 4 2
975 The \*(L"system\*(R" calls link, unlink, rename, etc. return 1 for success, not 0.
976 .Ip * 4 2
977 Signal handlers deal with signal names, not numbers.
978 .PP
979 Seasoned sed programmers should take note of the following:
980 .Ip * 4 2
981 Backreferences in substitutions use $ rather than \e.
982 .Ip * 4 2
983 The pattern matching metacharacters (, ), and | do not have backslashes in front.
984 .SH BUGS
985 .PP
986 You can't currently dereference array elements inside a double-quoted string.
987 You must assign them to a temporary and interpolate that.
988 .PP
989 Associative arrays really ought to be first class objects.
990 .PP
991 Recursive subroutines are not currently supported, due to the way temporary
992 values are stored in the syntax tree.
993 .PP
994 Arrays ought to be passable to subroutines just as strings are.
995 .PP
996 The array literal consisting of one element is currently misinterpreted, i.e.
997 .nf
998
999         @array = (123);
1000
1001 .fi
1002 doesn't work right.
1003 .PP
1004 .I Perl
1005 actually stands for Pathologically Eclectic Rubbish Lister, but don't tell
1006 anyone I said that.
1007 .rn }` ''