aargvark 0.0.14 → 0.0.15

data/HISTORY

@@ -0,0 +1,9 @@
+
+== 0.0.15 / 2009-05-21
+
+* 3 minor enhancements
+  * Added HISTORY file in /, ammended Rakefile to include HISTORY in rdoc.
+  * Fixed bug #25969 (improper description) in /Rakefile.
+  * Amended README file to observe proper rdoc indenting for code.
+
+

data/README

@@ -1,180 +1,180 @@
 
-#=Aargvark
-#  Version 0.0.14
-#  Updated 2009-05-12
-#  
-#  Maintainer: Mike Zazaian, mike@zop.io, http://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].
-#
-#
+=Aargvark
+Version 0.0.14
+Updated 2009-05-12
+
+Maintainer: Mike Zazaian, mike@zop.io, http://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].
+
+

data/Rakefile

@@ -6,7 +6,7 @@ require 'rake/gempackagetask'
 
 spec = Gem::Specification.new do |s| 
   s.name = "aargvark"
-  s.version = "0.0.14"
+  s.version = "0.0.15"
   s.author = "Mike Zazaian"
   s.email = "zazaian@gmail.com"
   s.homepage = "aargvark.rubyforge.org"
@@ -15,7 +15,7 @@ spec = Gem::Specification.new do |s|
   
   s.summary = "A simple, powerful argument parser for Ruby."
   s.description = <<-EOL
-  Prawn is a fast, tiny, and nimble PDF generator for Ruby
+  A simple, powerful argument parser for Ruby
 EOL
   
   s.files = %[ lib/aargvark.rb ]
@@ -24,12 +24,12 @@ EOL
                        '--main'  << 'README' << '-q'
   s.require_path = "lib"
   s.has_rdoc = true
-  s.extra_rdoc_files = %w[ README LICENSE ]
+  s.extra_rdoc_files = %w[ README HISTORY LICENSE ]
 end
 
 desc "genrates documentation"
 Rake::RDocTask.new do |rdoc|
-  rdoc.rdoc_files.include( "README", "LICENSE", "lib/" )
+  rdoc.rdoc_files.include( "README", "HISTORY", "LICENSE", "lib/" )
   rdoc.main     = "README"
   rdoc.rdoc_dir = "doc/html"
   rdoc.title    = "Aargvark Documentation"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: aargvark
 version: !ruby/object:Gem::Version 
-  version: 0.0.14
+  version: 0.0.15
 platform: ruby
 authors: 
 - Mike Zazaian
@@ -9,11 +9,11 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-05-20 00:00:00 +10:00
+date: 2009-05-21 00:00:00 +10:00
 default_executable: 
 dependencies: []
 
-description: Prawn is a fast, tiny, and nimble PDF generator for Ruby
+description: A simple, powerful argument parser for Ruby
 email: zazaian@gmail.com
 executables: []
 
@@ -21,11 +21,13 @@ extensions: []
 
 extra_rdoc_files: 
 - README
+- HISTORY
 - LICENSE
 files: 
 - lib/aargvark.rb
 - Rakefile
 - README
+- HISTORY
 - LICENSE
 has_rdoc: true
 homepage: aargvark.rubyforge.org