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