Short-Query Awk Wrapper

Post Reply
User avatar
sorcerykid
Member
Posts: 1841
Joined: Fri Aug 26, 2016 15:36
GitHub: sorcerykid
In-game: Nemo
Location: Illinois, USA

Short-Query Awk Wrapper

by sorcerykid » Post

Short-Query Awk Wrapper
sqawk (by sorcerykid)

I often find myself writing awk scripts to parse the Minetest debug log and various other data files associated with Minetest. One of my biggest pet peeves, however, is the verbosity of passing arguments as well as the lack of usage examples. So I developed Short-Query Awk Wrapper for this purpose.

Short-Query Awk Wrapper simplifies the passing of arguments to your awk scripts, by introducing POSIX-like options:

Instead of
% awk -f checklog.awk -v year=2022 -v player=Nemo debug.txt

Now you can do
% ./checklog.awk -y 2022 -u Nemo debug.txt

Note that unlike the POSIX conventions, all options expect an argument and the arguments must be separated by a space. This was intentional to avoid ambiguity and streamline parsing.

https://pubs.opengroup.org/onlinepubs/0 ... #tag_12_02

POSIX 1003.1-2003, Base Definitions, Chapter 12, Section 2 gives the following guidelines about utility command-line syntax: "Each option name should be a single alphanumeric character (the alnum character classification) from the portable character set." and "All options should be preceded by the ’−’ delimiter character."

I've also included two sample scripts within the package for parsing the Minetest debug log:
  • lognode.awk
    Report all node-dig or node-place actions within the given area by the given player. Prefix player name with '^' for inverse match.

    lognode.awk -m [MODE] -p [POSITION] -r [RADIUS] -h [HEIGHT] -u [PLAYER] [FILESPEC]
    • logchat.awk
      Report all chat messages matching the given regex by the given player in the given number of days.

      logchat.awk -u [PLAYER] -d [DAYS] -x [REGEXP] [FILESPEC]
    Repository:

    https://bitbucket.org/sorcerykid/sqawk

    Download Archive (.zip)
    Download Archive (.tar.gz)

    Source Code License:

    The MIT License

    Usage Instructions

    To get started, simply install the sqawk.pl wrapper into your program path. This will ordinarily be at /usr/local/bin for system-wide use on Linux distros.

    Next, replace the awk command at the top of your script with

    Code: Select all

    #!/usr/local/bin/sqawk.pl
    All arguments to your script are now available as variables with an underscore prefix. For example:

    Code: Select all

    BEGIN {
            print _u;  # prints "Nemo"
            print _y;  # prints "2022"
    }
    
    To make working with arguments easier, several functions are provided for basic type-conversions:
    • get_param_string( val, def )
      Returns val as a string, or def if undefined.
      • get_param_number( val, def )
        Returns val as a number, or def if undefined. If val does not represent a number (see below), then the script will terminate.

        Examples: "10", "-5", "12.222", "0x0a", "0xff00"
        • get_param_boolean( val, def )
          Returns val as a boolean (1 for true or 0 for false), or def if undefined. If val does not represent a boolean (see below), then the script will terminate.

          Values for true: "true", "yes", "on", or "y"
          Values for false: "false", "no", "off", or "n"
          • put_param_vector_3d( val, res )
            Sets array res to a 3d vector (3-element numeric array) based on val. If val does not represent a 3d vector or is undefined, then the script will terminate.

            Examples: "0.0,12.0,0.0", "-10,-10,-10", "0,5.5,0"
            • put_param_vector_2d( val, res )
              Identical to the function above, but expects a 2d vector.
            Note that def is optional in the functions above. If it is not provided, then val is required by default.

            The following special options are also available for use in your awk scripts:
            • help: the title and a short description of the program.
            • example: one or more sample invocations for the program.
            • version: the program's version and a copyright notice.
            These options don't any have any arguments. Instead they are enabled by prefixing two-hyphens, as in --help.

            For these options to be processed, they must be added to an array and passed to init_params( ) within the BEGIN block of your script. For example:

            Code: Select all

            BEGIN {
                    params[ "help" ] = "...some help text...";
                    params[ "example" ] = "...some example text...";
            
                    init_params( params );
                    player = get_param_string( _u );
                    year = get_param_number( _y );
            }
            
            To make use of the library functions described above, you must install sqawklib.awk into your awk program path. This is likely at /usr/share/awk or /usr/local/share/awk.

            Post Reply

            Who is online

            Users browsing this forum: No registered users and 5 guests