config_parser 0.5.4 → 0.5.5

data/History.rdoc

@@ -1,3 +1,12 @@
+== 0.5.5 / 2011-07-18
+
+* [issue #3] added options to to_s to allow changes to the option/desc columns 
+  widths
+* [issue #4] made parser check for option_break such that breaks on non-option 
+  args is possible
+* [issue #5] single-character keys now default to a short rather than long 
+  option
+
 == 0.5.4 / 2011-07-11
 
 Misc cleanup to the README and project structure. Also:

data/README.rdoc

@@ -20,10 +20,10 @@ Define options and their default values using +add+:
   parser.add :switch, true           # true makes a --[no-]switch
   parser.add :flag, false            # false as a default makes a --flag
   parser.add :list, []               # an array makes a list-style option
-  
+
   parser.parse 'a b --flag --list x --list y,z c'
   # => ['a', 'b', 'c']
-  
+
   parser.config
   # => {
   #   :option => 'default',
@@ -64,19 +64,19 @@ to the option (although by default it does). As you may expect a block can be
 given to process values before they are set as configs.
 
   parser = ConfigParser.new
-  
+
   # use args to define the option
   parser.add(:x, nil, '-o', '--one')
-  
+
   # use an options hash to define the option
   parser.add(:y, nil, :short => 't', :long => 'two')
-  
+
   # use a block to process the values
   parser.add(:z, nil, :long => 'three') {|value| value.upcase }
-  
+
   parser.parse('a b --one uno --two dos --three tres c')
   # => ['a', 'b', 'c']
-  
+
   parser.config
   # => {:x => 'uno', :y => 'dos', :z => 'TRES'}
 
@@ -86,6 +86,16 @@ ConfigParser is available as a gem[http://rubygems.org/gems/config_parser].
 
   % gem install config_parser
 
+== Development
+
+To get started, checkout the code from GitHub[http://github.com/thinkerbot/config_parser] and run the tests:
+
+  git clone git://github.com/thinkerbot/config_parser.git
+  cd config_parser
+  rake test
+
+Please report any issues {here}[http://github.com/thinkerbot/config_parser/issues].
+
 == Info
 
 Developer:: {Simon Chiang}[http://github.com/thinkerbot]

data/lib/config_parser.rb

@@ -8,27 +8,27 @@ autoload(:Shellwords, 'shellwords')
 # additionally supports option declaration using an attributes hash.
 class ConfigParser
   include Utils
-  
+
   # Returns an array of the options registered with self, in the order in
   # which they were added.  Separators are also stored in the registry.
   attr_reader :registry
-  
+
   # A hash of (flag, Option) pairs mapping command line flags like '-s' or
   # '--long' to the Option that handles them.
   attr_reader :options
-  
+
   # The hash receiving parsed configs.
   attr_accessor :config
-  
+
   # The argument to stop processing options.
   attr_accessor :option_break
-  
+
   # Set to true to preserve the option break.
   attr_accessor :preserve_option_break
-  
+
   # Set to true to assign config defaults on parse.
   attr_accessor :assign_defaults
-  
+
   # Initializes a new ConfigParser and passes it to the block, if given.
   def initialize(config={}, opts={})
     opts = {
@@ -36,27 +36,27 @@ class ConfigParser
       :preserve_option_break => false,
       :assign_defaults => true
     }.merge(opts)
-    
+
     @registry = []
     @options = {}
     @config = config
     @option_break = opts[:option_break]
     @preserve_option_break = opts[:preserve_option_break]
     @assign_defaults = opts[:assign_defaults]
-    
+
     yield(self) if block_given?
   end
-  
+
   # Returns the config value for key.
   def [](key)
     config[key]
   end
-  
+
   # Sets the config value for key.
   def []=(key, value)
     config[key] = value
   end
-  
+
   # Adds a separator string to self, used in to_s.
   def separator(str)
     @registry << str
@@ -70,29 +70,29 @@ class ConfigParser
   # no error is raised.  Note that this may remove multiple options.
   def register(option, override=false)
     return nil if option.nil?
-    
+
     if override
       existing = option.flags.collect {|flag| @options.delete(flag) }
       @registry -= existing
     end
-    
+
     unless @registry.include?(option)
       @registry << option
     end
-    
+
     option.flags.each do |flag|
       current = @options[flag]
-      
+
       if current && current != option
         raise ArgumentError, "already mapped to a different option: #{flag}"
       end
-      
+
       @options[flag] = option
     end
-    
+
     option
   end
-  
+
   # Unregisters the option by removing it from the registry and options.
   # Returns option.
   def unregister(option)
@@ -100,16 +100,16 @@ class ConfigParser
     @options.delete_if {|key, value| option == value }
     option
   end
-  
+
   # Sorts options in the registry as specified by the block.  Groups of
   # options as delimited by separators are sorted independently.  If no block
   # is given, options are sorted by their long and short keys.
   def sort_opts!(&block)
     block ||= lambda {|option| (option.long || option.short).to_s.sub(/^-+/, '') }
-    
+
     splits = []
     current = []
-    
+
     options = self.options.values.uniq
     registry.each do |option|
       if options.include?(option)
@@ -120,14 +120,14 @@ class ConfigParser
         current = []
       end
     end
-    
+
     splits << current
     @registry = splits.collect {|split| split.kind_of?(Array) ? split.sort_by(&block) : split }
     @registry.flatten!
-    
+
     self
   end
-  
+
   # Constructs an Option using args and registers it with self. The args may
   # contain (in any order) a short switch, a long switch, and a description
   # string. A callback may be provided as a block to process values for the
@@ -183,12 +183,12 @@ class ConfigParser
   def on(*args, &block)
     register new_option(args, &block)
   end
-  
+
   # Same as on, but overrides options with overlapping flags.
   def on!(*args, &block)
     register new_option(args, &block), true
   end
-  
+
   # An alternate syntax for on, where the key and default attributes are set
   # by the first two args.  Like on, add can define option attributes using a
   # series of args or with a trailing hash.
@@ -204,7 +204,7 @@ class ConfigParser
     args << attrs
     on(*args, &block)
   end
-  
+
   # Removes options by key.  Any options with the specified key are removed.
   # Returns the removed options.
   def rm(key)
@@ -216,7 +216,7 @@ class ConfigParser
       end
     end.compact
   end
-  
+
   # Parses options from argv in a non-destructive manner. Parsing stops if an
   # argument matching option_break is reached. If preserve_option_break is
   # specified then the option break is preserved in the remaining arguments. 
@@ -228,90 +228,91 @@ class ConfigParser
     argv = argv.dup unless argv.kind_of?(String)
     parse!(argv, &block)
   end
-  
+
   # Same as parse, but removes parsed args from argv.
   def parse!(argv=ARGV)
     argv = Shellwords.shellwords(argv) if argv.kind_of?(String)
-    
+
     registry.each do |option|
       if assign_defaults && option.respond_to?(:assign_default)
         option.assign_default(config)
       end
     end
-    
+
     args = []
     while !argv.empty?
       arg = argv.shift
-  
-      # determine if the arg is an option
-      unless option?(arg)
-        args << arg
-        next
-      end
-      
+
       # add the remaining args and break
       # for the option break
       if option_break === arg
         argv.unshift(arg) if preserve_option_break
         break
       end
-      
+
+      # determine if the arg is an option
+      unless option?(arg)
+        args << arg
+        next
+      end
+
       flag, value = arg, nil
-      
+
       # try the flag directly
       unless option = @options[flag]
-        
+
         # then try --opt=value syntax
         flag, value = flag.split('=', 2)
-        
+
         # then try -ovalue syntax
         if value.nil? && flag[1] != ?-
           flag, value = flag[0, 2], flag[2, flag.length - 2]
         end
-        
+
         unless option = @options[flag]
           raise "unknown option: #{flag}"
         end
       end
-      
+
       option.parse(flag, value, argv, config)
     end
-    
+
     args.concat(argv)
     argv.replace(args)
-    
+
     block_given? ? yield(argv, config) : argv
   end
-  
+
   # Resets each option and clears the config (if specified).  Returns self.
   def reset(options={})
     options = {
       :clear => true
     }.merge(options)
-    
+
     registry.each do |option|
       if option.respond_to?(:reset)
         option.reset
       end
     end
-    
+
     config.clear if options[:clear]
     self
   end
-  
+
   # Converts the options and separators in self into a help string suitable
   # for display on the command line.
-  def to_s
+  def to_s(opts={})
     @registry.collect do |option|
-      option.to_s.rstrip
+      str = option.kind_of?(Flag) ? option.to_s(opts) : option.to_s
+      str.rstrip
     end.join("\n") + "\n"
   end
-  
+
   protected
-  
+
   def option_class(attrs) # :nodoc:
     type = attrs[:option_type] || guess_option_type(attrs)
-    
+
     case type
     when :option then Option
     when :flag   then Flag
@@ -321,16 +322,16 @@ class ConfigParser
     else raise "unknown option type: #{type}"
     end
   end
-  
+
   # helper to parse an option from an argv.  new_option is used
   # by on and on! to generate options
   def new_option(argv, &block) # :nodoc:
     attrs = argv.last.kind_of?(Hash) ? argv.pop : {}
     attrs = parse_attrs(argv).merge(attrs)
-    
+
     attrs[:hint] ||= guess_hint(attrs)
     attrs[:callback] = block if block
-    
+
     option_class(attrs).new(attrs)
   end
 end

data/lib/config_parser/flag.rb

@@ -1,59 +1,59 @@
 require 'config_parser/utils'
 
 class ConfigParser
-  
+
   # Represents a boolean flag-style option. Flag handles the parsing of
   # specific flags, and provides hooks for processing the various types of
   # options (Switch, Option, List).
   class Flag
     include Utils
-    
+
     # The config key.
     attr_reader :key
-    
+
     # The config nesting keys.
     attr_reader :nest_keys
-    
+
     # The default value.
     attr_reader :default
-    
+
     # The short flag mapping to self.
     attr_reader :short 
-    
+
     # The long flag mapping to self.
     attr_reader :long
-    
+
     # The description printed by to_s.
     attr_reader :desc
-    
+
     # A hint printed by to_s, after desc.
     attr_reader :hint
-    
+
     # A callback for processing values (must respond to call, or be nil).
     attr_reader :callback
-    
+
     # A tracking flag set to true when assign is called.  Useful when assign
     # works differently for the first assignment than later assignments.  See
     # reset.
     attr_reader :assigned
-    
+
     def initialize(attrs={})
       @key       = attrs[:key]
       @nest_keys = attrs[:nest_keys]
       @default   = attrs[:default]
-      @short     = shortify(attrs[:short])
+      @short     = shortify(attrs.has_key?(:short) ? attrs[:short] : default_short)
       @long      = longify(attrs.has_key?(:long) ? attrs[:long] : default_long)
       @desc      = attrs[:desc]
       @hint      = attrs[:hint]
       @callback  = attrs[:callback]
       reset
     end
-    
+
     # Returns an array of flags mapping to self (ie [long, short]).
     def flags
       [long, short].compact
     end
-    
+
     # Parse handles the parsing of flags, which happens in three steps:
     #
     # * determine the value (occurs in parse)
@@ -95,17 +95,17 @@ class ConfigParser
           raise "value specified for #{flag}: #{value.inspect}"
         end
       end
-      
+
       value = (default.nil? ? true : !default)
       assign(config, process(value))
     end
-    
+
     # Process the value by calling the callback, if specified, with the value
     # and returns the result.  Returns value if no callback is specified.
     def process(value)
       callback ? callback.call(value) : value
     end
-    
+
     # Assigns the default value into config and resets the assigned flag to
     # false, such that the next assign behaves as if self has not put a value
     # into config.  Returns config.
@@ -114,7 +114,7 @@ class ConfigParser
       reset
       config
     end
-    
+
     # Assign the value to the config hash, if key is set, and flips assigned
     # to true.  Returns config.
     def assign(config, value)
@@ -122,51 +122,58 @@ class ConfigParser
         nest_config = nest(config)
         nest_config[key] = value
       end
-      
+
       @assigned = true
       config
     end
-    
+
     # Returns the nested config hash for config, as specified by nest_keys.
     def nest(config)
       nest_keys.each do |key|
         config = (config[key] ||= {})
       end if nest_keys
-      
+
       config
     end
-    
+
     # Resets assigned to false.
     def reset
       @assigned = false
     end
-    
-    # Formats self as a help string for use on the command line.
-    def to_s
-      lines = wrap(desc_str, 43)
-      
+
+    # Formats self as a help string for use on the command line (deprecated
+    # for that use, see format instead).
+    def to_s(opts={})
+      width     = opts[:width] || 80
+      head_size = opts[:head_size] || (width * 0.45).to_i
+      desc_size = width - head_size - 1
+
+      format = "%-#{head_size}s %-#{desc_size}s"
+
+      lines  = wrap(desc_str, desc_size)
+
       header = header_str
-      header = header.length > 36 ? header.ljust(80) : (LINE_FORMAT % [header, lines.shift])
-      
+      header = header.length > head_size ? header.ljust(width) : (format % [header, lines.shift])
+
       if lines.empty?
         header
       else
-        lines.collect! {|line| LINE_FORMAT % [nil, line] }
+        lines.collect! {|line| format % [nil, line] }
         "#{header}\n#{lines.join("\n")}"
       end
     end
-    
+
     # Returns an inspect string.
     def inspect
       "#<#{self.class}:#{object_id} key=#{key.inspect} default=#{default.inspect} long=#{long.inspect} short=#{short.inspect}>"
     end
-    
+
     private
-    
+
     def header_str # :nodoc:
       "    #{short_str}#{long_str}"
     end
-    
+
     def short_str # :nodoc:
       case
       when short && long then "#{short}, "
@@ -174,11 +181,11 @@ class ConfigParser
       else '    '
       end
     end
-    
+
     def long_str # :nodoc:
       long
     end
-    
+
     def desc_str # :nodoc:
       case
       when hint.nil? && desc.nil?
@@ -189,9 +196,14 @@ class ConfigParser
         "#{desc} (#{hint})".strip
       end
     end
-    
+
     def default_long # :nodoc:
+      return nil if default_short
       nest_keys ? (nest_keys + [key]).join(':') : key
     end
+
+    def default_short # :nodoc:
+      key.to_s.length == 1 && nest_keys.nil? ? key : nil
+    end
   end
 end

data/lib/config_parser/list.rb

@@ -1,46 +1,46 @@
 require 'config_parser/option'
 
 class ConfigParser
-  
+
   # List represents a special type of Option where multiple values may be
   # assigned to the same key.
   class List < Option
-    
+
     # The delimiter on which to split single values into multiple values; use
     # nil to prevent splitting.
     attr_reader :delimiter
-    
+
     def initialize(attrs={})
       super
-      
+
       @delimiter = attrs.has_key?(:delimiter) ? attrs[:delimiter] : DELIMITER
       @default = split(@default)
     end
-    
+
     # Splits the value into multiple values, and then process as usual.
     def process(value)
       split(value).collect {|val| super(val) }
     end
-    
+
     # Assigns the values to config.  Multiple calls to assign will concatenate
     # (ie when assigned is true) new values onto the existing values.  As
     # usual, no values are assigned if key is not set.  Returns config.
     def assign(config, values)
       if key
         nest_config = nest(config)
-        
+
         unless assigned
           nest_config[key] = []
         end
-        
+
         array = (nest_config[key] ||= [])
         array.concat(values)
       end
-      
+
       @assigned = true
       config
     end
-    
+
     # Splits string values along the delimiter, if specified.  Returns array
     # values directly, and an empty array for nil.  All other values are
     # arrayified like [obj].
@@ -52,9 +52,9 @@ class ConfigParser
       else [obj]
       end
     end
-    
+
     private
-    
+
     def header_str # :nodoc:
       "    #{short_str}#{long_str} #{arg_name}..."
     end

data/lib/config_parser/option.rb

@@ -1,28 +1,28 @@
 require 'config_parser/switch'
 
 class ConfigParser
-  
+
   # An Option represents a Flag that takes a value.
   class Option < Flag
-    
+
     # The default argument name
     DEFAULT_ARGNAME = 'VALUE'
-    
+
     # Matches optional argnames
     OPTIONAL = /\A\[.*\]\z/
-    
+
     # The argument name printed by to_s.
     attr_reader :arg_name
-    
+
     # Set to true to make the argument optional.
     attr_reader :optional
-    
+
     def initialize(attrs={})
       super
       @arg_name = attrs[:arg_name] || (key ? key.to_s.upcase : DEFAULT_ARGNAME)
       @optional = (attrs.has_key?(:optional) ? attrs[:optional] : (arg_name =~ OPTIONAL ? true : false))
     end
-    
+
     # Parse the flag and value.  If no value is provided and a value is
     # required, then a value is shifted off of argv.  The value is then
     # processed and assigned into config.
@@ -36,12 +36,12 @@ class ConfigParser
           end
         end
       end
-      
+
       assign(config, process(value))
     end
-    
+
     private
-    
+
     def header_str # :nodoc:
       "    #{short_str}#{long_str} #{arg_name}"
     end

data/lib/config_parser/switch.rb

@@ -1,43 +1,43 @@
 require 'config_parser/flag'
 
 class ConfigParser
-  
+
   # Switch represents a special type of Option where both positive (--flag)
   # and negative (--no-flag) flags map to self.
   class Switch < Flag
-    
+
     # The negative mapping prefix, defaults to 'no'
     attr_reader :prefix
-    
+
     # The negative long flag, determined from long and prefix.
     attr_reader :negative_long
-    
+
     def initialize(attrs={})
       attrs[:default] = true unless attrs.has_key?(:default)
       super
-      
+
       raise ArgumentError, "no long specified" unless long
       @prefix = attrs[:prefix] || 'no'
       @negative_long = prefix_long(long, "#{prefix}-")
     end
-    
+
     # Returns an array of flags mapping to self (ie [long, negative_long, short]).
     def flags
       [long, negative_long, short].compact
     end
-    
+
     # Assigns default into config for positive flags and !default for negative
     # flags. The boolean value is then processed and assigned into config.
     # Raises an error if a value is provided (switches take none).
     def parse(flag, value=nil, argv=[], config={})
       raise "value specified for #{flag}: #{value.inspect}" if value
-      
+
       value = (flag == negative_long ? !default : default)
       assign(config, process(value))
     end
 
     private
-    
+
     def long_str # :nodoc:
       prefix_long(long, "[#{prefix}-]")
     end

data/lib/config_parser/utils.rb

@@ -1,24 +1,21 @@
 class ConfigParser
-  
+
   # A medly of methods used throughout the ConfigParser classes.
   module Utils
     module_function
-    
-    # A format string used by to_s
-    LINE_FORMAT = "%-36s %-43s"
-    
+
     # The default option break
     OPTION_BREAK = "--"
-    
+
     # Matches an option (long or short)
     OPTION = /\A-./
-    
+
     # Matches a long flag
     LONG_FLAG = /\A--.+\z/
 
     # Matches a short flag
     SHORT_FLAG = /\A-.\z/
-    
+
     # Matches a switch option (ex: '--[no-]opt', '--nest:[no-]opt'). After the
     # match:
     #   
@@ -27,17 +24,17 @@ class ConfigParser
     #   $3:: the long flag name ('opt')
     #
     SWITCH = /\A--(.*?)\[(.*?)-\](.+)\z/
-    
+
     # Matches a nest option (ex: '--nest:opt').  After the match:
     #
     #   $1:: the nesting prefix ('nest')
     #   $2:: the long option ('long')
     #
     NEST = /\A--(.*):(.+)\z/
-    
+
     # The default split character for multiple values
     DELIMITER = ','
-    
+
     # Turns the input into a short flag by prefixing '-' (as needed). Raises
     # an error if the input doesn't result in a short flag.   Nils are
     # returned directly.
@@ -47,14 +44,14 @@ class ConfigParser
     #
     def shortify(str)
       return nil if str.nil?
-  
+
       str = str.to_s
       str = "-#{str}" unless option?(str)
-      
+
       unless str =~ SHORT_FLAG
         raise ArgumentError, "invalid short flag: #{str}"
       end
-      
+
       str
     end
 
@@ -67,17 +64,17 @@ class ConfigParser
     #
     def longify(str)
       return nil if str.nil?
-  
+
       str = str.to_s
       str = "--#{str}" unless option?(str)
-      
+
       unless str =~ LONG_FLAG
         raise ArgumentError, "invalid long flag: #{str}"
       end
-      
+
       str
     end
-    
+
     # Adds a prefix onto the last nested segment of a long option.
     #
     #   prefix_long('--opt', 'no-')         # => '--no-opt'
@@ -89,25 +86,25 @@ class ConfigParser
       switch[-1] = "#{prefix}#{switch[-1]}"
       "--#{switch.join(':')}"
     end
-    
+
     # Returns true if the object is a string and matches OPTION.
     def option?(obj)
       obj.kind_of?(String) && obj =~ OPTION ? true : false
     end
-    
+
     # Shifts and returns the first argument off of argv if it is an argument
     # (rather than an option) or returns the default value.
     def next_arg(argv)
       option?(argv.at(0)) ? nil : argv.shift
     end
-    
+
     # A wrapping algorithm slightly modified from:
     # http://blog.macromates.com/2006/wrapping-text-with-regular-expressions/
     def wrap(line, cols=80, tabsize=2)
       line = line.gsub(/\t/, " " * tabsize) unless tabsize == nil
       line.gsub(/(.{1,#{cols}})( +|$\r?\n?)|(.{1,#{cols}})/, "\\1\\3\n").split(/\s*?\n/)
     end
-    
+
     # Parses the argv into an attributes hash for initializing an option.
     # Heuristics are used to infer what an argument implies.
     #  
@@ -129,7 +126,7 @@ class ConfigParser
     # arg_name with a switch) can be detected... others not so much.
     def parse_attrs(argv)
       attrs={}
-      
+
       argv.each do |arg|
         unless option?(arg)
           attrs[:desc] = arg
@@ -137,7 +134,7 @@ class ConfigParser
         end
 
         flag, arg_name = arg.split(/\s+/, 2)
-        
+
         if flag =~ NEST
           attrs[:nest_keys] = $1.split(':')
         end
@@ -150,7 +147,7 @@ class ConfigParser
         when SWITCH
           attrs[:long] = "--#{$1}#{$3}"
           attrs[:prefix] = $2
-          
+
           if arg_name
             raise ArgumentError, "arg_name specified for switch: #{arg_name}"
           end
@@ -165,10 +162,10 @@ class ConfigParser
           raise ArgumentError.new("invalid flag: #{arg.inspect}")
         end
       end
-      
+
       attrs
     end
-    
+
     # Guesses an option type based on the attrs.
     #
     #   if...            then...
@@ -190,12 +187,12 @@ class ConfigParser
         :flag
       end
     end
-    
+
     # Guesses :list if the arg_name has a comma, or nil.
     def guess_option_type_by_arg_name(arg_name)
       arg_name.to_s.include?(',') ? :list : nil
     end
-    
+
     # Guesses an option type based on a value.
     #
     #   if...            then...
@@ -213,10 +210,10 @@ class ConfigParser
       else :option
       end
     end
-    
+
     def guess_hint(attrs)
       default = attrs[:default]
-      
+
       case default
       when true, false, nil
         nil

data/lib/config_parser/version.rb

@@ -1,7 +1,7 @@
 class ConfigParser
   MAJOR = 0
   MINOR = 5
-  TINY  = 4
+  TINY  = 5
 
   VERSION = "#{MAJOR}.#{MINOR}.#{TINY}"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: config_parser
 version: !ruby/object:Gem::Version 
-  hash: 3
+  hash: 1
   prerelease: 
   segments: 
   - 0
   - 5
-  - 4
-  version: 0.5.4
+  - 5
+  version: 0.5.5
 platform: ruby
 authors: 
 - Simon Chiang
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-07-11 00:00:00 -06:00
+date: 2011-07-18 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency