tty-option 0.0.0 → 0.1.0

data/lib/tty/option.rb

@@ -1,9 +1,68 @@
 # frozen_string_literal: true
 
-require "tty/option/version"
+require_relative "option/conversions"
+require_relative "option/dsl"
+require_relative "option/errors"
+require_relative "option/parser"
+require_relative "option/formatter"
+require_relative "option/version"
 
 module TTY
   module Option
-    class Error < StandardError; end
-  end
-end
+    # Enhance object with command line option parsing
+    #
+    # @api public
+    def self.included(base)
+      base.module_eval do
+        include Interface
+        extend DSL
+        extend Inheritance
+      end
+    end
+
+    module Inheritance
+      # When class is inherited copy over parameter definitions
+      # This allows for definition of global parameters without
+      # affecting child class parameters and vice versa.
+      def inherited(subclass)
+        subclass.instance_variable_set(:@parameters, @parameters.dup)
+        super
+      end
+    end
+
+    module Interface
+      # The parsed parameters
+      #
+      # @api public
+      def params
+        @__params ||= Params.create
+      end
+
+      # Parse command line arguments
+      #
+      # @param [Array<String>] argv
+      #   the command line arguments
+      # @param [Hash] env
+      #   the hash of environment variables
+      #
+      # @api public
+      def parse(argv = ARGV, env = ENV, check_invalid_params: true,
+                raise_on_parse_error: false)
+        parser = Parser.new(self.class.parameters,
+                            check_invalid_params: check_invalid_params,
+                            raise_on_parse_error: raise_on_parse_error)
+        @__params = Params.create(*parser.parse(argv, env))
+        self
+      end
+
+      # Provide a formatted help usage for the configured parameters
+      #
+      # @return [String]
+      #
+      # @api public
+      def help(**config, &block)
+        Formatter.help(self.class.parameters, self.class.usage, **config, &block)
+      end
+    end
+  end # Option
+end # TTY

data/lib/tty/option/aggregate_errors.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+require_relative "usage_wrapper"
+
+module TTY
+  module Option
+    class AggregateErrors
+      include Enumerable
+      include UsageWrapper
+      extend Forwardable
+
+      def_delegators :@errors, :size, :empty?, :any?, :clear
+
+      # Create an intance from the passed error objects
+      #
+      # @api public
+      def initialize(errors = [])
+        @errors = errors
+      end
+
+      # Add error
+      #
+      # @api public
+      def add(error)
+        @errors << error
+        error
+      end
+
+      # Enumerate each error
+      #
+      # @example
+      #   errors = AggregateErrors.new
+      #   errors.each do |error|
+      #     # instance of TTY::Option::Error
+      #   end
+      #
+      # @api public
+      def each(&block)
+        @errors.each(&block)
+      end
+
+      # All error messages
+      #
+      # @example
+      #   errors = AggregateErrors.new
+      #   errors.add TTY::OptionInvalidArgument.new("invalid argument")
+      #   errors.messages
+      #   # => ["invalid argument"]
+      #
+      # @api public
+      def messages
+        map(&:message)
+      end
+
+      # Format errors for display in terminal
+      #
+      # @example
+      #   errors = AggregateErrors.new
+      #   errors.add TTY::OptionInvalidArgument.new("invalid argument")
+      #   errors.summary
+      #   # =>
+      #   # Error: invalid argument
+      #
+      # @param [Integer] :width
+      # @param [Integer] :indent
+      #
+      # @return [String]
+      #
+      # @api public
+      def summary(width: 80, indent: 0)
+        return "" if count.zero?
+
+        output = []
+        space_indent = " " * indent
+        if messages.count == 1
+          message = messages.first
+          label = "Error: "
+          output << "#{space_indent}#{label}" \
+                    "#{wrap(message, indent: indent + label.length, width: width)}"
+        else
+          output << space_indent + "Errors:"
+          messages.each_with_index do |message, num|
+            entry = "  #{num + 1}) "
+            output << "#{space_indent}#{entry}" \
+                      "#{wrap(message.capitalize, indent: indent + entry.length,
+                                                  width: width)}"
+          end
+        end
+        output.join("\n")
+      end
+    end # AggregateErrors
+  end # Option
+end # TTY

data/lib/tty/option/conversions.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require_relative "converter"
+
+module TTY
+  module Option
+    module Conversions
+      extend Converter
+
+      TRUE_VALUES = /^(true|y(es)?|t|1)$/i.freeze
+      FALSE_VALUES = /^(false|n(o)?|f|0)$/i.freeze
+
+      # @api public
+      def self.raise_invalid_argument(conv_name, val)
+        raise ConversionError,
+              format("invalid value of %<value>s for %<conv>s conversion",
+                     value: val.inspect, conv: conv_name.inspect)
+      end
+
+      convert :bool, :boolean do |val|
+        case val.to_s
+        when TRUE_VALUES
+          true
+        when FALSE_VALUES
+          false
+        else
+          raise_invalid_argument(:bool, val)
+        end
+      end
+
+      convert :date do |val|
+        begin
+          require "date" unless defined?(::Date)
+          ::Date.parse(val)
+        rescue ArgumentError, TypeError
+          raise_invalid_argument(:date, val)
+        end
+      end
+
+      convert :float do |val|
+        begin
+          Float(val)
+        rescue ArgumentError, TypeError
+          raise_invalid_argument(:float, val)
+        end
+      end
+
+      convert :int, :integer do |val|
+        begin
+          Float(val).to_i
+        rescue ArgumentError, TypeError
+          raise_invalid_argument(:integer, val)
+        end
+      end
+
+      convert :pathname, :path do |val|
+        require "pathname"
+        ::Pathname.new(val.to_s)
+      end
+
+      convert :regexp do |val|
+        begin
+          Regexp.new(val.to_s)
+        rescue TypeError, RegexpError
+          raise_invalid_argument(:regexp, val)
+        end
+      end
+
+      convert :sym, :symbol do |val|
+        begin
+          String(val).to_sym
+        rescue ArgumentError
+          raise_invalid_argument(:symbol, val)
+        end
+      end
+
+      convert :uri do |val|
+        begin
+          require "uri"
+          ::URI.parse(val)
+        rescue ::URI::InvalidURIError
+          raise_invalid_argument(:uri, val)
+        end
+      end
+
+      convert :list, :array do |val|
+        (val.respond_to?(:to_a) ? val : val.split(/(?<!\\),/))
+          .map { |v| v.strip.gsub(/\\,/, ",") }
+          .reject(&:empty?)
+      end
+
+      convert :map, :hash do |val|
+        values = val.respond_to?(:to_a) ? val : val.split(/[& ]/)
+        values.each_with_object({}) do |pair, pairs|
+          key, value = pair.split(/[=:]/, 2)
+          if (current = pairs[key.to_sym])
+            pairs[key.to_sym] = Array(current) << value
+          else
+            pairs[key.to_sym] = value
+          end
+          pairs
+        end
+      end
+
+      conversions.keys.each do |type|
+        next if type =~ /list|array|map|hash/
+
+        [:"#{type}_list", :"#{type}_array", :"#{type}s"].each do |new_type|
+          convert new_type do |val|
+            conversions[:list].(val).map do |obj|
+              conversions[type].(obj)
+            end
+          end
+        end
+
+        [:"#{type}_map", :"#{type}_hash"].each do |new_type|
+          convert new_type do |val|
+            conversions[:map].(val).each_with_object({}) do |(k, v), h|
+              h[k] = conversions[type].(v)
+            end
+          end
+        end
+      end
+    end # Conversions
+  end # Option
+end # TTY

data/lib/tty/option/converter.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module TTY
+  module Option
+    module Converter
+      # Store conversions
+      #
+      # @api public
+      def conversions
+        @conversions ||= {}
+      end
+
+      # Check if conversion is available
+      #
+      # @param [String] name
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      def contain?(name)
+        conv_name = name.to_s.downcase.to_sym
+        conversions.key?(conv_name)
+      end
+
+      # Register a new conversion type
+      #
+      # @example
+      #   convert(:int) { |val| Float(val).to_i }
+      #
+      # @api public
+      def convert(*names, &block)
+        names.each do |name|
+          if contain?(name)
+            raise ConversionAlreadyDefined,
+                "conversion #{name.inspect} is already defined"
+          end
+          conversions[name] = block
+        end
+      end
+
+      # Retrieve a conversion type
+      #
+      # @param [String] name
+      #
+      # @return [Proc]
+      #
+      # @api public
+      def [](name)
+        conv_name = name.to_s.downcase.to_sym
+        conversions.fetch(conv_name) { raise_unsupported_error(conv_name) }
+      end
+      alias fetch []
+
+      # Raise an error for unknown conversion type
+      #
+      # @api public
+      def raise_unsupported_error(conv_name)
+        raise UnsupportedConversion,
+             "unsupported conversion type #{conv_name.inspect}"
+      end
+    end # Converter
+  end # Option
+end # TTY

data/lib/tty/option/deep_dup.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module TTY
+  module Option
+    module DeepDup
+      NONDUPLICATABLE = [
+        Symbol, TrueClass, FalseClass, NilClass, Numeric, Method
+      ].freeze
+
+      # Duplicate an object making a deep copy
+      #
+      # @param [Object] object
+      #
+      # @api public
+      def self.deep_dup(object)
+        case object
+        when String then object.dup
+        when *NONDUPLICATABLE then object
+        when Hash   then deep_dup_hash(object)
+        when Array  then deep_dup_array(object)
+        else object.dup
+        end
+      end
+
+      # A deep copy of hash
+      #
+      # @param [Hash] object
+      #
+      # @api private
+      def self.deep_dup_hash(object)
+        object.each_with_object({}) do |(key, val), new_hash|
+          new_hash[deep_dup(key)] = deep_dup(val)
+        end
+      end
+
+      # A deep copy of array
+      #
+      # @param [Array] object
+      #
+      # @api private
+      def self.deep_dup_array(object)
+        object.each_with_object([]) do |val, new_array|
+          new_array << deep_dup(val)
+        end
+      end
+    end # DeepDup
+  end # Option
+end # TTY

data/lib/tty/option/dsl.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+require_relative "dsl/arity"
+require_relative "dsl/conversion"
+require_relative "inflection"
+require_relative "parameter/argument"
+require_relative "parameter/environment"
+require_relative "parameter/keyword"
+require_relative "parameter/option"
+require_relative "parameters"
+require_relative "usage"
+
+module TTY
+  module Option
+    module DSL
+      include Arity
+      include Conversion
+      include Inflection
+      extend Forwardable
+
+      def_delegators :usage, :command, :banner, :desc, :program,
+                             :header, :footer, :example, :no_command
+
+      # Holds the usage information
+      #
+      # @api public
+      def usage(**properties, &block)
+        @usage ||= Usage.create(**properties, &block).tap do |usage|
+                    if usage.command.empty?
+                      usage.command(dasherize(demodulize(self.name)))
+                    end
+                  end
+      end
+
+      # Specify an argument
+      #
+      # @api public
+      def argument(name, **settings, &block)
+        parameters << Parameter::Argument.create(name.to_sym, **settings, &block)
+      end
+
+      # Specify environment variable
+      #
+      # @example
+      #   EDITOR=vim
+      #
+      # @api public
+      def environment(name, **settings, &block)
+        parameters << Parameter::Environment.create(name.to_sym, **settings, &block)
+      end
+      alias env environment
+
+      # Specify a keyword
+      #
+      # @example
+      #   foo=bar
+      #
+      # @api public
+      def keyword(name, **settings, &block)
+        parameters << Parameter::Keyword.create(name.to_sym, **settings, &block)
+      end
+
+      # A shortcut to specify flag option
+      #
+      # @example
+      #   --foo
+      #
+      # @api public
+      def flag(name, **settings, &block)
+        defaults = { default: false }
+        option(name, **defaults.merge(settings), &block)
+      end
+
+      # Specify an option
+      #
+      # @example
+      #   -f
+      #   --foo
+      #   --foo bar
+      #
+      # @api public
+      def option(name, **settings, &block)
+        parameters << Parameter::Option.create(name.to_sym, **settings, &block)
+      end
+      alias opt option
+
+      # Remove parameter from the parameters definitions list
+      #
+      # @api public
+      def ignore(*names)
+        parameters.delete(*names)
+      end
+      alias skip ignore
+
+      # Holds all parameters
+      #
+      # @api public
+      def parameters
+        @parameters ||= Parameters.new
+      end
+    end # DSL
+  end # Option
+end # TTY