slop 3.6.0 → 4.0.0

data/lib/slop/error.rb

@@ -0,0 +1,20 @@
+module Slop
+  # Base error class.
+  class Error < StandardError
+  end
+
+  # Raised when calling `call` on Slop::Option (this
+  # method must be overriden in subclasses)
+  class NotImplementedError < Error
+  end
+
+  # Raised when an option that expects an argument is
+  # executed without one. Suppress with the `suppress_errors`
+  # config option.
+  class MissingArgument < Error
+  end
+
+  # Raised when an unknown option is parsed. Suppress
+  # with the `suppress_errors` config option.
+  class UnknownOption   < Error; end
+end

data/lib/slop/option.rb

@@ -1,214 +1,117 @@
-class Slop
+module 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
+    DEFAULT_CONFIG = {
+      help: true
     }
 
-    attr_reader :short, :long, :description, :config, :types
-    attr_accessor :count, :argument_in_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
+    # An Array of flags this option matches.
+    attr_reader :flags
 
-      @types = {
-        :string  => proc { |v| v.to_s },
-        :symbol  => proc { |v| v.to_sym },
-        :integer => proc { |v| value_to_integer(v) },
-        :float   => proc { |v| value_to_float(v) },
-        :range   => proc { |v| value_to_range(v) },
-        :regexp  => proc { |v| Regexp.new(v) },
-        :count   => proc { |v| @count }
-      }
-
-      if long && long.size > @slop.config[:longest_flag]
-        @slop.config[:longest_flag] = long.size
-      end
+    # A custom description used for the help text.
+    attr_reader :desc
 
-      @config.each_key do |key|
-        predicate = :"#{key}?"
-        unless self.class.method_defined? predicate
-          self.class.__send__(:define_method, predicate) { !!@config[key] }
-        end
-      end
-    end
+    # A Hash of configuration options.
+    attr_reader :config
 
-    # Returns true if this option expects an argument.
-    def expects_argument?
-      config[:argument] && config[:argument] != :optional
-    end
+    # An Integer count for the total times this option
+    # has been executed.
+    attr_reader :count
 
-    # Returns true if this option accepts an optional argument.
-    def accepts_optional_argument?
-      config[:optional_argument] || config[:argument] == :optional
-    end
+    # A custom proc that yields the option value when
+    # it's executed.
+    attr_reader :block
 
-    # Returns the String flag of this option. Preferring the long flag.
-    def key
-      long || short
-    end
+    # The end value for this option.
+    attr_writer :value
 
-    # 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)
+    def initialize(flags, desc, **config, &block)
+      @flags  = flags
+      @desc   = desc
+      @config = DEFAULT_CONFIG.merge(config)
+      @block  = block
+      reset
     end
 
-    # Set the new argument value for this option.
-    #
-    # We use this setter method to handle concatenating lists. That is,
-    # when an array type is specified and used more than once, values from
-    # both options will be grouped together and flattened into a single array.
-    def value=(new_value)
-      if config[:as].to_s.downcase == 'array'
-        @value ||= []
-
-        if new_value.respond_to?(:split)
-          @value.concat new_value.split(config[:delimiter], config[:limit])
-        end
-      else
-        @value = new_value
-      end
+    # Reset the option count and value. Used when calling .reset
+    # on the Parser.
+    def reset
+      @value = nil
+      @count = 0
     end
 
-    # Fetch the argument value for this option.
-    #
-    # Returns the Object once any type conversions have taken place.
-    def value
-      value = @value.nil? ? config[:default] : @value
+    # Since `call()` can be used/overriden in subclasses, this
+    # method is used to do general tasks like increment count. This
+    # ensures you don't *have* to call `super` when overriding `call()`.
+    # It's used in the Parser.
+    def ensure_call(value)
+      @count += 1
 
-      if [true, false, nil].include?(value) && config[:as].to_s != 'count'
-        return value
+      if value.nil? && expects_argument? && !suppress_errors?
+        raise Slop::MissingArgument, "missing argument for #{flag}"
       end
 
-      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
+      @value = call(value)
+      block.call(@value) if block.respond_to?(:call)
     end
 
-    # Returns the help String for this option.
-    def to_s
-      return config[:help] if config[:help].respond_to?(:to_str)
+    # This method is called immediately when an option is found.
+    # Override it in sub-classes.
+    def call(_value)
+      raise NotImplementedError,
+        "you must override the `call' method for option #{self.class}"
+    end
 
-      out = "    #{short ? "-#{short}, " : ' ' * 4}"
+    # By default this method does nothing. It's called when all options
+    # have been parsed and allows you to mutate the `@value` attribute
+    # according to other options.
+    def finish(_result)
+    end
 
-      if long
-        out << "--#{long}"
-        size = long.size
-        diff = @slop.config[:longest_flag] - size
-        out << (' ' * (diff + 6))
-      else
-        out << (' ' * (@slop.config[:longest_flag] + 8))
-      end
+    # Override this if this option type does not expect an argument
+    # (i.e a boolean option type).
+    def expects_argument?
+      true
+    end
 
-      if config[:default]
-        default = config[:default]
-        "#{out}#{description} (default: #{default})"
-      else
-        "#{out}#{description}"
-      end
+    # Override this if you want to ignore the return value for an option
+    # (i.e so Result#to_hash does not include it).
+    def null?
+      false
     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}"
+    # Returns the value for this option. Falls back to the default (or nil).
+    def value
+      @value || default_value
     end
 
-    private
-
-    # Convert an object to an Integer if possible.
-    #
-    # value - The Object we want to convert to an integer.
-    #
-    # Returns the Integer value if possible to convert, else a zero.
-    def value_to_integer(value)
-      if @slop.strict?
-        begin
-          Integer(value.to_s, 10)
-        rescue ArgumentError
-          raise InvalidArgumentError, "#{value} could not be coerced into Integer"
-        end
-      else
-        value.to_s.to_i
-      end
+    # Returns the default value for this option (default is nil).
+    def default_value
+      config[:default]
     end
 
-    # Convert an object to a Float if possible.
-    #
-    # value - The Object we want to convert to a float.
-    #
-    # Returns the Float value if possible to convert, else a zero.
-    def value_to_float(value)
-      if @slop.strict?
-        begin
-          Float(value.to_s)
-        rescue ArgumentError
-          raise InvalidArgumentError, "#{value} could not be coerced into Float"
-        end
-      else
-        value.to_s.to_f
-      end
+    # Returns true if we should ignore errors that cause exceptions to be raised.
+    def suppress_errors?
+      config[:suppress_errors]
     end
 
-    # Convert an object to a Range if possible.
-    #
-    # 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)
-      case value.to_s
-      when /\A(\-?\d+)\z/
-        Range.new($1.to_i, $1.to_i)
-      when /\A(-?\d+?)(\.\.\.?|-|,)(-?\d+)\z/
-        Range.new($1.to_i, $3.to_i, $2 == '...')
-      else
-        if @slop.strict?
-          raise InvalidArgumentError, "#{value} could not be coerced into Range"
-        else
-          value
-        end
-      end
+    # Returns all flags joined by a comma. Used by the help string.
+    def flag
+      flags.join(", ")
+    end
+
+    # Returns the last key as a symbol. Used in Options.to_hash.
+    def key
+      (config[:key] || flags.last.sub(/\A--?/, '')).to_sym
+    end
+
+    # Returns true if this option should be displayed in help text.
+    def help?
+      config[:help]
     end
 
+    # Returns the help text for this option (flags and description).
+    def to_s(offset: 0)
+      "%-#{offset}s  %s" % [flag, desc]
+    end
   end
 end

data/lib/slop/options.rb

@@ -0,0 +1,141 @@
+module Slop
+  class Options
+    include Enumerable
+
+    DEFAULT_CONFIG = {
+      suppress_errors: false,
+      type:            "null",
+      banner:          true,
+    }
+
+    # The Array of Option instances we've created.
+    attr_reader :options
+
+    # An Array of separators used for the help text.
+    attr_reader :separators
+
+    # Our Parser instance.
+    attr_reader :parser
+
+    # A Hash of configuration options.
+    attr_reader :config
+
+    # The String banner prefixed to the help string.
+    attr_accessor :banner
+
+    def initialize(**config)
+      @options    = []
+      @separators = []
+      @banner     = "usage: #{$0} [options]"
+      @config     = DEFAULT_CONFIG.merge(config)
+      @parser     = Parser.new(self, @config)
+
+      yield self if block_given?
+    end
+
+    # Add a new option. This method is an alias for adding a NullOption
+    # (i.e an option with an ignored return value).
+    #
+    # Example:
+    #
+    #   opts = Slop.parse do |o|
+    #     o.on '--version' do
+    #       puts Slop::VERSION
+    #     end
+    #   end
+    #
+    #   opts.to_hash #=> {}
+    #
+    # Returns the newly created Option subclass.
+    def on(*flags, **config, &block)
+      desc   = flags.pop unless flags.last.start_with?('-')
+      config = self.config.merge(config)
+      klass  = Slop.string_to_option_class(config[:type].to_s)
+      option = klass.new(flags, desc, config, &block)
+
+      add_option option
+    end
+
+    # Add a separator between options. Used when displaying
+    # the help text.
+    def separator(string)
+      if separators[options.size]
+        separators.last << "\n#{string}"
+      else
+        separators[options.size] = string
+      end
+    end
+
+    # Sugar to avoid `options.parser.parse(x)`.
+    def parse(strings)
+      parser.parse(strings)
+    end
+
+    # Implements the Enumerable interface.
+    def each(&block)
+      options.each(&block)
+    end
+
+    # Handle custom option types. Will fall back to raising an
+    # exception if an option is not defined.
+    def method_missing(name, *args, **config, &block)
+      if respond_to_missing?(name)
+        config[:type] = name
+        on(*args, config, &block)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      Slop.option_defined?(name) || super
+    end
+
+    # Return a copy of our options Array.
+    def to_a
+      options.dup
+    end
+
+    # Returns the help text for this options. Used by Result#to_s.
+    def to_s(prefix: " " * 4)
+      str = config[:banner] ? "#{banner}\n" : ""
+      len = longest_flag_length
+
+      options.select(&:help?).each_with_index do |opt, i|
+        # use the index to fetch an associated separator
+        if sep = separators[i]
+          str << "#{sep}\n"
+        end
+
+        str << "#{prefix}#{opt.to_s(offset: len)}\n"
+      end
+
+      str
+    end
+
+    private
+
+    def longest_flag_length
+      (o = longest_option) && o.flag.length || 0
+    end
+
+    def longest_option
+      options.max { |a, b| a.flag.length <=> b.flag.length }
+    end
+
+    def add_option(option)
+      options.each do |o|
+        flags = o.flags & option.flags
+
+        # Raise an error if we found an existing option with the same
+        # flags. I can't immediately see a use case for this..
+        if flags.any?
+          raise ArgumentError, "duplicate flags: #{flags}"
+        end
+      end
+
+      options << option
+      option
+    end
+  end
+end