You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

perl.man.1 28KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997
  1. .rn '' }`
  2. ''' $Header: perl.man.1,v 1.0 87/12/18 16:18:16 root Exp $
  3. '''
  4. ''' $Log: perl.man.1,v $
  5. ''' Revision 1.0 87/12/18 16:18:16 root
  6. ''' Initial revision
  7. '''
  8. '''
  9. .de Sh
  10. .br
  11. .ne 5
  12. .PP
  13. \fB\\$1\fR
  14. .PP
  15. ..
  16. .de Sp
  17. .if t .sp .5v
  18. .if n .sp
  19. ..
  20. .de Ip
  21. .br
  22. .ie \\n.$>=3 .ne \\$3
  23. .el .ne 3
  24. .IP "\\$1" \\$2
  25. ..
  26. '''
  27. ''' Set up \*(-- to give an unbreakable dash;
  28. ''' string Tr holds user defined translation string.
  29. ''' Bell System Logo is used as a dummy character.
  30. '''
  31. .tr \(bs-|\(bv\*(Tr
  32. .ie n \{\
  33. .ds -- \(bs-
  34. .if (\n(.H=4u)&(1m=24u) .ds -- \(bs\h'-12u'\(bs\h'-12u'-\" diablo 10 pitch
  35. .if (\n(.H=4u)&(1m=20u) .ds -- \(bs\h'-12u'\(bs\h'-8u'-\" diablo 12 pitch
  36. .ds L" ""
  37. .ds R" ""
  38. .ds L' '
  39. .ds R' '
  40. 'br\}
  41. .el\{\
  42. .ds -- \(em\|
  43. .tr \*(Tr
  44. .ds L" ``
  45. .ds R" ''
  46. .ds L' `
  47. .ds R' '
  48. 'br\}
  49. .TH PERL 1 LOCAL
  50. .SH NAME
  51. perl - Practical Extraction and Report Language
  52. .SH SYNOPSIS
  53. .B perl [options] filename args
  54. .SH DESCRIPTION
  55. .I Perl
  56. is a interpreted language optimized for scanning arbitrary text files,
  57. extracting information from those text files, and printing reports based
  58. on that information.
  59. It's also a good language for many system management tasks.
  60. The language is intended to be practical (easy to use, efficient, complete)
  61. rather than beautiful (tiny, elegant, minimal).
  62. It combines (in the author's opinion, anyway) some of the best features of C,
  63. \fIsed\fR, \fIawk\fR, and \fIsh\fR,
  64. so people familiar with those languages should have little difficulty with it.
  65. (Language historians will also note some vestiges of \fIcsh\fR, Pascal, and
  66. even BASIC-PLUS.)
  67. Expression syntax corresponds quite closely to C expression syntax.
  68. If you have a problem that would ordinarily use \fIsed\fR
  69. or \fIawk\fR or \fIsh\fR, but it
  70. exceeds their capabilities or must run a little faster,
  71. and you don't want to write the silly thing in C, then
  72. .I perl
  73. may be for you.
  74. There are also translators to turn your sed and awk scripts into perl scripts.
  75. OK, enough hype.
  76. .PP
  77. Upon startup,
  78. .I perl
  79. looks for your script in one of the following places:
  80. .Ip 1. 4 2
  81. Specified line by line via
  82. .B \-e
  83. switches on the command line.
  84. .Ip 2. 4 2
  85. Contained in the file specified by the first filename on the command line.
  86. (Note that systems supporting the #! notation invoke interpreters this way.)
  87. .Ip 3. 4 2
  88. Passed in via standard input.
  89. .PP
  90. After locating your script,
  91. .I perl
  92. compiles it to an internal form.
  93. If the script is syntactically correct, it is executed.
  94. .Sh "Options"
  95. Note: on first reading this section won't make much sense to you. It's here
  96. at the front for easy reference.
  97. .PP
  98. A single-character option may be combined with the following option, if any.
  99. This is particularly useful when invoking a script using the #! construct which
  100. only allows one argument. Example:
  101. .nf
  102. .ne 2
  103. #!/bin/perl -spi.bak # same as -s -p -i.bak
  104. .\|.\|.
  105. .fi
  106. Options include:
  107. .TP 5
  108. .B \-D<number>
  109. sets debugging flags.
  110. To watch how it executes your script, use
  111. .B \-D14.
  112. (This only works if debugging is compiled into your
  113. .IR perl .)
  114. .TP 5
  115. .B \-e commandline
  116. may be used to enter one line of script.
  117. Multiple
  118. .B \-e
  119. commands may be given to build up a multi-line script.
  120. If
  121. .B \-e
  122. is given,
  123. .I perl
  124. will not look for a script filename in the argument list.
  125. .TP 5
  126. .B \-i<extension>
  127. specifies that files processed by the <> construct are to be edited
  128. in-place.
  129. It does this by renaming the input file, opening the output file by the
  130. same name, and selecting that output file as the default for print statements.
  131. The extension, if supplied, is added to the name of the
  132. old file to make a backup copy.
  133. If no extension is supplied, no backup is made.
  134. Saying \*(L"perl -p -i.bak -e "s/foo/bar/;" ... \*(R" is the same as using
  135. the script:
  136. .nf
  137. .ne 2
  138. #!/bin/perl -pi.bak
  139. s/foo/bar/;
  140. which is equivalent to
  141. .ne 14
  142. #!/bin/perl
  143. while (<>) {
  144. if ($ARGV ne $oldargv) {
  145. rename($ARGV,$ARGV . '.bak');
  146. open(ARGVOUT,">$ARGV");
  147. select(ARGVOUT);
  148. $oldargv = $ARGV;
  149. }
  150. s/foo/bar/;
  151. }
  152. continue {
  153. print; # this prints to original filename
  154. }
  155. select(stdout);
  156. .fi
  157. except that the \-i form doesn't need to compare $ARGV to $oldargv to know when
  158. the filename has changed.
  159. It does, however, use ARGVOUT for the selected filehandle.
  160. Note that stdout is restored as the default output filehandle after the loop.
  161. .TP 5
  162. .B \-I<directory>
  163. may be used in conjunction with
  164. .B \-P
  165. to tell the C preprocessor where to look for include files.
  166. By default /usr/include and /usr/lib/perl are searched.
  167. .TP 5
  168. .B \-n
  169. causes
  170. .I perl
  171. to assume the following loop around your script, which makes it iterate
  172. over filename arguments somewhat like \*(L"sed -n\*(R" or \fIawk\fR:
  173. .nf
  174. .ne 3
  175. while (<>) {
  176. ... # your script goes here
  177. }
  178. .fi
  179. Note that the lines are not printed by default.
  180. See
  181. .B \-p
  182. to have lines printed.
  183. .TP 5
  184. .B \-p
  185. causes
  186. .I perl
  187. to assume the following loop around your script, which makes it iterate
  188. over filename arguments somewhat like \fIsed\fR:
  189. .nf
  190. .ne 5
  191. while (<>) {
  192. ... # your script goes here
  193. } continue {
  194. print;
  195. }
  196. .fi
  197. Note that the lines are printed automatically.
  198. To suppress printing use the
  199. .B \-n
  200. switch.
  201. .TP 5
  202. .B \-P
  203. causes your script to be run through the C preprocessor before
  204. compilation by
  205. .I perl.
  206. (Since both comments and cpp directives begin with the # character,
  207. you should avoid starting comments with any words recognized
  208. by the C preprocessor such as \*(L"if\*(R", \*(L"else\*(R" or \*(L"define\*(R".)
  209. .TP 5
  210. .B \-s
  211. enables some rudimentary switch parsing for switches on the command line
  212. after the script name but before any filename arguments.
  213. Any switch found there will set the corresponding variable in the
  214. .I perl
  215. script.
  216. The following script prints \*(L"true\*(R" if and only if the script is
  217. invoked with a -x switch.
  218. .nf
  219. .ne 2
  220. #!/bin/perl -s
  221. if ($x) { print "true\en"; }
  222. .fi
  223. .Sh "Data Types and Objects"
  224. .PP
  225. Perl has about two and a half data types: strings, arrays of strings, and
  226. associative arrays.
  227. Strings and arrays of strings are first class objects, for the most part,
  228. in the sense that they can be used as a whole as values in an expression.
  229. Associative arrays can only be accessed on an association by association basis;
  230. they don't have a value as a whole (at least not yet).
  231. .PP
  232. Strings are interpreted numerically as appropriate.
  233. A string is interpreted as TRUE in the boolean sense if it is not the null
  234. string or 0.
  235. Booleans returned by operators are 1 for true and '0' or '' (the null
  236. string) for false.
  237. .PP
  238. References to string variables always begin with \*(L'$\*(R', even when referring
  239. to a string that is part of an array.
  240. Thus:
  241. .nf
  242. .ne 3
  243. $days \h'|2i'# a simple string variable
  244. $days[28] \h'|2i'# 29th element of array @days
  245. $days{'Feb'}\h'|2i'# one value from an associative array
  246. but entire arrays are denoted by \*(L'@\*(R':
  247. @days \h'|2i'# ($days[0], $days[1],\|.\|.\|. $days[n])
  248. .fi
  249. .PP
  250. Any of these four constructs may be assigned to (in compiler lingo, may serve
  251. as an lvalue).
  252. (Additionally, you may find the length of array @days by evaluating
  253. \*(L"$#days\*(R", as in
  254. .IR csh .
  255. [Actually, it's not the length of the array, it's the subscript of the last element, since there is (ordinarily) a 0th element.])
  256. .PP
  257. Every data type has its own namespace.
  258. You can, without fear of conflict, use the same name for a string variable,
  259. an array, an associative array, a filehandle, a subroutine name, and/or
  260. a label.
  261. Since variable and array references always start with \*(L'$\*(R'
  262. or \*(L'@\*(R', the \*(L"reserved\*(R" words aren't in fact reserved
  263. with respect to variable names.
  264. (They ARE reserved with respect to labels and filehandles, however, which
  265. don't have an initial special character.)
  266. Case IS significant\*(--\*(L"FOO\*(R", \*(L"Foo\*(R" and \*(L"foo\*(R" are all
  267. different names.
  268. Names which start with a letter may also contain digits and underscores.
  269. Names which do not start with a letter are limited to one character,
  270. e.g. \*(L"$%\*(R" or \*(L"$$\*(R".
  271. (Many one character names have a predefined significance to
  272. .I perl.
  273. More later.)
  274. .PP
  275. String literals are delimited by either single or double quotes.
  276. They work much like shell quotes:
  277. double-quoted string literals are subject to backslash and variable
  278. substitution; single-quoted strings are not.
  279. The usual backslash rules apply for making characters such as newline, tab, etc.
  280. You can also embed newlines directly in your strings, i.e. they can end on
  281. a different line than they begin.
  282. This is nice, but if you forget your trailing quote, the error will not be
  283. reported until perl finds another line containing the quote character, which
  284. may be much further on in the script.
  285. Variable substitution inside strings is limited (currently) to simple string variables.
  286. The following code segment prints out \*(L"The price is $100.\*(R"
  287. .nf
  288. .ne 2
  289. $Price = '$100';\h'|3.5i'# not interpreted
  290. print "The price is $Price.\e\|n";\h'|3.5i'# interpreted
  291. .fi
  292. .PP
  293. Array literals are denoted by separating individual values by commas, and
  294. enclosing the list in parentheses.
  295. In a context not requiring an array value, the value of the array literal
  296. is the value of the final element, as in the C comma operator.
  297. For example,
  298. .nf
  299. @foo = ('cc', '\-E', $bar);
  300. assigns the entire array value to array foo, but
  301. $foo = ('cc', '\-E', $bar);
  302. .fi
  303. assigns the value of variable bar to variable foo.
  304. Array lists may be assigned to if and only if each element of the list
  305. is an lvalue:
  306. .nf
  307. ($a, $b, $c) = (1, 2, 3);
  308. ($map{'red'}, $map{'blue'}, $map{'green'}) = (0x00f, 0x0f0, 0xf00);
  309. .fi
  310. .PP
  311. Numeric literals are specified in any of the usual floating point or
  312. integer formats.
  313. .PP
  314. There are several other pseudo-literals that you should know about.
  315. If a string is enclosed by backticks (grave accents), it is interpreted as
  316. a command, and the output of that command is the value of the pseudo-literal,
  317. just like in any of the standard shells.
  318. The command is executed each time the pseudo-literal is evaluated.
  319. Unlike in \f2csh\f1, no interpretation is done on the
  320. data\*(--newlines remain newlines.
  321. .PP
  322. Evaluating a filehandle in angle brackets yields the next line
  323. from that file (newline included, so it's never false until EOF).
  324. Ordinarily you must assign that value to a variable,
  325. but there is one situation where in which an automatic assignment happens.
  326. If (and only if) the input symbol is the only thing inside the conditional of a
  327. .I while
  328. loop, the value is
  329. automatically assigned to the variable \*(L"$_\*(R".
  330. (This may seem like an odd thing to you, but you'll use the construct
  331. in almost every
  332. .I perl
  333. script you write.)
  334. Anyway, the following lines are equivalent to each other:
  335. .nf
  336. .ne 3
  337. while ($_ = <stdin>) {
  338. while (<stdin>) {
  339. for (\|;\|<stdin>;\|) {
  340. .fi
  341. The filehandles
  342. .IR stdin ,
  343. .I stdout
  344. and
  345. .I stderr
  346. are predefined.
  347. Additional filehandles may be created with the
  348. .I open
  349. function.
  350. .PP
  351. The null filehandle <> is special and can be used to emulate the behavior of
  352. \fIsed\fR and \fIawk\fR.
  353. Input from <> comes either from standard input, or from each file listed on
  354. the command line.
  355. Here's how it works: the first time <> is evaluated, the ARGV array is checked,
  356. and if it is null, $ARGV[0] is set to '-', which when opened gives you standard
  357. input.
  358. The ARGV array is then processed as a list of filenames.
  359. The loop
  360. .nf
  361. .ne 3
  362. while (<>) {
  363. .\|.\|. # code for each line
  364. }
  365. .ne 10
  366. is equivalent to
  367. unshift(@ARGV, '\-') \|if \|$#ARGV < $[;
  368. while ($ARGV = shift) {
  369. open(ARGV, $ARGV);
  370. while (<ARGV>) {
  371. .\|.\|. # code for each line
  372. }
  373. }
  374. .fi
  375. except that it isn't as cumbersome to say.
  376. It really does shift array ARGV and put the current filename into
  377. variable ARGV.
  378. It also uses filehandle ARGV internally.
  379. You can modify @ARGV before the first <> as long as you leave the first
  380. filename at the beginning of the array.
  381. .PP
  382. If you want to set @ARGV to you own list of files, go right ahead.
  383. If you want to pass switches into your script, you can
  384. put a loop on the front like this:
  385. .nf
  386. .ne 10
  387. while ($_ = $ARGV[0], /\|^\-/\|) {
  388. shift;
  389. last if /\|^\-\|\-$\|/\|;
  390. /\|^\-D\|(.*\|)/ \|&& \|($debug = $1);
  391. /\|^\-v\|/ \|&& \|$verbose++;
  392. .\|.\|. # other switches
  393. }
  394. while (<>) {
  395. .\|.\|. # code for each line
  396. }
  397. .fi
  398. The <> symbol will return FALSE only once.
  399. If you call it again after this it will assume you are processing another
  400. @ARGV list, and if you haven't set @ARGV, will input from stdin.
  401. .Sh "Syntax"
  402. .PP
  403. A
  404. .I perl
  405. script consists of a sequence of declarations and commands.
  406. The only things that need to be declared in
  407. .I perl
  408. are report formats and subroutines.
  409. See the sections below for more information on those declarations.
  410. All objects are assumed to start with a null or 0 value.
  411. The sequence of commands is executed just once, unlike in
  412. .I sed
  413. and
  414. .I awk
  415. scripts, where the sequence of commands is executed for each input line.
  416. While this means that you must explicitly loop over the lines of your input file
  417. (or files), it also means you have much more control over which files and which
  418. lines you look at.
  419. (Actually, I'm lying\*(--it is possible to do an implicit loop with either the
  420. .B \-n
  421. or
  422. .B \-p
  423. switch.)
  424. .PP
  425. A declaration can be put anywhere a command can, but has no effect on the
  426. execution of the primary sequence of commands.
  427. Typically all the declarations are put at the beginning or the end of the script.
  428. .PP
  429. .I Perl
  430. is, for the most part, a free-form language.
  431. (The only exception to this is format declarations, for fairly obvious reasons.)
  432. Comments are indicated by the # character, and extend to the end of the line.
  433. If you attempt to use /* */ C comments, it will be interpreted either as
  434. division or pattern matching, depending on the context.
  435. So don't do that.
  436. .Sh "Compound statements"
  437. In
  438. .IR perl ,
  439. a sequence of commands may be treated as one command by enclosing it
  440. in curly brackets.
  441. We will call this a BLOCK.
  442. .PP
  443. The following compound commands may be used to control flow:
  444. .nf
  445. .ne 4
  446. if (EXPR) BLOCK
  447. if (EXPR) BLOCK else BLOCK
  448. if (EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK
  449. LABEL while (EXPR) BLOCK
  450. LABEL while (EXPR) BLOCK continue BLOCK
  451. LABEL for (EXPR; EXPR; EXPR) BLOCK
  452. LABEL BLOCK continue BLOCK
  453. .fi
  454. (Note that, unlike C and Pascal, these are defined in terms of BLOCKs, not
  455. statements.
  456. This means that the curly brackets are \fIrequired\fR\*(--no dangling statements allowed.
  457. If you want to write conditionals without curly brackets there are several
  458. other ways to do it.
  459. The following all do the same thing:
  460. .nf
  461. .ne 5
  462. if (!open(foo)) { die "Can't open $foo"; }
  463. die "Can't open $foo" unless open(foo);
  464. open(foo) || die "Can't open $foo"; # foo or bust!
  465. open(foo) ? die "Can't open $foo" : 'hi mom';
  466. .fi
  467. though the last one is a bit exotic.)
  468. .PP
  469. The
  470. .I if
  471. statement is straightforward.
  472. Since BLOCKs are always bounded by curly brackets, there is never any
  473. ambiguity about which
  474. .I if
  475. an
  476. .I else
  477. goes with.
  478. If you use
  479. .I unless
  480. in place of
  481. .IR if ,
  482. the sense of the test is reversed.
  483. .PP
  484. The
  485. .I while
  486. statement executes the block as long as the expression is true
  487. (does not evaluate to the null string or 0).
  488. The LABEL is optional, and if present, consists of an identifier followed by
  489. a colon.
  490. The LABEL identifies the loop for the loop control statements
  491. .IR next ,
  492. .I last
  493. and
  494. .I redo
  495. (see below).
  496. If there is a
  497. .I continue
  498. BLOCK, it is always executed just before
  499. the conditional is about to be evaluated again, similarly to the third part
  500. of a
  501. .I for
  502. loop in C.
  503. Thus it can be used to increment a loop variable, even when the loop has
  504. been continued via the
  505. .I next
  506. statement (similar to the C \*(L"continue\*(R" statement).
  507. .PP
  508. If the word
  509. .I while
  510. is replaced by the word
  511. .IR until ,
  512. the sense of the test is reversed, but the conditional is still tested before
  513. the first iteration.
  514. .PP
  515. In either the
  516. .I if
  517. or the
  518. .I while
  519. statement, you may replace \*(L"(EXPR)\*(R" with a BLOCK, and the conditional
  520. is true if the value of the last command in that block is true.
  521. .PP
  522. The
  523. .I for
  524. loop works exactly like the corresponding
  525. .I while
  526. loop:
  527. .nf
  528. .ne 12
  529. for ($i = 1; $i < 10; $i++) {
  530. .\|.\|.
  531. }
  532. is the same as
  533. $i = 1;
  534. while ($i < 10) {
  535. .\|.\|.
  536. } continue {
  537. $i++;
  538. }
  539. .fi
  540. .PP
  541. The BLOCK by itself (labeled or not) is equivalent to a loop that executes
  542. once.
  543. Thus you can use any of the loop control statements in it to leave or
  544. restart the block.
  545. The
  546. .I continue
  547. block is optional.
  548. This construct is particularly nice for doing case structures.
  549. .nf
  550. .ne 6
  551. foo: {
  552. if (/abc/) { $abc = 1; last foo; }
  553. if (/def/) { $def = 1; last foo; }
  554. if (/xyz/) { $xyz = 1; last foo; }
  555. $nothing = 1;
  556. }
  557. .fi
  558. .Sh "Simple statements"
  559. The only kind of simple statement is an expression evaluated for its side
  560. effects.
  561. Every expression (simple statement) must be terminated with a semicolon.
  562. Note that this is like C, but unlike Pascal (and
  563. .IR awk ).
  564. .PP
  565. Any simple statement may optionally be followed by a
  566. single modifier, just before the terminating semicolon.
  567. The possible modifiers are:
  568. .nf
  569. .ne 4
  570. if EXPR
  571. unless EXPR
  572. while EXPR
  573. until EXPR
  574. .fi
  575. The
  576. .I if
  577. and
  578. .I unless
  579. modifiers have the expected semantics.
  580. The
  581. .I while
  582. and
  583. .I unless
  584. modifiers also have the expected semantics (conditional evaluated first),
  585. except when applied to a do-BLOCK command,
  586. in which case the block executes once before the conditional is evaluated.
  587. This is so that you can write loops like:
  588. .nf
  589. .ne 4
  590. do {
  591. $_ = <stdin>;
  592. .\|.\|.
  593. } until $_ \|eq \|".\|\e\|n";
  594. .fi
  595. (See the
  596. .I do
  597. operator below. Note also that the loop control commands described later will
  598. NOT work in this construct, since loop modifiers don't take loop labels.
  599. Sorry.)
  600. .Sh "Expressions"
  601. Since
  602. .I perl
  603. expressions work almost exactly like C expressions, only the differences
  604. will be mentioned here.
  605. .PP
  606. Here's what
  607. .I perl
  608. has that C doesn't:
  609. .Ip (\|) 8 3
  610. The null list, used to initialize an array to null.
  611. .Ip . 8
  612. Concatenation of two strings.
  613. .Ip .= 8
  614. The corresponding assignment operator.
  615. .Ip eq 8
  616. String equality (== is numeric equality).
  617. For a mnemonic just think of \*(L"eq\*(R" as a string.
  618. (If you are used to the
  619. .I awk
  620. behavior of using == for either string or numeric equality
  621. based on the current form of the comparands, beware!
  622. You must be explicit here.)
  623. .Ip ne 8
  624. String inequality (!= is numeric inequality).
  625. .Ip lt 8
  626. String less than.
  627. .Ip gt 8
  628. String greater than.
  629. .Ip le 8
  630. String less than or equal.
  631. .Ip ge 8
  632. String greater than or equal.
  633. .Ip =~ 8 2
  634. Certain operations search or modify the string \*(L"$_\*(R" by default.
  635. This operator makes that kind of operation work on some other string.
  636. The right argument is a search pattern, substitution, or translation.
  637. The left argument is what is supposed to be searched, substituted, or
  638. translated instead of the default \*(L"$_\*(R".
  639. The return value indicates the success of the operation.
  640. (If the right argument is an expression other than a search pattern,
  641. substitution, or translation, it is interpreted as a search pattern
  642. at run time.
  643. This is less efficient than an explicit search, since the pattern must
  644. be compiled every time the expression is evaluated.)
  645. The precedence of this operator is lower than unary minus and autoincrement/decrement, but higher than everything else.
  646. .Ip !~ 8
  647. Just like =~ except the return value is negated.
  648. .Ip x 8
  649. The repetition operator.
  650. Returns a string consisting of the left operand repeated the
  651. number of times specified by the right operand.
  652. .nf
  653. print '-' x 80; # print row of dashes
  654. print '-' x80; # illegal, x80 is identifier
  655. print "\et" x ($tab/8), ' ' x ($tab%8); # tab over
  656. .fi
  657. .Ip x= 8
  658. The corresponding assignment operator.
  659. .Ip .. 8
  660. The range operator, which is bistable.
  661. It is false as long as its left argument is false.
  662. Once the left argument is true, it stays true until the right argument is true,
  663. AFTER which it becomes false again.
  664. (It doesn't become false till the next time it's evaluated.
  665. It can become false on the same evaluation it became true, but it still returns
  666. true once.)
  667. The .. operator is primarily intended for doing line number ranges after
  668. the fashion of \fIsed\fR or \fIawk\fR.
  669. The precedence is a little lower than || and &&.
  670. The value returned is either the null string for false, or a sequence number
  671. (beginning with 1) for true.
  672. The sequence number is reset for each range encountered.
  673. The final sequence number in a range has the string 'E0' appended to it, which
  674. doesn't affect its numeric value, but gives you something to search for if you
  675. want to exclude the endpoint.
  676. You can exclude the beginning point by waiting for the sequence number to be
  677. greater than 1.
  678. If either argument to .. is static, that argument is implicitly compared to
  679. the $. variable, the current line number.
  680. Examples:
  681. .nf
  682. .ne 5
  683. if (101 .. 200) { print; } # print 2nd hundred lines
  684. next line if (1 .. /^$/); # skip header lines
  685. s/^/> / if (/^$/ .. eof()); # quote body
  686. .fi
  687. .PP
  688. Here is what C has that
  689. .I perl
  690. doesn't:
  691. .Ip "unary &" 12
  692. Address-of operator.
  693. .Ip "unary *" 12
  694. Dereference-address operator.
  695. .PP
  696. Like C,
  697. .I perl
  698. does a certain amount of expression evaluation at compile time, whenever
  699. it determines that all of the arguments to an operator are static and have
  700. no side effects.
  701. In particular, string concatenation happens at compile time between literals that don't do variable substitution.
  702. Backslash interpretation also happens at compile time.
  703. You can say
  704. .nf
  705. .ne 2
  706. 'Now is the time for all' . "\|\e\|n" .
  707. 'good men to come to.'
  708. .fi
  709. and this all reduces to one string internally.
  710. .PP
  711. Along with the literals and variables mentioned earlier,
  712. the following operations can serve as terms in an expression:
  713. .Ip "/PATTERN/" 8 4
  714. Searches a string for a pattern, and returns true (1) or false ('').
  715. If no string is specified via the =~ or !~ operator,
  716. the $_ string is searched.
  717. (The string specified with =~ need not be an lvalue\*(--it may be the result of an expression evaluation, but remember the =~ binds rather tightly.)
  718. See also the section on regular expressions.
  719. .Sp
  720. If you prepend an `m' you can use any pair of characters as delimiters.
  721. This is particularly useful for matching Unix path names that contain `/'.
  722. .Sp
  723. Examples:
  724. .nf
  725. .ne 4
  726. open(tty, '/dev/tty');
  727. <tty> \|=~ \|/\|^[Yy]\|/ \|&& \|do foo(\|); # do foo if desired
  728. if (/Version: \|*\|([0-9.]*\|)\|/\|) { $version = $1; }
  729. next if m#^/usr/spool/uucp#;
  730. .fi
  731. .Ip "?PATTERN?" 8 4
  732. This is just like the /pattern/ search, except that it matches only once between
  733. calls to the
  734. .I reset
  735. operator.
  736. This is a useful optimization when you only want to see the first occurence of
  737. something in each of a set of files, for instance.
  738. .Ip "chdir EXPR" 8 2
  739. Changes the working director to EXPR, if possible.
  740. Returns 1 upon success, 0 otherwise.
  741. See example under die().
  742. .Ip "chmod LIST" 8 2
  743. Changes the permissions of a list of files.
  744. The first element of the list must be the numerical mode.
  745. LIST may be an array, in which case you may wish to use the unshift()
  746. command to put the mode on the front of the array.
  747. Returns the number of files successfully changed.
  748. Note: in order to use the value you must put the whole thing in parentheses.
  749. .nf
  750. $cnt = (chmod 0755,'foo','bar');
  751. .fi
  752. .Ip "chop(VARIABLE)" 8 5
  753. .Ip "chop" 8
  754. Chops off the last character of a string and returns it.
  755. It's used primarily to remove the newline from the end of an input record,
  756. but is much more efficient than s/\en// because it neither scans nor copies
  757. the string.
  758. If VARIABLE is omitted, chops $_.
  759. Example:
  760. .nf
  761. .ne 5
  762. while (<>) {
  763. chop; # avoid \en on last field
  764. @array = split(/:/);
  765. .\|.\|.
  766. }
  767. .fi
  768. .Ip "chown LIST" 8 2
  769. Changes the owner (and group) of a list of files.
  770. LIST may be an array.
  771. The first two elements of the list must be the NUMERICAL uid and gid, in that order.
  772. Returns the number of files successfully changed.
  773. Note: in order to use the value you must put the whole thing in parentheses.
  774. .nf
  775. $cnt = (chown $uid,$gid,'foo');
  776. .fi
  777. Here's an example of looking up non-numeric uids:
  778. .nf
  779. .ne 16
  780. print "User: ";
  781. $user = <stdin>;
  782. open(pass,'/etc/passwd') || die "Can't open passwd";
  783. while (<pass>) {
  784. ($login,$pass,$uid,$gid) = split(/:/);
  785. $uid{$login} = $uid;
  786. $gid{$login} = $gid;
  787. }
  788. @ary = ('foo','bar','bie','doll');
  789. if ($uid{$user} eq '') {
  790. die "$user not in passwd file";
  791. }
  792. else {
  793. unshift(@ary,$uid{$user},$gid{$user});
  794. chown @ary;
  795. }
  796. .fi
  797. .Ip "close(FILEHANDLE)" 8 5
  798. .Ip "close FILEHANDLE" 8
  799. Closes the file or pipe associated with the file handle.
  800. You don't have to close FILEHANDLE if you are immediately going to
  801. do another open on it, since open will close it for you.
  802. (See
  803. .IR open .)
  804. However, an explicit close on an input file resets the line counter ($.), while
  805. the implicit close done by
  806. .I open
  807. does not.
  808. Also, closing a pipe will wait for the process executing on the pipe to complete,
  809. in case you want to look at the output of the pipe afterwards.
  810. Example:
  811. .nf
  812. .ne 4
  813. open(output,'|sort >foo'); # pipe to sort
  814. ... # print stuff to output
  815. close(output); # wait for sort to finish
  816. open(input,'foo'); # get sort's results
  817. .fi
  818. .Ip "crypt(PLAINTEXT,SALT)" 8 6
  819. Encrypts a string exactly like the crypt() function in the C library.
  820. Useful for checking the password file for lousy passwords.
  821. Only the guys wearing white hats should do this.
  822. .Ip "die EXPR" 8 6
  823. Prints the value of EXPR to stderr and exits with a non-zero status.
  824. Equivalent examples:
  825. .nf
  826. .ne 3
  827. die "Can't cd to spool." unless chdir '/usr/spool/news';
  828. (chdir '/usr/spool/news') || die "Can't cd to spool."
  829. .fi
  830. Note that the parens are necessary above due to precedence.
  831. See also
  832. .IR exit .
  833. .Ip "do BLOCK" 8 4
  834. Returns the value of the last command in the sequence of commands indicated
  835. by BLOCK.
  836. When modified by a loop modifier, executes the BLOCK once before testing the
  837. loop condition.
  838. (On other statements the loop modifiers test the conditional first.)
  839. .Ip "do SUBROUTINE (LIST)" 8 3
  840. Executes a SUBROUTINE declared by a
  841. .I sub
  842. declaration, and returns the value
  843. of the last expression evaluated in SUBROUTINE.
  844. (See the section on subroutines later on.)
  845. .Ip "each(ASSOC_ARRAY)" 8 6
  846. Returns a 2 element array consisting of the key and value for the next
  847. value of an associative array, so that you can iterate over it.
  848. Entries are returned in an apparently random order.
  849. When the array is entirely read, a null array is returned (which when
  850. assigned produces a FALSE (0) value).
  851. The next call to each() after that will start iterating again.
  852. The iterator can be reset only by reading all the elements from the array.
  853. The following prints out your environment like the printenv program, only
  854. in a different order:
  855. .nf
  856. .ne 3
  857. while (($key,$value) = each(ENV)) {
  858. print "$key=$value\en";
  859. }
  860. .fi
  861. See also keys() and values().
  862. .Ip "eof(FILEHANDLE)" 8 8
  863. .Ip "eof" 8
  864. Returns 1 if the next read on FILEHANDLE will return end of file, or if
  865. FILEHANDLE is not open.
  866. If (FILEHANDLE) is omitted, the eof status is returned for the last file read.
  867. The null filehandle may be used to indicate the pseudo file formed of the
  868. files listed on the command line, i.e. eof() is reasonable to use inside
  869. a while (<>) loop.
  870. Example:
  871. .nf
  872. .ne 7
  873. # insert dashes just before last line
  874. while (<>) {
  875. if (eof()) {
  876. print "--------------\en";
  877. }
  878. print;
  879. }
  880. .fi
  881. .Ip "exec LIST" 8 6
  882. If there is more than one argument in LIST,
  883. calls execvp() with the arguments in LIST.
  884. If there is only one argument, the argument is checked for shell metacharacters.
  885. If there are any, the entire argument is passed to /bin/sh -c for parsing.
  886. If there are none, the argument is split into words and passed directly to
  887. execvp(), which is more efficient.
  888. Note: exec (and system) do not flush your output buffer, so you may need to
  889. set $| to avoid lost output.
  890. .Ip "exit EXPR" 8 6
  891. Evaluates EXPR and exits immediately with that value.
  892. Example:
  893. .nf
  894. .ne 2
  895. $ans = <stdin>;
  896. exit 0 \|if \|$ans \|=~ \|/\|^[Xx]\|/\|;
  897. .fi
  898. See also
  899. .IR die .
  900. .Ip "exp(EXPR)" 8 3
  901. Returns e to the power of EXPR.
  902. .Ip "fork" 8 4
  903. Does a fork() call.
  904. Returns the child pid to the parent process and 0 to the child process.
  905. Note: unflushed buffers remain unflushed in both processes, which means
  906. you may need to set $| to avoid duplicate output.
  907. .Ip "gmtime(EXPR)" 8 4
  908. Converts a time as returned by the time function to a 9-element array with
  909. the time analyzed for the Greenwich timezone.
  910. Typically used as follows:
  911. .nf
  912. .ne 3
  913. ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst)
  914. = gmtime(time);
  915. .fi
  916. All array elements are numeric.
  917. ''' End of part 1