Path: utzoo!utgpu!news-server.csri.toronto.edu!cs.utexas.edu!usc!ucsd!ucbvax!bloom-beacon!eru!luth!sunic!mcsun!hp4nl!mhres!jv
From: jv@mh.nl (Johan Vromans)
Newsgroups: comp.lang.perl
Subject: REPOST: texinfo version of perl refguide (1 of 3)
Message-ID: <JV.90Jun27102943@squirrel.mh.nl>
Date: 27 Jun 90 16:29:43 GMT
Sender: news@mhres.mh.nl
Reply-To: Johan Vromans <jv@mh.nl>
Organization: Multihouse Automation, the Netherlands
Lines: 644
X-Checksum-Snefru: 4e2d9abc 80a9ef76 174e0adf cf08ab0f


Archive-name: perlref.texinfo/part01

---- Cut Here and unpack ----
#!/bin/sh
# This is perlref.texinfo, a shell archive (shar 3.24)
# made 06/26/1990 19:44 UTC by jv@squirrel
# Source directory /u/jv/perlref/texinfo
#
# existing files WILL be overwritten
#
# This is part 1 of a multipart archive                                    
# do not concatenate these parts, unpack them in order with /bin/sh        
#
# This shar contains:
# length  mode       name
# ------ ---------- ------------------------------------------
#  43795 -rw-r--r-- perlref.texinfo
#
if touch 2>&1 | fgrep '[-amc]' > /dev/null
 then TOUCH=touch
 else TOUCH=true
fi
if test -r shar3_seq_.tmp; then
	echo "Must unpack archives in sequence!"
	next=`cat shar3_seq_.tmp`; echo "Please unpack part $next next"
	exit 1
fi
# ============= perlref.texinfo ==============
echo "x - extracting perlref.texinfo (Text)"
sed 's/^X//' << 'SHAR_EOF' > perlref.texinfo &&
X\input texinfo   @c -*-texinfo-*-
X@setfilename perlref.info
X@settitle perlref
X
X@ifinfo
XThis file documents perl, a practical extension and report language.
XGNU texinfo version 3.0.18.1.1 adapted by rich@@rice.edu.
X
XCopyright @copyright{} 1989, 1990 Johan Vromans
X@TeX{} version Copyright @copyright{} 1990 Raymond Chen
XRev. 3.0.18.1
XUse and reproduction of this information is unlimited.
X@end ifinfo
X
X@titlepage
X@sp 10
X@center @titlefont{Perl Reference Guide}
X@sp 1
X@center for perl version 3.0
X@sp 2
X@center Perl program designed and created by Larry Wall (lwall@@jpl-devvax.jpl.nasa.gov)
X@sp .5
X@center Reference guide designed and created by Johan Vromans (jv@@mh.nl)
X@sp .5
X@center @TeX{} version by Raymond Chen (raymond@@math.berkeley.edu)
X@vskip 0pt plus 1filll
XCopyright @copyright{} 1989, 1990 Johan Vromans
X@sp .1
X@TeX{} version Copyright @copyright{} 1990 Raymond Chen
X@sp .1
XRev. 3.0.18.1
X@sp .1
XUse and reproduction of this information is unlimited.
X@end titlepage
X
X
X@node Top, Command line options, (dir), (dir)
X
X@menu
X* Command line options::
X* Literals::
X* Variables::
X* Statements::
X* Flow control::
X* Operators::
X* File test operators::
X* Arithmetic functions::
X* Conversion functions::
X* Structure conversion::
X* String functions::
X* Array and list functions::
X* File operations::
X* Directory reading routines::
X* Input/Output::
X* Search and replace functions::
X* System interaction::
X* Networking::
X* Miscellaneous::
X* Info from system files::
X* Regular expressions::
X* Formats::
X* Special variables::
X* Special arrays::
X* The perl debugger::
X* Index::
X@end menu
X
X@node Command line options, Literals, , Top
X@chapter Command line options
X
X@table @samp
X@item -a
Xturns on autosplit mode when used with @samp{-n} or @samp{-p}.  Splits
Xto @samp{@@F}.@refill
X
X@samp{-d}
Xruns the script under the debugger. Use @samp{-de 0} to start the
Xdebugger without a script.@refill
X
X@item -D@var{number}
Xsets debugging flags.
X
X@item -e @var{commandline}
Xmay be used to enter one line of script. Multiple @samp{-e} commands may
Xbe given to build up a multi-line script.@refill
X
X@item -i@var{extension}
Xspecifies that files processed by the @code{<>} construct are to be
Xedited in-place.@refill
X
X@item -I@var{directory}
Xwith @samp{-P}:  tells the C preprocessor where to look
Xfor include files.@refill
X
X@item -n
Xassumes an input loop around your script. Lines are not printed.
X
X@item -p
Xassumes an input loop around your script. Lines are printed.
X
X@item -P
Xruns the C preprocessor on the script before compilation by perl.
X
X@item -s
Xinterprets @samp{-xxx} on the command line as switches and sets the
Xcorresponding variables @var{$xxx} in the script.@refill
X
X@item -S
Xuses the @var{PATH} environment variable to search for the script.
X
X@item -u
Xdumps core after compiling the script.
X
X@item -U
Xallows perl to do unsafe operations.
X
X@item -v
Xprints the version and patchlevel of your perl executable.
X
X@item -w
Xprints warnings about possible spelling errors and other error-prone
Xconstructs in the script.@refill
X@end table
X
X@c----------------------------------------------------------------
X@node Literals, Variables, Command line options, Top
X@chapter Literals
X
X@table @asis
X@item Numeric:
X@code{123},  @code{123.4},  @code{5E-10},  @code{0xff} (hex),
X@code{0377} (octal).@refill
X
X@item String:
X@code{"abc"}, @code{'abc'}.  Variables are interpolated when
X@code{"@dots{}"} are used.  @code{q/@dots{}/} can be used instead
Xof @code{'@dots{}'}, @code{qq/@dots{}/} instead of @code{"@dots{}"},
X(any delimiter instead of @code{/@dots{}/}).@refill
X
X@item Array:
X@code{(1,2,3)}. @code{()} is empty array. Also: @code{($a,$b,@@rest) =
X(1,2,@dots{});} Enums are fine: @code{(1..4)} is @code{(1,2,3,4)}.
XLikewise @code{('abc'..'ade')}.@refill
X
X@item Filehandles:
X@code{<STDIN>}, @code{<STDOUT>}, @code{<STDERR>}, @code{<handle>},
X@code{<$var>}. @code{<>} is the input stream formed by the files
Xspecified in @code{@@ARGV}, or @code{STDIN} if no arguments are
Xsupplied.@refill
X
X@item Globs:
X@code{<pattern>} evaluates to all filenames according to the pattern.
XUse @code{<${var}>} to glob from a variable.@refill
X
X@item Commands:
X@code{`command`} evaluates to the output of the command.
X
X@c
X@c                 Is Here-Is correct? Is it clear? Rich
X@c
X@item Here-Is:
XThe identifier must follow @code{<<} immediately.
X@example
X@code{<<identifier}.
X@var{input text}
Xidentifier
X@end example
X@end table
X
X@c----------------------------------------------------------------
X@node Variables, Statements, Literals, Top
X@chapter Variables
X
X@table @code
X@item $var
Xa simple scalar variable
X
X@item $var[28]
X29th element of array @code{@@var} (the @code{[]} are part of it)
X
X@item $var{'Feb'}
Xone value from associative array @code{%var}
X
X@item $#var
Xlast index of array @code{@@var}
X
X@item @@var
Xthe entire array
X
X@item @@var[3,4,5]
Xa slice of the array @code{@@var}
X
X@item @@var{'a','b'}
Xa slice of @code{%var}; same as @code{('a','b')}
X
X@item %var
Xthe entire associative array
X
X@item $var{'a',1,@dots{}}
Xemulates a multi-dimensional array
X
X@item ('a',1,@dots{})[4]
Xsubscripts an array literal
X
X@item *name
Xrefers to all objects represented by name.  @code{*name1 = *name2} makes
X@code{name1} identical to @code{name2}.
X@end table
X
X@c----------------------------------------------------------------
X@node Statements, Flow control, Variables, Top
X@chapter Statements
X
XEvery statement is an expression, optionally followed by a modifier, and
Xterminated by a semi-colon.
X
XExecution of expressions can depend on other expressions using one of
Xthe modifiers @code{if}, @code{unless}, @code{while} or @code{until}, e.g.:
X@example
X@var{EXPR1} if @var{EXPR2};
X@var{EXPR1} until @var{EXPR2};
X@end example
X
XAlso, by using one of the logical operators @code{||}, @code{&&}
Xor @code{?:}, e.g.:
X@example
X@var{EXPR1} || @var{EXPR2};
X@var{EXPR1} ? @var{EXPR2} : @var{EXPR3};
X@end example
X
XStatements can be combined to form a @var{BLOCK} when enclosed in @code{@{@}}.
X
XCompound statements may be used to control flow (@code{[]} denote optional
Xparts, @code{*} means: defaults to @code{$_} if omitted):@refill
X
X@example
Xif (@var{EXPR}) @var{BLOCK} [ [ elsif (@var{EXPR}) @var{BLOCK} @dots{} ] else @var{BLOCK} ]
Xunless (@var{EXPR}) @var{BLOCK} [ else @var{BLOCK} ]
X[@var{LABEL}:] while (@var{EXPR}) @var{BLOCK} [ continue @var{BLOCK} ]
X[@var{LABEL}:] until (@var{EXPR}) @var{BLOCK} [ continue @var{BLOCK} ]
X[@var{LABEL}:] for (@var{EXPR}; @var{EXPR}; @var{EXPR}) @var{BLOCK}
X[@var{LABEL}:] foreach @var{VAR}* (@var{ARRAY}) @var{BLOCK}
X[@var{LABEL}:] @var{BLOCK} [ continue @var{BLOCK} ]
X@end example
X
XSpecial forms are:
X@example
Xdo @var{BLOCK} while @var{EXPR};
Xdo @var{BLOCK} until @var{EXPR};
X@end example
Xwhich are guaranteed to perform @var{BLOCK} once before testing @var{EXPR}.
X
X@c----------------------------------------------------------------
X@node Flow control, Operators, Statements, Top
X@chapter Flow control
X
X@table @code
X
X@item do @var{BLOCK}
XReturns the value of the last command in the sequence of
Xcommands indicated by @var{BLOCK}.
X
X@item do @var{SUBROUTINE} (@var{LIST})
XExecutes a @var{SUBROUTINE} declared by a @code{sub} declaration, and
Xreturns the value of the last expression evaluated in
X@var{SUBROUTINE}. Also: @code{&@var{SUBROUTINE}}.@refill
X
X@item do @var{EXPR}
XUses the value of @var{EXPR} as a filename and executes the contents of
Xthe file as a perl script. Errors are returned in @code{$@@}.@refill
X
X@item goto @var{LABEL}
XContinue execution at the specified label.
X
X@item last [@var{LABEL}]
XImmediately exits the loop in question. Skips continue block.
X
X@item next [@var{LABEL}]
XStarts the next iteration of the loop.
X
Xredo [@var{LABEL}]
X@item Restarts the loop block without evaluating the conditional again.
X
X@item return @var{EXPR}
XReturns from a subroutine with the value specified.
X@end table
X
X@c----------------------------------------------------------------
X@node Operators, File test operators, Flow control, Top
X@chapter Operators
X
X@table @asis
X@item @code{+} @code{-} @code{*} @code{/}
XAddition, subtraction, multiplication, division.
X
X@item @code{%}
XModulo division.
X
X@item @code{|} @code{&} @code{^}
XBitwise or, bitwise and, bitwise exclusive or.
X
X@item @code{>>} @code{<<}
XBitwise shift right, bitwise shift left.
X
X@item @code{**}
XExponentiation.
X
X@item @code{.}
XConcatenation of two strings.
X
X@item @code{x}
XReturns a string consisting of the left operand repeated the
Xnumber of times specified by the right operand.@refill
X@end table
X
XAll of the above operators also have an assignment operator, e.g. @code{.=}.
X
X@table @code
X@item @code{++} @code{--}
XAuto-increment (magical on strings), auto-decrement.
X
X@item @code{?:}
XAlternation (if-then-else) operator.
X
X@item @code{||} @code{&&}
XLogical or, logical and.
X
X@item @code{==} @code{!=}
XNumeric equality, inequality.
X
X@item @code{eq} @code{ne}
XString equality, inequality.
X
X@item @code{<} @code{>}
XNumeric less than, greater than.
X
X@item @code{lt} @code{gt}
XString less than, greater than.
X
X@item @code{<=} @code{>=}
XNumeric less (greater) than or equal to.
X
X@item @code{le} @code{ge}
XString less (greater) than or equal.
X
X@item @code{=~} @code{!~}
XSearch pattern, substitution, or translation (negated).
X
X@item @code{..}
XEnumeration, also input line range operator.
X
X@item @code{,}
XComma operator.
X@end table
X
X@c----------------------------------------------------------------
X@node File test operators, Arithmetic functions, Operators, Top
X@chapter File test operators
X
X@c %%rjc%% Changed "This unary operator" to "These unary operators"
X@c %%rjc%%  and concomitant grammar changes
X
XThese unary operators take one argument, either a filename or a
Xfilehandle, and test the associated file to see if something is true
Xabout it. If the argument is omitted, tests @code{$_} (except for
X@code{-t}, which tests @var{STDIN}).  If the special argument @code{_}
X(underscore) is passed, uses the info of the preceding test.@refill
X
X@table @asis
X@code{-r}/@code{-w}/@code{-x}/@code{-o}
XFile is readable/writable/executable/owned by effective uid.
X
X@item @code{-R}/@code{-W}/@code{-X}/@code{-O}
XFile is readable/writable/executable/owned by real uid.
X
X@item @code{-e}/@code{-z}/@code{-s}
XFile exists / has zero/non-zero size.
X
X@item @code{-f}/@code{-d}
XFile is a plain file, a directory.
X
X@item @code{-l}/@code{-S}/@code{-p}
XFile is a symbolic link, a socket,  a named pipe (FIFO).
X
X@item @code{-b}/@code{-c}
XFile is a block/character special file.
X
X@item @code{-u}/@code{-g}/@code{-k}
XFile has setuid/setgid/sticky bit set.
X
X@item @code{-t}
XTests if filehandle (STDIN by default) is opened to a tty.
X
X@item @code{-T}/@code{-B}
XFile is a text/non-text (binary) file.  Both @code{-T} and @code{-B}
Xreturn @var{TRUE} on a null file, or a file at EOF when testing a
Xfilehandle.@refill
X@end table
X
XAn @code{*} after the parameter list indicates that this function may be
Xused either as a function or as a unary operator, without the
Xparentheses.  The symbol @code{*} after a parameter indicates that this
Xparameter will default to @code{$_} if omitted.@refill
X
X@c----------------------------------------------------------------
X@node Arithmetic functions, Conversion functions, File test operators, Top
X@chapter Arithmetic functions
X
X@table @code
X
X@item atan2(@var{X},@var{Y})
XReturns the arctangent of @var{X/Y} in the range -Pi to Pi.
X
X@item cos(@var{EXPR}*)*
XReturns the cosine of @var{EXPR} (expressed in radians).
X
X@item exp(@var{EXPR}*)*
XReturns e to the power of @var{EXPR}.
X
X@item int(@var{EXPR}*)*
XReturns the integer portion of @var{EXPR}.
X
X@item log(@var{EXPR}*)*
XReturns natural logarithm (base @var{e}) of @var{EXPR}.
X
X@item rand [(@var{EXPR})*]
XReturns a random fractional number between 0 and the value of
X@var{EXPR}. If @var{EXPR} is omitted, returns a value between 0 and
X1.@refill
X
X@item sin(@var{EXPR}*)*
XReturns the sine of @var{EXPR} (expressed in radians).
X
X@item sqrt(@var{EXPR}*)*
XReturn the square root of @var{EXPR}.
X
X@item srand[(@var{EXPR})*]
XSets the random number seed for the rand operator.
X
X@item time
XReturns the number of seconds since January 1, 1970. Suitable for
Xfeeding to gmtime(@dots{}) and localtime(@dots{}).@refill
X@end table
X
X@c----------------------------------------------------------------
X@node Conversion functions, Structure conversion, Arithmetic functions, Top
X@chapter Conversion functions
X
X@table @code
X
X@item gmtime(@var{EXPR})*
XConverts a time as returned by the time function to a 9-element
Xarray @code{($sec, $min, $hour, $mday, $mon, $year, $wday, $yday,
X$isdst)} with the time analyzed for the Greenwich timezone. @code{$mon}
Xhas the range 0@dots{}11 and @code{$wday} has the range
X0@dots{}6.@refill
X
X@c %%rjc%% \* added
X@item hex(@var{EXPR}*)*
XReturns the decimal value of @var{EXPR} interpreted as an hex string.
X
X@item localtime(@var{EXPR})*
XConverts a time as returned by the time function to a 9-element
Xarray with the time analyzed for the local timezone.@refill
X
X@c %%rjc%% \* added
X@item oct(@var{EXPR}*)*
XReturns the decimal value of @var{EXPR} interpreted as an octal string.
XIf @var{EXPR} starts off with 0x, interprets it as a hex string
Xinstead.@refill
X
X@item ord(@var{EXPR}*)*
XReturns the ascii value of the first character of @var{EXPR}.
X
X@item vec(@var{EXPR},@var{OFFSET},@var{BITS})
XTreats @var{EXPR} as a string of unsigned ints, and yields the bit at
X@var{OFFSET}. @var{BITS} must be between 1 and 32. May be used as an
Xlvalue.@refill
X@end table
X
XA @var{LIST} is a (possibly parenthesised) list of expressions,
Xvariables or @var{LIST}s. In all circumstances, an array variable or an
Xarray slice may be used instead of a @var{LIST}.@refill
X
X@c----------------------------------------------------------------
X@node Structure conversion, String functions, Conversion functions, Top
X@chapter Structure conversion
X
X@table @code
X
X@item pack(@var{TEMPLATE},@var{LIST})
XPacks the values into a binary structure using @var{TEMPLATE}.
X
X@item unpack(@var{TEMPLATE},@var{EXPR})
XUnpacks the structure @var{EXPR} into an array, using @var{TEMPLATE}.
X
X@var{TEMPLATE} is a sequence of characters as follows:
X
X@table @asis
X@item @code{a}/@code{A}
XAscii string, null/space padded
X
X@item @code{c}/@code{C}
XNative/unsigned char value
X
X@item @code{s}/@code{S}
XSigned/unsigned short value
X
X@item @code{i}/@code{I}
XSigned/unsigned integer value
X
X@item @code{l}/@code{L}
XSigned/unsigned long value
X
X@item @code{n}/@code{N}
XShort/long in network byte order
X
X@item @code{p}
XPointer to a string
X
X@item @code{x}
XNull byte
X@end table
X@end table
X
XEach character may be followed by a decimal number which will be used as
Xa repeat count. Spaces may be included in the template for readability
Xpurposes.@refill
X
X@c----------------------------------------------------------------
X@node String functions, Array and list functions, Structure conversion, Top
X@chapter String functions
X
X@table @code
X
X@item chop(@var{LIST}*)
XChops off the last character on all elements of the list; returns the
Xlast chopped character. The parentheses may be omitted if @var{LIST} is
Xa single variable.@refill
X
X@item crypt(@var{PLAINTEXT},@var{SALT})
XEncrypts a string.
X
X@c %%rjc%%\* added
X@item eval(@var{EXPR}*)*
X@var{EXPR} is parsed and executed as if it were a little perl program.
XThe value returned is the value of the last expression evaluated. If
Xthere is a syntax error or runtime error, an undefined string is
Xreturned by eval, and @code{$@@} is set to the error message.@refill
X
X@item index(@var{STR},@var{SUBSTR})
XReturns the position of @var{SUBSTR} in @var{STR}. If the substring is not
Xfound, returns @code{$[-1}.@refill
X
X@c %%rjc%% \* added
X@item length(@var{EXPR}*)*
XReturns the length in characters of the value of @var{EXPR}.
X
X@item rindex(@var{STR},@var{SUBSTR})
XReturns the position of the last occurrence of @var{SUBSTR} in @var{STR}.
X
X@item substr(@var{EXPR},@var{OFFSET},@var{LEN})
XExtracts a substring out of @var{EXPR} and returns it. If @var{OFFSET} is
Xnegative, counts from the end of the string. May be used as an
Xlvalue.@refill
X@end table
X
X@c----------------------------------------------------------------
X@node Array and list functions, File operations, String functions, Top
X@chapter Array and list functions
X
X@table @code
X
X@item delete @code{$}@var{ARRAY}$@{$@var{KEY}$@}$
XDeletes the specified value from the specified associative array.
XReturns the deleted value.@refill
X
X@item each(@code{%}@var{ARRAY})*
XReturns a 2-element array consisting of the key and value for the
Xnext value of an associative array. Entries are returned in an
Xapparently random order. When the array is entirely read, a null array
Xis returned. The next call to each(@dots{}) after that will start
Xiterating again.@refill
X
X@item grep(@var{EXPR},@var{LIST})
XEvaluates @var{EXPR} for each element of the @var{LIST}, locally setting
X@code{$_} to refer to the element. Modifying @code{$_} will modify the
Xcorresponding element from @var{LIST}. Returns array of elements from
X@var{LIST} for which @var{EXPR} returned true.@refill
X
X@item join(@var{EXPR},@var{LIST})
XJoins the separate strings of @var{LIST} into a single string with fields
Xseparated by the value of @var{EXPR}, and returns the string.@refill
X
X@item keys(@code{%}@var{ARRAY})*
XReturns a normal array consisting of all the keys of the named
Xassociative array.@refill
X
X@item pop(@code{@@}@var{ARRAY})*
XPops and returns the last value of the array, shortens the array by 1.
X
X@item push(@code{@@}@var{ARRAY},@var{LIST})
XPushes the values of @var{LIST} onto the end of @var{ARRAY}. The length of
SHAR_EOF
echo "End of perlref.texinfo part 1"
echo "File perlref.texinfo is continued in part 2"
echo "2" > shar3_seq_.tmp
exit 0
--
Johan Vromans				       jv@mh.nl via internet backbones
Multihouse Automatisering bv		       uucp: ..!{uunet,hp4nl}!mh.nl!jv
Doesburgweg 7, 2803 PL Gouda, The Netherlands  phone/fax: +31 1820 62911/62500
------------------------ "Arms are made for hugging" -------------------------