trollop 1.13 → 1.14

data/FAQ.txt

@@ -1,11 +1,14 @@
 Trollop FAQ
 -----------
 
+Q: Why is it called "Trollop"?
+A: No reason.
+
 Q: Why should I use Trollop?
-A: Because it will take you FEWER LINES OF CODE to do reasonable option
-   parsing than any other option parser in existence.
+A: Because it will take you FEWER LINES OF CODE to do reasonable option parsing
+   than any other option parser out there.
 
-   Look:
+   Look at this:
 
      opts = Trollop::options do
        opt :monkey, "Use monkey mode"
@@ -15,21 +18,67 @@ A: Because it will take you FEWER LINES OF CODE to do reasonable option
 
    That's it. And opts is a hash and you do whatever you want with it.
    Trivial. You don't have to mix option processing code blocks with the
-   declarations. You don't have to make a class for every option (what is
-   this, Java?). You don't have to write more than 1 line of code per
-   option.
+   declarations. You don't have to make a class for every option (what is this,
+   Java?). You don't have to write more than 1 line of code per option.
 
-Q: Why is it called "Trollop"?
-A: No reason.
+   Plus, you get a beautiful help screen that detects your terminal width and
+   wraps appropriately. C'mon, that's hot.
+
+Q: What is the philosophy behind Trollop?
+A: Must a commandline option processor have a philosophy?
+
+Q: Seriously now. What is it?
+A: Ok, it's this: Trollop *just* does the parsing and gives you a hash table
+   of the result. So whatever fancy logic or constraints you need, you can
+   implement by operating on that hash table. Options that disable other
+   options, fancy constraints involving multiple sets of values across multiple
+   sets of options, etc. are all left for you to do manually.
+
+   (Trollop does support limited constraint setting (see #conflicts and
+   #depends), but any non-trivial program will need to get fancier.)
+
+   The result is that using Trollop is pretty simple, and whatever bizarre
+   logic you want, you can write yourself. And don't forget, you can call
+   Trollop::die to abort the program and give a fancy options-related error
+   message.
+
+Q: What happens to the other stuff on the commandline?
+A: Anything Trollop doesn't recognize as an option or as an option parameter is
+   left in ARGV for you to process.
+
+Q: Does Trollop support multiple-value arguments?
+A: Yes. If you set the :type of an option to something plural, like ":ints",
+   ":strings", ":doubles", ":floats", ":ios", it will accept multiple arguments
+   on the commandline and the value will be an array of these.
+
+Q: Does Trollop support arguments that can be given multiple times?
+A: Yes. If you set :multi to true, then the argument can appear multiple times
+   on the commandline, and the value will be an array of the parameters.
+
+Q: Does Trollop support subcommands?
+A: Yes. You get subcommand support by adding a call #stop_on within the options
+   block, and passing the names of the subcommands to it. (See the third
+   example on the webpage.) When Trollop encounters one of these subcommands on
+   the commandline, it stops processing and returns.
+
+   ARGV at that point will contain the subcommand followed by any subcommand
+   options, since Trollop has contained the rest. So you can consume the
+   subcommand and call Trollop.options again with the particular options set
+   for that subcommand.
+
+   If you don't know the subcommands ahead of time, you can call
+   #stop_on_unknown, which will cause Trollop to stop when it encounters any
+   unknown token. This might be more trouble than its worth if you're also
+   passing filenames on the commandline.
 
-Q: Why does Trollop disallow numeric short argument names, like '-1'
-   and '-9'?
-A: Because it's ambiguous whether these are arguments or negative
-   integer or floating-point parameters to arguments. E.g., what
-   about "-f -3". Is that a negative three parameter to -f, or two
-   separate parameters? 
+   It's probably easier to see the example on the webpage than to read all
+   that.
 
-   I could be very clever and detect when there are no arguments
-   that require floating-point parameters, and allow such short option
-   names in those cases, but opted for simplicity and consistency.
+Q: Why does Trollop disallow numeric short argument names, like '-1' and '-9'?
+A: Because it's ambiguous whether these are arguments or negative integer or
+   floating-point parameters to arguments. E.g., what about "-f -3".  Is that a
+   negative three parameter to -f, or two separate parameters? 
 
+   I could be very clever and detect when there are no arguments that require
+   floating-point parameters, and allow such short option names in those cases,
+   but opted for simplicity and consistency.

data/History.txt

@@ -1,3 +1,7 @@
+== 1.14 / 2009-06-19
+* Make :multi arguments default to [], not nil, when not set on the commandline.
+* Minor commenting and error message improvements
+
 == 1.13 / 2009-03-16
 * Fix parsing of "--longarg=<value with spaces>".
 

data/lib/trollop.rb

@@ -3,9 +3,11 @@
 ## Copyright:: Copyright 2007 William Morgan
 ## License::   GNU GPL version 2
 
+require 'date'
+
 module Trollop
 
-VERSION = "1.13"
+VERSION = "1.14"
 
 ## Thrown by Parser in the event of a commandline error. Not needed if
 ## you're using the Trollop::options entry.
@@ -39,16 +41,17 @@ class Parser
   ## +:type+ parameter of #opt.
   FLAG_TYPES = [:flag, :bool, :boolean]
 
-  ## The set of values that indicate a single-parameter option when
+  ## The set of values that indicate a single-parameter (normal) option when
   ## passed as the +:type+ parameter of #opt.
   ##
   ## A value of +io+ corresponds to a readable IO resource, including
   ## a filename, URI, or the strings 'stdin' or '-'.
-  SINGLE_ARG_TYPES = [:int, :integer, :string, :double, :float, :io]
+  SINGLE_ARG_TYPES = [:int, :integer, :string, :double, :float, :io, :date]
 
-  ## The set of values that indicate a multiple-parameter option when
-  ## passed as the +:type+ parameter of #opt.
-  MULTI_ARG_TYPES = [:ints, :integers, :strings, :doubles, :floats, :ios]
+  ## The set of values that indicate a multiple-parameter option (i.e., that
+  ## takes multiple space-separated values on the commandline) when passed as
+  ## the +:type+ parameter of #opt.
+  MULTI_ARG_TYPES = [:ints, :integers, :strings, :doubles, :floats, :ios, :dates]
 
   ## The complete set of legal values for the +:type+ parameter of #opt.
   TYPES = FLAG_TYPES + SINGLE_ARG_TYPES + MULTI_ARG_TYPES
@@ -104,6 +107,8 @@ class Parser
   ##
   ## Arguments that can occur multiple times should be marked with
   ## +:multi+ => +true+. The value of this argument will also be an array.
+  ## In contrast with regular non-multi options, if not specified on
+  ## the commandline, the default value will be [], not nil.
   ##
   ## These two attributes can be combined (e.g. +:type+ => +:strings+,
   ## +:multi+ => +true+), in which case the value of the argument will be
@@ -128,12 +133,13 @@ class Parser
       when :double; :float
       when :doubles; :floats
       when Class
-        case opts[:type].to_s # sigh... there must be a better way to do this
+        case opts[:type].name
         when 'TrueClass', 'FalseClass'; :flag
         when 'String'; :string
         when 'Integer'; :int
         when 'Float'; :float
         when 'IO'; :io
+        when 'Date'; :date
         else
           raise ArgumentError, "unsupported argument type '#{opts[:type].class.name}'"
         end
@@ -161,6 +167,7 @@ class Parser
       when TrueClass, FalseClass; :flag
       when String; :string
       when IO; :io
+      when Date; :date
       when Array
         if opts[:default].empty?
           raise ArgumentError, "multiple argument type cannot be deduced from an empty array for '#{opts[:default][0].class.name}'"
@@ -170,6 +177,7 @@ class Parser
         when Numeric; :floats
         when String; :strings
         when IO; :ios
+        when Date; :dates
         else
           raise ArgumentError, "unsupported multiple argument type '#{opts[:default][0].class.name}'"
         end
@@ -178,7 +186,7 @@ class Parser
         raise ArgumentError, "unsupported argument type '#{opts[:default].class.name}'"
       end
 
-    raise ArgumentError, ":type specification and default type don't match" if opts[:type] && type_from_default && opts[:type] != type_from_default
+    raise ArgumentError, ":type specification and default type don't match (default type is #{type_from_default})" if opts[:type] && type_from_default && opts[:type] != type_from_default
 
     opts[:type] = opts[:type] || type_from_default || :flag
 
@@ -280,6 +288,7 @@ class Parser
     @specs.each do |sym, opts|
       required[sym] = true if opts[:required]
       vals[sym] = opts[:default]
+      vals[sym] = [] if opts[:multi] && !opts[:default] # multi arguments default to [], not nil
     end
 
     resolve_default_short_options
@@ -364,6 +373,8 @@ class Parser
         vals[sym] = params.map { |pg| pg.map { |p| p.to_s } }
       when :io, :ios
         vals[sym] = params.map { |pg| pg.map { |p| parse_io_parameter p, arg } }
+      when :date, :dates
+        vals[sym] = params.map { |pg| pg.map { |p| parse_date_parameter p, arg } }
       end
 
       if SINGLE_ARG_TYPES.include?(opts[:type])
@@ -387,6 +398,19 @@ class Parser
     vals
   end
 
+  def parse_date_parameter param, arg #:nodoc:
+    begin
+      begin
+        time = Chronic.parse(param)
+      rescue NameError
+        # chronic is not available
+      end
+      time ? Date.new(time.year, time.month, time.day) : Date.parse(param)
+    rescue ArgumentError => e
+      raise CommandlineError, "option '#{arg}' needs a date"
+    end
+  end
+
   ## Print the help message to +stream+.
   def educate stream=$stdout
     width # just calculate it now; otherwise we have to be careful not to
@@ -406,6 +430,8 @@ class Parser
         when :floats; " <f+>"
         when :io; " <filename/uri>"
         when :ios; " <filename/uri+>"
+        when :date; " <date>"
+        when :dates; " <date+>"
         end
     end
 
@@ -587,7 +613,7 @@ private
       opts = @specs[name]
       next if opts[:short]
 
-      c = opts[:long].split(//).find { |c| c !~ INVALID_SHORT_ARG_REGEX && !@short.member?(c) }
+      c = opts[:long].split(//).find { |d| d !~ INVALID_SHORT_ARG_REGEX && !@short.member?(d) }
       raise ArgumentError, "can't generate a default short option name for #{opts[:long].inspect}: out of unique characters" unless c
 
       opts[:short] = c

data/test/test_trollop.rb

@@ -99,6 +99,15 @@ class Trollop < ::Test::Unit::TestCase
     assert_equal 2, opts["argsf"]
     assert_raise(CommandlineError) { @p.parse(%w(--argsf hello)) }
 
+    # single arg: date
+    date = Date.today
+    assert_nothing_raised { @p.opt "argsd", "desc", :default => date }
+    assert_nothing_raised { opts = @p.parse("--") }
+    assert_equal Date.today, opts["argsd"]
+    assert_nothing_raised { opts = @p.parse(['--argsd', 'Jan 4, 2007']) }
+    assert_equal Date.civil(2007, 1, 4), opts["argsd"]
+    assert_raise(CommandlineError) { @p.parse(%w(--argsd hello)) }
+
     # single arg: string
     assert_nothing_raised { @p.opt "argss", "desc", :default => "foobar" }
     assert_nothing_raised { opts = @p.parse("--") }
@@ -127,14 +136,23 @@ class Trollop < ::Test::Unit::TestCase
     assert_equal [4.0], opts["argmf"]
     assert_raise(CommandlineError) { @p.parse(%w(--argmf hello)) }
 
+    # multi args: dates
+    dates = [Date.today, Date.civil(2007, 1, 4)]
+    assert_nothing_raised { @p.opt "argmd", "desc", :default => dates }
+    assert_nothing_raised { opts = @p.parse("--") }
+    assert_equal dates, opts["argmd"]
+    assert_nothing_raised { opts = @p.parse(['--argmd', 'Jan 4, 2007']) }
+    assert_equal [Date.civil(2007, 1, 4)], opts["argmd"]
+    assert_raise(CommandlineError) { @p.parse(%w(--argmd hello)) }
+
     # multi args: strings
-    assert_nothing_raised { @p.opt "argms", "desc", :default => %w(hello world) }
+    assert_nothing_raised { @p.opt "argmst", "desc", :default => %w(hello world) }
     assert_nothing_raised { opts = @p.parse("--") }
-    assert_equal %w(hello world), opts["argms"]
-    assert_nothing_raised { opts = @p.parse(%w(--argms 3.4)) }
-    assert_equal ["3.4"], opts["argms"]
-    assert_nothing_raised { opts = @p.parse(%w(--argms goodbye)) }
-    assert_equal ["goodbye"], opts["argms"]
+    assert_equal %w(hello world), opts["argmst"]
+    assert_nothing_raised { opts = @p.parse(%w(--argmst 3.4)) }
+    assert_equal ["3.4"], opts["argmst"]
+    assert_nothing_raised { opts = @p.parse(%w(--argmst goodbye)) }
+    assert_equal ["goodbye"], opts["argmst"]
   end    
 
   ## :type and :default must match if both are specified
@@ -146,10 +164,12 @@ class Trollop < ::Test::Unit::TestCase
 
     assert_nothing_raised { @p.opt "argsi", "desc", :type => :int, :default => 4 }
     assert_nothing_raised { @p.opt "argsf", "desc", :type => :float, :default => 3.14 }
+    assert_nothing_raised { @p.opt "argsd", "desc", :type => :date, :default => Date.today }
     assert_nothing_raised { @p.opt "argss", "desc", :type => :string, :default => "yo" }
     assert_nothing_raised { @p.opt "argmi", "desc", :type => :ints, :default => [4] }
     assert_nothing_raised { @p.opt "argmf", "desc", :type => :floats, :default => [3.14] }
-    assert_nothing_raised { @p.opt "argms", "desc", :type => :strings, :default => ["yo"] }
+    assert_nothing_raised { @p.opt "argmd", "desc", :type => :dates, :default => [Date.today] }
+    assert_nothing_raised { @p.opt "argmst", "desc", :type => :strings, :default => ["yo"] }
   end
 
   def test_long_detects_bad_names
@@ -352,6 +372,20 @@ EOM
     assert_raises(CommandlineError) { @p.parse %w(-f -.) }
   end
 
+  def test_date_formatting
+    @p.opt :arg, "desc", :type => :date, :short => 'd'
+    opts = nil
+    assert_nothing_raised { opts = @p.parse(['-d', 'Jan 4, 2007']) }
+    assert_equal Date.civil(2007, 1, 4), opts[:arg]
+    begin
+      require 'chronic'
+      assert_nothing_raised { opts = @p.parse(['-d', 'today']) }
+      assert_equal Date.today, opts[:arg]
+    rescue LoadError
+      # chronic is not available
+    end
+  end
+
   def test_short_options_cant_be_numeric
     assert_raises(ArgumentError) { @p.opt :arg, "desc", :short => "-1" }
     @p.opt :a1b, "desc"
@@ -1002,6 +1036,12 @@ EOM
     assert_equal "hello there", opts[:arg2]
     assert_equal 0, @p.leftovers.size
   end
+
+  def test_multi_args_default_to_empty_array
+    @p.opt :arg1, "arg", :multi => true
+    opts = @p.parse ""
+    assert_equal [], opts[:arg1]
+  end
 end
 
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: trollop
 version: !ruby/object:Gem::Version 
-  version: "1.13"
+  version: "1.14"
 platform: ruby
 authors: 
 - William Morgan
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-03-16 00:00:00 -07:00
+date: 2009-06-19 00:00:00 -04:00
 default_executable: 
 dependencies: []
 
@@ -55,7 +55,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: trollop
-rubygems_version: 1.2.0
+rubygems_version: 1.3.1
 signing_key: 
 specification_version: 2
 summary: 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.