slop 2.4.4 → 3.0.0.rc1

data/lib/slop/commands.rb

@@ -0,0 +1,154 @@
+class Slop
+  class Commands
+    include Enumerable
+
+    attr_reader :config, :commands
+    attr_writer :banner
+
+    # Create a new instance of Slop::Commands and optionally build
+    # Slop instances via a block. Any configuration options used in
+    # this method will be the default configuration options sent to
+    # each Slop object created.
+    #
+    # config - An optional configuration Hash.
+    # block  - Optional block used to define commands.
+    def initialize(config = {}, &block)
+      @config = config
+      @commands = {}
+      @banner = nil
+
+      if block_given?
+        block.arity == 1 ? yield(self) : instance_eval(&block)
+      end
+    end
+
+    # Optionally set the banner for this command help output.
+    #
+    # banner - The String text to set the banner.
+    #
+    # Returns the String banner if one is set.
+    def banner(banner = nil)
+      @banner = banner if banner
+      @banner
+    end
+
+    # Add a Slop instance for a specific command.
+    #
+    # command - A String or Symbol key used to identify this command.
+    # config  - A Hash of configuration options to pass to Slop.
+    # block   - An optional block used to pass options to Slop.
+    #
+    # Returns the newly created Slop instance mapped to command.
+    def on(command, config = {}, &block)
+      commands[command] = Slop.new(@config.merge(config), &block)
+    end
+
+    # Add a Slop instance used when no other commands exist.
+    #
+    # config - A Hash of configuration options to pass to Slop.
+    # block  - An optional block used to pass options to Slop.
+    #
+    # Returns the newly created Slop instance mapped to default.
+    def default(config = {}, &block)
+      commands['default'] = Slop.new(@config.merge(config), &block)
+    end
+
+    # Add a global Slop instance.
+    #
+    # config - A Hash of configuration options to pass to Slop.
+    # block  - An optional block used to pass options to Slop.
+    #
+    # Returns the newly created Slop instance mapped to global.
+    def global(config = {}, &block)
+      commands['global'] = Slop.new(@config.merge(config), &block)
+    end
+
+    # Fetch the instance of Slop tied to a command.
+    #
+    # key - The String or Symbol key used to locate this command.
+    #
+    # Returns the Slop instance if this key is found, nil otherwise.
+    def [](key)
+      commands[key.to_s]
+    end
+    alias get []
+
+    # Parse a list of items.
+    #
+    # items - The Array of items to parse.
+    #
+    # Returns the original Array of items.
+    def parse(items = ARGV)
+      parse_items(items)
+    end
+
+    # Enumerable interface.
+    def each(&block)
+      @commands.each(&block)
+    end
+
+    # Parse a list of items, removing any options or option arguments found.
+    #
+    # items - The Array of items to parse.
+    #
+    # Returns the original Array of items with options removed.
+    def parse!(items = ARGV)
+      parse_items(items, true)
+    end
+
+    # Returns a nested Hash with Slop options and values. See Slop#to_hash.
+    def to_hash
+      Hash[commands.map { |k, v| [k.to_sym, v.to_hash] }]
+    end
+
+    # Returns the help String.
+    def to_s
+      defaults = commands.delete('default')
+      globals = commands.delete('global')
+      helps = commands.reject { |_, v| v.options.none? }
+      helps.merge!('Global options' => globals.to_s) if globals
+      helps.merge!('Other options' => defaults.to_s) if defaults
+      banner = @banner ? "#{@banner}\n" : ""
+      banner + helps.map { |key, opts| "  #{key}\n#{opts}" }.join("\n\n")
+    end
+    alias help to_s
+
+    # Returns the inspection String.
+    def inspect
+      "#<Slop::Commands #{config.inspect} #{commands.values.map(&:inspect)}>"
+    end
+
+    private
+
+    # Parse a list of items.
+    #
+    # items - The Array of items to parse.
+    # bang  - When true, #parse! will be called instead of #parse.
+    #
+    # Returns the Array of items (with options removed if bang == true).
+    def parse_items(items, bang = false)
+      if opts = commands[items[0].to_s]
+        items.shift
+        bang ? opts.parse!(items) : opts.parse(items)
+        execute_global_opts(items, bang)
+      else
+        if opts = commands['default']
+          bang ? opts.parse!(items) : opts.parse(items)
+        else
+          if config[:strict] && items[0]
+            raise InvalidCommandError, "Unknown command `#{items[0]}`"
+          end
+        end
+        execute_global_opts(items, bang)
+      end
+      items
+    end
+
+    def execute_global_opts(items, bang)
+      if global_opts = commands['global']
+        bang ? global_opts.parse!(items) : global_opts.parse(items)
+      end
+    end
+
+  end
+end

data/lib/slop/option.rb

@@ -0,0 +1,149 @@
+class Slop
+  class Option
+
+    # The default Hash of configuration options this class uses.
+    DEFAULT_OPTIONS = {
+      :argument => false,
+      :optional_argument => false,
+      :tail => false,
+      :default => nil,
+      :callback => nil,
+      :delimiter => ',',
+      :limit => 0,
+      :match => nil,
+      :optional => true,
+      :required => false,
+      :as => String,
+      :autocreated => false
+    }
+
+    attr_reader :short, :long, :description, :config, :types
+    attr_accessor :count
+    attr_writer :value
+
+    # Incapsulate internal option information, mainly used to store
+    # option specific configuration data, most of the meat of this
+    # class is found in the #value method.
+    #
+    # slop        - The instance of Slop tied to this Option.
+    # short       - The String or Symbol short flag.
+    # long        - The String or Symbol long flag.
+    # description - The String description text.
+    # config      - A Hash of configuration options.
+    # block       - An optional block used as a callback.
+    def initialize(slop, short, long, description, config = {}, &block)
+      @slop = slop
+      @short = short
+      @long = long
+      @description = description
+      @config = DEFAULT_OPTIONS.merge(config)
+      @count = 0
+      @callback = block_given? ? block : config[:callback]
+      @value = nil
+
+      @types = {
+        :string  => proc { |v| v.to_s },
+        :symbol  => proc { |v| v.to_sym },
+        :integer => proc { |v| v.to_s.to_i },
+        :float   => proc { |v| v.to_f },
+        :array   => proc { |v| v.split(@config[:delimiter], @config[:limit]) },
+        :range   => proc { |v| value_to_range(v) }
+      }
+
+      if long && long.size > @slop.config[:longest_flag]
+        @slop.config[:longest_flag] = long.size
+      end
+
+      @config.each_key do |key|
+        self.class.send(:define_method, "#{key}?") { !!@config[key] }
+      end
+    end
+
+    # Returns true if this option expects an argument.
+    def expects_argument?
+      config[:argument] && config[:argument] != :optional
+    end
+
+    # Returns true if this option accepts an optional argument.
+    def accepts_optional_argument?
+      config[:optional_argument] || config[:argument] == :optional
+    end
+
+    # Returns the String flag of this option. Preferring the long flag.
+    def key
+      long || short
+    end
+
+    # Call this options callback if one exists, and it responds to call().
+    #
+    # Returns nothing.
+    def call(*objects)
+      @callback.call(*objects) if @callback.respond_to?(:call)
+    end
+
+    # Fetch the argument value for this option.
+    #
+    # Returns the Object once any type conversions have taken place.
+    def value
+      value = @value || config[:default]
+      return if value.nil?
+
+      type = config[:as]
+      if type.respond_to?(:call)
+        type.call(value)
+      else
+        if callable = types[type.to_s.downcase.to_sym]
+          callable.call(value)
+        else
+          value
+        end
+      end
+    end
+
+    # Returns the help String for this option.
+    def to_s
+      return config[:help] if config[:help].respond_to?(:to_str)
+
+      out = "    "
+      out += short ? "-#{short}, " : ' ' * 4
+
+      if long
+        out += "--#{long}"
+        size = long.size
+        diff = @slop.config[:longest_flag] - size
+        out += " " * (diff + 6)
+      else
+        out += " " * (@slop.config[:longest_flag] + 8)
+      end
+
+      "#{out}#{description}"
+    end
+    alias help to_s
+
+    # Returns the String inspection text.
+    def inspect
+      "#<Slop::Option [-#{short} | --#{long}" +
+      "#{'=' if expects_argument?}#{'=?' if accepts_optional_argument?}]" +
+      " (#{description}) #{config.inspect}"
+    end
+
+    private
+
+    # Convert an object to a Range if possible. If this method is passed
+    # what does *not* look like a Range, but looks like an Integer of some
+    # sort, it will call #to_i on the Object and return the Integer
+    # representation.
+    #
+    # value - The Object we want to convert to a range.
+    #
+    # Returns the Range value if one could be found, else the original object.
+    def value_to_range(value)
+      if value.to_s =~ /\A(?:\-?\d+|(-?\d+?)(\.\.\.?|-|,)(-?\d+))\z/
+        $1 ? Range.new($1.to_i, $3.to_i, $2 == '...') : value.to_i
+      else
+        value
+      end
+    end
+
+  end
+end

data/slop.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = 'slop'
-  s.version = '2.4.4'
+  s.version = '3.0.0.rc1'
   s.summary = 'Option gathering made easy'
   s.description = 'A simple DSL for gathering options and parsing the command line'
   s.author = 'Lee Jarvis'

data/test/commands_test.rb

@@ -1,151 +1,90 @@
 require 'helper'
 
 class CommandsTest < TestCase
-  test 'creating commands' do
-    slop = Slop.new do
-      command :foo do on :f, :foo, 'foo option' end
-      command :bar do on :f, :foo; on :b, :bar, true end
-    end
-
-    slop.commands.each_value do |command|
-      assert_kind_of Slop, command
-    end
 
-    assert 'foo option', slop.commands[:foo].options[:foo].description
+  def setup
+    @commands = Slop::Commands.new do
+      on 'new' do
+        on '--force', 'Force creation'
+        on '--outdir=', 'Output directory'
+      end
 
-    slop.parse %w/bar --bar baz/
-    assert 'baz', slop.commands[:bar][:bar]
-    assert_nil slop.commands['bar']
+      on 'version' do
+        add_callback(:empty) { 'version 1' }
+      end
+    end
   end
 
-  test 'repeating existing commands' do
-    slop = Slop.new
-    assert slop.command :foo
-    assert_raises(ArgumentError) { slop.command :foo }
+  test "it nests instances of Slop" do
+    assert_empty Slop::Commands.new.commands
+    @commands.commands.each_value { |k| assert_kind_of Slop, k }
   end
 
-  test 'commands inheriting options' do
-    slop = Slop.new :strict do
-      command :foo do end
-    end
-    assert slop.commands[:foo].instance_variable_get(:@strict)
+  test "accessing Slop instances via get/[]" do
+    assert_kind_of Slop, @commands['new']
+    assert_kind_of Slop, @commands[:new]
+    assert_nil @commands[:unknown]
+    assert_equal 'Force creation', @commands[:new].fetch_option(:force).description
   end
 
-  test 'commands setting options' do
-    slop = Slop.new :strict => false do
-      command :foo, :strict => true do end
-    end
-    assert slop.commands[:foo].instance_variable_get(:@strict)
+  test "to_hash" do
+    assert_equal({
+      :new => { :force => nil, :outdir => nil },
+      :version => {}
+    }, @commands.to_hash)
   end
 
-  test 'inception' do
-    slop = Slop.new do
-      command(:foo) { command(:bar) { command(:baz) { on :f, 'D:' } } }
-    end
-    desc = slop.commands[:foo].commands[:bar].commands[:baz].options[:f].description
-    assert_equal 'D:', desc
+  test "raising on unknown commands with :strict => true" do
+    cmds = Slop::Commands.new(:strict => true)
+    assert_raises(Slop::InvalidCommandError) { cmds.parse %w( abc ) }
   end
 
-  test 'commands with banners' do
-    slop = Slop.new do
-      command(:foo, :banner => 'bar') { }
-      command(:bar) { banner 'bar' }
-    end
-    assert_equal 'bar', slop.commands[:foo].banner
-    assert_equal 'bar', slop.commands[:bar].banner
+  test "adding global options" do
+    cmds = Slop::Commands.new { global { on '--verbose' } }
+    cmds.parse %w( --verbose )
+    assert cmds[:global].verbose?
   end
 
-  test 'executing on_empty on separate commands' do
-    incmd = inslop = false
-    slop = Slop.new do
-      command(:foo) { on(:bar) {}; on_empty { incmd = true }}
-      on_empty { inslop = true }
-    end
-    slop.parse %w//
-    assert inslop
-    refute incmd
-    inslop = false
-    slop.parse %w/foo/
-    assert incmd
-    refute inslop
+  test "global options are always executed" do
+    @commands.global { on 'foo=' }
+    @commands.parse %w( new --force --foo bar )
+    assert_equal 'bar', @commands[:global][:foo]
   end
 
-  test 'executing blocks' do
-    foo = bar = nil
-    slop = Slop.new
-    slop.command :foo do
-      on :v, :verbose
-      execute { |o, a| foo = o.verbose? }
-    end
-    slop.command :bar do
-      on :v, :verbose
-      execute { |o, a| bar = o.verbose? }
-    end
-    slop.parse %w[ foo --verbose ]
-
-    assert foo
-    refute bar
+  test "default options are only executed when there's nothing else" do
+    @commands.default { on 'foo=' }
+    @commands.parse %w( new --force --foo bar )
+    assert_nil @commands[:default][:foo]
   end
 
-  test 'executing blocks and command arguments' do
-    opts = args = nil
-    slop = Slop.new
-    slop.command :foo do
-      execute do |o, a|
-        opts = o
-        args = a
-      end
-    end
-    slop.parse %w[ foo bar baz ]
-
-    assert_equal %w[ bar baz ], args
-    assert_kind_of Slop, opts
+  test "adding default options" do
+    cmds = Slop::Commands.new { default { on '--verbose' } }
+    cmds.parse %w( --verbose )
+    assert cmds[:default].verbose?
   end
 
-  test 'executing nested commands' do
-    args = nil
-    slop = Slop.new
-    slop.command :foo do
-      command :bar do
-        execute { |o, a| args = a }
-      end
-    end
-    slop.parse %w[ foo bar baz ]
-
-    assert_equal %w[ baz ], args
+  test "on/global and default all return newly created slop instances" do
+    assert_kind_of Slop, @commands.on('foo')
+    assert_kind_of Slop, @commands.default
+    assert_kind_of Slop, @commands.global
   end
 
-  test 'aliases' do
-    slop = Slop.new
-    slop.command :foo, :alias => :bar
-    slop.command :baz, :aliases => [:lorem, :ipsum]
+  test "parse does nothing when there's nothing to parse" do
+    assert @commands.parse []
+  end
 
-    assert_equal [:bar], slop.commands[:foo].aliases
-    assert_equal [:lorem, :ipsum], slop.commands[:baz].aliases
+  test "parse returns the original array of items" do
+    items = %w( foo bar baz )
+    assert_equal items, @commands.parse(items)
 
-    assert_raises(ArgumentError) { slop.command :lorem }
+    items = %w( new --force )
+    assert_equal items, @commands.parse(items)
   end
 
-  test 'command completion' do
-    foo = bar = bara = nil
-    slop = Slop.new
-    slop.command(:foo) { execute { foo = true } }
-    slop.parse %w[ fo ]
-    assert foo
-
-    slop.command(:bar) { execute { bar = true } }
-    slop.command(:bara) { execute { bara = true } }
-    slop.parse %w[ bar ]
-    assert bar
-    refute bara
+  test "parse! removes options/arguments" do
+    items = %w( new --outdir foo )
+    @commands.parse!(items)
+    assert_equal [], items
   end
 
-  test 'ambiguous command completion' do
-    io = StringIO.new
-    slop = Slop.new(:io => io)
-    slop.command :bar
-    slop.command :baz
-    slop.parse %w[ ba ]
-    assert_equal "Command 'ba' is ambiguous:\n  bar, baz\n", io.string
-  end
 end