Standalone script

   #!/usr/local/bin/runawk

line or something like this instead of

   #!/usr/bin/awk -f

or similar.

AWK modules

  #use "module1.awk"
  #use "module2.awk"

that is the line that specifies module name is treated as a comment line by normal AWK interpreter but is processed by runawk especially.

Unless you run runawk with option -e, #use must begin with column 0, that is no spaces or tabs symbols are allowed before it and no symbols are allowed between # and use.

Also note that AWK modules can also "use" another modules and so forth. All them are collected in a depth-first order and each one is added to the list of awk interpreter arguments prepanded with -f option. That is #use directive is *NOT* similar to #include in C programming language, runawk's module code is not inserted into the place of #use. Runawk's modules are closer to Perl's "use" command. In case some module is mentioned more than once, only one -f will be added for it, i.e duplications are removed automatically.

Position of #use directive in a source file does matter, i.e. the earlier module is mentioned, the earlier -f will be generated for it.

Example:

  file prog:
     #!/usr/local/bin/runawk

     #use "A.awk"
     #use "B.awk"
     #use "E.awk"

     PROG code
     ...

  file B.awk:
     #use "A.awk"
     #use "C.awk"
     B code
     ...

  file C.awk:
     #use "A.awk"
     #use "D.awk"

     C code
     ...

  A.awk and D.awk don't contain #use directive

If you run

  runawk prog file1 file2

or

  /path/to/prog file1 file2

the following command

  awk -f A.awk -f D.awk -f C.awk -f B.awk -f E.awk -f prog -- file1 file2

will actually run.

You can check this by running

  runawk -d prog file1 file2

Module search strategy

An absolute path to the module can also be specified.

Program as an argument

 /path/to/runawk -e '
 #use "alt_assert.awk"

 {
   assert($1 >= 0 && $1 <= 10, "Bad value: " $1)

   # your code below
   ...
 }'

runawk can also be used for writing oneliners

 runawk -f abs.awk -e 'BEGIN {print abs(-1)}'

Selecting a preferred AWK interpreter

  file prog:
     #!/usr/local/bin/runawk

     #use "A.awk"
     #use "B.awk"

     #interp "/usr/pkg/bin/nbawk"

     # your code here
     ...

Note that #interp directive should also begin with column 0, no spaces are allowed before it and between # and interp.

Sometimes it also makes sense to give users ability to select their preferred AWK interpreter without changing the source code. In runawk it is possible using special directive #interp-var which sets an environment variable name assignable by user that specifies an AWK interpreter. For example, the following script

  file foobar:
     #!/usr/bin/env runawk

     #interp-var "FOOBAR_AWK"

     BEGIN {
        print "This is a FooBar application"
     }

can be run as

     env FOOBAR_AWK=mawk foobar

or just

     foobar

In the former case mawk will be used as AWK interpreter, in the latter -- the default AWK interpreter.

Using existing modules only

  file foobar:
    #!/usr/bin/env runawk

    #safe-use "~/.foobarrc" "/etc/foobar.conf"

    BEGIN {
      print foo, bar, baz
    }

  file ~/.foobarrc:
    BEGIN {
      foo = "foo10"
      bar = "bar20"
      baz = 123
    }

Of course, #safe-use directive may be used for other purposes as well. #safe-use directive accepts as much modules as you want, but at most one can be included using awk option -f, others are silently ignored, also note that modules are analysed from left to right. Leading tilde in the module name is replaced with user's home directory. Another example:

  file foobar:
    #!/usr/bin/env runawk

    #use "/usr/share/foobar/default.conf"
    #safe-use "~/.foobarrc" "/etc/foobar.conf"

    your code is here

Here the default settings are set in /usr/share/foobar/default.conf, and configuration files (if any) are used for overriding them.

Setting environment

runawk provides #env directive for this. String inside double quotes is passed to putenv(3) libc function.

Example:

  file prog:
     #!/usr/local/bin/runawk

     #env "LC_ALL=C"

     $1 ~ /^[A-Z]+$/ { # A-Z is valid if LC_CTYPE=C
         print $1
     }