trollop 1.10 → 1.10.1

data/History.txt

@@ -1,3 +1,10 @@
+== 1.10.1 / 2008-10-22
+* Options hash now responds to method calls as well as standard hash lookup.
+* Default values for multi-occurrence parameters now autoboxed.
+* The relationship between multi-value, multi-occurrence, and default values
+  improved and explained.
+* Documentation improvements.
+
 == 1.10 / 2008-10-21
 * Added :io type for parameters that point to IO streams (filenames, URIs, etc).
 * For screen size detection, first try `stty size` before loading Curses.

data/README.txt

@@ -4,7 +4,7 @@ by William Morgan <wmorgan-trollop@masanjin.net>
 
 http://trollop.rubyforge.org
 
-Documentation quickstart: See Trollop::Parser.
+Documentation quickstart: See Trollop::options and Trollop::Parser#opt.
 
 == DESCRIPTION
 

data/Rakefile

@@ -7,8 +7,8 @@ $:.unshift "lib"
 require 'trollop'
 
 class Hoe
-  def extra_deps; @extra_deps.reject { |x| Array(x).first == "hoe" } end
-end # thanks to "Mike H"
+  def extra_dev_deps; @extra_dev_deps.reject { |x| x[0] == "hoe" } end
+end
 
 Hoe.new('trollop', Trollop::VERSION) do |p|
   p.rubyforge_name = 'trollop'
@@ -25,8 +25,12 @@ task :upload_webpage => WWW_FILES do |t|
   sh "rsync -Paz -essh #{t.prerequisites * ' '} wmorgan@rubyforge.org:/var/www/gforge-projects/trollop/"
 end
 
-task :upload_docs => [:docs] do |t|
-  sh "rsync -Paz -essh doc/* wmorgan@rubyforge.org:/var/www/gforge-projects/trollop/trollop/"
+task :rdoc do |t|
+  sh "rdoc lib README.txt History.txt"
+end
+
+task :upload_docs => [:rdoc] do |t|
+  sh "rsync -az -essh doc/* wmorgan@rubyforge.org:/var/www/gforge-projects/trollop/trollop/"
 end
 
 # vim: syntax=ruby

data/lib/trollop.rb

@@ -5,7 +5,7 @@
 
 module Trollop
 
-VERSION = "1.10"
+VERSION = "1.10.1"
 
 ## Thrown by Parser in the event of a commandline error. Not needed if
 ## you're using the Trollop::options entry.
@@ -26,7 +26,7 @@ FLOAT_RE = /^-?((\d+(\.\d+)?)|(\.\d+))$/
 PARAM_RE = /^-(-|\.$|[^\d\.])/
 
 ## The commandline parser. In typical usage, the methods in this class
-## will be handled internally by Trollop#options. In this case, only the
+## will be handled internally by Trollop::options. In this case, only the
 ## #opt, #banner and #version, #depends, and #conflicts methods will
 ## typically be called.
 ##
@@ -79,18 +79,43 @@ class Parser
   end
 
   ## Define an option. +name+ is the option name, a unique identifier
-  ## for the option that you will use internally. This should probably
-  ## be a symbol. +desc+ is a string description which will be displayed
-  ## in help messages.
+  ## for the option that you will use internally, which should be a
+  ## symbol or a string. +desc+ is a string description which will be
+  ## displayed in help messages.
   ##
   ## Takes the following optional arguments:
   ##
   ## [+:long+] Specify the long form of the argument, i.e. the form with two dashes. If unspecified, will be automatically derived based on the argument name by turning the +name+ option into a string, and replacing any _'s by -'s.
   ## [+:short+] Specify the short form of the argument, i.e. the form with one dash. If unspecified, will be automatically derived from +name+.
-  ## [+:type+] Require that the argument take a parameter or parameters of type +type+. For a single parameter, the value can be a member of +SINGLE_ARG_TYPES+, or a corresponding Ruby class (e.g. +Integer+ for +:int+). For multiple parameters, the value can be any member of +MULTI_ARG_TYPES+ constant. If unset, the default argument type is +:flag+, meaning that the argument does not take a parameter. The specification of +:type+ is not necessary if +:default+ is given.
-  ## [+:default+] Set the default value for an argument. Without a default value, the hash returned by #parse (and thus Trollop#options) will have a +nil+ value for this key unless the option is set on the commandline. The argument type is derived automatically from the class of the default value given, if any.  Specifying a +:flag+ argument on the commandline whose default value is +true+ will result in a value of +false+.
+  ## [+:type+] Require that the argument take a parameter or parameters of type +type+. For a single parameter, the value can be a member of +SINGLE_ARG_TYPES+, or a corresponding Ruby class (e.g. +Integer+ for +:int+). For multiple-argument parameters, the value can be any member of +MULTI_ARG_TYPES+ constant. If unset, the default argument type is +:flag+, meaning that the argument does not take a parameter. The specification of +:type+ is not necessary if a +:default+ is given.
+  ## [+:default+] Set the default value for an argument. Without a default value, the hash returned by #parse (and thus Trollop::options) will have a +nil+ value for this key unless the argument is given on the commandline. The argument type is derived automatically from the class of the default value given, so specifying a +:type+ is not necessary if a +:default+ is given. (But see below for an important caveat when +:multi+: is specified too.) If the argument is a flag, and the default is set to +true+, then if it is specified on the the commandline the value will be +false+.
   ## [+:required+] If set to +true+, the argument must be provided on the commandline.
-  ## [+:multi+] If set to +true+, allows multiple instances of the option on the commandline. Otherwise, only a single instance of the option is allowed.
+  ## [+:multi+] If set to +true+, allows multiple occurrences of the option on the commandline. Otherwise, only a single instance of the option is allowed. (Note that this is different from taking multiple parameters. See below.)
+  ##
+  ## Note that there are two types of argument multiplicity: an argument
+  ## can take multiple values, e.g. "--arg 1 2 3". An argument can also
+  ## be allowed to occur multiple times, e.g. "--arg 1 --arg 2".
+  ##
+  ## Arguments that take multiple values should have a +:type+ parameter
+  ## drawn from +MULTI_ARG_TYPES+ (e.g. +:strings+), or a +:default:+
+  ## value of an array of the correct type (e.g. [String]). The
+  ## value of this argument will be an array of the parameters on the
+  ## commandline.
+  ##
+  ## Arguments that can occur multiple times should be marked with
+  ## +:multi+ => +true+. The value of this argument will also be an array.
+  ##
+  ## These two attributes can be combined (e.g. +:type+ => +:strings+,
+  ## +:multi+ => +true+), in which case the value of the argument will be
+  ## an array of arrays.
+  ##
+  ## There's one ambiguous case to be aware of: when +:multi+: is true and a
+  ## +:default+ is set to an array (of something), it's ambiguous whether this
+  ## is a multi-value argument as well as a multi-occurrence argument.
+  ## In thise case, Trollop assumes that it's not a multi-value argument.
+  ## If you want a multi-value, multi-occurrence argument with a default
+  ## value, you must specify +:type+ as well.
+
   def opt name, desc="", opts={}
     raise ArgumentError, "you already have an argument named '#{name}'" if @specs.member? name
 
@@ -118,8 +143,19 @@ class Parser
         opts[:type]
       end
 
+    ## for options with :multi => true, an array default doesn't imply
+    ## a multi-valued argument. for that you have to specify a :type
+    ## as well. (this is how we disambiguate an ambiguous situation;
+    ## see the docs for Parser#opt for details.)
+    disambiguated_default =
+      if opts[:multi] && opts[:default].is_a?(Array) && !opts[:type]
+        opts[:default].first
+      else
+        opts[:default]
+      end
+
     type_from_default =
-      case opts[:default]
+      case disambiguated_default
       when Integer; :int
       when Numeric; :float
       when TrueClass, FalseClass; :flag
@@ -144,7 +180,7 @@ class Parser
 
     raise ArgumentError, ":type specification and default type don't match" if opts[:type] && type_from_default && opts[:type] != type_from_default
 
-    opts[:type] = (opts[:type] || type_from_default || :flag)
+    opts[:type] = opts[:type] || type_from_default || :flag
 
     ## fill in :long
     opts[:long] = opts[:long] ? opts[:long].to_s : name.to_s.gsub("_", "-")
@@ -184,6 +220,9 @@ class Parser
     ## fill in :default for flags
     opts[:default] = false if opts[:type] == :flag && opts[:default].nil?
 
+    ## autobox :default for :multi (multi-occurrence) arguments
+    opts[:default] = [opts[:default]] if opts[:default] && opts[:multi] && !opts[:default].is_a?(Array)
+
     ## fill in :multi
     opts[:multi] ||= false
 
@@ -417,6 +456,12 @@ class Parser
       # else: multiple options, with multiple parameters
     end
 
+    ## allow openstruct-style accessors
+    class << vals
+      def method_missing(m, *args)
+        self[m] || self[m.to_s]
+      end
+    end
     vals
   end
 
@@ -509,16 +554,27 @@ class Parser
 
       spec = @specs[opt]
       stream.printf "  %#{leftcol_width}s:   ", left[opt]
-      desc = spec[:desc] + 
+      desc = spec[:desc] + begin
+        default_s = case spec[:default]
+        when $stdout; "<stdout>"
+        when $stdin; "<stdin>"
+        when $stderr; "<stderr>"
+        when Array
+          spec[:default].join(", ")
+        else
+          spec[:default].to_s
+        end
+
         if spec[:default]
           if spec[:desc] =~ /\.$/
-            " (Default: #{spec[:default]})"
+            " (Default: #{default_s})"
           else
-            " (default: #{spec[:default]})"
+            " (default: #{default_s})"
           end
         else
           ""
         end
+      end
       stream.puts wrap(desc, :width => width - rightcol_start - 1, :prefix => rightcol_start)
     end
   end
@@ -573,7 +629,19 @@ end
 ## (Parser#opt), zero or more calls to +text+ (Parser#text), and
 ## probably a call to +version+ (Parser#version).
 ##
-## See the examples at http://trollop.rubyforge.org.
+## Example:
+##
+##   require 'trollop'
+##   opts = Trollop::options do
+##     opt :monkey, "Use monkey mode"                     # a flag --monkey, defaulting to false
+##     opt :goat, "Use goat mode", :default => true       # a flag --goat, defaulting to true
+##     opt :num_limbs, "Number of limbs", :default => 4   # an integer --num-limbs <i>, defaulting to 4
+##     opt :num_thumbs, "Number of thumbs", :type => :int # an integer --num-thumbs <i>, defaulting to nil
+##   end
+##
+##   p opts # returns a hash: { :monkey => false, :goat => true, :num_limbs => 4, :num_thumbs => nil }
+##
+## See more examples at http://trollop.rubyforge.org.
 def options args = ARGV, *a, &b
   @p = Parser.new(*a, &b)
   begin

data/test/test_trollop.rb

@@ -884,14 +884,73 @@ EOM
     assert_kind_of File, opts[:arg]
     assert_equal "/dev/null", opts[:arg].path
 
-    assert_nothing_raised { opts = @p.parse %w(--arg2 http://google.com/) }
-    assert_kind_of StringIO, opts[:arg2]
+    #TODO: move to mocks
+    #assert_nothing_raised { opts = @p.parse %w(--arg2 http://google.com/) }
+    #assert_kind_of StringIO, opts[:arg2]
 
     assert_nothing_raised { opts = @p.parse %w(--arg3 stdin) }
     assert_equal $stdin, opts[:arg3]
 
     assert_raises(CommandlineError) { opts = @p.parse %w(--arg /fdasfasef/fessafef/asdfasdfa/fesasf) }
   end
+
+  def test_openstruct_style_access
+    @p.opt "arg1", "desc", :type => :int
+    @p.opt :arg2, "desc", :type => :int
+
+    opts = @p.parse(%w(--arg1 3 --arg2 4))
+
+    assert_nothing_raised { opts.arg1 }
+    assert_nothing_raised { opts.arg2 }
+    assert_equal 3, opts.arg1
+    assert_equal 4, opts.arg2
+  end
+
+  def test_multi_args_autobox_defaults
+    @p.opt :arg1, "desc", :default => "hello", :multi => true
+    @p.opt :arg2, "desc", :default => ["hello"], :multi => true
+
+    opts = @p.parse
+    assert_equal ["hello"], opts[:arg1]
+    assert_equal ["hello"], opts[:arg2]
+
+    opts = @p.parse %w(--arg1 hello)
+    assert_equal ["hello"], opts[:arg1]
+    assert_equal ["hello"], opts[:arg2]
+
+    opts = @p.parse %w(--arg1 hello --arg1 there)
+    assert_equal ["hello", "there"], opts[:arg1]
+  end
+
+  def test_ambigious_multi_plus_array_default_resolved_as_specified_by_documentation
+    @p.opt :arg1, "desc", :default => ["potato"], :multi => true
+    @p.opt :arg2, "desc", :default => ["potato"], :multi => true, :type => :strings
+    @p.opt :arg3, "desc", :default => ["potato"]
+    @p.opt :arg4, "desc", :default => ["potato", "rhubarb"], :short => :none, :multi => true
+
+    ## arg1 should be multi-occurring but not multi-valued
+    opts = @p.parse %w(--arg1 one two)
+    assert_equal ["one"], opts[:arg1]
+    assert_equal ["two"], @p.leftovers
+
+    opts = @p.parse %w(--arg1 one --arg1 two)
+    assert_equal ["one", "two"], opts[:arg1]
+    assert_equal [], @p.leftovers
+
+    ## arg2 should be multi-valued and multi-occurring
+    opts = @p.parse %w(--arg2 one two)
+    assert_equal [["one", "two"]], opts[:arg2]
+    assert_equal [], @p.leftovers
+
+    ## arg3 should be multi-valued but not multi-occurring
+    opts = @p.parse %w(--arg3 one two)
+    assert_equal ["one", "two"], opts[:arg3]
+    assert_equal [], @p.leftovers
+
+    ## arg4 should be multi-valued but not multi-occurring
+    opts = @p.parse %w()
+    assert_equal ["potato", "rhubarb"], opts[:arg4]
+  end
 end
 
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: trollop
 version: !ruby/object:Gem::Version 
-  version: "1.10"
+  version: 1.10.1
 platform: ruby
 authors: 
 - William Morgan
@@ -9,19 +9,10 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-10-21 00:00:00 -07:00
+date: 2008-10-22 00:00:00 -07:00
 default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
-  name: hoe
-  type: :development
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: 1.8.0
-    version: 
+dependencies: []
+
 description: == DESCRIPTION  Trollop is a commandline option parser for Ruby that just gets out of your way. One line of code per option is all you need to write. For that, you get a nice automatically-generated help page, robust option parsing, command subcompletion, and sensible defaults for everything you don't specify.  * A burning desire to write less code.  == INSTALL  * gem install trollop  == LICENSE  Copyright (c) 2008 William Morgan. Trollop is distributed under the same terms as Ruby.
 email: wmorgan-trollop@masanjin.net
 executables: []