gawk: Library Names

1 
1 10.1 Naming Library Function Global Variables
1 =============================================
1 
1 Due to the way the 'awk' language evolved, variables are either "global"
1 (usable by the entire program) or "local" (usable just by a specific
1 function).  There is no intermediate state analogous to 'static'
1 variables in C.
1 
1    Library functions often need to have global variables that they can
1 use to preserve state information between calls to the function--for
1 example, 'getopt()''s variable '_opti' (⇒Getopt Function).  Such
1 variables are called "private", as the only functions that need to use
1 them are the ones in the library.
1 
1    When writing a library function, you should try to choose names for
1 your private variables that will not conflict with any variables used by
1 either another library function or a user's main program.  For example,
1 a name like 'i' or 'j' is not a good choice, because user programs often
1 use variable names like these for their own purposes.
1 
1    The example programs shown in this major node all start the names of
1 their private variables with an underscore ('_').  Users generally don't
1 use leading underscores in their variable names, so this convention
1 immediately decreases the chances that the variable names will be
1 accidentally shared with the user's program.
1 
1    In addition, several of the library functions use a prefix that helps
1 indicate what function or set of functions use the variables--for
11 example, '_pw_byname()' in the user database routines (⇒Passwd
 Functions).  This convention is recommended, as it even further
1 decreases the chance of inadvertent conflict among variable names.  Note
1 that this convention is used equally well for variable names and for
1 private function names.(1)
1 
1    As a final note on variable naming, if a function makes global
1 variables available for use by a main program, it is a good convention
1 to start those variables' names with a capital letter--for example,
1 'getopt()''s 'Opterr' and 'Optind' variables (⇒Getopt Function).
1 The leading capital letter indicates that it is global, while the fact
1 that the variable name is not all capital letters indicates that the
1 variable is not one of 'awk''s predefined variables, such as 'FS'.
1 
1    It is also important that _all_ variables in library functions that
1 do not need to save state are, in fact, declared local.(2)  If this is
1 not done, the variables could accidentally be used in the user's
1 program, leading to bugs that are very difficult to track down:
1 
1      function lib_func(x, y,    l1, l2)
1      {
1          ...
1          # some_var should be local but by oversight is not
1          USE VARIABLE some_var
1          ...
1      }
1 
1    A different convention, common in the Tcl community, is to use a
1 single associative array to hold the values needed by the library
1 function(s), or "package."  This significantly decreases the number of
1 actual global names in use.  For example, the functions described in
1 ⇒Passwd Functions might have used array elements
1 'PW_data["inited"]', 'PW_data["total"]', 'PW_data["count"]', and
1 'PW_data["awklib"]', instead of '_pw_inited', '_pw_awklib', '_pw_total',
1 and '_pw_count'.
1 
1    The conventions presented in this minor node are exactly that:
1 conventions.  You are not required to write your programs this way--we
1 merely recommend that you do so.
1 
1    ---------- Footnotes ----------
1 
1    (1) Although all the library routines could have been rewritten to
1 use this convention, this was not done, in order to show how our own
1 'awk' programming style has evolved and to provide some basis for this
1 discussion.
1 
1    (2) 'gawk''s '--dump-variables' command-line option is useful for
1 verifying this.
1