GNU Info

Info Node: (gawk.info)Library Names

(gawk.info)Library Names


Next: General Functions Prev: Library Functions Up: Library Functions
Enter node , (file) or (file)node

Naming Library Function Global Variables
========================================

   Due to the way the `awk' language evolved, variables are either
"global" (usable by the entire program) or "local" (usable just by a
specific function).  There is no intermediate state analogous to
`static' variables in C.

   Library functions often need to have global variables that they can
use to preserve state information between calls to the function--for
example, `getopt''s variable `_opti' (Note: Processing Command-Line
Options.).  Such variables are called "private", since
the only functions that need to use them are the ones in the library.

   When writing a library function, you should try to choose names for
your private variables that will not conflict with any variables used by
either another library function or a user's main program.  For example,
a name like `i' or `j' is not a good choice, because user programs
often use variable names like these for their own purposes.

   The example programs shown in this major node all start the names of
their private variables with an underscore (`_').  Users generally
don't use leading underscores in their variable names, so this
convention immediately decreases the chances that the variable name
will be accidentally shared with the user's program.

   In addition, several of the library functions use a prefix that helps
indicate what function or set of functions use the variables--for
example, `_pw_byname' in the user database routines (Note: Reading the
User Database.).  This convention is recommended,
since it even further decreases the chance of inadvertent conflict
among variable names.  Note that this convention is used equally well
for variable names and for private function names as well.(1)

   As a final note on variable naming, if a function makes global
variables available for use by a main program, it is a good convention
to start that variable's name with a capital letter--for example,
`getopt''s `Opterr' and `Optind' variables (Note: Processing
Command-Line Options.).  The leading capital letter
indicates that it is global, while the fact that the variable name is
not all capital letters indicates that the variable is not one of
`awk''s built-in variables, such as `FS'.

   It is also important that _all_ variables in library functions that
do not need to save state are, in fact, declared local.(2) If this is
not done, the variable could accidentally be used in the user's
program, leading to bugs that are very difficult to track down:

     function lib_func(x, y,    l1, l2)
     {
         ...
         USE VARIABLE some_var   # some_var should be local
         ...                   # but is not by oversight
     }

   A different convention, common in the Tcl community, is to use a
single associative array to hold the values needed by the library
function(s), or "package."  This significantly decreases the number of
actual global names in use.  For example, the functions described in
Note: Reading the User Database, might have used
array elements `PW_data["inited"]', `PW_data["total"]',
`PW_data["count"]', and `PW_data["awklib"]', instead of `_pw_inited',
`_pw_awklib', `_pw_total', and `_pw_count'.

   The conventions presented in this minor node are exactly that:
conventions. You are not required to write your programs this way--we
merely recommend that you do so.

   ---------- Footnotes ----------

   (1) While all the library routines could have been rewritten to use
this convention, this was not done, in order to show how my own `awk'
programming style has evolved, and to provide some basis for this
discussion.

   (2) `gawk''s `--dump-variables' command-line option is useful for
verifying this.


automatically generated by info2www version 1.2.2.9