.topic NoCtx
 {Mawk}
 {THE AWK LANGUAGE:Awk_Lang}
 {Index}

.topic Index

 {BEGIN:Program_structure}
 {END:Program_structure}
 {if:Program_structure}
 {while:Program_structure}
 {for:Program_structure}
 {do:Program_structure}
 {continue:Program_structure}
 {break:Program_structure}

 {ARGC:Builtin_var}
 {ARGV:Builtin_var}
 {FILENAME:Builtin_var}
 {FNR:Builtin_var}
 {FS:Builtin_var}
 {NF:Builtin_var}
 {NR:Builtin_var}
 {OFMT:Builtin_var}
 {OFS:Builtin_var}
 {ORS:Builtin_var}
 {RLENGTH:Builtin_var}
 {RS:Builtin_var}
 {RSTART:Builtin_var}
 {SUBSEP:Builtin_var}

 {gsub:Builtinfun}
 {index:Builtinfun}
 {length:Builtinfun}
 {match:Builtinfun}
 {split:Builtinfun}
 {sprintf:Builtinfun}
 {sub:Builtinfun}
 {substr:Builtinfun}
 {atan2:Builtinfun}
 {cos:Builtinfun}
 {exp:Builtinfun}
 {int:Builtinfun}
 {log:Builtinfun}
 {rand:Builtinfun}
 {sin:Builtinfun}
 {sqrt:Builtinfun}
 {srand:Builtinfun}

 {print:inout}
 {getline:inout}

.topic Mawk

MAWK(1)                   USER COMMANDS                   MAWK(1)



NAME
     mawk - pattern scanning and text processing language


SYNOPSIS
     mawk [-Fs] 'program text' [file ...]
     mawk [-Fs] -f program-file [file ...]
     {mawk -V:VMawk}


DESCRIPTION
     mawk is an interpreter for  the  AWK  Programming  Language.
     The  AWK  language is useful for manipulation of data files,
     text retrieval  and  processing,  and  for  prototyping  and
     experimenting with algorithms.  mawk is a new awk meaning it
     implements the AWK language as defined in Aho, Kernighan and
     Weinberger,  The  AWK  Programming  Language, Addison-Wesley
     Publishing, 1988.  (Hereafter referred to as the AWK book.)

     An AWK program is a sequence of pattern óactionò  pairs  and
     function  definitions.   Short  programs  are entered on the
     command  line  usually  enclosed  in  '  '  to  avoid  shell
     interpretation.   Longer programs can be read in from a file
     with the -f option.  Data  input is read from  the  list  of
     files  on  the  command line or from standard input when the
     list is empty.  The input is broken into records  as  deter-
     mined by the record separator variable, RS.  Initially, RS =
     "\n" and records are synonymous with lines.  Each record  is
     compared against each pattern and if it matches, the program
     text for óactionò is executed.


OPTIONS
     -Fs  Set the field separator, FS, to string s.


     -f file
          Read the program text from file  instead  of  from  the
          command line.


     {-V:VMawk}   mawk writes its version and copyright notice to  stdout
          and  internal limits to stderr and exits 0.  The inter-
          nal limits can be changed by recompilation.

     The -f option must be last and when the -V option is  recog-
     nized the rest of the command line is ignored.
.topic VMawk
 $Execute-
 $cn\mawk\mawk $NoReread $NoReDraw
 -V
.topic AWK_Lang

THE AWK LANGUAGE
  {1. Program structure:Program_structure}
  {2. Data types, conversion and comparison:Data_types}
  {3. Regular expressions:regexp}
  {4. Records and fields:Records}
  {5. Expressions and operators:Expressions}
  {6. Arrays:Arrays}
  {7. Builtin-variables:Builtin_var}
  {8. Built-in functions:Builtinfun}
  {9. Input and output:inout}
  {10. User defined functions:Userfunc}
  {11. Splitting strings, records and files:Splitting}
  {12. Multi-line records:Multiline}
  {13. Program execution:Program_exec}
  {EXAMPLES}
  {COMPATIBILITY ISSUES:COMPATIBILITY}
  {DIAGNOSTICS}
  {SEE ALSO:SEEALSO}
  {BUGS}
  {AUTHOR}
  {Notes for MsDOS:MsDOS}

.topic Program_structure
  1. Program structure
     An AWK program is a sequence of pattern óactionò  pairs  and
     user function definitions.
 {BEGIN:Color_X} {END:Color_X}
     A pattern can be:
          BEGIN
          END
          {expression:Expressions}
          /{regular expression:regexp}/
          ( pattern )
          ! pattern
          pattern || pattern
          pattern && pattern
          pattern , pattern    (a range pattern)

     Range, BEGIN and END patterns cannot be combined with  other
     patterns.   One,  but  not  both, of pattern óactionò can be
     omitted.   If óactionò is omitted it is implicitly  ó  print
     ò.   If  pattern  is omitted, then it is implicitly matched.
     BEGIN and END patterns require an action.

     Statements are terminated by newlines, semi-colons or  both.
     Groups  of  statements  such  as  actions or loop bodies are
     blocked via ó ... ò as in C.  The last statement in a  block
     doesn't  need a terminator.  Blank lines have no meaning; an
     empty statement is terminated with a semi-colon. Long state-
     ments can be continued with a backslash, \.  A statement can
     be broken without a backslash after a comma, left brace, &&,
     ||,  do,  else, the right parenthesis of an if, while or for
     statement, and the right parenthesis of a  function  defini-
     tion.   A comment starts with # and extends to, but does not
     include the end of line.

     The following statements control program flow inside blocks.
               {if:Color_X}
          if ( expr ) statement

          if ( expr ) statement else statement
               {while:Color_X}
          while ( expr ) statement
               {do:Color_X}
          do statement while ( expr )
               {for:Color_X}
          for ( opt_expr ; opt_expr ; opt_expr ) statement

          for ( var in array ) statement
               {continue:Color_X}
          continue
               {break:Color_X}
          break
.topic Data_types
  2. Data types, conversion and comparison
     There are two basic data types, numeric and string.  Numeric
     constants  can  be integer like -2, decimal like 1.08, or in
     scientific notation like -1.1e4 or .28E-3.  All numbers  are
     represented  internally  and  all  computations  are done in
     floating point arithmetic.  So for example,  the  expression
     0.2e2 == 20 is true and true is represented as 1.0.

     String constants are enclosed in double quotes.

           "This is a string with a newline at the end.\n"

     Strings can be continued across a line by escaping  (\)  the
     newline.  The following escape sequences are recognized.

          \\        \
          \"        "
          \a        alert, ascii 7
          \b        backspace, ascii 8
          \t        tab, ascii 9
          \n        newline, ascii 10
          \v        vertical tab, ascii 11
          \f        formfeed, ascii 12
          \r        carriage return, ascii 13
          \ddd      1, 2 or 3 octal digits for ascii ddd
          \xhh      1 or 2 hex digits for ascii  hh

     If you escape any other character \c, you get \c, i.e., mawk
     ignores the escape.

     There are really three basic data types; the third is number
     and string which has both a numeric value and a string value
     at  the  same  time.   User  defined  variables  come   into
     existence when first referenced and are initialized to null,
     a number and string value which  has  numeric  value  0  and
     string  value  "".  Non-trivial number and string typed data
     come from input and are typically stored  in  fields.   (See
     section 4).

     The type of an expression is determined by its  context  and
     automatic type conversion occurs if needed.  For example, to
     evaluate the statements

          y = x + 2  ;  z = x  "hello"

     The value stored in variable y will be typed numeric.  If  x
     is  not  numeric,  the  value  taken  from x is converted to
     numeric before it is added to 2 and stored in y.  The  value
     stored  in variable z will be typed string, and the value of
     x will be converted to string if necessary and  concatenated
     with "hello".  (Of course, the value and type stored in x is
     not changed by any conversions.) A string expression is con-
     verted  to  numeric using its longest numeric prefix as with
     atof(3).  A numeric expression is  converted  to  string  by
     replacing  expr  with sprintf( OFMT, expr).  Sprintf() is an
     AWK  built-in   that   duplicates   the   functionality   of
     sprintf(3).   Explicit  type conversions can be forced, expr
     "" is string and expr+0 is numeric.

     To evaluate,  expr1  rel-op  expr2,  if  both  operands  are
     numeric or number and string then the comparison is numeric;
     if both operands are string the comparison is string; if one
     operand  is  string, the non-string operand is converted and
     the comparison is string.  The result is numeric,  1  or  0.
     In boolean contexts such as, if ( expr ) statement, a string
     expression evaluates true if and only if it is not the empty
     string ""; otherwise if and only if not numerically zero.

.topic regexp
  3. Regular expressions
     In the AWK language, records, fields and strings  are  often
     tested  for  matching a regular expression.  Regular expres-
     sions are enclosed in slashes, and

          expr ~ /r/

     is an AWK expression that evaluates to 1 if  expr  "matches"
     r,  which means a substring of expr is in the set of strings
     defined by r.  With no match the expression evaluates to  0;
     replacing ~ with the "not match" operator, !~ , reverses the
     meaning.  As a pattern,

          /r/ ó action ò

     is the same as

          $0 ~ /r/ ó action ò

     and for each input record that matches  r,  action  is  exe-
     cuted.

     AWK uses extended regular expressions as with egrep(1).  The
     regular  expression metacharacters, i.e., those with special
     meaning in regular expressions are

           ^ $ . [ ] | ( ) * + ?

     Regular expressions are built up from characters as follows:

          c            matches any non-metacharacter c.

          \c           matches a character defined  by  the  same
                       escape  sequences used in string constants
                       or the literal character c if \c is not an
                       escape sequence.

          .            matches any character (including newline).

          ^            matches the front of a string.

          $            matches the back of a string.

          [c1c2c3...]  matches  any  character   in   the   class
                       c1c2c3...  .  An interval of characters is
                       denoted c1-c2 inside a class [...].

          [^c1c2c3...] matches any character  not  in  the  class
                       c1c2c3...

     Regular expressions are built up from other regular  expres-
     sions as follows:

          r1r2 matches r1 followed immediately by r2  (concatena-
               tion).

          r1 | r2
               matches r1 or r2 (alternation).

          r*   matches r repeated zero or more times.

          r+   matches r repeated one or more times.

          r?   matches r zero or once.

          (r)  matches r, providing grouping.

     The increasing precedence of operators is alternation,  con-
     catenation and unary (*, + or ?).

     For example,

          /^[_a-zA-Z][_a-zA-Z0-9]*$/  and
          /^[-+]?([0-9]+\.?|\.[0-9])[0-9]*([eE][-+]?[0-9]+)?$/

     are matched by AWK identifiers  and  AWK  numeric  constants
     respectively.   Note  that  . has to be escaped to be recog-
     nized as a decimal point, and that  metacharacters  are  not
     special inside character classes.

     Any expression can be used on the right hand side of  the  ~
     or !~ operators or passed to a built-in that expects a regu-
     lar expression.  If needed, it is converted  to  string  and
     then interpreted as a regular expression.  For example,

          BEGIN ó identifier = "[_a-zA-Z][_a-zA-Z0-9]*" ò

          $0 ~ "^" identifier

     prints all lines that start with an AWK identifier.

     mawk recognizes the  empty  regular  expression,  //,  which
     matches  the empty string and hence is matched by any string
     at the front, back and between every character.   For  exam-
     ple,

          echo  abc | mawk ó gsub(//, "X") ; print ò
          XaXbXcX

.topic Records
  4. Records and fields
     Records are read in one at a time, and stored in  the  field
     variable  $0.   The  record  is  split into fields which are
     stored in $1, $2, ..., $NF.  The built-in variable NF is set
     to  the  number of fields, and NR and FNR are incremented by
     1.  Fields above $NF are set to "".

     Assignment to $0 causes the fields and NF to be  recomputed.
     Assignment to NF or to a field causes $0 to be reconstructed
     using OFS.  Assignment to a field with  index  greater  than
     NF, increases NF and causes $0 to be reconstructed.

     Data input stored in fields is  string,  unless  the  entire
     field  has  numeric  form  and  then  the type is number and
     string.  For example,

          echo 24 24E |
          mawk 'ó print($1>100, $1>"100", $2>100, $2>"100") ò'
          0 1 1 1

     $0 and $2 are string and $1 is number and string.  The first
     comparison  is  numeric,  the second is string, the third is
     string (100 is converted to "100"), and the last is string.

.topic Expressions
  5. Expressions and operators
     The expression syntax is similar to C.  Primary  expressions
     are  numeric constants, string constants, variables, fields,
     arrays and functions. The identifier for a  variable,  array
     or  function can be a sequence of letters, digits and under-
     scores, that does not start with a digit.  Variables are not
     declared;  they exist when first referenced and are initial-
     ized to null.

     New expressions are composed with the following operators in
     order of increasing precedence.

          assignment          =  +=  -=  *=  /=  %=  ^=
          conditional         ?  :
          logical or          ||
          logical and         &&
          array membership    in
          matching       ~   !~
          relational          <  >   <=  >=  ==  !=
          concatenation       (no explicit operator)
          add ops             +  -
          mul ops             *  /  %
          unary               +  -
          logical not         !
          exponentiation      ^
          inc and dec         ++ -- (both post and pre)
          field               $

     Assignment, conditional and exponentiation  associate  right
     to  left;  the other operators associate left to right.  Any
     expression can be parenthesized.

.topic Arrays
  6. Arrays
     Awk provides one-dimensional  arrays.   Array  elements  are
     expressed as array[expr].  Initially an array is empty; ele-
     ments exist when first accessed.   An  expression,  expr  in
     array evaluates to 1 if array[expr] exists, else to 0.

     There is a form of the for statement that  loops  over  each
     element of an array.

          for ( var in array ) statement

     sets var to each element of array  and  executes  statement.
     The order of execution is not defined.

     The statement, delete array[expr], causes array[expr] not to
     exist.

     Multidimensional arrays are synthesized  with  concatenation
     using  the  built-in variable SUBSEP.  array[expr1,expr2] is
     equivalent to array[expr1 SUBSEP expr2].  Testing for a mul-
     tidimensional element uses a parenthesized index, such as

          if ( (i, j) in A )  print A[i, j]

.topic Builtin_var
  7. Builtin-variables
     The following variables are built-in and initialized  before
     program execution.
                       {ARGC:Color_X}
          ARGC      number of command line arguments.
                       {ARGV:Color_X}
          ARGV      array of command line arguments, 0..ARGC-1.
                       {FILENAME:Color_X}
          FILENAME  name of the current input file.
                       {FNR:Color_X}
          FNR       current record number in FILENAME.
                       {FS:Color_X}
          FS        splits  records  into  fields  as  a  regular
                    expression.
                       {NF:Color_X}
          NF        number of fields in the current record.
                       {NR:Color_X}
          NR        current record  number  in  the  total  input
                    stream.
                       {OFMT:Color_X}
          OFMT      format  for  printing  numbers;  initially  =
                    "%.6g".
                       {OFS:Color_X}
          OFS       inserted between fields on output,  initially
                    = " ".
                       {ORS:Color_X}
          ORS       terminates each record on output, initially =
                    "\n".
                       {RLENGTH:Color_X}
          RLENGTH   length set by the last call to  the  built-in
                    function, match().
                       {RS:Color_X}
          RS        input record separator, initially = "\n".
                       {RSTART:Color_X}
          RSTART    index set by the last call to match().
                       {SUBSEP:Color_X}
          SUBSEP    used to build multiple array subscripts, ini-
                    tially = "\034".
.topic Builtinfun
  8. Built-in functions
     String functions
                       {gsub:Color_X}
          gsub(r,s,t)  gsub(r,s)
               Global  substitution,  every  match   of   regular
               expression  r  in variable t is replaced by string
               s.  The number of replacements is returned.  If  t
               is  omitted,  $0 is used.  An & in the replacement
               string s is replaced by the matched  substring  of
               t.  \& puts a literal & in the replacement string.
                       {index:Color_X}
          index(s,t)
               If t is a substring of s, then the position  where
               t  starts  is  returned,  else 0 is returned.  The
               first character of s is in position 1.
                       {length:Color_X}
          length(s)  length
               Returns the length of string s; without  an  argu-
               ment, returns the length of $0.
                       {match:Color_X}
          match(s,r)
               Returns the index of the first  longest  match  of
               regular expression r in string s.  Returns 0 if no
               match.  As a side effect, RSTART  is  set  to  the
               return value.  RLENGTH is set to the length of the
               match or -1 if no match.  If the empty  string  is
               matched, RLENGTH is set to 0, and 1 is returned if
               the match is at  the  front,  and  length(s)+1  is
               returned if the match is at the back.
                       {split:Color_X}
          split(s,A,r)  split(s,A)
               String s is split into fields by  regular  expres-
               sion  r  and  the  fields are loaded into array A.
               The number of fields is returned.  See section  11
               below  for  more  detail.   If r is omitted, FS is
               used.
                       {sprintf:Color_X}
          sprintf(format,expr-list)
               Returns  a  string  constructed   from   expr-list
               according  to  format.   See  the  description  of
               printf() below.
                       {sub:Color_X}
          sub(r,s,t)  sub(r,s)
               Single substitution, same as gsub() except at most
               one substitution.
                       {substr:Color_X}
          substr(s,i,n)  substr(s,i)
               Returns the substring of  string  s,  starting  at
               index i, of length n.  If n is omitted, the suffix
               of s, starting at i is returned.

     Arithmetic functions
                       {atan2:Color_X}
          atan2(y,x)     Arctan of y/x between -pi and pi.
                       {cos:Color_X}
          cos(x)         Cosine function, x in radians.
                       {exp:Color_X}
          exp(x)         Exponential function.
                       {int:Color_X}
          int(x)         Returns x truncated towards zero.
                       {log:Color_X}
          log(x)         Natural logarithm.
                       {rand:Color_X}
          rand()         Returns a random number between zero and one.
                       {sin:Color_X}
          sin(x)         Sine function, x in radians.
                       {sqrt:Color_X}
          sqrt(x)        Returns square root of x.
                       {srand:Color_X}
          srand(expr)  srand()
               Seeds the random number generator, using the clock
               if  expr  is omitted, and returns the value of the
               previous seed.  mawk seeds the random number  gen-
               erator  from  the  clock at startup so there is no
               real need to call srand().  Srand(expr) is  useful
               for repeating pseudo random sequences.

.topic inout
  9. Input and output
                       {print:Color_X}
     There are two output statements, print and printf.

          print
               writes $0  ORS to standard output.

          print expr1, expr2, ..., exprn
               writes expr1 OFS expr2 OFS ... exprn ORS to  stan-
               dard output.

          printf format, expr-list
               duplicates the printf C library  function  writing
               to standard output.  Supported conversions are %c,
               %d, %e, %f, %g, %o and %x. -, width and .prec  are
               supported.   Dynamic  widths  can  be  built using
               string operations.

     The output of print and printf can be redirected to  a  file
     or  command by appending > file, >> file or | command to the
     end of the print statement.  Redirection opens file or  com-
     mand  only  once,  subsequent  redirections  append  to  the
     already open stream.  The argument list to print  or  printf
     can optionally be enclosed in parentheses.
                       {getline:Color_X}
     The input function getline has the following variations.

          getline
               reads $0, updates the fields, NF, NR and FNR.

          getline < file
               reads $0 from file, updates the fields and NF.

          getline var
               reads the next record into  var,  updates  NR  and
               FNR.

          getline var < file
               reads the next record of file into var.

           command | getline
               pipes a record from command into  $0  and  updates
               the fields and NF.

           command | getline var
               pipes a record from command into var.

     Getline returns 0 on end-of-file, -1 on error, otherwise  1.
     Command is executed by /bin/sh.

     The function close(expr) closes the file or pipe  associated
     with  expr.  Close returns 0 or -1 if expr is not associated
     with an open stream.  Close() is used to reread  a  file  or
     command,  make  sure the other end of an output pipe is fin-
     ished or conserve file resources.

     The function system(expr) uses /bin/sh to execute  expr  and
     returns the exit status of the command expr.

.topic Userfunc
  10. User defined functions
     The syntax for a user defined function is

          function name( args ) ó statements ò

     The function body can contain a return statement

          return opt_expr

     A return statement is not required. Function  calls  may  be
     nested  or  recursive.   Functions are passed expressions by
     value and arrays by reference.   Extra  arguments  serve  as
     local  variables  and are initialized to null.  For example,
     csplit(s,A) puts each  character  of  s  into  array  A  and
     returns the length of s.

          function csplit(s, A,    n, i)
          ó
            n = length(s)
            for( i = 1 ; i <= n ; i++ ) A[i] = substr(s, i, 1)
            return n
          ò

     Putting extra space between passed arguments and local vari-
     ables  is  conventional.  Functions can be referenced before
     they are defined, but the function name and the '('  of  the
     arguments must touch to avoid confusion with concatenation.

.topic Splitting
  11. Splitting strings, records and files
     Awk programs use the same algorithm to  split  strings  into
     arrays  with  split(),  and records into fields on FS.  mawk
     uses essentially the same  algorithm  to  split  files  into
     records on RS.

     Split(expr,A,sep) works as follows:

          (1)  If sep is omitted, it is replaced by FS.  Sep  can
               be  an expression or regular expression.  If it is
               an expression of non-string type, it is  converted
               to string.

          (2)  If sep = " " (a single  space),  then  <SPACE>  is
               trimmed  from  the front and back of expr, and sep
               becomes <SPACE>.  mawk defines <SPACE> as the reg-
               ular  expression  /[ \t\r\n]+/.  Otherwise  sep is
               treated  as  a  regular  expression,  except  that
               meta-characters are ignored for a string of length
               1, e.g., split(x, A, "*") and  split(x,  A,  /\*/)
               are the same.

          (3)  If expr is not string, it is converted to  string.
               If  expr  is  then  the  empty  string "", split()
               returns 0 and  A  is  unchanged.   Otherwise,  all
               non-overlapping,  non-null  and longest matches of
               sep in expr, separate expr into fields  which  are
               loaded  into  A.   The  fields are placed in A[1],
               A[2], ..., A[n] and split() returns n, the  number
               of fields which is the number of matches plus one.
               Data placed in  A  that  looks  numeric  is  typed
               number and string.

     Splitting records into fields  works  the  same  except  the
     pieces  are loaded into $1, $2,..., $NF.  If $0 is empty, NF
     is set to 0 and all $i to "".

     mawk splits files into records by the  same  algorithm,  but
     with  the  slight  difference that RS is really a terminator
     instead of a separator. (ORS is really a terminator too).

          E.g., if FS = ":+" and $0 = "a::b:" , then NF =  3  and
          $1  =  "a", $2 = "b" and $3 = "", but if "a::b:" is the
          contents of an input file and RS = ":+", then there are
          two records "a" and "b".

     RS = " " is not special.

.topic Multiline
  12. Multi-line records
     Since mawk interprets RS as a regular expression, multi-line
     records  are  easy.  Setting RS = "\n\n+", makes one or more
     blank lines separate records.  If FS = "  "  (the  default),
     then single newlines, by the rules for <SPACE> above, become
     space and single newlines are field separators.

          For example, if a file is "a b\nc\n\n",  RS  =  "\n\n+"
          and  FS  =  " ", then there is one record "a b\nc" with
          three fields "a", "b" and "c".   Changing  FS  =  "\n",
          gives two fields "a b" and "c"; changing FS = "", gives
          one field identical to the record.

     If you want lines with  spaces  or  tabs  to  be  considered
     blank,  set  RS  =  "\n([ \t]*\n)+".  For compatibility with
     other awks, setting RS = "" has the same effect on determin-
     ing  records  as  RS  = "\n\n+".  (This interpretation makes
     mawk picky that the input not start  with  blank  lines  and
     that  the  last record is fully terminated with at least two
     newlines.)

     Most of the time when you change RS for multi-line  records,
     you  will  also  want  to change ORS to "\n\n" so the record
     spacing is preserved on output.

.topic Program_exec
  13. Program execution
     This section  describes  the  order  of  program  execution.
     First  ARGC is set to the total number of command line argu-
     ments passed to the execution phase of the program.  ARGV[0]
     is  set  the  name  of  the  AWK interpreter and ARGV[1] ...
     ARGV[ARGC-1] holds  the  remaining  command  line  arguments
     exclusive of options and program source.  For example with

          mawk  -f  prog  v=1  A  t=hello  B

     ARGC = 5 with ARGV[0] = "mawk", ARGV[1] = "v=1",  ARGV[2]  =
     "A", ARGV[3] = "t=hello" and ARGV[4] = "B".

     Next, each BEGIN block is executed in order.  If the program
     consists  entirely  of  BEGIN  blocks,  then  execution ter-
     minates, else an input stream is opened and  execution  con-
     tinues.  If ARGC equals 1, the input stream is set to stdin,
     else  the command line arguments  ARGV[1]  ...  ARGV[ARGC-1]
     are examined for a file argument.

     The command line arguments  divide  into  three  sets:  file
     arguments,  assignment  arguments  and empty strings "".  An
     assignment has the form  var=string.   When  an  ARGV[i]  is
     examined  as  a possible file argument, if it is empty it is
     skipped; if it is an assignment argument, the assignment  to
     var  takes  place  and  i  skips  to the next argument; else
     ARGV[i] is opened for input.  If it fails to open, execution
     terminates with exit code 1.  If no command line argument is
     a file argument, then input comes from stdin.  Getline in  a
     BEGIN  action  opens  input.  "-" as a file argument denotes
     stdin.

     Once an input stream is open, each input  record  is  tested
     against  each  pattern,  and  if  it matches, the associated
     action is executed.  An expression pattern matches if it  is
     boolean  true (see the end of section 2).  A regular expres-
     sion pattern matches if $0 matches the  regular  expression.
     A  BEGIN pattern matches before any input has been read, and
     an END pattern matches after all input  has  been  read.   A
     range  pattern, pat1,pat2 , matches every record between the
     match of pat1 and the match pat2 inclusively.

     When end of file occurs on the input stream,  the  remaining
     command line arguments are examined for a file argument, and
     if there is one it is opened, else the END pattern  is  con-
     sidered matched and all END actions are executed.

     In the example, the assignment v=1  takes  place  after  the
     BEGIN  actions  are  executed,  and  the data placed in v is
     typed number and string.  Input is then read  from  file  A.
     On  end  of file A, t is set to the string "hello", and B is
     opened for input.  On end of file B,  the  END  actions  are
     executed.

     Program flow at the pattern óactionò level  can  be  changed
     with the

          next   and
          exit  opt_expr

     statements.  A next statement causes the next  input  record
     to  be  read  and  pattern testing to restart with the first
     pattern óactionò pair in the  program.   An  exit  statement
     causes  immediate  execution  of  the END actions or program
     termination if there are none or if the exit  occurs  in  an
     END action.  The opt_expr sets the exit value of the program
     unless overridden by a later exit or subsequent error.

.topic EXAMPLES
EXAMPLES
     1. emulate cat.

          ó print ò

     2. emulate wc.

          ó chars += length($0) + 1  # add one for the \n
            words += NF
          ò

          ENDó print NR, words, chars ò

     3. count the number of unique "real words".

          BEGIN ó FS = "[^A-Za-z]+" ò

          ó for(i = 1 ; i <= NF ; i++)  word[$i] = "" ò

          END ó delete word[""]
                for ( i in word )  cnt++
                print cnt
          ò

     4. sum the second field of every record based on  the  first
     field.

          $1 ~ /credit|gain/ ó sum += $2 ò
          $1 ~ /debit|loss/  ó sum -= $2 ò

          END ó print sum ò

     5. sort a file, comparing as string

          ó line[NR] = $0 "" ò  # make sure of comparison type
                                # in case some lines look numeric

          END ó  isort(line, NR)
            for(i = 1 ; i <= NR ; i++) print line[i]
          ò

          #insertion sort of A[1..n]
          function isort( A, n,    i, j, hold)
          ó
            for( i = 2 ; i <= n ; i++)
            ó
              hold = A[j = i]
              while ( A[j-1] > hold )
              ó j-- ; A[j+1] = A[j] ò
              A[j] = hold
            ò
            # sentinel A[0] = "" will be created if needed
          ò


.topic COMPATIBILITY
COMPATIBILITY ISSUES
     mawk and SystemVR3 nawk (new awk) implement the AWK language
     as  described  in the AWK book.  SystemVR4 nawk, with influ-
     ence from GNU gawk, added a few features that are now speci-
     fied in the draft 11.1 POSIX standard for awk, most notably,
     functions  toupper()  and  tolower(),  and  access  to   the
     environment through an array, ENVIRON[].

     With mawk, the following are all equivalent,

          x ~ /a\+b/    x ~ "a\+b"     x ~ "a\\+b"

     The strings get scanned twice, once as string  and  once  as
     regular  expression.   On  the string scan, mawk ignores the
     escape on non-escape characters while the AWK book advocates
     \c be recognized as c which necessitates the double escaping
     of meta-characters in strings.  For programs that  must  run
     under  a  variety  of awks, the more portable but less read-
     able, double escape should be used.

     POSIX AWK is oriented to operate on files a line at a  time.
     RS can be changed from "\n" to another single character, but
     it is hard to find any use for this - there are no  examples
     in  the AWK book.  By convention, RS = "", makes one or more
     blank lines separate records, allowing  multi-line  records.
     When RS = "", "\n" is always a field separator regardless of
     the value in FS.

     mawk, on the other hand, allows RS to be a  regular  expres-
     sion.  When "\n" appears in records, it is treated as space,
     and FS always determines fields.  RS =  ""  is  treated  the
     same as RS = "\n\n+".

     Removing the line at a time paradigm can make some  programs
     simpler  and  can  often  improve performance.  For example,
     redoing example 3 from above,

          BEGIN ó RS = "[^A-Za-z]+" ò

          ó word[ $0 ] = "" ò

          END ó delete  word[ "" ]
            for( i in word )  cnt++
            print cnt
          ò

     counts the number of unique words  by  making  each  word  a
     record.   On  moderate  size  files,  mawk executes twice as
     fast, because of the simplified inner loop.

     The following program replaces  each  comment  by  a  single
     space in a C program file,

          BEGIN ó
            RS = "/\*([^*]|\*+[^/*])*\*+/"
               # comment is record separator
            ORS = " "
            getline  hold
            ò

            ó print hold ; hold = $0 ò

            END ó printf "%s" , hold ò

     Buffering one record is needed to avoid terminating the last
     record with a space.

     Finally, here is how mawk handles exceptional cases not dis-
     cussed  in the AWK book or the POSIX draft.  It is unsafe to
     assume consistency across awks and safe to skip to the  next
     section.

          substr(s, i, n) returns the  characters  of  s  in  the
          intersection  of the closed interval [1, length(s)] and
          the half-open interval [i, i+n).  When  this  intersec-
          tion  is  empty,  the  empty  string  is  returned;  so
          substr("ABC", 1, 0) = "" and  substr("ABC",  -4,  6)  =
          "A".

          Every string, including the empty string,  matches  the
          empty  string  at  the front so, s ~ // and s ~ "", are
          always 1 as is match(s, //) and match(s, "").  The last
          two set RLENGTH to 0.

          index(s, t) is always the same as match(s, t1) where t1
          is  the  same  as t with metacharacters escaped.  Hence
          consistency  with  match  requires  that  index(s,  "")
          always  returns 1.  Also the condition, index(s,t) != 0
          if  and  only  t  is  a  substring   of   s,   requires
          index("","") = 1.

          If getline encounters end of file, getline var,  leaves
          var unchanged.  Similarly, on entry to the END actions,
          $0, the fields and NF have their value  unaltered  from
          the last record.

.topic DIAGNOSTICS
DIAGNOSTICS
     A previously undiscussed option -D causes mawk  to  dump  to
     stderr an assembler like listing of its internal representa-
     tion of the program which is linear byte code for a  virtual
     stack machine.

.topic SEEALSO
SEE ALSO
     egrep (1)

     Aho, Kernighan and Weinberger, The AWK Programming Language,
     Addison-Wesley Publishing, 1988, (the AWK book), defines the
     language, opening with a  tutorial  and  advancing  to  many
     interesting  programs  that  delve  into  issues of software
     design and analysis relevant to programming in any language.

     The GAWK Manual, The Free Software Foundation,  1991,  is  a
     tutorial  and  language  reference that does not attempt the
     depth of the AWK book and assumes the reader may be a novice
     programmer. The section on AWK arrays is excellent.  It also
     discusses POSIX requirements for AWK.

.topic BUGS
BUGS
     mawk cannot handle ascii NUL \0 in the source or data files.
     You can output NUL using printf with %c, and any other 8 bit
     character is acceptable input.

     Implementors of the AWK language  have  shown  a  consistent
     lack of imagination when naming their programs.

.topic AUTHOR
AUTHOR
     Mike Brennan (brennan@boeing.com).


.topic MsDOS
Notes for MsDOS
---------------

For a number of reasons, entering a mawk program on the command line
using command.com as your shell is an exercise in futility, so under
MsDOS the command syntax is

        mawk [-Fs] optional_list_of_files

You'll get a prompt, and then type in the program.  The -f option works
as before.

If you use a DOS shell that gives you a Unix style command line, to use
it you'll need to provide a C function reargv() that retrieves argc and
argv[] from your shell.

Some features are missing from the DOS version of mawk: No system(), and
no input or output pipes.  To provide a hook to stderr, I've added

        errmsg( "string" )

which prints "string\n" to stderr which will be the console and only the
console under command.com.  A better solution would be to associate a
file with handle 2, so print and printf would be available.  Consider
the errmsg() feature as temporary.

For compatibility with Unix, CR are silently stripped from input and LF
silently become CRLF on output.

WARNING: If you write an infinite loop that does not print to the
screen, then you will have to reboot.  For example

        x = 1
        while( x < 10 )  A[x] = x
        x++

By mistake the x++ is outside the loop.  What you need to do is type
control break and the keyboard hardware will generate an interrupt and
the operating system will service that interrupt and terminate your
program, but unfortunately MsDOS does not have such a feature.
