! 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]GAWK2 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 dash3 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 file4 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 processed3 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 ({}).