GAWK: Effective AWK Programming

Chapter 12: A Library of awk Functions 187Section 12.4 [Processing Command-Line Options], page 201). Such variables are calledprivate, 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 variablesthat will not conflict with any variables used by either another library function or auser’s main program. For example, a name like ‘i’ or ‘j’ is not a good choice, because userprograms often use variable names like these for their own purposes.The example programs shown in this chapter all start the names of their private variableswith an underscore (‘_’). Users generally don’t use leading underscores in their variablenames, so this convention immediately decreases the chances that the variable name will beaccidentally shared with the user’s program.In addition, several of the library functions use a prefix that helps indicate what functionor set of functions use the variables—for example, _pw_byname in the user database routines(see Section 12.5 [Reading the User Database], page 206). This convention is recommended,since it even further decreases the chance of inadvertent conflict among variable names. Notethat this convention is used equally well for variable names and for private function namesas well. 2As a final note on variable naming, if a function makes global variables available for useby a main program, it is a good convention to start that variable’s name with a capitalletter—for example, getopt’s Opterr and Optind variables (see Section 12.4 [ProcessingCommand-Line Options], page 201). 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 isnot 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 stateare, in fact, declared local. 3 If this is not done, the variable could accidentally be used inthe 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 associativearray to hold the values needed by the library function(s), or “package.” This significantlydecreases the number of actual global names in use. For example, the functions describedin Section 12.5 [Reading the User Database], page 206, might have used array elementsPW_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 section are exactly that: conventions. You are notrequired to write your programs this way—we merely recommend that you do so.2 While all the library routines could have been rewritten to use this convention, this was not done, in orderto show how my own awk programming style has evolved and to provide some basis for this discussion.3 gawk’s ‘--dump-variables’ command-line option is useful for verifying this.