command_mapper 0.1.0.pre1

data/lib/command_mapper/types/key_value.rb

@@ -0,0 +1,131 @@
+require 'command_mapper/types/type'
+require 'command_mapper/types/str'
+
+module CommandMapper
+  module Types
+    #
+    # Represents a key-value type.
+    #
+    class KeyValue < Type
+
+      # The separator String between the key and value.
+      #
+      # @return [String]
+      attr_reader :separator
+
+      # The key's type.
+      #
+      # @return [Type]
+      attr_reader :key
+
+      # The value's type.
+      #
+      # @return [Type]
+      attr_reader :value
+
+      #
+      # Initializes the key-value value type.
+      #
+      # @param [String] separator
+      #   The key-value separator.
+      #
+      # @param [Type, Hash] key
+      #   The key's value type.
+      #
+      # @param [Type, Hash] value
+      #   The value's value type.
+      #
+      # @param [Hash{Symbol => Object}]
+      #   Additional keyword arguments for {Type#initialize}.
+      #
+      def initialize(separator: '=', key: Str.new, value: Str.new)
+        @separator = separator
+
+        if key.nil?
+          raise(ArgumentError,"key: keyword cannot be nil")
+        end
+
+        if value.nil?
+          raise(ArgumentError,"value: keyword cannot be nil")
+        end
+
+        @key   = Types::Type(key)
+        @value = Types::Type(value)
+      end
+
+      #
+      # Valides the given value.
+      #
+      # @param [Object] value
+      #
+      # @return [true, (false, String)]
+      #
+      def validate(value)
+        case value
+        when Hash
+          if value.length < 1
+            return [false, "cannot be empty"]
+          end
+
+          if value.length > 1
+            return [false, "cannot contain multiple key:value pairs (#{value.inspect})"]
+          end
+
+          key, value = value.first
+        when Array
+          if value.length < 2
+            return [false, "must contain two elements (#{value.inspect})"]
+          end
+
+          if value.length > 2
+            return [false, "cannot contain more than two elements (#{value.inspect})"]
+          end
+
+          key, value = value
+        else
+          return [false, "must be a Hash or an Array (#{value.inspect})"]
+        end
+
+        valid, message = @key.validate(key)
+
+        unless valid
+          return [false, "key #{message}"]
+        end
+
+        valid, message = @value.validate(value)
+
+        unless valid
+          return [false, "value #{message}"]
+        end
+
+        return true
+      end
+
+      #
+      # Formats a value into a key-value pair.
+      #
+      # @param [Hash, Array, #to_s] value
+      #   The given value.
+      #
+      # @return [String]
+      #   The formatted key-value pair.
+      #
+      def format(value)
+        case value
+        when Hash, Array
+          case value
+          when Hash
+            key, value = value.first
+          when Array
+            key, value = value
+          end
+
+          "#{@key.format(key)}#{@separator}#{@value.format(value)}"
+        else
+          super(value)
+        end
+      end
+
+    end
+  end
+end

data/lib/command_mapper/types/key_value_list.rb

@@ -0,0 +1,45 @@
+require 'command_mapper/types/list'
+require 'command_mapper/types/key_value'
+
+module CommandMapper
+  module Types
+    #
+    # Represents a list of `key=value` pairs.
+    #
+    class KeyValueList < List
+
+      #
+      # Initializes the key-value list.
+      #
+      # @param [String] separator
+      #   The list separator character (ex: `,`).
+      #
+      # @param [String] key_value_separator
+      #   The key-value separator (ex: `=`).
+      #
+      # @param [Hash{Symbol => Object}] kwargs
+      #   Additional keyword arguments for {KeyValue#initialize}.
+      #
+      def initialize(separator: ',', key_value_separator: '=', **kwargs)
+        super(
+          type:      KeyValue.new(separator: key_value_separator, **kwargs),
+          separator: separator
+        )
+      end
+
+      #
+      # Formats the value.
+      #
+      # @param [Hash, Array((key, value))] value
+      #   The list of key-value pairs.
+      #
+      # @return [String]
+      #   The formatted key-value list.
+      #
+      def format(value)
+        super(Array(value).map(&@type.method(:format)))
+      end
+
+    end
+  end
+end

data/lib/command_mapper/types/list.rb

@@ -0,0 +1,90 @@
+require 'command_mapper/types/type'
+require 'command_mapper/types/str'
+
+module CommandMapper
+  module Types
+    #
+    # Represents a list type.
+    #
+    class List < Type
+
+      # The seperator character.
+      #
+      # @return [String]
+      attr_reader :separator
+
+      # The list element type.
+      #
+      # @return [Type]
+      attr_reader :type
+
+      #
+      # Initializes the list type.
+      #
+      # @param [String] separator
+      #   The list separator character.
+      #
+      # @param [Type, Hash] value
+      #   The list's value type.
+      #
+      def initialize(separator: ',', type: Str.new, allow_empty: false)
+        if type.nil?
+          raise(ArgumentError,"type: keyword cannot be nil")
+        end
+
+        @separator = separator
+        @type      = Types::Type(type)
+
+        @allow_empty = allow_empty
+      end
+
+      #
+      # Specifies whether the option's value may accept empty values.
+      #
+      # @return [Boolean]
+      #
+      def allow_empty?
+        @allow_empty
+      end
+
+      #
+      # Validates the value.
+      #
+      # @param [Object] value
+      #
+      # @return [true, (false, String)]
+      #
+      def validate(value)
+        values = Array(value)
+
+        if values.empty?
+          unless allow_empty?
+            return [false, "cannot be empty"]
+          end
+        end
+
+        values.each do |element|
+          valid, message = @type.validate(element)
+
+          unless valid
+            return [false, "element #{message}"]
+          end
+        end
+
+        return true
+      end
+
+      #
+      # Formats the value into a list.
+      #
+      # @param [Object] value
+      #
+      # @return [String]
+      #
+      def format(value)
+        Array(value).map(&@type.method(:format)).join(@separator)
+      end
+
+    end
+  end
+end

data/lib/command_mapper/types/map.rb

@@ -0,0 +1,64 @@
+require 'command_mapper/types/type'
+
+module CommandMapper
+  module Types
+    class Map < Type
+
+      # @return [Hash{Object => String}]
+      attr_reader :map
+
+      #
+      # Initializes the map value type.
+      #
+      # @param [Hash{Object => String}] map
+      #   The map of values to Strings.
+      #
+      def initialize(map)
+        @map = map
+      end
+
+      #
+      # Creates a new map.
+      #
+      # @param [Hash{Object => String}] map
+      #   The map of values to Strings.
+      #
+      # @return [Map]
+      #
+      def self.[](map)
+        new(map)
+      end
+
+      # Maps boolean values to "yes" and "no"
+      YesNo = new(true => 'yes', false => 'no')
+
+      # Maps boolean values to "enabled" and "disabled"
+      EnabledDisabled = new(true => 'enabled', false => 'disabled')
+
+      #
+      # Validates a value.
+      #
+      # @param [Object] value
+      #
+      # @return [true, (false, String)]
+      #
+      def validate(value)
+        unless @map.has_key?(value)
+          return [false, "unknown value (#{value.inspect})"]
+        end
+
+        return true
+      end
+
+      #
+      # @param [Object] value
+      #
+      # @return [String]
+      #
+      def format(value)
+        super(@map.fetch(value))
+      end
+
+    end
+  end
+end

data/lib/command_mapper/types/num.rb

@@ -0,0 +1,50 @@
+require 'command_mapper/types/type'
+
+module CommandMapper
+  module Types
+    #
+    # Represents a numeric value.
+    #
+    class Num < Type
+
+      #
+      # Validates a value.
+      #
+      # @param [String, Integer] value
+      #
+      # @return [true, (false, String)]
+      #
+      def validate(value)
+        case value
+        when Integer
+          return true
+        when String
+          unless value =~ /\A\d+\z/
+            return [false, "contains non-numeric characters (#{value.inspect})"]
+          end
+        else
+          unless value.respond_to?(:to_i)
+            return [false, "cannot be converted into an Integer (#{value.inspect})"]
+          end
+        end
+
+        return true
+      end
+
+      #
+      # Formats a numeric value.
+      #
+      # @param [String, Integer, #to_i] value
+      #
+      # @return [String]
+      #
+      def format(value)
+        case value
+        when Integer, String then value.to_s
+        else                      value.to_i.to_s
+        end
+      end
+
+    end
+  end
+end

data/lib/command_mapper/types/str.rb

@@ -0,0 +1,85 @@
+require 'command_mapper/types/type'
+
+module CommandMapper
+  module Types
+    class Str < Type
+      #
+      # Initializes the value.
+      #
+      # @param [Boolean] allow_empty
+      #   Specifies whether the argument may accept empty values.
+      #
+      # @param [Boolean] allow_blank
+      #   Specifies whether the argument may accept blank values.
+      #
+      def initialize(allow_empty: false, allow_blank: false)
+        @allow_empty = allow_empty
+        @allow_blank = allow_blank
+      end
+
+      #
+      # Specifies whether the option's value may accept empty values.
+      #
+      # @return [Boolean]
+      #
+      def allow_empty?
+        @allow_empty
+      end
+
+      #
+      # Specifies whether the option's value may accept blank values.
+      #
+      # @return [Boolean]
+      #
+      def allow_blank?
+        @allow_blank
+      end
+
+      #
+      # Validates the given value.
+      #
+      # @param [Object] value
+      #   The given value to validate.
+      #
+      # @return [true, (false, String)]
+      #   Returns true if the valid is considered valid, or false and a
+      #   validation message if the value is not valid.
+      #   * If `nil` is given and a value is required, then `false` will be
+      #     returned.
+      #   * If an empty value is given and empty values are not allowed, then
+      #     `false` will be returned.
+      #   * If an empty value is given and blank values are not allowed, then
+      #     `false` will be returned.
+      #
+      def validate(value)
+        case value
+        when nil
+          unless allow_empty?
+            return [false, "cannot be nil"]
+          end
+        when Enumerable
+          return [false, "cannot convert a #{value.class} into a String (#{value.inspect})"]
+        else
+          unless value.respond_to?(:to_s)
+            return [false, "does not define a #to_s method (#{value.inspect})"]
+          end
+
+          string = value.to_s
+
+          if string.empty?
+            unless allow_empty?
+              return [false, "does not allow an empty value"]
+            end
+          elsif string =~ /\A\s+\z/
+            unless allow_blank?
+              return [false, "does not allow a blank value (#{value.inspect})"]
+            end
+          end
+        end
+
+        return true
+      end
+
+    end
+  end
+end

data/lib/command_mapper/types/type.rb

@@ -0,0 +1,102 @@
+module CommandMapper
+  module Types
+    #
+    # The base type for all command-line argument types.
+    #
+    # ## Custom Types
+    #
+    # Custom types can be defined by extending the {Type} class.
+    # 
+    #     class PortRange < CommandMapper::Types::Type
+    #     
+    #       def validate(value)
+    #         case value
+    #         when Integer
+    #           true
+    #         when Range
+    #           if value.begin.kind_of?(Integer)
+    #             true
+    #           else
+    #             [false, "port range can only contain Integers"]
+    #           end
+    #         else
+    #           [false, "port range must be an Integer or a Range of Integers"]
+    #         end
+    #       end
+    #     
+    #       def format(value)
+    #         case value
+    #         when Integer
+    #           "#{value}"
+    #         when Range
+    #           "#{value.begin}-#{value.end}"
+    #         end
+    #       end
+    #     
+    #     end
+    #
+    #
+    # The custom type can define the following methods:
+    #
+    # * `#initialize` - accepts additional configuration options.
+    # * `#validate` - accepts a value object and returns `true` (indicating the
+    #   value is valid) or `[false, message]` (indicating the value is invalid).
+    # * `#format` - accepts a validated value and returns a formatted String.
+    #
+    # Once defined, custom {Type} classes can be used with `option` or
+    # `argument` and passed in via the `type:` keyword argument.
+    #
+    #     option "--ports", value: {required: true, type: PortRange.new}
+    #
+    #     argument :ports, required: true, type: PortRange.new
+    #
+    class Type
+
+      #
+      # The default `validate` method for all types.
+      #
+      # @param [Object]
+      #
+      # @return [true, (false, String)]
+      #
+      def validate(value)
+        true
+      end
+
+      #
+      # The default `format` method for all types.
+      #
+      # @param [#to_s] value
+      #
+      # @return [String]
+      #   The String version of the value.
+      #
+      def format(value)
+        value.to_s
+      end
+
+    end
+
+    require 'command_mapper/types/str'
+
+    #
+    # Converts a value into a {Type} object.
+    #
+    # @param [Type, Hash, nil] value
+    #
+    # @return [Type]
+    #
+    # @raise [ArgumentError]
+    #
+    def self.Type(value)
+      case value
+      when Type      then value
+      when Hash      then Str.new(**value)
+      when nil       then nil
+      else
+        raise(ArgumentError,"value must be a #{Type}, Hash, or nil: #{value.inspect}")
+      end
+    end
+
+  end
+end

data/lib/command_mapper/types.rb

@@ -0,0 +1,6 @@
+require 'command_mapper/types/type'
+require 'command_mapper/types/str'
+require 'command_mapper/types/map'
+require 'command_mapper/types/list'
+require 'command_mapper/types/key_value'
+require 'command_mapper/types/key_value_list'

data/lib/command_mapper/version.rb

@@ -0,0 +1,4 @@
+module CommandMapper
+  # Version of command_mapper
+  VERSION = '0.1.0.pre1'
+end

data/lib/command_mapper.rb

@@ -0,0 +1,2 @@
+require 'command_mapper/command'
+require 'command_mapper/version'