gawk.hlp

早期freebsd实现

! Gawk.Hlp
!                                                       Pat Rankin, Jun'90
!                                                          revised, Jun'91
!                                                          revised, Jul'92
!   Online help for GAWK.
!
1 GAWK
 GAWK is GNU awk, the Free Software Foundation's implementation of
 the awk programming language.  awk is an interpretive language which
 can handle many data-reformatting jobs with just a few lines of code.
 It has powerful string manipulation and pattern matching capabilities
 built in.  This version should be compatible with POSIX 1003.2 awk.

 The VMS version of GAWK supports both the original UN*X-style command
 interface and a DCL interface.  The only setup requirement for GAWK
 is to define it as a 'foreign' command:  a DCL symbol with a value
 which begins with '$'.
       $ GAWK :== $disk:[directory]GAWK
2 GNU_syntax
 GAWK's UN*X-style interface uses the 'dash' convention for specifying
 options and uses spaces to separate multiple arguments.

 There are two main alternatives, depending on how the awk program is
 to be passed to GAWK.  Both alternatives share most options.

 Usage: $ gawk [-W opts] [-F fs] [-v var=val] -f progfile [--] file ...
    or  $ gawk [-W opts] [-F fs] [-v var=val] [--] "program" file ...

 The options are case-sensitive.  On VMS, the DCL command interpreter
 converts unquoted text into uppercase before passing it to the running
 program.  However, GAWK is written in 'C' and the C Run-Time Library
 (VAXCRTL) converts unquoted text into *lowercase*.  Therefore, the
 -Fval and -W options must be enclosed in quotes.

 Note:  under VMS POSIX, the usual shell command line processing occurs.
3 options
 -f file    use the specified file as the awk program source; if more
            than one instance of -f is used, each file will be read
            in succession
 -Fstring   define a value for the FS variable (field separator)
 -v var=val assign a value of 'val' to the variable 'var'
 -W 'options'  additional gawk-specific options; multiple values may
            be separated by commas, or by spaces if they're quoted,
            or mulitple occurrences of -W may be used.
 -W compat  use awk "compatibility mode" to disable GAWK extensions
            and get the behavior of UN*X awk.
 -W copyright [or -W copyleft]  display an abbreviated version of
            the GNU copyright information
 -W lint    warn about suspect or non-portable awk program code
 -W posix   compatibility mode with additional restrictions
 -W version display program version number
 --         don't check further arguments for leading dash
3 program_text
 If the '-f file' option is not used on the command line, then the
 first "non-dash" argument is assumed to be a string of text containing
 the awk source program.  Here is a complete sample program:
       $ gawk -- "BEGIN {print ""\nHello, World!\n""}"
 This program would print a blank line (based on first "\n"), followed
 by a line reading "Hello, World!", followed by another blank line
 (since awk's 'print' statement includes the trailing 'newline').

 On VMS, to include a quote character inside of a quoted string, two
 successive quotes ("") must be used.  (Not necessary for VMS POSIX.)
3 data_files
 After all dash-options are examined, and after the program text if
 there were no occurrences of the -f option, remaining (space separated)
 command line arguments are considered to be data files for the awk
 program to process.  If any of these actually contains an equals sign
 (=), then it is interpreted as a variable assignment instead of a data
 file.  The syntax is 'variable_name=value'.  For example, the command
       $ gawk -f myprog.awk infile.one flag=2 start=0 infile.two
 would read file 'infile.one' for the program in 'myprog.awk', then it
 would set 'flag' to 2 and 'start' to 0, and finally it would read file
 'infile.two' for the program.  Note that in a case like this, the two
 assignments actually occur after the first file has been processed,
 not at program startup when the command line is first scanned.
3 IO_redirection
 The command parsing in the VMS implementation of GAWK does some
 emulation of a UN*X-style shell, where certain characters on the
 command line have special meaning.  In particular, the symbols '<',
 '>', '|', '*', and '?' receive special handling before the main part
 of the program has a chance to see them.  The symbols '<' and '>'
 perform some file manipulation from the command line:

 <ifile     open file 'ifile' (readonly) as 'stdin' [SYS$INPUT]
 >nfile     create 'nfile' as 'stdout' [SYS$OUTPUT], in stream-lf format
 >>ofile    append to 'ofile' for 'stdout'; create it if necessary
 >&efile    point 'stderr' [SYS$ERROR] at 'efile', but don't open it yet
 >$vfile    create 'vfile' as 'stdout', using RMS attributes appropriate
            for a standard text file (variable length records with
            implied carriage control)
 2>&1       route error messages into the regular output stream
 1>&2       send output data to the error destination
 <<sentinel error; reading stdin until 'sentinel' not supported
 <-, >-     error; closure of stdin or stdout from cmd line not supported
 >>$vfile   incorrect; would be interpreted as file "$vfile" in stream-lf
            format rather than as file "vfile" in RMS 'text' format
 |          error; command line pipes not supported

 Note:  under VMS POSIX these features are implemented by the shell
 rather than inside GAWK, so consult the shell documentation for
 specific details.
3 wildcard_expansion
 The command parsing in the VMS implementation of GAWK does some
 emulation of a UN*X-style shell, where certain characters on the
 command line have special meaning.  In particular, the symbols '<',
 '>', '*', '%', and '?' receive special handling before the main part
 of the program has a chance to see them.  The symbols '*', '%' and '?'
 are used as wildcards in filenames.  '*' and '%' have their usual VMS
 meanings of multiple character and single character wildcards,
 respectively, and '?' is also treated as a single character wildcard.

 When a command line argument that should be a filename contains any
 of the wildcard characters, a directory lookup is attempted for files
 which match the specified pattern.  If one or more matching files are
 found, those filenames are put into the command line in place of the
 original pattern.  If no matching files are found, the original
 pattern is left in place.

 Note:  under VMS POSIX wildcard expansion, or "file globbing", is
 performed by the shell rather than inside GAWK, so consult the shell
 documentation for details.  In particular, the last sentence of the
 previous paragraph does not apply.
2 DCL_syntax
 GAWK's DCL-style interface is more or less a standard DCL command, with
 one required parameter.  Multiple values--when present--are separated
 by commas.

 There are two main alternatives, depending on how the awk program is
 to be passed to GAWK.  Both alternatives share most options.

 Usage:  GAWK  /COMMANDS="awk program text"  data_file[,data_file,...]
    or   GAWK  /INPUT=awk_file  data_file[,"Var=value",data_file,...]
 (  or   GAWK  /INPUT=(awk_file1,awk_file2,...)  data_file[,...]       )

 Not applicable under VMS POSIX.
3 Parameter
 data_file[,datafile,...]       (data_file data_file ...)
 data_file[,"Var=value",...,data_file,...]      (data_file Var=value &c)

  Data file(s) for the awk program to process.  If any of these
  actually contains an equals sign (=), then it is interpreted as
  a variable assignment instead of a data file.  The syntax is
  "variable_name=value".  Quotes are required for non-file parameters.

  For example, the command
       $ gawk/input=myprog.awk infile.one,"flag=2","start=0",infile.two
  would read file 'infile.one' for the program in 'myprog.awk', then it
  would set 'flag' to 2 and 'start' to 0, and finally it would read file
  'infile.two' for the program.  Note that in a case like this, the two
  assignments actually occur after the first file has been processed,
  not at program startup when the command line is first scanned.

  Wildcard file lookups are attempted on data file specifications.  See
  subtopic 'GAWK GNU_syntax wildcard_expansion' for details.

  At least one data_file parameter value is required.  An exception is
  made if /usage, /version, or /copyright is specified *and* if GAWK is
  defined as a 'foreign' command rather than a 'native' DCL command.
3 Qualifiers
/COMMANDS
 /COMMANDS="awk program text"   (-- "awk program text")

  For short programs, it is possible to include the complete program
  on the command line.  The quotes are required.  Here is a complete
  sample program:
       $ gawk/commands="BEGIN {print ""\nHello, World!\n""}" NL:
  This program would print a blank line (based on first "\n"), followed
  by a line reading "Hello, World!", followed by another blank line
  (since awk's 'print' statement includes the trailing 'newline').

  To include a quote character inside of a quoted string, two
  successive quotes ("") must be used.

  Either /COMMANDS or /INPUT (but not both) must be supplied.
/INPUT
 /INPUT=(awk_file1,awk_file2)   (-f awk_file1 -f awk_file2)

  Used to specify one or more files containing the source code of
  the awk program.  If more than one file is used, separate them
  with commas and enclose the list in parentheses.

  Multiple source files are processed in order as if they had been
  concatenated together.

  Either /INPUT or /COMMANDS (but not both) must be supplied.
/FIELD_SEPARATOR
 /FIELD_SEPARATOR="FS_value"    (-F"FS_value")

  Assign a value to the built in variable FS (field separator).
/VARIABLES
 /VARIABLES=("Var1=val1","Var2=val2",...)  (-v Var1=val1 -v Var2=val2)

  Assign value(s) to the specified variable(s).
/REG_EXPR
 /REG_EXPR={AWK | EGREP | POSIX}   (-a vs -e options [obsolete])

  This qualifier is obsolete and has no effect.
/STRICT
 /[NO]STRICT            (-"W compat" option)

  Use strict awk compatibility mode (/strict) and suppress GAWK
  extensions.  The default is /NOSTRICT.
/POSIX
 /[NO]POSIX             (-"W posix" option)

  Use POSIX compatibility mode (/posix) and suppress GAWK extensions.
  The default is /NOPOSIX.  Slightly more restrictive than /strict.
/LINT
 /[NO]LINT              (-"W lint" option)

  Check the awk program cafefully for potential problems that might
  be encountered if it were to be used with other awk implementations,
  and print warnings for anything found.  The default in /NOLINT.
/VERSION
 /VERSION               (-"W version" option)

  Print GAWK's version number.
/COPYRIGHT
 /COPYRIGHT             (-"W copyright" or -"W copyleft" option)

  Print a brief version of GAWK's copyright notice.
/USAGE
 /USAGE                 (no corresponding GNU_syntax option)

  Print a compact summary of the command line options.

  After the 'usage' message is printed, GAWK terminates regardless
  of any other command line options.
/OUTPUT
 /OUTPUT=out_file       (>$out_file)

  Write program output into 'out_file'.  The default is SYS$OUTPUT.
2 awk_language
 An awk program consists of one or more pattern-action pairs, sometimes
 referred to as "rules".  For each record of an input (data) file, the
 rules are checked sequentially.  Any pattern which matches the input
 record triggers that rule's action.  Actions are instructions which
 resemble statements in the 'C' programming language.  Patterns come
 in several varieties, including field comparisons, regular expression
 matching, and special cases defined by reserved keywords.

 All awk keywords and variables are case-sensitive.  Text matching is
 also sensitive to character case unless the builtin variable IGNORECASE
 is set to a non-zero value.
3 rules
 The syntax for a pattern-action 'rule' is simply
       PATTERN { ACTION }
 where the braces ({}) are required punctuation for the action.
 Semicolons (;) or 'newlines' (ie, having the text on a separate line)
 delimit multiple rules and also multiple actions within a given rule.
 Either the pattern or the action may be omitted; an empty pattern
 matches every record of the input file; a missing action (not an empty
 action inside of braces), is an implicit request to print the current
 record; an empty action (ie, {}) is legal but not very useful.
3 patterns
 There are several types of patterns available for awk rules.

  expression  an 'expression' is something to be evaluated (perhaps
                         a comparison or function call) which will
                         be considered true if non-zero (for numeric
                         results) or if non-null (for strings)
  /regular_expression/ slashes (/) delimit a regular expression
                         which is used as a pattern
  pattern1, pattern2   a pair of patterns separated by a comma (,),
                         which causes a range of records to trigger
                         the associated action; the records which
                         match the patterns are included in the range
  <null>      an omitted pattern (in this text, the  string '<null>'
                         is displayed, but in an awk program, it
                         would really be blank) matches every record
  BEGIN       keyword for specifying a rule to be executed prior to
                         reading the 1st record of the 1st input file
  END         keyword for specifying a rule to be executed after
                         handling the last input record of last file
4 examples
 Some example patterns (mostly with the corresponding actions omitted)

 NF > 0     # comparison expression:  matches non-null records
 $0         # implied comparison:  also matches non-null records
 $2 > 1000 && sum <= 999999     # slightly more elaborate expression
 /x/        # regular expression matching any record with an 'x' in it
 /^ /       # reg-expr matching records beginning with a space
 $1 == "start", $NF == "stop"   # range pattern for input in which
                some data lines begin with 'start' and/or end with
                'stop' in order to collect groups of records
        { sum += $1 }   # null pattern:  it's action (add field #1 to
                variable 'sum') would be executed for every record
 BEGIN  { sum = 0 }     # keyword 'BEGIN':  perform this action before
                reading the input file (note: initialization to 0 is
                unnecessary in awk)
 END    { print "total =", sum }    # keyword 'END':  perform this
                action after the last input record has been processed
3 actions
 An 'action' is something to do when a given record has matched the
 corresponding pattern in a rule.  In general, actions resemble 'C'
 statements and expressions.  The action in a rule must be enclosed
 in braces ({}).