trollop 1.9 → 1.10

data/FAQ.txt

@@ -33,12 +33,3 @@ A: Because it's ambiguous whether these are arguments or negative
    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 options appearing multiple times, despite
-   the POSIX standard allowing it?
-A: Because basically I think it's confusing, and more often than
-   not, a symptom of you making a mistake (e.g. getting lost in a long
-   command line and accidentally setting the same thing twice.) 
-   I also don't see that much advantage to "-vvvvv" over "-v 5", so
-   Trollop will produce an error if you try to use the same argument
-   multiple times.
-

data/History.txt

@@ -1,3 +1,8 @@
+== 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.
+* Improved documentation.
+
 == 1.9 / 2008-08-20
 * Added 'stop_on_unknown' command to stop parsing on any unknown argument.
   This is useful for handling sub-commands when you don't know the entire

data/README.txt

@@ -23,62 +23,6 @@ subcompletion, and sensible defaults for everything you don't specify.
 - Automatic help message generation, wrapped to current screen width.
 - Lots of unit tests.
 
-== SYNOPSIS
-
-  ####################
-  ###### simple ######
-  ####################
-
-  require 'trollop'
-  opts = Trollop::options do
-    opt :monkey, "Use monkey mode"
-    opt :goat, "Use goat mode", :default => true
-    opt :num_limbs, "Set number of limbs", :default => 4
-  end
-
-  p opts # { :monkey => false, :goat => true, :num_limbs => 4 }
-
-  ####################
-  ###### medium ######
-  ####################
-
-  require 'trollop'
-  opts = Trollop::options do
-    version "test 1.2.3 (c) 2007 William Morgan"
-    banner <<-EOS
-  Test is an awesome program that does something very, very important.
-
-  Usage:
-         test [options] <filenames>+
-  where [options] are:
-  EOS
-
-    opt :ignore, "Ignore incorrect values"
-    opt :file, "Extra data filename to read in, with a very long option description like this one", :type => String
-    opt :volume, "Volume level", :default => 3.0
-    opt :iters, "Number of iterations", :default => 5
-  end
-  Trollop::die :volume, "must be non-negative" if opts[:volume] < 0
-  Trollop::die :file, "must exist" unless File.exist?(opts[:file]) if opts[:file]
-  ################################
-  ##### sub-command support ######
-  ################################
-
-  require 'trollop'
-  global_opts = Trollop::options do
-    opt :global_option, "This is a global option"
-    stop_on %w(sub-command-1 sub-command-2)
-  end
-
-  cmd = ARGV.shift
-  cmd_opts = Trollop::options do
-    opt :cmd_option, "This is an option only for the subcommand"
-  end
-
-  p global_opts
-  p cmd
-  p cmd_opts
-
 == REQUIREMENTS
 
 * A burning desire to write less code.
@@ -89,6 +33,4 @@ subcompletion, and sensible defaults for everything you don't specify.
 
 == LICENSE
 
-Copyright (c) 2008 William Morgan.
-
-Trollop is distributed under the same terms as Ruby.
+Copyright (c) 2008 William Morgan. Trollop is distributed under the same terms as Ruby.

data/lib/trollop.rb

@@ -5,7 +5,7 @@
 
 module Trollop
 
-VERSION = "1.9"
+VERSION = "1.10"
 
 ## Thrown by Parser in the event of a commandline error. Not needed if
 ## you're using the Trollop::options entry.
@@ -26,26 +26,31 @@ 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 which case only the
-## methods #opt, #banner and #version, #depends, and #conflicts will
+## will be handled internally by Trollop#options. In this case, only the
+## #opt, #banner and #version, #depends, and #conflicts methods will
 ## typically be called.
+##
+## If it's necessary to instantiate this class (for more complicated
+## argument-parsing situations), be sure to call #parse to actually
+## produce the output hash.
 class Parser
 
-  ## The set of values that indicate a flag type of option when one of
-  ## the values is given to the :type parameter to #opt.
+  ## The set of values that indicate a flag option when passed as the
+  ## +:type+ parameter of #opt.
   FLAG_TYPES = [:flag, :bool, :boolean]
 
-  ## The set of values that indicate an option that takes a single
-  ## parameter when one of the values is given to the :type parameter to
-  ## #opt.
-  SINGLE_ARG_TYPES = [:int, :integer, :string, :double, :float]
+  ## The set of values that indicate a single-parameter 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]
 
-  ## The set of values that indicate an option that takes multiple
-  ## parameters when one of the values is given to the :type parameter to
-  ## #opt.
-  MULTI_ARG_TYPES = [:ints, :integers, :strings, :doubles, :floats]
+  ## 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 specifiable as the :type parameter to #opt.
+  ## The complete set of legal values for the +:type+ parameter of #opt.
   TYPES = FLAG_TYPES + SINGLE_ARG_TYPES + MULTI_ARG_TYPES
 
   INVALID_SHORT_ARG_REGEX = /[\d-]/ #:nodoc:
@@ -73,62 +78,44 @@ class Parser
     cloaker(&b).bind(self).call(*a) if b
   end
 
-  ## Add an option. 'name' is the argument name, a unique identifier
-  ## for the option that you will use internally. 'desc' a string
-  ## description which will be displayed in help messages. Takes the
-  ## following optional arguments:
+  ## 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.
   ##
-  ## * :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.
-  ## * :short: Specify the short form of the argument, i.e. the form
-  ##   with one dash. If unspecified, will be automatically derived
-  ##   based on the argument 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 the SINGLE_ARG_TYPES constant or a corresponding class
-  ##   (e.g. Integer for :int). For multiple parameters, the value can
-  ##   be a member of the 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 not contain the argument unless it is
-  ##   given 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 change its value to 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. Otherwise, only a single instance of the option is
-  ##   allowed.
+  ## 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+.
+  ## [+: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.
   def opt name, desc="", opts={}
     raise ArgumentError, "you already have an argument named '#{name}'" if @specs.member? name
 
     ## fill in :type
-    opts[:type] = 
+    opts[:type] = # normalize
       case opts[:type]
-      when :flag, :boolean, :bool; :flag
-      when :int, :integer; :int
-      when :ints, :integers; :ints
-      when :string; :string
-      when :strings; :strings
-      when :double, :float; :float
-      when :doubles, :floats; :floats
+      when :boolean, :bool; :flag
+      when :integer; :int
+      when :integers; :ints
+      when :double; :float
+      when :doubles; :floats
       when Class
         case opts[:type].to_s # sigh... there must be a better way to do this
         when 'TrueClass', 'FalseClass'; :flag
         when 'String'; :string
         when 'Integer'; :int
         when 'Float'; :float
+        when 'IO'; :io
         else
           raise ArgumentError, "unsupported argument type '#{opts[:type].class.name}'"
         end
       when nil; nil
       else
         raise ArgumentError, "unsupported argument type '#{opts[:type]}'" unless TYPES.include?(opts[:type])
+        opts[:type]
       end
 
     type_from_default =
@@ -137,6 +124,7 @@ class Parser
       when Numeric; :float
       when TrueClass, FalseClass; :flag
       when String; :string
+      when IO; :io
       when Array
         if opts[:default].empty?
           raise ArgumentError, "multiple argument type cannot be deduced from an empty array for '#{opts[:default][0].class.name}'"
@@ -145,6 +133,7 @@ class Parser
         when Integer; :ints
         when Numeric; :floats
         when String; :strings
+        when IO; :ios
         else
           raise ArgumentError, "unsupported multiple argument type '#{opts[:default][0].class.name}'"
         end
@@ -206,11 +195,12 @@ class Parser
   end
 
   ## Sets the version string. If set, the user can request the version
-  ## on the commandline. Should be of the form "<program name>
+  ## on the commandline. Should probably be of the form "<program name>
   ## <version number>".
   def version s=nil; @version = s if s; @version end
 
-  ## Adds text to the help display.
+  ## Adds text to the help display. Can be interspersed with calls to
+  ## #opt to build a multi-section help page.
   def banner s; @order << [:text, s] end
   alias :text :banner
 
@@ -228,19 +218,23 @@ class Parser
     @constraints << [:conflicts, syms]
   end
 
-  ## Defines a set of words which cause parsing to terminate when encountered,
-  ## such that any options to the left of the word are parsed as usual, and
-  ## options to the right of the word are left intact.
+  ## Defines a set of words which cause parsing to terminate when
+  ## encountered, such that any options to the left of the word are
+  ## parsed as usual, and options to the right of the word are left
+  ## intact.
   ##
-  ## A typical use case would be for subcommand support, where these would be
-  ## set to the list of subcommands. A subsequent Trollop invocation would
-  ## then be used to parse subcommand options.
+  ## A typical use case would be for subcommand support, where these
+  ## would be set to the list of subcommands. A subsequent Trollop
+  ## invocation would then be used to parse subcommand options, after
+  ## shifting the subcommand off of ARGV.
   def stop_on *words
     @stop_words = [*words].flatten
   end
 
-  ## Similar to stop_on, but stops on any unknown word when encountered (unless
-  ## it is a parameter for an argument).
+  ## Similar to #stop_on, but stops on any unknown word when encountered
+  ## (unless it is a parameter for an argument). This is useful for
+  ## cases where you don't know the set of subcommands ahead of time,
+  ## i.e., without first parsing the global options.
   def stop_on_unknown
     @stop_on_unknown = true
   end
@@ -317,7 +311,8 @@ class Parser
     remains
   end
 
-  def parse cmdline #:nodoc:
+  ## Parses the commandline. Typically called by Trollop::options.
+  def parse cmdline=ARGV
     vals = {}
     required = {}
 
@@ -406,6 +401,8 @@ class Parser
         vals[sym] = params.map { |pg| pg.map { |p| parse_float_parameter p, arg } }
       when :string, :strings
         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 } }
       end
 
       if SINGLE_ARG_TYPES.include?(opts[:type])
@@ -433,6 +430,19 @@ class Parser
     param.to_f
   end
 
+  def parse_io_parameter param, arg #:nodoc:
+    case param
+    when /^(stdin|-)$/i; $stdin
+    else
+      require 'open-uri'
+      begin
+        open param
+      rescue SystemCallError => e
+        raise CommandlineError, "file or url for option '#{arg}' cannot be opened: #{e.message}"
+      end
+    end
+  end
+
   def collect_argument_parameters args, start_at #:nodoc:
     params = []
     pos = start_at
@@ -446,21 +456,22 @@ class Parser
   def width #:nodoc:
     @width ||= 
       if $stdout.tty?
-        begin
-          require 'curses'
-          Curses::init_screen
-          x = Curses::cols
-          Curses::close_screen
-          x
-        rescue Exception
-          80
+        if `stty size` =~ /^(\d+) (\d+)$/
+          $2.to_i
+        else
+          begin
+            require 'curses'
+            Curses::init_screen
+            x = Curses::cols
+            Curses::close_screen
+            x
+          rescue Exception
+          end
         end
-      else
-        80
-      end
+      end || 80
   end
 
-  ## Print the help message to 'stream'.
+  ## Print the help message to +stream+.
   def educate stream=$stdout
     width # just calculate it now; otherwise we have to be careful not to
           # call this unless the cursor's at the beginning of a line.
@@ -477,6 +488,8 @@ class Parser
         when :strings; " <s+>"
         when :float; " <f>"
         when :floats; " <f+>"
+        when :io; " <filename/uri>"
+        when :ios; " <filename/uri+>"
         end
     end
 
@@ -552,15 +565,15 @@ end
 
 ## The top-level entry method into Trollop. Creates a Parser object,
 ## passes the block to it, then parses +args+ with it, handling any
-## errors or requests for help or version information appropriately
-## (and then exiting). Modifies +args+ in place. Returns a hash of
-## option values.
+## errors or requests for help or version information appropriately (and
+## then exiting). Modifies +args+ in place. Returns a hash of option
+## values.
 ##
-## The block passed in should contain one or more calls to #opt
-## (Parser#opt), one or more calls to text (Parser#text), and
-## probably a call to version (Parser#version).
+## The block passed in should contain zero or more calls to +opt+
+## (Parser#opt), zero or more calls to +text+ (Parser#text), and
+## probably a call to +version+ (Parser#version).
 ##
-## See the synopsis in README.txt for examples.
+## See the examples at http://trollop.rubyforge.org.
 def options args = ARGV, *a, &b
   @p = Parser.new(*a, &b)
   begin
@@ -612,3 +625,4 @@ end
 module_function :options, :die
 
 end # module
+

data/test/test_trollop.rb

@@ -870,6 +870,28 @@ EOM
       assert_equal true, opts[physicist]
     end
   end
+
+  def test_io_arg_type
+    @p.opt :arg, "desc", :type => :io
+    @p.opt :arg2, "desc", :type => IO
+    @p.opt :arg3, "desc", :default => $stdout
+
+    opts = nil
+    assert_nothing_raised { opts = @p.parse() }
+    assert_equal $stdout, opts[:arg3]
+
+    assert_nothing_raised { opts = @p.parse %w(--arg /dev/null) }
+    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]
+
+    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
 end
 
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: trollop
 version: !ruby/object:Gem::Version 
-  version: "1.9"
+  version: "1.10"
 platform: ruby
 authors: 
 - William Morgan
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-08-20 00:00:00 -07:00
+date: 2008-10-21 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -20,9 +20,9 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 1.7.0
+        version: 1.8.0
     version: 
-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.  #################### ###### simple ###### ####################  require 'trollop' opts = Trollop::options do opt :monkey, \"Use monkey mode\" opt :goat, \"Use goat mode\", :default => true opt :num_limbs, \"Set number of limbs\", :default => 4 end  p opts # { :monkey => false, :goat => true, :num_limbs => 4 }  #################### ###### medium ###### ####################  require 'trollop' opts = Trollop::options do version \"test 1.2.3 (c) 2007 William Morgan\" banner <<-EOS Test is an awesome program that does something very, very important.  Usage: test [options] <filenames>+ where [options] are: EOS  opt :ignore, \"Ignore incorrect values\" opt :file, \"Extra data filename to read in, with a very long option description like this one\", :type => String opt :volume, \"Volume level\", :default => 3.0 opt :iters, \"Number of iterations\", :default => 5 end Trollop::die :volume, \"must be non-negative\" if opts[:volume] < 0 Trollop::die :file, \"must exist\" unless File.exist?(opts[:file]) if opts[:file] ################################ ##### sub-command support ###### ################################  require 'trollop' global_opts = Trollop::options do opt :global_option, \"This is a global option\" stop_on %w(sub-command-1 sub-command-2) end  cmd = ARGV.shift cmd_opts = Trollop::options do opt :cmd_option, \"This is an option only for the subcommand\" end  p global_opts p cmd p cmd_opts"
+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: []