opt-simple 0.7.1

data/GPLv2-LICENSE

@@ -0,0 +1,18 @@
+OptSimple is a utility for parsing command line arguments. 
+Copyright (C) 2011  Ethan Stryker
+
+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 2
+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, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+
+Questions/Comments on OptSimple can be mailed to Ethan Stryker, e.stryker@gmail.com

data/README

@@ -0,0 +1,160 @@
+= OptSimple provides a very simple interface to command line parsing. 
+
+== Description
+Parameter specification, validity checking and argument transformations
+can be put in one place, default parameters are easily set, and an automatic
+usage statement is constructed.
+
+There are three methods to define command line parameters:
+
+ flag - a command line switch with no arguments following (although you can still use flag
+ as a synonym for option. But default behavior is to expect no args.)
+ 
+ option - an optional command line parameter with one or more arguments
+ 
+ argument - a mandatory command line parameter with one or more arguments
+
+Inside the blocks in flag, option, and argument a shortcut function called 'set_opt'
+can be used to set an option that will be returned in the options hash.
+
+The number of arguments are determined by the 'arity' of the block. 
+
+The order in which the parameters are defined dictate their order on the command line.
+
+User defined help banners, summaries or the whole usage statement can be defined. 
+
+== Documentation
+
+See OptSimple for the API specification
+
+== Installation
+
+It is recommended to install OptSimple using RubyGems:
+
+ $ sudo gem install opt-simple
+
+== Examples
+
+=== A very simple example with no error checking. Use at your own risk!
+
+ require 'opt_simple'
+ 
+ defaults = {
+ 'max' => 40
+ } 
+ 
+ options,arguments = OptSimple.new(defaults).parse_opts! 
+
+ puts "Options"
+ puts options.inspect
+ 
+ puts "Arguments"
+ puts arguments.inspect
+ 
+ puts "ARGV"
+ puts ARGV
+ 
+ 
+=== An example that provides error checking on ARGV, using all default behavior
+ 
+ require 'opt_simple'
+ 
+ options,arguments = OptSimple.new.parse_opts! do 
+   argument "-i","inFile" 
+   option %w[-p --pattern --glob-pattern], "glob pattern"
+   flag "-v","Verbose"
+   flag "-whatever"
+ end
+ 
+ puts "Options"
+ puts options.inspect
+ 
+ puts "Arguments"
+ puts arguments.inspect
+ 
+ puts "ARGV"
+ puts ARGV
+
+
+=== An example that shows how to use 'set_opt', set the banner string, and add a summary.
+
+ require 'opt_simple'
+ 
+ defaults = {
+   "max" => 10
+ }
+ 
+ options,arguments = OptSimple.new(defaults).parse_opts! do 
+   banner "USAGE: #{$0}"
+   summary "Show how to set a banner and summary."
+ 
+   argument "-i","inFile" 
+   option %w[-m -max --maximum-value],"Maximum val" do |arg|
+     set_opt arg.to_i
+   end
+ end
+ 
+ puts "Options"
+ puts options.inspect
+ 
+ puts "Arguments"
+ puts arguments.inspect
+ 
+ puts "ARGV"
+ puts ARGV
+
+=== An example that shows that you can easily set your defaults in normal Ruby variables and provide your own help.
+
+ require 'opt_simple'
+ 
+ in_file = nil
+ min = 0
+ max = 10
+ pattern = "*"
+
+ usage_string = <<-UL
+ Usage: $0 [options]
+ 
+   -i, --infile FILE
+  [--range (min - default #{min}, max - default #{max})]
+  [-p, --pattern, --glob-pattern (default #{pattern})]
+  [-v (verbose)]
+  [-h, --help (help)]
+
+ UL
+
+ OptSimple.new.parse_opts! do 
+   help usage_string
+
+   argument %w[-i --infile],"inFile" do |arg|
+     in_file = arg
+     error "inFile must exist and be readable" unless(File.readable?(in_file))
+   end
+   
+   option ["--range"], "range: min,max (both >0) default is #{min},#{max}" do | arg1,arg2 |
+     min = arg1.to_i
+     max = arg2.to_i    
+     
+     error "max must be greater than min" unless max > min
+     error "both must be >=0" if min < 0
+   end  
+ 
+   option %w[-p --pattern --glob-pattern], "glob pattern, default is #{pattern}" do |arg|
+     pattern = arg
+   end
+ 
+   flag "-v","Verbose"
+ end
+ 
+ puts "in_file #{in_file}"
+ puts "min #{min}"
+ puts "max #{max}"
+ puts "pattern #{pattern}"
+ 
+ puts "ARGV"
+ puts ARGV
+ 
+== Questions and/or Comments
+
+email {Ethan Stryker}[mailto:e.stryker@gmail.com]
+

data/extensions/test_unit_extensions.rb

@@ -0,0 +1,21 @@
+module Test::Unit
+  # Used to fix a minor minitest/unit incompatibility in flexmock 
+  AssertionFailedError = Class.new(StandardError)
+  
+  class TestCase
+   
+    def self.must(name, &block)
+      test_name = "test_#{name.gsub(/\s+/,'_')}".to_sym
+      defined = instance_method(test_name) rescue false
+      raise "#{test_name} is already defined in #{self}" if defined
+      if block_given?
+        define_method(test_name, &block)
+      else
+        define_method(test_name) do
+          flunk "No implementation provided for #{name}"
+        end
+      end
+    end
+
+  end
+end

data/lib/opt_simple.rb

@@ -0,0 +1,369 @@
+=begin rdoc
+
+= OptSimple provides a very simple interface to command line parsing. 
+
+There are three methods to define command line parameters:
+
+ flag - a command line switch with no arguments following (although you can still use flag
+ as a synonym for option. But default behavior is to expect no args.)
+ 
+ option - an optional command line parameter with one or more arguments
+ 
+ argument - a mandatory command line parameter with one or more arguments
+
+Inside the blocks in flag, option, and argument a shortcut function called 'set_opt'
+can be used to set an option that will be returned in the options hash.
+
+The number of arguments are determined by the 'arity' of the block. 
+
+The order in which the parameters are defined dictate their order on the command line.
+
+User defined help banners, summaries or the whole usage statement can be defined. 
+=end
+class OptSimple
+  attr_accessor :args
+  attr_reader :mandatory_opts, :optional_opts
+
+  # default keys should should be strings, 
+  # args can be any list of strings, but defaults to ARGV
+  def initialize(defaults = {},args = ARGV)
+    @mandatory_opts = []
+    @optional_opts = []
+    @parameters = []
+    @param_names = {}
+    @longest_switch_len = 0 
+    @options = defaults.dup # not sure if I have to dup this
+    @positional_arguments = []
+    @args = args
+    @banner = "Usage: #{File.basename($0)} [options]"
+    @summary = ""
+    @help = ""
+  end
+
+  # set the Summary string at the end of the usage statement
+  def summary(str)
+    @summary = str
+  end
+
+  # provide a user defined help string, and override the auto-generated one
+  def help(str)
+    @help = str
+  end
+  
+  # set the banner to str, overriding the default: "Usage: #{File.basename($0)} [options]"
+  def banner(str)
+    @banner = str
+  end
+
+  # Parse the options, destructively pulling them out of the args array as it goes.
+  # If no block is given, then a default parser with no error checking will be run. 
+  def parse_opts!(&block)
+    
+    if block_given?
+      # call the block to register all the parameters and
+      # their corresponding code blocks
+      # We use instance_exec so that the API is cleaner. 
+      begin
+	instance_exec(@options,@positional_arguments,&block)
+      ensure
+	# we are ensuring that the options that occur before any break statement
+	# actually get parsed. 
+	
+	# add the help option at the end
+	option %w[-h --help] ,"(for this help message)"
+	
+	# first look for a call for help
+	unless (%w[-h --help] & @args).empty?
+	  $stdout.puts self.to_s
+	  exit(0)
+	end
+	
+	mandatory_check = mandatory_opts.map {|m| m.switches}
+	
+	if(loc = @args.index('--'))
+	  #remove the '--', but don't include it w/ positional arguments
+	  @positional_arguments += @args.slice!(loc..-1)[1..-1] 
+	end
+	
+	# now actually parse the args, and call all the stored up blocks from the options
+	@parameters.each do | parm |
+	  intersection =  @args & parm.switches
+	  unless intersection.empty?
+	    loc = @args.index(intersection.first)
+	    
+	    # remove the flag, but skip it to put it into pieces
+	    pieces = @args.slice!(loc .. loc + parm.block.arity)[1..-1]
+	    if pieces.length < parm.block.arity or
+		pieces.any? {|p| p.start_with?('-')}
+	      raise OptSimple::MissingArgument.new "Not enough args following #{intersection.first}",self 
+	    end
+	    
+	    mandatory_check.delete(parm.switches)
+
+	    begin
+	      parm.instance_exec(*pieces,&parm.block)
+	    rescue OptSimple::Error => e
+	      raise OptSimple::Error.new e.message,self
+	    end
+
+	    @options.merge!(parm.param_options)
+	  end
+	end
+	
+	unless mandatory_check.empty?
+	  raise MissingArgument.new "Must set the following parameters: #{mandatory_check.map {|a| a.join(' OR ')}.join(', ')}",self
+	end
+
+	extra_switches = @args.find_all {|a| a.start_with?('-') }
+	raise OptSimple::InvalidOption.new "Unknown options: #{extra_switches.join(' ')}",self unless extra_switches.empty?
+	
+	@positional_arguments += @args.slice!(0..-1)
+      end
+    else
+      #parse the @args array by looking for switches/args by regex
+      default_arg_parser
+    end	
+    return [@options,@positional_arguments]
+  end
+
+  # Parse the options in a non-destructive way to the args array passed in.
+  # If no block is given, then a default parser with no error checking will be run. 
+  def parse_opts(&block)
+    @original_args = @args # do I really need these around?
+    @args = @args.dup
+    parse_opts! &block
+  end
+
+  # You do not want to call this function. 
+  # This provides a default behavior for all switches on the command line if no
+  # block is given to parse_opts
+  def default_arg_parser 
+    flag = nil
+    @args.each_with_index do |arg,loc|
+      if arg == '--'
+	# end of flag marker
+	@positional_args += @args[i+1 .. -1]
+	break
+      elsif arg =~ /^-+(.*)/
+	# assume flags are boolean
+	@options[$1] = true
+	flag = $1
+      elsif flag
+	# unless followed by an arg
+	@options[flag] = arg
+	flag = nil
+      else
+	@positional_args << arg
+      end
+    end
+    @args.slice!(0..-1)
+  end
+
+  # Registers an optional parameter, usually with nothing following it. 
+  # although if the block has arity > 0, we'll be happy to handle 
+  # it as such. 
+  # 'switches' can be a String or an Array of Strings, and specifies the switches expected on the CL.
+  # 'help' provides a description of the parameter
+  # and an optional block can do parameter validation/transformation.
+  # If no block is given, then the strings specified (after the 
+  # leading '-'s removed) will be used as keys in the options hash 
+  # and the values set to true when  seen in the args array
+  def flag(switches,help="",&block)
+    add_parameter(Flag.new(switches,help,&block))
+  end
+
+  # Registers an optional parameter, with one or more argument following it.
+  # 'switches' can be a String or an Array of Strings, and specifies the switches expected on the CL.
+  # 'help' provides a description of the parameter
+  # and an optional block can do parameter validation/transformation.
+  # If no block is given, then the strings specified (after the 
+  # leading '-'s removed) will be used as keys in the options hash 
+  # and the values set to the arg following the switch in the args array.
+  def option(switches,help="",&block)
+    add_parameter(Option.new(switches,help,&block))
+  end
+
+  # Registers a mandatory parameter, with one or more argument following it.
+  # 'switches' can be a String or an Array of Strings, and specifies the switches expected on the CL.
+  # 'help' provides a description of the parameter
+  # and an optional block can do parameter validation/transformation.
+  # If no block is given, then the strings specified (after the 
+  # leading '-'s removed) will be used as keys in the options hash 
+  # and the values set to the arg following the switch the args array.
+  def argument(switches,help="",&block)
+    add_parameter(Argument.new(switches,help,&block))
+  end
+
+  # A shortcut for raising an OptSimple::Error exception
+  def error(string=nil)
+    raise OptSimple::Error.new string
+  end
+
+  # returns the automatic usage statement
+  def to_s
+    if @help.empty?
+      help_str = ""
+      
+      help_str << "  MANDATORY ARGS:\n" unless mandatory_opts.empty?
+      mandatory_opts.each do | parm |
+	help_str << parm.help_str(@longest_switch_len) << "\n"
+      end 
+      help_str << "\n" unless mandatory_opts.empty?
+      
+      help_str << "  OPTIONS:\n" unless  optional_opts.empty?
+      optional_opts.each do | parm |
+	help_str << parm.help_str(@longest_switch_len)
+	
+	# check to see if we have any defaults set to help in the help doc
+	intersection = @options.keys & parm.names
+	if intersection.empty?
+	  help_str << "\n\n"
+	else
+	  help_str << " (default is #{@options[intersection.first]})\n\n"
+	end
+      end
+      help_str << "  SUMMARY:\n\n    #{@summary}\n\n" unless @summary.empty?
+      
+      @help = @banner + "\n\n" + help_str 
+    end
+    @help
+  end
+
+  # You probably don't want to call this method. 
+  # A lower level function that adds a Flag, Option, or Argument,
+  def add_parameter(parm)
+    total_switch_len = parm.switches.join(', ').length
+    @longest_switch_len = total_switch_len if total_switch_len > @longest_switch_len
+
+    parm.names.each do | n |
+      if @param_names.has_key?(n)
+	raise OptSimple::Error.new "Command line switch already in use!"
+      else
+	@param_names[n] = true
+      end
+
+    end
+    @parameters << parm
+    @mandatory_opts << parm if parm.mandatory?
+    @optional_opts << parm if not parm.mandatory?
+  end
+
+  # The base class for command line parameter objects from which Flag, 
+  # Option and Argument are derived. Provides documentation methods, 
+  # an 'error method', and the 'set_opt' utility funciton. 
+  class Parameter
+    attr_reader :switches,:param_options,:block
+
+    # 'switches' can be a String or an Array of Strings, and specifies the switches expected on the CL.
+    # 'help' provides a description of the parameter
+    # and an optional block can do parameter validation/transformation.
+    def initialize(switches,help="",&block)
+      self.switches = switches
+      @help = help
+      @block = block
+      @param_options = {}
+      @names = nil
+    end
+
+    # ensures that the switches is an array. Should be an array of Strings
+    def switches=(switches)
+      @switches = [switches].flatten
+    end
+
+    # returns a list of the switches without the leading '-'s
+    def names
+      @names ||= switches.map {|s| s.sub(/^-+/,'')}
+    end
+
+    # a single line that will be put in the overall usage string
+    def help_str(switch_len)
+      short_parms = @switches.find_all {|st| st.start_with?('-') and st.length == 2 and st[1] != '-'} 
+      long_parms = @switches.find_all {|st| st.start_with?('--') or (st.start_with?('-') and st.length > 2)} 
+      other_parms = @switches.find_all {|st| not st.start_with?('-')}
+      
+      sh_str = short_parms.empty? ?  " " * 4 : short_parms.first
+      long_str = long_parms.join(', ') + other_parms.join(', ')
+      sh_str << ', ' unless sh_str =~/^\s+$/ or long_str.empty?
+      
+      "    %-#{switch_len}s" % (sh_str + long_str) + " \t#{@help}"
+    end
+
+    # A shortcut for raising an OptSimple::Error exception
+    def error(string)
+      raise OptSimple::Error.new string
+    end
+
+    # A utility function that sets all the names to the specified value
+    # in the param_options hash. 
+    def set_opt val
+      names.each {|n| @param_options[n] = val}
+    end
+
+    # is it mandatory to see this parameter on the command line?
+    def mandatory?; false; end
+
+  end
+
+  # An optional parameter, usually with nothing following it. 
+  # although if the block has arity > 0, we'll be happy to handle 
+  # it as such. 
+  # 'switches' can be a String or an Array of Strings, and specifies the switches expected on the CL.
+  # 'help' provides a description of the parameter
+  # and an optional block can do parameter validation/transformation.
+  # If no block is given, then the strings specified (after the 
+  # leading '-'s removed) will be used as keys in the options hash 
+  # and the values set to true when  seen in the args array  
+  class Flag < Parameter
+    def initialize(switches,help="",&block)
+      super(switches,help,&block)
+      unless block_given?
+	@block = Proc.new { names.each {|n| @param_options[n] = true}}
+      end
+    end
+  end
+
+  # An optional parameter, with one or more argument following it.
+  # 'switches' can be a String or an Array of Strings, and specifies the switches expected on the CL.
+  # 'help' provides a description of the parameter
+  # and an optional block can do parameter validation/transformation.
+  # If no block is given, then the strings specified (after the 
+  # leading '-'s removed) will be used as keys in the options hash 
+  # and the values set to the arg following the switch in the args array.
+  class Option < Parameter
+    def initialize(switches,help="",&block)
+      super(switches,help,&block)
+      unless block_given?
+	@block = Proc.new {|arg| names.each {|n| @param_options[n] = arg}}
+      end
+    end
+  end
+  
+  # A mandatory parameter, with one or more argument following it.
+  # 'switches' can be a String or an Array of Strings, and specifies the switches expected on the CL.
+  # 'help' provides a description of the parameter
+  # and an optional block can do parameter validation/transformation.
+  # If no block is given, then the strings specified (after the 
+  # leading '-'s removed) will be used as keys in the options hash 
+  # and the values set to the arg following the switch the args array.
+  class Argument < Option
+    def mandatory?; true; end
+  end
+
+  # A general error in the options
+  class Error < Exception
+    def initialize(string,option_obj=nil)
+      super("#{string}\n#{option_obj.to_s}")
+      set_backtrace []
+    end
+  end
+
+  # An exception that is thrown if an unspecified parameter
+  # is used on the command line
+  class InvalidOption < Error;end
+
+  # An exception thrown if a mandatory parameter is not
+  # used on the command line
+  class MissingArgument < Error;end
+
+end
+ 

data/lib/test_unit_extensions.rb

@@ -0,0 +1,21 @@
+module Test::Unit
+  # Used to fix a minor minitest/unit incompatibility in flexmock 
+  AssertionFailedError = Class.new(StandardError)
+  
+  class TestCase
+   
+    def self.must(name, &block)
+      test_name = "test_#{name.gsub(/\s+/,'_')}".to_sym
+      defined = instance_method(test_name) rescue false
+      raise "#{test_name} is already defined in #{self}" if defined
+      if block_given?
+        define_method(test_name, &block)
+      else
+        define_method(test_name) do
+          flunk "No implementation provided for #{name}"
+        end
+      end
+    end
+
+  end
+end

data/test/test_arglist.rb

@@ -0,0 +1,38 @@
+require 'opt_simple'
+require 'test/unit' 
+require 'test_unit_extensions'
+
+class ArglistTest < Test::Unit::TestCase
+  def setup
+    @args = %w[infile1 -v infile2 -o out.txt infile3 -- -infile4 infile5]
+    @os = OptSimple.new({},@args)
+    @block = Proc.new {
+      flag '-v'
+      argument '-o'
+    }
+  end
+
+  must "put all args after the dash dash in the pos argument list" do
+    options,arguments = @os.parse_opts &@block
+    assert arguments.include? '-infile4' and arguments.include? 'infile5'
+  end
+
+  must "return all positional args in the arguments list" do 
+    options,arguments = @os.parse_opts &@block
+    assert_equal arguments.sort,%w[infile1 infile2 infile3 -infile4 infile5].sort
+  end
+
+  must "empty out ARGV when using parse_opts!" do
+    arg_copy = @args.dup
+    @os.parse_opts! &@block 
+    assert @args.empty?
+  end
+
+  must "preserve ARGV when using parse_opts" do
+    arg_copy = @args.dup
+    @os.parse_opts &@block 
+
+    assert_equal @args.sort,arg_copy.sort
+  end
+
+end

data/test/test_help.rb

@@ -0,0 +1,45 @@
+require 'opt_simple'
+require 'test/unit' 
+require 'test_unit_extensions'
+
+class TestHelpStatement < Test::Unit::TestCase
+
+  must "add default info to help string" do 
+    defaults = {
+      'a' => 1000
+    }
+    os = OptSimple.new(defaults)
+    os.add_parameter(OptSimple::Option.new '-a' )
+    
+    assert os.to_s =~/default.*#{defaults['a']}/
+  end
+
+  must "order help according to specification order" do 
+    os = OptSimple.new({},['-h'])
+    os.add_parameter(OptSimple::Option.new '-a')
+    os.add_parameter(OptSimple::Flag.new '-b')
+    os.add_parameter(OptSimple::Option.new '-c')
+    os.add_parameter(OptSimple::Argument.new '-x')
+    os.add_parameter(OptSimple::Argument.new '-y')
+    os.add_parameter(OptSimple::Argument.new '-z')
+
+    assert os.to_s.match(Regexp.new("\-x.*\-y.*\-z.*\-a.*\-b.*\-c.*",Regexp::MULTILINE))
+  end
+
+  must "allow user defined help statements" do
+    my_help = "Totally irrelevant"
+    os = OptSimple.new({},['-h'])
+    os.add_parameter(OptSimple::Option.new '-a')
+    os.add_parameter(OptSimple::Flag.new '-b')
+    os.help my_help
+    
+    assert os.to_s == my_help
+  end
+
+  must "provide user specified summary statement in help" do
+    os = OptSimple.new({},['-h'])
+    os.add_parameter(OptSimple::Option.new '-a')
+    os.summary "My summary"
+    assert os.to_s.match(Regexp.new("My summary",Regexp::MULTILINE))
+  end
+end

data/test/test_usage.rb

@@ -0,0 +1,28 @@
+require 'opt_simple'
+require 'test/unit' 
+require 'test_unit_extensions'
+
+class TestHelpStatement < Test::Unit::TestCase
+
+  must "disallow name collisions in argument spec" do
+    assert_raise(OptSimple::Error) { OptSimple.new.parse_opts! {option %w[-a --awesome]; flag '-awesome' } }
+  end
+
+  must "raise error when unknown option is given" do 
+    os = OptSimple.new({},['-not-specified'])
+    assert_raise(OptSimple::InvalidOption) { os.parse_opts! { option %w[-a --awesome]  }  }
+  end
+
+  must "raise error when not enough arguments are given" do
+    os = OptSimple.new({},['-a'])
+    assert_raise(OptSimple::MissingArgument) do
+      os.parse_opts! do
+	option '-a' do |arg| 
+	  nil
+	end
+      end
+    end
+  end
+
+end
+

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification 
+name: opt-simple
+version: !ruby/object:Gem::Version 
+  version: 0.7.1
+platform: ruby
+authors: 
+- Ethan Stryker
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-03-04 00:00:00 +00:00
+default_executable: 
+dependencies: []
+
+description: "  Parameter specification, validity checking and argument transformations \n  can be put in one place, default parameters are easily set, and an \n  automatic usage statement is constructed.\n"
+email: e.stryker@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/test_unit_extensions.rb
+- lib/opt_simple.rb
+- test/test_help.rb
+- test/test_usage.rb
+- test/test_arglist.rb
+- extensions/test_unit_extensions.rb
+- README
+- GPLv2-LICENSE
+has_rdoc: true
+homepage: http://opt-simple.rubyforge.org/
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+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: opt-simple
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: A simple and elegant command line option parser.
+test_files: []
+