aargvark 0.0.14

data/LICENSE

@@ -0,0 +1,16 @@
+    Aargvark, a simple, powerful argument parser for the Ruby programming language.
+    Copyright (C) 2009 Mike Zazaian
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+

data/README

@@ -0,0 +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].
+#
+#

data/Rakefile

@@ -0,0 +1,47 @@
+
+require 'rubygems'
+require 'rake'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+
+spec = Gem::Specification.new do |s| 
+  s.name = "aargvark"
+  s.version = "0.0.14"
+  s.author = "Mike Zazaian"
+  s.email = "zazaian@gmail.com"
+  s.homepage = "aargvark.rubyforge.org"
+  s.platform = Gem::Platform::RUBY
+  s.rubyforge_project = "aargvark"
+  
+  s.summary = "A simple, powerful argument parser for Ruby."
+  s.description = <<-EOL
+  Prawn is a fast, tiny, and nimble PDF generator for Ruby
+EOL
+  
+  s.files = %[ lib/aargvark.rb ]
+  s.files =  Dir.glob("{lib}/**/**/*") + ["Rakefile"]
+  s.rdoc_options << '--title' << 'Aargvark Documentation' <<
+                       '--main'  << 'README' << '-q'
+  s.require_path = "lib"
+  s.has_rdoc = true
+  s.extra_rdoc_files = %w[ README LICENSE ]
+end
+
+desc "genrates documentation"
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_files.include( "README", "LICENSE", "lib/" )
+  rdoc.main     = "README"
+  rdoc.rdoc_dir = "doc/html"
+  rdoc.title    = "Aargvark Documentation"
+end     
+ 
+Rake::GemPackageTask.new(spec) do |pkg| 
+  pkg.need_tar = true 
+  pkg.need_zip = true
+end
+
+task :default => "pkg/#{spec.name}-#{spec.version}.gem" do
+    puts "Generated #{spec.name}-#{spec.version}.gem (latest version) in ./pkg directory."
+end
+
+# EOF

data/lib/aargvark.rb

@@ -0,0 +1,284 @@
+#!/usr/bin/ruby1.8
+      
+
+class Aargvark
+  attr_accessor :argument_pool, :letter_array, :noarg_count, :matches, :aliens
+
+  def initialize(argv, all_args)
+    @argv = argv
+    @argument_pool = []
+    @letter_array = []
+    @matches = []
+
+    all_args.each {|i| @argument_pool << Argument.new(i)}
+    @noarg_count = [0,0,0]
+    @argument_pool.each do |i|
+      if i.noarg
+        @noarg_count[0] += 1 if i.required
+        @noarg_count[1] += 1
+      end
+    end
+    get_matches
+  end
+
+  def get_matches
+    # Add all present argument letters and aliases to the letter_array array
+    @argument_pool.each do |arg|
+      @letter_array << arg.letter
+      if arg.alias
+        @letter_array << arg.alias
+      end
+    end
+
+    @argv.each do |s|
+      if s.is_arg? || s.is_alias?
+        unless @letter_array.index(s)
+          type = s.is_arg? ? "Argument" : "Alias"
+          raise ArgumentError, "#{type} #{s} was entered, but is not valid."
+        end
+      end
+    end
+    
+    @argument_pool.each do |arg|
+      
+      if arg.letter
+        letter_pos = @argv.index(arg.letter)
+        if letter_pos
+          subarg_pos = letter_pos + 1
+        end
+      end
+
+      if arg.alias
+        alias_pos = @argv.index(arg.alias)
+        if alias_pos
+          subarg_pos = alias_pos + 1
+        end
+      end
+
+      if ! letter_pos && ! alias_pos && ! arg.noarg && arg.required
+        error = "The use of argument \"#{arg.letter}\" "
+        error += arg.alias ? "or its alias \"#{arg.alias}\" are" : "is"
+        error += " required when running this script.\nPlease make sure that "
+        error += arg.alias ? "either of these are" : "this is"
+        error += " called when running the script from the commandline."
+        
+        raise ArgumentError, error
+      end
+
+      #need script to input the values for the :noarg arguments based on the end of
+      #the sub-arguments for the last argument in the argv array
+      if arg.noarg
+        last_arg = @argv.collect {|e| e.scan(/^-[a-z]$|^--[a-z\-]+$/)}.flatten.pop
+        arg_obj = spit_argument(last_arg)
+        last_arg_pos = @argv.rindex(last_arg)
+        diff = @argv.size - last_arg_pos
+      end
+
+      if letter_pos || alias_pos
+        if @argv.rindex(arg.letter) != letter_pos || @argv.rindex(arg.alias) != alias_pos
+          raise ArgumentError, "Argument \"#{arg.letter}\" was called twice from the commandline.  "+
+                               "Each argument should only be called once."
+        end
+
+        # Raise an error if both an argument and its alias are called from the
+        # command line
+        if letter_pos && alias_pos
+          raise ArgumentError, "Argument \"#{arg.letter}\" and alias \"#{arg.alias}\" were both" +
+                               " called from the command line.  Please use only the letter" +
+                               " argument or the alias, not both."
+        end
+
+        alien_pos = subarg_pos
+        alien_count = 0
+        if @argv[alien_pos] != nil
+          while ! @argv[alien_pos].is_arg? && ! @argv[alien_pos].is_alias?
+            argv_diff = @argv.size - alien_pos
+            break if @noarg_count[0] <= argv_diff && argv_diff <= @noarg_count[1]
+            alien_pos += 1
+            alien_count += 1
+            break if ! @argv[alien_pos]
+          end
+        end
+        
+        min = arg.subarg_range[0]
+        max = arg.subarg_range[1]
+        if alien_count < min || max < alien_count
+          error = "#{alien_count} sub-arguments have been given for argument #{arg.letter}.\n" +
+                  "The current parameters for #{arg.letter} specify that you use "          
+          error += min == max ? "exactly #{min}" : "between #{min} and #{max}"
+          error += " sub-arguments.  \nPlease double-check your " +
+          "input array and ensure the correct number of sub-arguments."
+
+          raise ArgumentError, error
+        end
+        
+        @matches << arg.letter
+        if arg.sub_args
+          arg.sub_args.each do |subarg_array|
+            required = subarg_array[0]
+            type = subarg_array[1]
+            if required == false
+              if @argv[subarg_pos].class.to_s == type.to_s.capitalize && @letter_array.index(@argv[subarg_pos]) == nil
+                @matches << @argv[subarg_pos]
+              end
+            elsif required == true
+              if @argv[subarg_pos].class.to_s == type.to_s.capitalize && @letter_array.index(@argv[subarg_pos]) == nil
+                @matches << @argv[subarg_pos]
+              else
+                raise ArgumentError, "\"#{@argv[subarg_pos]}\" is not a valid sub-argument for argument #{arg.letter}.\n" +
+                                     "A valid sub-argument of type #{type.to_s.capitalize} must be entered in this position."
+              end
+            end
+            subarg_pos += 1
+          end
+        end
+      end
+    end
+  end
+
+  def spit_argument(in_arg)
+    if ! in_arg.is_arg? && ! in_arg.is_alias?
+      raise ArgumentError, "#{in_arg} is not a valid argument request for spit_argument.  The \"letter\" " +
+                           "variable should be either an argument or an alias."
+    end
+    @argument_pool.each do |a|
+      return a if a.letter == in_arg || a.alias == in_arg
+    end
+  end
+  
+  def matches
+    puts @matches
+  end
+
+  class Argument
+    attr_accessor :letter, :noarg, :alias, :required, :sub_args, :subarg_range
+
+    def initialize (arg_array)
+      @sub_args = []
+      @subarg_range = [0,0]
+
+      if arg_array.class != Array
+        if arg_array.class == String
+          if arg_array.is_arg?
+            @letter = arg_array
+          end 
+        else
+          raise ArgumentError, "\"#{arg_array}\" is not a valid argument.  Arguments and the details" +
+                               " thereof must be entered as an Array in the format:" +
+                               "[\"-n\", \"--argument-alias\", [true/false, :string/:integer/:float], etc...]"
+        end
+      else
+        if arg_array[0].is_arg?
+          @letter = arg_array[0]
+        elsif arg_array[0].is_noarg?
+          @noarg = true
+        else
+          raise ArgumentError, "The first item in each Argument array must be either a lowercase letter preceded by" +
+                             " a hyphen or the symbol :noarg.  Please go back and make sure that your argument arrays conform to" +
+                             " these standards."
+        end
+      end
+
+      if arg_array.size > 1
+        
+        #If the second item in an argument array is an alias, set the alias for the
+        #argument as that value.
+        if arg_array[1].is_alias?
+          @alias = arg_array[1]
+        end
+
+        if arg_array[1] == :required || arg_array[2] == :required
+          @required = true
+        else
+          @required = false
+        end
+        
+        first_subarg = 1
+        if @alias
+          first_subarg += 1
+        end
+
+        if @required
+          first_subarg += 1
+        end
+        
+        first_subarg.upto(arg_array.size - 1) do |x|
+          if arg_array[x].is_subarg?
+            @sub_args << arg_array[x]
+          end
+        end
+      end
+
+      @sub_args.each do |subarg|
+        @subarg_range[0] += 1 if subarg.to_s == "true"
+        @subarg_range[1] += 1
+      end
+
+    end
+  end
+end
+
+
+class String
+
+  def is_arg?
+    match(/^-[A-Za-z{1}]$/)
+  end
+   
+  def is_alias?
+    match(/^--[A-Za-z\-]+$/)
+  end
+
+  def is_noarg?
+    return false
+  end
+
+end
+
+class Symbol
+
+  def is_arg?
+    return false
+  end
+
+  def is_alias?
+    return false
+  end
+
+  def is_noarg?
+    return self == :noarg ? true : false
+  end
+
+end
+
+
+public
+def is_subarg?(throw_errors = true)
+  if self.class != Array
+    return false
+    if throw_errors
+      raise ArgumentError, "Sub-arguments must be entered as an array, in the format:"
+                           + "[true/false, :string/:integer/:float]"
+    end
+  else
+    has_true_false = self[0].to_s.match(/^true|false$/)
+    result = self[1].to_s.match(/^string|integer|float$/)
+    has_subarg_type = result && self[1].class == Symbol ? true : false
+    if ! has_true_false
+      return false
+      if throw_errors
+        raise ArgumentError, "The first value in each sub-argument array must be either 'true' or 'false'"
+      end
+    elsif ! has_subarg_type
+      return false
+      if throw_errors
+        raise ArgumentError, "The second value in each sub-argument array must be either :string, :integer or :float"
+      end
+    else
+      return true
+    end
+  end
+end
+
+  
+

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification 
+name: aargvark
+version: !ruby/object:Gem::Version 
+  version: 0.0.14
+platform: ruby
+authors: 
+- Mike Zazaian
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-05-20 00:00:00 +10:00
+default_executable: 
+dependencies: []
+
+description: Prawn is a fast, tiny, and nimble PDF generator for Ruby
+email: zazaian@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- LICENSE
+files: 
+- lib/aargvark.rb
+- Rakefile
+- README
+- LICENSE
+has_rdoc: true
+homepage: aargvark.rubyforge.org
+post_install_message: 
+rdoc_options: 
+- --title
+- Aargvark Documentation
+- --main
+- README
+- -q
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: aargvark
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: A simple, powerful argument parser for Ruby.
+test_files: []
+