REQUIREZ adds a keyword "requirez(x)" to the gawk syntax. The keyword
adds in the source code for "x" and if that contains "requirez"s,
then those cause more text to be added in recursively.

The results of calling

    requirez file

(where file contains "requirez" statements) is written to $HOME/bin/file.
The file is made into an executable "she bang" file so, after the
call ends, then calling

	file arg1 arg2 ...

will result in the processing of those arguments by "file".

REQUIREZ comes with a library of dozens of gawk routines to perform
various functions like printing histograms, generating help desk,
command-line processing, etc, etc, etc

REQUIREZ also defines a debug statement.  The sequence

	requirez file
    $Audit file arg1 arg2 ...

will generate a (large) number of  lint statements as well as two
files: "awkvars.out" and "awkprof.out". The lint report is mostly
false negatives but statements like

  function `set' called but never defined

means that your code is missing a function definition. As to the
generated files, "awkvars.out" holds an alphabetical listing of the
globals.  This can be studied for stray local variables that should
be defined within a function To simplify that search, the following
convetion is recommended:

- start all your local variables within a function in a lower case letter;

- start all your globabs with an upper case letter, followed by MiXedCase

- never name a variable in all UPPER CASE

If this convention is followed, then it is very quick to scan
"awkvars.out" for stray locals (they'll be all lower case) while
ignoring gawk's built in globals (they'll be all in upper case).

The file "awkprof.out" stores a print-print profile listing of the
file, with the number of times each line was called printed on the
left-hand-side.  This listing can be quite informative. For example:

- functions with zero calls are dead code

- IF statements that are tested many times, but their bodies are
  never executed, indicate tests that are never passed

- statements that are called just a few times are generally not
  worth optimizing

- statements that are called many times are candidates for in-line
  optimization.

To support in-lining, REQUIREZ passes the generated source code
through the "m4 -P" macro pre-processor so function calls can be
replaced with macro calls. M4 is also useful if you want to simplify
some repeated processing; e.g.

  m4_define(`Push',`$1[++$1[0]]=$2')

This call keeps a counter of stack size at array position one. A
call to

  Push(list,"happy")

will increment stack size and store "happy" as top of stack.

Note that the keyword "requirez" can hide behind one comment
character; e.g.

  # require(maths.awk)

To comment it out and to stop inclusion of source code, use two (or
more) comment characters; e.g.

  ## require(maths.awk)