*** perl.texinfo-3d-release	Sat Jan 12 19:48:26 1991
--- perl.texinfo	Tue Apr 16 15:27:55 1991
***************
*** 40,47 ****
  
  @titlepage
  @title Perl Manual (Texinfo version)
! @subtitle for perl version 3.0 patchlevel 44
! @subtitle Edition 0.3d, dated 12 January 1991, printed on @today{}
  
  @sp 2
  @center This is a @strong{DRAFT} copy of the Texinfo version of the perl manual!
--- 40,47 ----
  
  @titlepage
  @title Perl Manual (Texinfo version)
! @subtitle for perl version 4.0 patchlevel 03
! @subtitle Edition 0.4, dated 15 April 1991, printed on @today{}
  
  @sp 2
  @center This is a @strong{DRAFT} copy of the Texinfo version of the perl manual!
***************
*** 77,84 ****
  @comment  node-name,  next,  previous,  up
  
  @ifinfo
! This Info file contains edition 0.3d, dated 12 January 1991, "printed" on
! @today{} of the Perl Manual for Perl version 3.0 patchlevel 44.
  
  This is a @strong{DRAFT} copy of the Texinfo version of the perl manual!
  @end ifinfo
--- 77,84 ----
  @comment  node-name,  next,  previous,  up
  
  @ifinfo
! This Info file contains edition 0.4, dated 15 April 1991, "printed" on
! @today{} of the Perl Manual for Perl version 4.0 patchlevel 03.
  
  This is a @strong{DRAFT} copy of the Texinfo version of the perl manual!
  @end ifinfo
***************
*** 692,697 ****
--- 692,722 ----
  where to look for include files.  By default @file{/usr/include} and
  @file{/usr/lib/perl} are searched.@refill
  
+ @item -l octnum
+ enables automatic line-ending processing.  It has two effects: first, it
+ automatically chops the line terminator when used with @samp{-n} or
+ @samp{-p}, and second, it assigns @samp{$\} to have the value of
+ @var{octnum} so that any print statements will have that line terminator
+ added back on.  If @var{octnum} is omitted, sets @samp{$\} to the
+ current value of @samp{$/}.  For instance, to trim lines to 80
+ columns:@refill
+ 
+ @example
+ perl -lpe 'substr($_, 80) = ""'
+ @end example
+ 
+ Note that the assignment @code{$\ = $/} is done when the switch is
+ processed, so the input record separator can be different than the
+ output record separator if the @samp{-l} switch is followed by a
+ @samp{-0} switch:@refill
+ 
+ @example
+ gnufind / -print0 | perl -ln0e 'print "found $_" if -p'
+ @end example
+ 
+ This sets @samp{$\} to newline and then sets @samp{$/} to the null
+ character.@refill
+ 
  @item -n
  causes @emph{perl} to assume the following loop around your script,
  which makes it iterate over filename arguments somewhat like
***************
*** 707,716 ****
--- 732,747 ----
  option to have lines printed.  Here is an efficient way to delete all
  files older than a week:@refill
  
+ [ before version 4.003 ]
  @example
  find . -mtime +7 -print | perl -ne 'chop;unlink;'
  @end example
  
+ [ version 4.003 and beyond ]
+ @example
+ find . -mtime +7 -print | perl -nle 'unlink;'
+ @end example
+ 
  This is faster than using the @samp{-exec} switch of find because you
  don't have to start a process on every filename found.@refill
  
***************
*** 965,979 ****
  work much like shell quotes: double-quoted string literals are subject
  to backslash and variable substitution; single-quoted strings are not
  (except for \' and \\).  The usual backslash rules apply for making
! characters such as newline, tab, etc.  You can also embed newlines
! directly in your strings, i.e. they can end on a different line than
! they begin.  This is nice, but if you forget your trailing quote, the
! error will not be reported until @emph{perl} finds another line
! containing the quote character, which may be much further on in the
! script.  Variable substitution inside strings is limited to scalar
! variables, normal array values, and array slices.  (In other words,
! identifiers beginning with @samp{$} or @samp{@@}, followed by an
! optional bracketed expression as a subscript.)  The following code
  segment prints out @samp{The price is $100.}@refill
  
  @example
--- 996,1030 ----
  work much like shell quotes: double-quoted string literals are subject
  to backslash and variable substitution; single-quoted strings are not
  (except for \' and \\).  The usual backslash rules apply for making
! characters such as newline, tab, etc., as well as some more exotic
! forms:@refill
! 
! @example
! \t      tab
! \n      newline
! \r      return
! \f      form feed
! \b      backspace
! \a      alarm (bell)
! \e      escape
! \033    octal char
! \x1b    hex char
! \c[     control char
! \l      lowercase next char
! \u      uppercase next char
! \L      lowercase till \E
! \U      uppercase till \E
! \E      end case modification
! @end example
! 
! You can also embed newlines directly in your strings, i.e. they can end
! on a different line than they begin.  This is nice, but if you forget
! your trailing quote, the error will not be reported until @emph{perl}
! finds another line containing the quote character, which may be much
! further on in the script.  Variable substitution inside strings is
! limited to scalar variables, normal array values, and array slices.  (In
! other words, identifiers beginning with @samp{$} or @samp{@@}, followed
! by an optional bracketed expression as a subscript.)  The following code
  segment prints out @samp{The price is $100.}@refill
  
  @example
***************
*** 1590,1597 ****
  The @code{if} and @code{unless} modifiers have the expected semantics.
  The @code{while} and @code{until} modifiers also have the expected
  semantics (conditional evaluated first), except when applied to a
! do-BLOCK command, in which case the block executes once before the
! conditional is evaluated.  This is so that you can write loops like:@refill
  
  @example
  do @{
--- 1641,1649 ----
  The @code{if} and @code{unless} modifiers have the expected semantics.
  The @code{while} and @code{until} modifiers also have the expected
  semantics (conditional evaluated first), except when applied to a
! do-BLOCK or a do-SUBROUTINE command, in which case the block executes
! once before the conditional is evaluated.  This is so that you can write
! loops like:@refill
  
  @example
  do @{
***************
*** 1680,1686 ****
  
  @item x
  The repetition operator.  Returns a string consisting of the left
! operand repeated the number of times specified by the right operand.@refill
  
  @example
  print '-' x 80;         # print row of dashes
--- 1732,1740 ----
  
  @item x
  The repetition operator.  Returns a string consisting of the left
! operand repeated the number of times specified by the right operand.  In
! an array context, if the left operand is a list in parens, it repeats
! the list.@refill
  
  @example
  print '-' x 80;         # print row of dashes
***************
*** 1687,1696 ****
  print '-' x80;          # illegal, x80 is identifier
  
  print "\t" x ($tab/8), ' ' x ($tab%8);  # tab over
  @end example
  
  @item x=
! The repetition assignment operator.
  
  @item ..
  The range operator, which is really two different operators depending on
--- 1741,1753 ----
  print '-' x80;          # illegal, x80 is identifier
  
  print "\t" x ($tab/8), ' ' x ($tab%8);  # tab over
+ 
+ @@ones = (1) x 80;      # an array of 80 1's
+ @@ones = (5) x @@ones;  # set all elements to 5
  @end example
  
  @item x=
! The repetition assignment operator.  Only works on scalars.
  
  @item ..
  The range operator, which is really two different operators depending on
***************
*** 3696,3702 ****
  such a pattern to be compiled only once, add an @samp{o} after the
  trailing delimiter.  This avoids expensive run-time recompilations, and
  is useful when the value you are interpolating won't change over the
! life of the script.@refill
  
  If used in a context that requires an array value, a pattern match returns
  an array consisting of the subexpressions matched by the parentheses in
--- 3753,3760 ----
  such a pattern to be compiled only once, add an @samp{o} after the
  trailing delimiter.  This avoids expensive run-time recompilations, and
  is useful when the value you are interpolating won't change over the
! life of the script.  If the @var{PATTERN} evaluates to a null string,
! the most recent successful regular expression is used instead.@refill
  
  If used in a context that requires an array value, a pattern match returns
  an array consisting of the subexpressions matched by the parentheses in
***************
*** 3768,3775 ****
  variable rather than an end-of-string test, the variable will be
  interpolated into the pattern at run-time.  If you only want the pattern
  compiled once the first time the variable is interpolated, add an
! @samp{o} at the end.  @xref{Regular Expressions}, for more info.
! Examples:@refill
  
  @example
  @cindex Examples, substitute function
--- 3826,3834 ----
  variable rather than an end-of-string test, the variable will be
  interpolated into the pattern at run-time.  If you only want the pattern
  compiled once the first time the variable is interpolated, add an
! @samp{o} at the end.  If the @var{PATTERN} evaluates to a null string,
! the most recent successful regular expression is used instead.
! @xref{Regular Expressions}, for more info.  Examples:@refill
  
  @example
  @cindex Examples, substitute function
***************
*** 3841,3847 ****
  
  Note that if you have to look for strings that you don't know till
  runtime, you can build an entire loop as a string and eval that to avoid
! recompiling all your patterns all the time.  Together with setting
  @samp{$/} to input entire files as one record, this can be very fast,
  often faster than specialized programs like @samp{fgrep}.  The following
  scans a list of files (@samp{@@files}) for a list of words
--- 3900,3906 ----
  
  Note that if you have to look for strings that you don't know till
  runtime, you can build an entire loop as a string and eval that to avoid
! recompiling all your patterns all the time.  Together with undefining
  @samp{$/} to input entire files as one record, this can be very fast,
  often faster than specialized programs like @samp{fgrep}.  The following
  scans a list of files (@samp{@@files}) for a list of words
***************
*** 3859,3865 ****
  @}
  $search .= "@}";
  @@ARGV = @@files;
! $/ = "\177";            # something that doesn't occur
  eval $search;           # this screams
  $/ = "\n";              # put back to normal input delim
  foreach $file (sort keys(%seen)) @{
--- 3918,3924 ----
  @}
  $search .= "@}";
  @@ARGV = @@files;
! undef $/
  eval $search;           # this screams
  $/ = "\n";              # put back to normal input delim
  foreach $file (sort keys(%seen)) @{
***************
*** 3914,3933 ****
  @cindex @code{y/SEARCHLIST/REPLACEMENTLIST/} example
  $ARGV[1] =~ y/A-Z/a-z/;          # canonicalize to lower case
  
! $cnt = tr/*/*/;                    # count the stars in $_
  
! $cnt = tr/0-9//;                   # count the digits in $_
  
! tr/a-zA-Z//s;                      # bookkeeper -> bokeper
  
  ($HOST = $host) =~ tr/a-z/A-Z/;
  
  y/\001-@@[-_@{-\177/ /;            # change non-alphas to space
!                                    #   (before the c & s modifiers)
! y/a-zA-Z/ /cs;                     # change non-alphas to single space
!                                    #   (version 3.0 patchlevel 40+)
  
! tr/\200-\377/\0-\177/;             # delete 8th bit
  @end example
  @end table
  
--- 3973,3992 ----
  @cindex @code{y/SEARCHLIST/REPLACEMENTLIST/} example
  $ARGV[1] =~ y/A-Z/a-z/;          # canonicalize to lower case
  
! $cnt = tr/*/*/;                  # count the stars in $_
  
! $cnt = tr/0-9//;                 # count the digits in $_
  
! tr/a-zA-Z//s;                    # bookkeeper -> bokeper
  
  ($HOST = $host) =~ tr/a-z/A-Z/;
  
  y/\001-@@[-_@{-\177/ /;            # change non-alphas to space
!                                  #   (before the c & s modifiers)
! y/a-zA-Z/ /cs;                   # change non-alphas to single space
!                                  #   (version 3.0 patchlevel 40+)
  
! tr/\200-\377/\0-\177/;           # delete 8th bit
  @end example
  @end table
  
***************
*** 5459,5475 ****
  
  @item q/@var{STRING}/
  @itemx qq/@var{STRING}/
  @cindex Quote operator
  @findex q (single quote operator)
  @findex qq (double quote operator)
  These are not really functions, but simply syntactic sugar to let you
  avoid putting too many backslashes into quoted strings.  The @code{q}
  operator is a generalized single quote, and the @code{qq} operator a
! generalized double quote.  Any non-alphanumeric delimiter can be used in
! place of @samp{/}, including newline.  If the delimiter is an opening
! bracket or parenthesis, the final delimiter will be the corresponding
! closing bracket or parenthesis.  (Embedded occurrences of the closing
! bracket need to be backslashed as usual.)  Examples:@refill
  
  @example
  @cindex Example, @code{q} operator
--- 5518,5537 ----
  
  @item q/@var{STRING}/
  @itemx qq/@var{STRING}/
+ @itemx qx/@var{STRING}/
  @cindex Quote operator
  @findex q (single quote operator)
  @findex qq (double quote operator)
+ @findex qx (backquote operator)
  These are not really functions, but simply syntactic sugar to let you
  avoid putting too many backslashes into quoted strings.  The @code{q}
  operator is a generalized single quote, and the @code{qq} operator a
! generalized double quote.  The @code{qx} operator is a generalized
! backquote.  Any non-alphanumeric delimiter can be used in place of
! @samp{/}, including newline.  If the delimiter is an opening bracket or
! parenthesis, the final delimiter will be the corresponding closing
! bracket or parenthesis.  (Embedded occurrences of the closing bracket
! need to be backslashed as usual.)  Examples:@refill
  
  @example
  @cindex Example, @code{q} operator
***************
*** 5478,5483 ****
--- 5540,5546 ----
  @cindex @code{qq} operator example
  $foo = q!I said, "You said, 'She said it.'"!;
  $bar = q('This is it.');
+ $today = qx@{ date @};
  $_ .= qq
  *** The previous line contains the naughty word "$&".\n
          if /(ibm|apple|awk)/;      # :-)
***************
*** 5826,5850 ****
  of the V8 routines.)  In addition, @samp{\w} matches an alphanumeric
  character (including @samp{_}) and @samp{\W} a nonalphanumeric.  Word
  boundaries may be matched by @samp{\b}, and non-boundaries by @samp{\B}.
! A whitespace character is matched by @samp{\s}, non-whitespace by @samp{\S}.
! A numeric character is matched by @samp{\d}, non-numeric by @samp{\D}.
! You may use @samp{\w}, @samp{\s} and @samp{\d} within character classes.
! Also, @samp{\n}, @samp{\r}, @samp{\f}, @samp{\t} and @samp{\NNN} have
! their normal interpretations.  Within character classes @samp{\b}
! represents backspace rather than a word boundary.  Alternatives may be
! separated by @samp{|}.  The bracketing construct @samp{(@dots{})} may
! also be used, in which case @samp{\<digit>} matches the digit'th
! substring, where digit can range from 1 to 9.  (Outside of the pattern,
! always use @samp{$} instead of @samp{\} in front of the digit.  The
! scope of @samp{$<digit>} (and @samp{$`}, @samp{$&} and @samp{$'})
! extends to the end of the enclosing BLOCK or eval string, or to the next
! pattern match with subexpressions.  The @samp{\<digit>} notation
! sometimes works outside the current pattern, but should not be relied
! upon.)  @samp{$+} returns whatever the last bracket match matched.
! @samp{$&} returns the entire matched string.  (@samp{$0} used to return
! the same thing, but not any more.)  @samp{$`} returns everything before
! the matched string.  @samp{$'} returns everything after the matched
! string.  Examples:@refill
  
  @example
  @cindex Examples of regular expressions
--- 5889,5922 ----
  of the V8 routines.)  In addition, @samp{\w} matches an alphanumeric
  character (including @samp{_}) and @samp{\W} a nonalphanumeric.  Word
  boundaries may be matched by @samp{\b}, and non-boundaries by @samp{\B}.
! A whitespace character is matched by @samp{\s}, non-whitespace by
! @samp{\S}.  A numeric character is matched by @samp{\d}, non-numeric by
! @samp{\D}.  You may use @samp{\w}, @samp{\s} and @samp{\d} within
! character classes.  Also, @samp{\n}, @samp{\r}, @samp{\f}, @samp{\t} and
! @samp{\NNN} have their normal interpretations.  Within character classes
! @samp{\b} represents backspace rather than a word boundary.
! Alternatives may be separated by @samp{|}.  The bracketing construct
! @samp{(@dots{})} may also be used, in which case @samp{\<digit>} matches
! the digit'th substring.  (Outside of the pattern, always use @samp{$}
! instead of @samp{\} in front of the digit.  The scope of @samp{$<digit>}
! (and @samp{$`}, @samp{$&} and @samp{$'}) extends to the end of the
! enclosing BLOCK or eval string, or to the next pattern match with
! subexpressions.  The @samp{\<digit>} notation sometimes works outside
! the current pattern, but should not be relied upon.)  You may have as
! many parentheses as you wish.  If you have more than 9 substrings, the
! variables @samp{$10}, @samp{$11}, @dots{} refer to the corresponding
! substring.  Within the pattern, @samp{\10}, @samp{\11}, etc. refer back
! to substrings if there have been at least that many left parens before
! the backreference.  Otherwise (for backward compatibilty) @samp{\10} is
! the same as @samp{\010}, a backspace, and @samp{\11} the same as
! @samp{\011}, a tab.  And so on.  (@samp{\1} through @samp{\9} are always
! backreferences.)@refill
! 
! @samp{$+} returns whatever the last bracket match matched.  @samp{$&}
! returns the entire matched string.  (@samp{$0} used to return the same
! thing, but not any more.)  @samp{$`} returns everything before the
! matched string.  @samp{$'} returns everything after the matched string.
! Examples:@refill
  
  @example
  @cindex Examples of regular expressions
***************
*** 6224,6231 ****
  @item $/
  The input record separator, newline by default.  Works like @code{awk}'s
  RS variable, including treating blank lines as delimiters if set to the
! null string.  If set to a value longer than one character, only the
! first character is used.  (Mnemonic: @samp{/} is used to delimit line
  boundaries when quoting poetry.)@refill
  
  @item $,
--- 6296,6303 ----
  @item $/
  The input record separator, newline by default.  Works like @code{awk}'s
  RS variable, including treating blank lines as delimiters if set to the
! null string.  You may set it to a multicharacter string to match a
! multi-character delimiter.  (Mnemonic: @samp{/} is used to delimit line
  boundaries when quoting poetry.)@refill
  
  @item $,
***************
*** 6355,6361 ****
  
  @item $0
  Contains the name of the file containing the @emph{perl} script being
! executed.  (Mnemonic: same as @code{sh} and @code{ksh}.)@refill
  
  @item $<digit>
  Contains the subpattern from the corresponding set of parentheses in the
--- 6427,6435 ----
  
  @item $0
  Contains the name of the file containing the @emph{perl} script being
! executed.  Assigning to @samp{$0} modifies the argument area that the
! @code{ps(1)} program sees.  (Mnemonic: same as @code{sh} and
! @code{ksh}.)@refill
  
  @item $<digit>
  Contains the subpattern from the corresponding set of parentheses in the
***************
*** 6493,6498 ****
--- 6567,6592 ----
  @samp{ \n-}, to break on whitespace or hyphens.  (Mnemonic: a ``colon''
  in poetry is a part of a line.)@refill
  
+ @item $^D
+ The current value of the debugging flags.  (Mnemonic: value of @samp{-D}
+ switch.)@refill
+ 
+ @item $^I
+ The current value of the inplace-edit extension.  Use @code{undef} to
+ disable inplace editing.  (Mnemonic: value of @samp{-i} switch.)@refill
+ 
+ @item $^P
+ The name that Perl itself was invoked as, from argv[0].
+ 
+ @item $^T
+ The time at which the script began running, in seconds since the epoch.
+ The values returned by the @samp{-M}, @samp{-A}, and @samp{-C} filetests
+ are based on this value.@refill
+ 
+ @item $^W
+ The current value of the warning switch.  (Mnemonic: related to the
+ @samp{-w} switch.)
+ 
  @item $ARGV
  The scalar variable @samp{$ARGV} contains the name of the current file
  when reading from @samp{<>}.@refill
***************
*** 7153,7159 ****
  @section Bugs in a2p
  @cindex a2p bugs
  @cindex a2p problems
! @cindex Problems with conversion of awk scripts using a2p
  @cindex Problems using a2p
  
  It would be possible to emulate awk's behavior in selecting string
--- 7247,7253 ----
  @section Bugs in a2p
  @cindex a2p bugs
  @cindex a2p problems
! @cindex Problems converting awk scripts using a2p
  @cindex Problems using a2p
  
  It would be possible to emulate awk's behavior in selecting string
***************
*** 7476,7482 ****
  operations such as type casting, @code{atof()} and @code{sprintf()}.@refill
  
  If your stdio requires a @code{seek} or @code{eof} between reads and writes
! on a particular stream, so does @emph{perl}.@refill
  
  While none of the built-in data types have any arbitrary size limits (apart
  from memory size), there are still a few arbitrary limits: a given
--- 7570,7577 ----
  operations such as type casting, @code{atof()} and @code{sprintf()}.@refill
  
  If your stdio requires a @code{seek} or @code{eof} between reads and writes
! on a particular stream, so does @emph{perl}.  (This doesn't apply to
! @code{sysread()} and @code{syswrite()}.)@refill
  
  While none of the built-in data types have any arbitrary size limits (apart
  from memory size), there are still a few arbitrary limits: a given
***************
*** 7515,7526 ****
  
  @itemize @bullet
  @item
! The @samp{-0} switch was added to Perl after the book went to press.
  @item
! The new @samp{@@###.##} format was omitted accidentally.
  @item
! It wasn't known at press time that @samp{s///ee} caused multiple
! evaluations.
  @end itemize
  
  @node     Command Summary, Function Index, Errata, Top
--- 7610,7663 ----
  
  @itemize @bullet
  @item
! On page 5, the examples which read
! 
! @example
! eval '/usr/bin/perl
! @end example
! 
! should read
! 
! @example
! eval 'exec /usr/bin/perl
! @end example
! 
! @item
! On page 195, the equivalent to the System V @code{sum} program only works for
! very small files.  To do larger files, use
! 
! @example
! undef $/;
! $checksum = unpack("%32C*",<>) % 32767;
! @end example
! 
! @item
! The @samp{-0} switch to set the initial value of @samp{$/} was added to
! Perl after the book went to press.
! @item
! The @samp{-l} switch now does automatic line ending processing.
! @item
! The @code{qx//} construct is now a synonym for backticks.
! @item
! @samp{$0} may now be assigned to set the argument displayed by
! @code{ps(1)}.@refill
! @item
! The new @samp{@@###.##} format was omitted accidentally from the
! description on formats.@refill
! @item
! It wasn't known at press time that @code{s///ee} caused multiple
! evaluations of the replacement expression.  This is to be construed as a
! feature.@refill
! @item
! @code{(@var{LIST}) x $count} now does array replication.
! @item
! There is now no limit on the number of parentheses in a regular
! expression.@refill
  @item
! In double-quote context, more escapes are supported: \e, \a, \x1b, \c[,
! \l, \L, \u, \U, \E.  The latter five control up/lower case translation.
  @item
! The @samp{$/} variable may now be set to a multi-character delimiter.
  @end itemize
  
  @node     Command Summary, Function Index, Errata, Top