2.7 Including Other Files into Your Program ¶

This section describes a feature that is specific to gawk.

The @include directive can be used to read external awk source files. This gives you the ability to split large awk source files into smaller, more manageable pieces, and also lets you reuse common awk code from various awk scripts. In other words, you can group together awk functions used to carry out specific tasks into external files. These files can be used just like function libraries, using the @include directive in conjunction with the AWKPATH environment variable. Note that source files may also be included using the -i option.

Let’s see an example. We’ll start with two (trivial) awk scripts, namely test1 and test2. Here is the test1 script:

BEGIN {
    print "This is script test1."
}

and here is test2:

@include "test1"
BEGIN {
    print "This is script test2."
}

Running gawk with test2 produces the following result:

$ gawk -f test2
-| This is script test1.
-| This is script test2.

gawk runs the test2 script, which includes test1 using the @include directive. So, to include external awk source files, you just use @include followed by the name of the file to be included, enclosed in double quotes.

NOTE: Keep in mind that this is a language construct and the file name cannot be a string variable, but rather just a literal string constant in double quotes.

The files to be included may be nested; e.g., given a third script, namely test3:

@include "test2"
BEGIN {
    print "This is script test3."
}

Running gawk with the test3 script produces the following results:

$ gawk -f test3
-| This is script test1.
-| This is script test2.
-| This is script test3.

The file name can, of course, be a pathname. For example:

@include "../io_funcs"

and:

@include "/usr/awklib/network"

are both valid. The AWKPATH environment variable can be of great value when using @include. The same rules for the use of the AWKPATH variable in command-line file searches (see The AWKPATH Environment Variable) apply to @include also.

This is very helpful in constructing gawk function libraries. If you have a large script with useful, general-purpose awk functions, you can break it down into library files and put those files in a special directory. You can then include those “libraries,” either by using the full pathnames of the files, or by setting the AWKPATH environment variable accordingly and then using @include with just the file part of the full pathname. Of course, you can keep library files in more than one directory; the more complex the working environment is, the more directories you may need to organize the files to be included.

Given the ability to specify multiple -f options, the @include mechanism is not strictly necessary. However, the @include directive can help you in constructing self-contained gawk programs, thus reducing the need for writing complex and tedious command lines. In particular, @include is very useful for writing CGI scripts to be run from web pages.

The @include directive and the -i/--include command line option are completely equivalent. An included program source is not loaded if it has been previously loaded.

The rules for finding a source file described in The AWKPATH Environment Variable also apply to files loaded with @include.

Finally, files included with @include are treated as if they had ‘@namespace "awk"’ at their beginning. See Changing The Namespace, for more information.