#=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]. # #