'================================================================== SPECIAL.DAT
' PERL Special Variables for Norton Guides Database
' Kevin Grover, grover@isri.unlv.edu, 11 Jun 1992, Mod: 27 Feb 1993
'==============================================================================
'
'--------------------------------------------------------------------------- $_
'
!short: $_     Default input and pattern-searching space

     $_      The default input and pattern-searching space.   The
             following pairs are equivalent:

                  while (<>) {...     # only equivalent in while!
                  while ($_ = <>) {...

                  /^^Subject:/
                  $_ =~ /^^Subject:/

                  y/a-z/A-Z/
                  $_ =~ y/a-z/A-Z/

                  chop
                  chop($_)

             (Mnemonic: underline is understood in certain opera-
             tions.)
'
'--------------------------------------------------------------------------- $.
'
!short: $.     Current input line number of last filehandle that was read

     $.      The current input line number of the last filehandle
             that  was  read.   Readonly.   Remember that only an
             explicit close on the  filehandle  resets  the  line
             number.  Since <> never does an explicit close, line
             numbers increase across ARGV files (but see examples
             under  eof).  (Mnemonic: many programs use . to mean
             the current line number.)
'
'--------------------------------------------------------------------------- $/
'
!short: $/     Input record separator, newline by default

     $/      The input  record  separator,  newline  by  default.
             Works  like  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: / is used  to
             delimit line boundaries when quoting poetry.)
'
'--------------------------------------------------------------------------- $,
'
!short: $,     Output field separator for the print operator

     $,      The output field separator for the  print  operator.
             Ordinarily  the print operator simply prints out the
             comma separated fields you specify.  In order to get
             behavior  more  like  awk,  set this variable as you
             would set awk's OFS  variable  to  specify  what  is
             printed  between fields.  (Mnemonic: what is printed
             when there is a , in your print statement.)
'
'--------------------------------------------------------------------------- $"
'
!short: $"     Separator which joins elements of arrays interpolated in strings

     $"      This is like $, except  that  it  applies  to  array
             values  interpolated into a double-quoted string (or
             similar interpreted string).  Default  is  a  space.
             (Mnemonic: obvious, I think.)
'
'--------------------------------------------------------------------------- $\
'
!short: $\     Output record separator for the print operator

     $\      The output record separator for the print  operator.
             Ordinarily  the print operator simply prints out the
             comma separated fields you specify, with no trailing
             newline  or  record  separator assumed.  In order to
             get behavior more like awk, set this variable as you
             would  set  awk's  ORS  variable  to specify what is
             printed at the end of the print.  (Mnemonic: you set
             $\  instead  of  adding  \n at the end of the print.
             Also, it's just like /, but it's what you get "back"
             from perl.)
'
'--------------------------------------------------------------------------- $#
'
!short: $#     Output format for printer numbers.  Initial valis is "%.20g"

     $#      The output format for printed numbers.   This  vari-
             able is a half-hearted attempt to emulate awk's OFMT
             variable.  There are times, however,  when  awk  and
             perl  have  differing  notions  of  what  is in fact
             numeric.  Also, the initial value  is  %.20g  rather
             than  %.6g,  so you need to set $# explicitly to get
             awk's value.  (Mnemonic: # is the number sign.)
'
'--------------------------------------------------------------------------- $%
'
!short: $%     Current page number of the current output channel.

     $%      The current page number of  the  currently  selected
             output  channel.   (Mnemonic:  %  is  page number in
             nroff.)
'
'--------------------------------------------------------------------------- $=
'
!short: $=     Page length of current output channel.  Default is 60 lines.

     $=      The current page length  (printable  lines)  of  the
             currently  selected  output channel.  Default is 60.
             (Mnemonic: = has horizontal lines.)
'
'--------------------------------------------------------------------------- $-
'
!short: $-     Number of lines left on the page

     $-      The  number  of  lines  left  on  the  page  of  the
             currently   selected   output  channel.   (Mnemonic:
             lines_on_page - lines_printed.)
'
'--------------------------------------------------------------------------- $~
'
!short: $~     Name of the current report format

     $~      The name  of  the  current  report  format  for  the
             currently  selected output channel.  Default is name
             of the filehandle.  (Mnemonic: brother to $^^.)
'
'--------------------------------------------------------------------------- $^
'
!short: $^^     Name of the current top-of-page format

     $^^      The name of the current top-of-page format  for  the
             currently  selected output channel.  Default is name
             of the filehandle with "_TOP" appended.   (Mnemonic:
             points to top of page.)
'
'--------------------------------------------------------------------------- $|
'
!short: $|     Force flush after exec write or print on currnet channel (0=no)

     $|      If set to nonzero, forces a flush after every  write
             or  print  on the currently selected output channel.
             Default is 0.  Note that STDOUT  will  typically  be
             line buffered if output is to the terminal and block
             buffered otherwise.  Setting this variable is useful
             primarily when you are outputting to a pipe, such as
             when you are running a perl  script  under  rsh  and
             want   to   see   the   output  as  it's  happening.
             (Mnemonic: when you want your  pipes  to  be  piping
             hot.)
'
'--------------------------------------------------------------------------- $$
'
!short: $$     Process number of the perl running this script

     $$      The process number of the perl running this  script.
             (Mnemonic:  same  as  shells.)   On  MS-DOS, this is
             perl's PSP (program segment prefix) segment.
'
'--------------------------------------------------------------------------- $?
'
!short: $?     Status returned by last 'CMD', pipe close, or system operator

     $?      The status returned by the last pipe close, backtick
             (``)  command or system operator.  Note that this is
             the status word returned by the wait() system  call,
             so  the exit value of the subprocess is actually ($?
             >> 8).  $? & 255 gives which  signal,  if  any,  the
             process  died  from,  and  whether  there was a core
             dump.  MS-DOS users  should  note  that  the  MS-DOS
             return values are fudged internally so that $? gives
             Unix-like results.  (Mnemonic:  similar  to  sh  and
             ksh.)
'
'--------------------------------------------------------------------------- $&
'
!short: $&     String matched by the last pattern match

     $&      The string matched by the last  pattern  match  (not
             counting  any  matches hidden within a BLOCK or eval
             enclosed by the current BLOCK).  (Mnemonic:  like  &
             in some editors.)
'
'--------------------------------------------------------------------------- $`
'
!short: $`     String preceding what was matched by last pattern match

     $`      The string preceding whatever  was  matched  by  the
             last  pattern match (not counting any matches hidden
             within a BLOCK  or  eval  enclosed  by  the  current
             BLOCK).    (Mnemonic:  `  often  precedes  a  quoted
             string.)
'
'--------------------------------------------------------------------------- $'
'
!short: $'     String following what was matched by last pattern match

     $'      The string following whatever  was  matched  by  the
             last  pattern match (not counting any matches hidden
             within a BLOCK  or  eval  enclosed  by  the  current
             BLOCK).    (Mnemonic:   '  often  follows  a  quoted
             string.)  Example:

                  $_ = 'abcdefghi';
                  /def/;
                  print "$`:$&:$'\n";      # prints abc:def:ghi
'
'--------------------------------------------------------------------------- $+
'
!short: $+     Last bracket matched by last search pattern

     $+      The last bracket matched by the last search pattern.
             This  is  useful if you don't know which of a set of
             alternative patterns matched.  For example:

                 /Version: (.*)|Revision: (.*)/ && ($rev = $+);

             (Mnemonic: be positive and forward looking.)
'
'--------------------------------------------------------------------------- $*
'
!short: $*     Flag for multiline matching in strings (zero=no, non-zero-yes)

     $*      Set to 1 to do multiline matching within a string, 0
             to tell perl that it can assume that strings contain
             a single line, for the purpose of optimizing pattern
             matches.  Pattern matches on strings containing mul-
             tiple newlines can produce confusing results when $*
             is  0.  Default is 0.  (Mnemonic: * matches multiple
             things.)  Note that this  variable  only  influences
             the  interpretation  of  ^^ and $.  A literal newline
             can be searched for even when $* == 0.
'
'--------------------------------------------------------------------------- $0
'
!short: $0     Name of the file containing the perl script being executed

     $0      Contains the name of the file  containing  the  perl
             script being executed.  Assigning to $0 modifies the
             argument  area  that   the   ps(1)   program   sees.
             (Mnemonic: same as sh and ksh.)
'
'------------------------------------------------------------------------- $<d>
'
!short: $<d>   ($1..$9,etc) Subpatterns matched in last pattern matched

     $<digit>
             Contains the subpattern from the  corresponding  set
             of  parentheses  in  the  last  pattern matched, not
             counting patterns matched in nested blocks that have
             been exited already.  (Mnemonic: like \digit.)
'
'--------------------------------------------------------------------------- $[
'
!short: $[     Index of the first element in an array and 1st char in string

     $[      The index of the first element in an array,  and  of
             the  first  character in a substring.  Default is 0,
             but you could set it to 1 to make perl  behave  more
             like  awk  (or  Fortran)  when subscripting and when
             evaluating  the  index()  and  substr()   functions.
             (Mnemonic: [ begins subscripts.)
'
'--------------------------------------------------------------------------- $]
'
!short: $]     Perl version string (displayed by perl -v)

     $]      The string printed out when you say "perl  -v".   It
             can  be  used  to  determine  at  the beginning of a
             script whether the perl  interpreter  executing  the
             script  is  in the right range of versions.  If used
             in  a  numeric  context,  returns  the   version   +
             patchlevel / 1000.  Example:

                  # see if getc is available
                     ($version,$patchlevel) =
                        $] =~ /(\d+\.\d+).*\nPatch level: (\d+)/;
                     print STDERR "(No filename completion available.)\n"
                        if $version * 1000 + $patchlevel < 2016;

             or, used numerically,

                  warn "No checksumming!\n" if $] < 3.019;

             (Mnemonic: Is this version  of  perl  in  the  right
             bracket?)
'
'--------------------------------------------------------------------------- $;
'
!short: $;     Subscript separator for multi-dimensoinal array emulation.

     $;      The subscript separator for multi-dimensional  array
             emulation.   If  you  refer  to an associative array
             element as
                  $foo{$a,$b,$c}

             it really means

                  $foo{join($;, $a, $b, $c)}

             But don't put

                  @foo{$a,$b,$c}      # a slice--note the @

             which means

                  ($foo{$a},$foo{$b},$foo{$c})

             Default is "\034", the same as SUBSEP in awk.   Note
             that  if  your  keys contain binary data there might
             not be any safe value for $;.  (Mnemonic: comma (the
             syntactic  subscript separator) is a semi-semicolon.
             Yeah, I know, it's pretty lame, but  $,  is  already
             taken for something more important.)
'
'--------------------------------------------------------------------------- $!
'
!short: $!     Current error number or string (depending upon context)

     $!      If used in a numeric  context,  yields  the  current
             value  of  errno, with all the usual caveats.  (This
             means that you shouldn't depend on the value  of  $!
             to  be anything in particular unless you've gotten a
             specific error return indicating  a  system  error.)
             If  used in a string context, yields the correspond-
             ing system error string.  You can assign  to  $!  in
             order  to set errno if, for instance, you want $! to
             return the string for error n, or you  want  to  set
             the  exit  value  for  the die operator.  (Mnemonic:
             What just went bang?)
'
'--------------------------------------------------------------------------- $@
'
!short: $@     Perl error message from last eval or "do EXPR" command

     $@      The perl syntax error message  from  the  last  eval
             command.  If null, the last eval parsed and executed
             correctly (although the operations you  invoked  may
             have  failed  in  the  normal  fashion).  (Mnemonic:
             Where was the syntax error "at"?)
'
'--------------------------------------------------------------------------- $<
'
!short: $<     Real uid of this process

     $<      The real uid of this process.  (Mnemonic:  it's  the
             uid you came FROM, if you're running setuid.)
'
'--------------------------------------------------------------------------- $>
'
!short: $>     Effective uid of this process

     $>      The effective uid of this process.  Example:

                  $< = $>;  # set real uid to the effective uid
                  ($<,$>) = ($>,$<);  # swap real and effective uid

             (Mnemonic: it's the uid you went TO, if you're  run-
             ning  setuid.)   Note: $< and $> can only be swapped
             on machines supporting setreuid().
'
'--------------------------------------------------------------------------- $(
'
!short: $(     Read gid of this process

     $(      The real gid of this  process.   If  you  are  on  a
             machine  that supports membership in multiple groups
             simultaneously, gives  a  space  separated  list  of
             groups  you  are  in.   The  first number is the one
             returned by getgid(), and  the  subsequent  ones  by
             getgroups(),  one  of  which  may be the same as the
             first number.  (Mnemonic: parentheses  are  used  to
             GROUP  things.   The real gid is the group you LEFT,
             if you're running setgid.)
'
'--------------------------------------------------------------------------- $)
'
!short: $)     Effective gid of this process

     $)      The effective gid of this process.  If you are on  a
             machine  that supports membership in multiple groups
             simultaneously, gives  a  space  separated  list  of
             groups  you  are  in.   The  first number is the one
             returned by getegid(), and the  subsequent  ones  by
             getgroups(),  one  of  which  may be the same as the
             first number.  (Mnemonic: parentheses  are  used  to
             GROUP things.  The effective gid is the group that's
             RIGHT for you, if you're running setgid.)

             Note: $<, $>, $( and $) can only be set on  machines
             that  support the corresponding set[re][ug]id() rou-
             tine.  $( and $) can only  be  swapped  on  machines
             supporting setregid().
'
'--------------------------------------------------------------------------- $:
'
!short: $:     Current set of characters after which a string may be broken

     $:      The current set of characters after which  a  string
             may  be broken to fill continuation fields (starting
             with ^^) in a format.  Default is " \n-", to break on
             whitespace or hyphens.  (Mnemonic: a "colon" in poe-
             try is a part of a line.)
'
'-------------------------------------------------------------------------- $^D
'
!short: $^^D    Debug flags as passed to perl using -D

     $^^D     The  current   value   of   the   debugging   flags.
             (Mnemonic: value of -D switch.)
'
'-------------------------------------------------------------------------- $^F
'
!short: $^^F    Highest system file descriptor, ordinarily 2

     $^^F     The maximum system file  descriptor,  ordinarily  2.
             System  file descriptors are passed to subprocesses,
             while higher file descriptors are  not.   During  an
             open,  system file descriptors are preserved even if
             the  open  fails.   Ordinary  file  descriptors  are
             closed before the open is attempted.
'
'-------------------------------------------------------------------------- $^I
'
!short: $^^I    In-place edit extention as passed to perl using -i

     $^^I     The current value  of  the  inplace-edit  extension.
             Use  undef  to  disable inplace editing.  (Mnemonic:
             value of -i switch.)
'
'-------------------------------------------------------------------------- $^P
'
!short: $^^P    Internal debuggin flag

     $^^P     The internal flag that the debugger clears  so  that
             it doesn't debug itself.  You could conceivable dis-
             able debugging yourself by clearing it.
'
'-------------------------------------------------------------------------- $^T
'
!short: $^^T    Time when program started (delivered by ^Btime^b).

     $^^T     The time at  which  the  script  began  running,  in
             seconds since the epoch.  The values returned by the
             -M , -A and -C filetests are based on this value.
'
'-------------------------------------------------------------------------- $^W
'
!short: $^^W    Value of the -w option passed to perl

     $^^W     The current value of the warning switch.  (Mnemonic:
             related to the -w switch.)
'
'-------------------------------------------------------------------------- $^X
'
!short: $^^X    Name by which perl was invoked

     $^^X     The name that Perl  itself  was  executed  as,  from
             argv[0].
'
'------------------------------------------------------------------------ $ARGV
'
!short: $ARGV  Name of the current file when reading from <>

     $ARGV   contains the name of the current file  when  reading
             from <>.
'
'------------------------------------------------------------------------ @ARGV
'
!short: @ARGV  Contains command line args for script (not included script name)

     @ARGV   The array ARGV contains the command  line  arguments
             intended  for  the  script.  Note that $#ARGV is the
             generally  number  of  arguments  minus  one,  since
             $ARGV[0]  is  the  first  argument,  NOT the command
             name.  See $0 for the command name.
'
'------------------------------------------------------------------------ @INC
'
!short: @INC   List of places to list for script included with ^Bdo^b and ^Brequire^b

     @INC    The array INC contains the list of  places  to  look
             for  perl  scripts  to be evaluated by the "do EXPR"
             command or the "require" command.  It initially con-
             sists  of  the  arguments  to  any  -I  command line
             switches, followed  by  the  default  perl  library,
             probably  "/usr/local/lib/perl", followed by ".", to
             represent the current directory.
'
'------------------------------------------------------------------------ %INC
'
!short: %INC   List of files the have been ^Brequire^bd or ^Bdo^bne

     %INC    The associative array INC contains entries for  each
             filename   that   has  been  included  via  "do"  or
             "require".  The key is the filename  you  specified,
             and  the  value is the location of the file actually
             found.  The "require" command  uses  this  array  to
             determine  whether  a  given  file  has already been
             included.
'
'------------------------------------------------------------------------ $ENV
'
!short: %ENV   Accessing the environment list as a hash table

     $ENV{expr}
             The associative  array  ENV  contains  your  current
             environment.   Setting  a  value  in ENV changes the
             environment for child processes.
'
'------------------------------------------------------------------------ $SIG
'
!short: %SIG   Set signal handlers via and associative array

     $SIG{expr}
             The associative array SIG  is  used  to  set  signal
             handlers for various signals.  Example:

                  sub handler {  # 1st argument is signal name
                       local($sig) = @_;
                       print "Caught a SIG$sig--shutting down\n";
                       close(LOG);
                       exit(0);
                  }

                  $SIG{'INT'} = 'handler';
                  $SIG{'QUIT'} = 'handler';
                  ...
                  $SIG{'INT'} = 'DEFAULT'; # restore default action
                  $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT

             The SIG array only contains values for  the  signals
             actually set within the perl script.
