Aargvark

Version 0.0.14 Updated 2009-05-12

Maintainer: Mike Zazaian, mike@zop.io, zop.io License: This file is placed in the public domain.

OVERVIEW

Aargvark is a utility written in Ruby to process arguments for command-line scripts and applications. It allows you to define a simple structure for your script's arguments, then compares them against the ARGV array that's produced by Ruby when your script is called from a command line, such as:

ruby myscript.rb -a -b -c --example-alias inputfile.txt outputfile.txt

INSTALL

To install Aargvark, either install Aargvark as a Rubygem, like this:

gem install –remote aargvark

Or just put lib/aargvark.rb in your own script's lib/ directory, and add the path to the LOAD_PATH global like this:

$LOAD_PATH << "/path/to/aargvark/directory"

This assumes that /path/to/aargvark/directory is whichever directory in which the aargvark.rb file is located.

Once you've got aargvark in place, you can import it into your script with require, such as:

require 'aargbark'

CREATING AN AARGVARK

Once you've required Aargvark into your script, you can use it catch arguments called from a command line like this:

processed_arguments = Aargvark.new(called_arguments, argument_structure)

There are three important parts to this equation, being:

*THE CALLED ARGUMENTS ARRAY* An array of arguments called by the

script's user that are passed into the script. In this example it's intended to be Ruby's ARGV array, which automatically passes arguments called from the commandline into the Ruby script. However, “called_arguments” can be any array within your script that contains called arguments.

*THE ARGUMENT STRUCTURE ARRAY* This array represents the structure of how the

script will process and recognize available and required arguments.

This array contains one or more SUB-ARRAYS, each of which represent an argument that CAN or MUST be passed into the script. An example of basic SUB-ARRAY structure is:

["-a", "--alias", :required, [true, :string], [false, :integer], ...]

           |-a| *ARGUMENT.*  Used to call the argument from the command line.  Must
                be a single letter [A-Za-z] preceded by a single hyphen "-".

                This is the only value that MUST be included regardless of whether or
                not an ALIAS is provided. If both an ARGUMENT and an ALIAS are
                set in the structure array, only ONE of the can be called from
                the commandline when invoking the script, otherwise an error will
                be thrown.

      |--alias| *ALIAS.*  Must be a series of uppercase, lowercase letters and
                hyphens [A-Za-z\-] preceded by two hyphens "--".

                Can be used in substitute of the argument to call the argument 
                from the commandline, but cannot be called simultaneously with the
                argument.  May be OMITTED.

    |:required| *REQUIREMENT.*  Determines whether this argument (or its alias) is
                required to be called when running the script.  This may be set as
                either :required, or OMITTED.

|[true, :string]| SUB-ARGUMENT. The first value (true||false) indicates whether the

      sub-argument must be called along with the argument.  The second
      value (:string||:integer||:float), determines what type of
      information must be passed in this place.  May be OMITTED.

|...| *PLACEHOLDER FOR MORE SUB-ARGUMENTS.*  May be as few or as many as
      you need, or may be OMITTED.

To break this down a bit, this sub-array represents ONE ARGUMENT that can be called with the letter “-a”, OR its alias “–alias”. The :required symbol after the alias indicates that this argument must be called when running the parent script. So that's the first part of the sub-array.

The remaining arrays represent SUB-ARGUMENTS, arguments that can or must be called along with the primary argument. The first value in the SUB-ARGUMENT array is boolean (true||false) indicating whether or not the sub-argument is required, and the second value is a symbol (:string|:integer|:float) indicating the type of data that the subargument must contain.

EXAMPLES OF VALID SUB-ARRAYS

An argument that is called with the letter -r that has the alias “–recursive”:

["-r", "--recursive"]

An argument that is called with the letter -b, that has no alias, but is required and has two sub-arguments that are strings and are also required.

["-b", :required, [true, :string], [true, :string]]

An argument called with the letter -z that has the alias “–zip-me-up”, is required, has one integer sub-argument that is required, and one float sub-argument that isn't required.

["-z", "--zip-me-up", :required, [true, :integer], [false, :float]]

An argument that is only called with the letter -c, has no alias or sub-arguments, and is not required.

["-c"]

THE NO-ARGUMENT SUB-ARRAY

Sometimes you may want to include an argument that isn't called with a letter or an alias. For this you use the [:noarg] array.

The [:noarg] array, or, if it's required, the [:noarg, :required] array, can be included at the end of the *ARGUMENT STRUCTURE ARRAY*, after all *ARGUMENT SUB-ARRAYS* are called.

AN EXAMPLE OF A FULL ARGUMENT-STRUCTURE ARRAY

Here's an example of a full *ARGUMENT-STRUCTURE ARRAY*. Note that the order of the sub-arrays doesn't matter (“-e” can be called after “-c”), except for the fact that all [:noarg] arguments must be placed at the end of the array.

argument structure = []
argument_structure << ["-a", "--alias", :required]
argument_structure << ["-e"]
argument_structure << ["-c", :required, [true, :string]]
argument_structure << [:noarg, :required]
argument_structure << [:noarg]

OR

argument_structure = [["-a", "--alias", :required], ["-e"], ["-c", :required, [true, :string]], [:noarg, :required], [:noarg]]

THE PROCESSED ARGUMENTS ARRAY

The result of comparing the *CALLED ARGUMENTS ARRAY* (ARGV, etc.) against the *ARGUMENT STRUCTURE ARRAY* (such as the one seen above).

If the *ARGUMENT-STRUCTURE ARRAY* is of the correct format, and all of the arguments passed in from the *CALLED ARGUMENTS ARRAY* fit that structure, this array will spit out a single-level array with all of the ARGUMENT and SUB-ARGUMENT values that have been passed into the script.

AN EXAMPLE OF A PROCESSED ARGUMENTS ARRAY

Suppose you passed arguments into the script according to the *ARGUMENT-STRUCTURE ARRAY* seen immediately above. The resulting array, which would be identical to the incoming ARGV array, might look something like this:

["-a", "-c", "file_name.txt", "output_file.txt"]

Note that this array contains only four values, as only four are required by the above *ARGUMENT-STRUCTURE ARRAY*, but this include as many as SIX values if the argument “-e” were called, along with a value for the second [:noarg].