home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD2.bin / bbs / gnu / gawk-2.15.5-src.lha / gawk-2.15.5 / vms / gawk.hlp < prev    next >
Text File  |  1992-07-06  |  61KB  |  1,190 lines
  1. ! Gawk.Hlp
  2. !                                                       Pat Rankin, Jun'90
  3. !                                                          revised, Jun'91
  4. !                                                          revised, Jul'92
  5. !   Online help for GAWK.
  6. !
  7. 1 GAWK
  8.  GAWK is GNU awk, the Free Software Foundation's implementation of
  9.  the awk programming language.  awk is an interpretive language which
  10.  can handle many data-reformatting jobs with just a few lines of code.
  11.  It has powerful string manipulation and pattern matching capabilities
  12.  built in.  This version should be compatible with POSIX 1003.2 awk.
  13.  
  14.  The VMS version of GAWK supports both the original UN*X-style command
  15.  interface and a DCL interface.  The only setup requirement for GAWK
  16.  is to define it as a 'foreign' command:  a DCL symbol with a value
  17.  which begins with '$'.
  18.        $ GAWK :== $disk:[directory]GAWK
  19. 2 GNU_syntax
  20.  GAWK's UN*X-style interface uses the 'dash' convention for specifying
  21.  options and uses spaces to separate multiple arguments.
  22.  
  23.  There are two main alternatives, depending on how the awk program is
  24.  to be passed to GAWK.  Both alternatives share most options.
  25.  
  26.  Usage: $ gawk [-W opts] [-F fs] [-v var=val] -f progfile [--] file ...
  27.     or  $ gawk [-W opts] [-F fs] [-v var=val] [--] "program" file ...
  28.  
  29.  The options are case-sensitive.  On VMS, the DCL command interpreter
  30.  converts unquoted text into uppercase before passing it to the running
  31.  program.  However, GAWK is written in 'C' and the C Run-Time Library
  32.  (VAXCRTL) converts unquoted text into *lowercase*.  Therefore, the
  33.  -Fval and -W options must be enclosed in quotes.
  34.  
  35.  Note:  under VMS POSIX, the usual shell command line processing occurs.
  36. 3 options
  37.  -f file    use the specified file as the awk program source; if more
  38.             than one instance of -f is used, each file will be read
  39.             in succession
  40.  -Fstring   define a value for the FS variable (field separator)
  41.  -v var=val assign a value of 'val' to the variable 'var'
  42.  -W 'options'  additional gawk-specific options; multiple values may
  43.             be separated by commas, or by spaces if they're quoted,
  44.             or mulitple occurrences of -W may be used.
  45.  -W compat  use awk "compatibility mode" to disable GAWK extensions
  46.             and get the behavior of UN*X awk.
  47.  -W copyright [or -W copyleft]  display an abbreviated version of
  48.             the GNU copyright information
  49.  -W lint    warn about suspect or non-portable awk program code
  50.  -W posix   compatibility mode with additional restrictions
  51.  -W version display program version number
  52.  --         don't check further arguments for leading dash
  53. 3 program_text
  54.  If the '-f file' option is not used on the command line, then the
  55.  first "non-dash" argument is assumed to be a string of text containing
  56.  the awk source program.  Here is a complete sample program:
  57.        $ gawk -- "BEGIN {print ""\nHello, World!\n""}"
  58.  This program would print a blank line (based on first "\n"), followed
  59.  by a line reading "Hello, World!", followed by another blank line
  60.  (since awk's 'print' statement includes the trailing 'newline').
  61.  
  62.  On VMS, to include a quote character inside of a quoted string, two
  63.  successive quotes ("") must be used.  (Not necessary for VMS POSIX.)
  64. 3 data_files
  65.  After all dash-options are examined, and after the program text if
  66.  there were no occurrences of the -f option, remaining (space separated)
  67.  command line arguments are considered to be data files for the awk
  68.  program to process.  If any of these actually contains an equals sign
  69.  (=), then it is interpreted as a variable assignment instead of a data
  70.  file.  The syntax is 'variable_name=value'.  For example, the command
  71.        $ gawk -f myprog.awk infile.one flag=2 start=0 infile.two
  72.  would read file 'infile.one' for the program in 'myprog.awk', then it
  73.  would set 'flag' to 2 and 'start' to 0, and finally it would read file
  74.  'infile.two' for the program.  Note that in a case like this, the two
  75.  assignments actually occur after the first file has been processed,
  76.  not at program startup when the command line is first scanned.
  77. 3 IO_redirection
  78.  The command parsing in the VMS implementation of GAWK does some
  79.  emulation of a UN*X-style shell, where certain characters on the
  80.  command line have special meaning.  In particular, the symbols '<',
  81.  '>', '|', '*', and '?' receive special handling before the main part
  82.  of the program has a chance to see them.  The symbols '<' and '>'
  83.  perform some file manipulation from the command line:
  84.  
  85.  <ifile     open file 'ifile' (readonly) as 'stdin' [SYS$INPUT]
  86.  >nfile     create 'nfile' as 'stdout' [SYS$OUTPUT], in stream-lf format
  87.  >>ofile    append to 'ofile' for 'stdout'; create it if necessary
  88.  >&efile    point 'stderr' [SYS$ERROR] at 'efile', but don't open it yet
  89.  >$vfile    create 'vfile' as 'stdout', using RMS attributes appropriate
  90.             for a standard text file (variable length records with
  91.             implied carriage control)
  92.  2>&1       route error messages into the regular output stream
  93.  1>&2       send output data to the error destination
  94.  <<sentinel error; reading stdin until 'sentinel' not supported
  95.  <-, >-     error; closure of stdin or stdout from cmd line not supported
  96.  >>$vfile   incorrect; would be interpreted as file "$vfile" in stream-lf
  97.             format rather than as file "vfile" in RMS 'text' format
  98.  |          error; command line pipes not supported
  99.  
  100.  Note:  under VMS POSIX these features are implemented by the shell
  101.  rather than inside GAWK, so consult the shell documentation for
  102.  specific details.
  103. 3 wildcard_expansion
  104.  The command parsing in the VMS implementation of GAWK does some
  105.  emulation of a UN*X-style shell, where certain characters on the
  106.  command line have special meaning.  In particular, the symbols '<',
  107.  '>', '*', '%', and '?' receive special handling before the main part
  108.  of the program has a chance to see them.  The symbols '*', '%' and '?'
  109.  are used as wildcards in filenames.  '*' and '%' have their usual VMS
  110.  meanings of multiple character and single character wildcards,
  111.  respectively, and '?' is also treated as a single character wildcard.
  112.  
  113.  When a command line argument that should be a filename contains any
  114.  of the wildcard characters, a directory lookup is attempted for files
  115.  which match the specified pattern.  If one or more matching files are
  116.  found, those filenames are put into the command line in place of the
  117.  original pattern.  If no matching files are found, the original
  118.  pattern is left in place.
  119.  
  120.  Note:  under VMS POSIX wildcard expansion, or "file globbing", is
  121.  performed by the shell rather than inside GAWK, so consult the shell
  122.  documentation for details.  In particular, the last sentence of the
  123.  previous paragraph does not apply.
  124. 2 DCL_syntax
  125.  GAWK's DCL-style interface is more or less a standard DCL command, with
  126.  one required parameter.  Multiple values--when present--are separated
  127.  by commas.
  128.  
  129.  There are two main alternatives, depending on how the awk program is
  130.  to be passed to GAWK.  Both alternatives share most options.
  131.  
  132.  Usage:  GAWK  /COMMANDS="awk program text"  data_file[,data_file,...]
  133.     or   GAWK  /INPUT=awk_file  data_file[,"Var=value",data_file,...]
  134.  (  or   GAWK  /INPUT=(awk_file1,awk_file2,...)  data_file[,...]       )
  135.  
  136.  Not applicable under VMS POSIX.
  137. 3 Parameter
  138.  data_file[,datafile,...]       (data_file data_file ...)
  139.  data_file[,"Var=value",...,data_file,...]      (data_file Var=value &c)
  140.  
  141.   Data file(s) for the awk program to process.  If any of these
  142.   actually contains an equals sign (=), then it is interpreted as
  143.   a variable assignment instead of a data file.  The syntax is
  144.   "variable_name=value".  Quotes are required for non-file parameters.
  145.  
  146.   For example, the command
  147.        $ gawk/input=myprog.awk infile.one,"flag=2","start=0",infile.two
  148.   would read file 'infile.one' for the program in 'myprog.awk', then it
  149.   would set 'flag' to 2 and 'start' to 0, and finally it would read file
  150.   'infile.two' for the program.  Note that in a case like this, the two
  151.   assignments actually occur after the first file has been processed,
  152.   not at program startup when the command line is first scanned.
  153.  
  154.   Wildcard fi