gawk: Include Files

1 
1 2.7 Including Other Files into Your Program
1 ===========================================
1 
1 This minor node describes a feature that is specific to 'gawk'.
1 
1    The '@include' keyword can be used to read external 'awk' source
1 files.  This gives you the ability to split large 'awk' source files
1 into smaller, more manageable pieces, and also lets you reuse common
1 'awk' code from various 'awk' scripts.  In other words, you can group
1 together 'awk' functions used to carry out specific tasks into external
1 files.  These files can be used just like function libraries, using the
1 '@include' keyword in conjunction with the 'AWKPATH' environment
1 variable.  Note that source files may also be included using the '-i'
1 option.
1 
1    Let's see an example.  We'll start with two (trivial) 'awk' scripts,
1 namely 'test1' and 'test2'.  Here is the 'test1' script:
1 
1      BEGIN {
1          print "This is script test1."
1      }
1 
1 and here is 'test2':
1 
1      @include "test1"
1      BEGIN {
1          print "This is script test2."
1      }
1 
1    Running 'gawk' with 'test2' produces the following result:
1 
1      $ gawk -f test2
1      -| This is script test1.
1      -| This is script test2.
1 
1    'gawk' runs the 'test2' script, which includes 'test1' using the
1 '@include' keyword.  So, to include external 'awk' source files, you
1 just use '@include' followed by the name of the file to be included,
1 enclosed in double quotes.
1 
1      NOTE: Keep in mind that this is a language construct and the file
1      name cannot be a string variable, but rather just a literal string
1      constant in double quotes.
1 
1    The files to be included may be nested; e.g., given a third script,
1 namely 'test3':
1 
1      @include "test2"
1      BEGIN {
1          print "This is script test3."
1      }
1 
1 Running 'gawk' with the 'test3' script produces the following results:
1 
1      $ gawk -f test3
1      -| This is script test1.
1      -| This is script test2.
1      -| This is script test3.
1 
1    The file name can, of course, be a pathname.  For example:
1 
1      @include "../io_funcs"
1 
1 and:
1 
1      @include "/usr/awklib/network"
1 
1 are both valid.  The 'AWKPATH' environment variable can be of great
1 value when using '@include'.  The same rules for the use of the
11 'AWKPATH' variable in command-line file searches (⇒AWKPATH
 Variable) apply to '@include' also.
1 
1    This is very helpful in constructing 'gawk' function libraries.  If
1 you have a large script with useful, general-purpose 'awk' functions,
1 you can break it down into library files and put those files in a
1 special directory.  You can then include those "libraries," either by
1 using the full pathnames of the files, or by setting the 'AWKPATH'
1 environment variable accordingly and then using '@include' with just the
1 file part of the full pathname.  Of course, you can keep library files
1 in more than one directory; the more complex the working environment is,
1 the more directories you may need to organize the files to be included.
1 
1    Given the ability to specify multiple '-f' options, the '@include'
1 mechanism is not strictly necessary.  However, the '@include' keyword
1 can help you in constructing self-contained 'gawk' programs, thus
1 reducing the need for writing complex and tedious command lines.  In
1 particular, '@include' is very useful for writing CGI scripts to be run
1 from web pages.
1 
11    The rules for finding a source file described in ⇒AWKPATH
 Variable also apply to files loaded with '@include'.
1