Syntax of Function Definitions
==============================

   Definitions of functions can appear anywhere between the rules of the
`awk' program.  Thus, the general form of an `awk' program is extended
to include sequences of rules *and* user-defined function definitions.

   The definition of a function named NAME looks like this:

     function NAME (PARAMETER-LIST) {
          BODY-OF-FUNCTION
     }

NAME is the name of the function to be defined.  A valid function name
is like a valid variable name: a sequence of letters, digits and
underscores, not starting with a digit.  Functions share the same pool
of names as variables and arrays.

   PARAMETER-LIST is a list of the function's arguments and local
variable names, separated by commas.  When the function is called, the
argument names are used to hold the argument values given in the call.
The local variables are initialized to the null string.

   The BODY-OF-FUNCTION consists of `awk' statements.  It is the most
important part of the definition, because it says what the function
should actually *do*.  The argument names exist to give the body a way
to talk about the arguments; local variables, to give the body places
to keep temporary values.

   Argument names are not distinguished syntactically from local
variable names; instead, the number of arguments supplied when the
function is called determines how many argument variables there are.
Thus, if three argument values are given, the first three names in
PARAMETER-LIST are arguments, and the rest are local variables.

   It follows that if the number of arguments is not the same in all
calls to the function, some of the names in PARAMETER-LIST may be
arguments on some occasions and local variables on others.  Another way
to think of this is that omitted arguments default to the null string.

   Usually when you write a function you know how many names you intend
to use for arguments and how many you intend to use as locals.  By
convention, you should write an extra space between the arguments and
the locals, so other people can follow how your function is supposed to
be used.

   During execution of the function body, the arguments and local
variable values hide or "shadow" any variables of the same names used
in the rest of the program.  The shadowed variables are not accessible
in the function definition, because there is no way to name them while
their names have been taken away for the local variables.  All other
variables used in the `awk' program can be referenced or set normally
in the function definition.

   The arguments and local variables last only as long as the function
body is executing.  Once the body finishes, the shadowed variables come
back.

   The function body can contain expressions which call functions.  They
can even call this function, either directly or by way of another
function.  When this happens, we say the function is "recursive".

   There is no need in `awk' to put the definition of a function before
all uses of the function.  This is because `awk' reads the entire
program before starting to execute any of it.

   In many `awk' implementations, the keyword `function' may be
abbreviated `func'.  However, POSIX only specifies the use of the
keyword `function'.  This actually has some practical implications.  If
`gawk' is in POSIX-compatibility mode (see Invoking `awk': Command Line.), then the following statement will *not* define a function:

     func foo() { a = sqrt($1) ; print a }

Instead it defines a rule that, for each record, concatenates the value
of the variable `func' with the return value of the function `foo', and
based on the truth value of the result, executes the corresponding
action.  This is probably not what was desired.  (`awk' accepts this
input as syntactically valid, since functions may be used before they
are defined in `awk' programs.)