ronin-core 0.1.0.beta1

data/lib/ronin/core/params/types/enum.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2021-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-core is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# ronin-core is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-core.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/core/params/types/type'
+
+module Ronin
+  module Core
+    module Params
+      module Types
+        #
+        # Represents a mapping of Ruby values to their String equivalents.
+        #
+        class Enum < Type
+
+          # The values of the enum.
+          #
+          # @return [Array<Object>]
+          #
+          # @api semipublic
+          attr_reader :values
+
+          #
+          # Initializes the enum type.
+          #
+          # @param [Array<Object>] values
+          #   The values of the enum type.
+          #
+          # @raise [ArgumentError]
+          #   Cannot initialize an enum type with an empty Array of values.
+          #
+          # @api semipublic
+          #
+          def initialize(values)
+            if values.empty?
+              raise(ArgumentError,"cannot initialize an empty Enum")
+            end
+
+            @values = values
+            @map    = Hash[values.map { |value| [value.to_s, value] }]
+          end
+
+          #
+          # Creates a new enum.
+          #
+          # @param [Array<Object>] values
+          #   List of enum values.
+          #
+          # @return [Enum]
+          #   The newly created enum object.
+          #
+          # @api public
+          #
+          def self.[](*values)
+            new(values)
+          end
+
+          #
+          # Coerces the value into one of the enum values.
+          #
+          # @param [::String, ::Symbol, Object] value
+          #
+          # @return [Symbol]
+          #   The coerced value.
+          #
+          # @raise [ValidationError]
+          #   The value was not a valid enum value or a String that maps to an
+          #   enum value.
+          #
+          # @api private
+          #
+          def coerce(value)
+            case value
+            when ::Symbol
+              unless @values.include?(value)
+                raise(ValidationError,"unknown value (#{value.inspect})")
+              end
+
+              value
+            when ::String
+              @map.fetch(value) do
+                raise(ValidationError,"unknown value (#{value.inspect})")
+              end
+            else
+              raise(ValidationError,"value must be either a Symbol or a String (#{value.inspect})")
+            end
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/core/params/types/float.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2021-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-core is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# ronin-core is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-core.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/core/params/types/numeric'
+
+module Ronin
+  module Core
+    module Params
+      module Types
+        #
+        # Represents a true/false param.
+        #
+        class Float < Numeric
+
+          #
+          # Coerces a value into a Float value.
+          #
+          # @param [::Float, ::String, #to_f, Object] value
+          #   The value to coerce.
+          #
+          # @return [::Float]
+          #   The coerced Float value.
+          #
+          # @raise [ValidationError]
+          #   The value was not a Float, a String, or was not within {#range},
+          #   or below {#min}, or above {#max}.
+          #
+          # @api private
+          #
+          def coerce(value)
+            case value
+            when ::Float
+              super(value)
+            when ::String
+              if value =~ /\A[+-]?\d+(?:\.\d+)?\z/
+                super(value.to_f)
+              else
+                raise(ValidationError,"value contains non-numeric characters (#{value.inspect})")
+              end
+            else
+              if value.respond_to?(:to_f)
+                super(value.to_f)
+              else
+                raise(ValidationError,"value does not define a #to_f method (#{value.inspect})")
+              end
+            end
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/core/params/types/integer.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2021-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-core is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# ronin-core is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-core.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/core/params/types/numeric'
+
+module Ronin
+  module Core
+    module Params
+      module Types
+        #
+        # Represents a numeric value.
+        #
+        class Integer < Numeric
+
+          #
+          # Coerces a String into an Integer value.
+          #
+          # @param [::Integer, ::String, #to_i, Object] value
+          #   The given value to coerce.
+          #
+          # @return [::Integer]
+          #   The coerced Integer value.
+          #
+          # @raise [ValidationError]
+          #   The value was not an Integer, a String, or was not within
+          #   {#range}, or below {#min}, or above {#max}.
+          #
+          # @api private
+          #
+          def coerce(value)
+            case value
+            when ::Integer then super(value)
+            when ::String
+              case value
+              when /\A[+-]?\d+\z/
+                super(value.to_i)
+              when /\A[+-]?0b[01]+\z/
+                super(parse_binary(value))
+              when /\A[+-]?(?:0x)?[0-9A-Fa-f]+\z/
+                super(parse_hexadecimal(value))
+              else
+                raise(ValidationError,"value contains non-numeric characters (#{value.inspect})")
+              end
+            else
+              if value.respond_to?(:to_i)
+                super(value.to_i)
+              else
+                raise(ValidationError,"value does not define a #to_i method (#{value.inspect})")
+              end
+            end
+          end
+
+          private
+
+          #
+          # Parses a binary string.
+          #
+          # @param [::String] string
+          #
+          # @return [::Integer]
+          #
+          def parse_binary(string)
+            integer = string.sub(/\A[+-]?0b/,'').to_i(2)
+            integer = -integer if string.start_with?('-')
+            integer
+          end
+
+          #
+          # Parses a hexadecimal string.
+          #
+          # @param [::String] string
+          #
+          # @return [::Integer]
+          #
+          def parse_hexadecimal(string)
+            integer = string.sub(/\A[+-]?(?:0x)?/,'').to_i(16)
+            integer = -integer if string.start_with?('-')
+            integer
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/core/params/types/numeric.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2021-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-core is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# ronin-core is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-core.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/core/params/types/type'
+
+module Ronin
+  module Core
+    module Params
+      module Types
+        #
+        # Represents a true/false param.
+        #
+        class Numeric < Type
+
+          # The optional minimum value.
+          #
+          # @return [::Integer, nil]
+          # 
+          # @api private
+          attr_reader :min
+
+          # The optional maximum value.
+          #
+          # @return [::Integer, nil]
+          #
+          # @api private
+          attr_reader :max
+
+          # The optional range of acceptable numbers.
+          #
+          # @return [Range, nil]
+          #
+          # @api private
+          attr_reader :range
+
+          #
+          # Initializes the numeric value.
+          #
+          # @param [::Integer, nil] min
+          #   Optional minimum value for the integer param.
+          #
+          # @param [::Integer, nil] max
+          #   Optional maximum value for the integer param.
+          #
+          # @param [Range] range
+          #   Optional range of acceptable integers.
+          #
+          def initialize(min: nil, max: nil, range: nil)
+            @min   = min
+            @max   = max
+            @range = range
+          end
+
+          #
+          # Validates a numeric value.
+          #
+          # @param [::Integer, ::Float] value
+          #   The value to validate.
+          #
+          # @return [::Integer, ::Float]
+          #   The validated value.
+          #
+          # @raise [ValidationError]
+          #   The value was not within {#range}, or below {#min}, or above
+          #   {#max}.
+          #
+          # @abstract
+          #
+          def coerce(value)
+            if @range
+              unless @range.include?(value)
+                raise(ValidationError,"value is not within the range of acceptable values #{@range.begin}-#{@range.end} (#{value.inspect})")
+              end
+            else
+              if @min && (value < @min)
+                raise(ValidationError,"value is below minimum value of #{@min} (#{value.inspect})")
+              end
+
+              if @max && (value > @max)
+                raise(ValidationError,"value is above maximum value of #{@max} (#{value.inspect})")
+              end
+            end
+
+            return value
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/core/params/types/regexp.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2021-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-core is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# ronin-core is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-core.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/core/params/types/type'
+
+module Ronin
+  module Core
+    module Params
+      module Types
+        #
+        # Represents a Regexp type.
+        #
+        class Regexp < Type
+
+          #
+          # Parses the String value.
+          #
+          # @param [::String, ::Regexp, Object] value
+          #   The String value to coerce.
+          #
+          # @return [Regexp]
+          #   The coerced Regexp value.
+          #
+          # @raise [ValidationError]
+          #   The value was not a Regexp, a String, or a String that could not
+          #   be parsed by `Regexp.new`.
+          #
+          # @api private
+          #
+          def coerce(value)
+            case value
+            when ::Regexp then value
+            when ::String
+              unless (value.start_with?('/') && value.end_with?('/'))
+                raise(ValidationError,"value must be of the format '/.../' (#{value.inspect})")
+              end
+
+              begin
+                ::Regexp.new(value[1..-2])
+              rescue RegexpError
+                raise(ValidationError,"value is not a valid Regexp (#{value.inspect})")
+              end
+            else
+              raise(ValidationError,"value must be either a String or a Regexp (#{value.inspect})")
+            end
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/core/params/types/string.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2021-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-core is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# ronin-core is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-core.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/core/params/types/type'
+
+module Ronin
+  module Core
+    module Params
+      module Types
+        #
+        # Represents a string type.
+        #
+        class String < Type
+
+          # Optional regexp to validate values with.
+          #
+          # @return [::Regexp, nil]
+          attr_reader :format
+
+          #
+          # 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.
+          #
+          # @param [(::Regexp, ::String), nil] format
+          #   Optional regular expression to validate the given param value.
+          #
+          def initialize(allow_empty: false, allow_blank: false, format: nil)
+            @allow_empty = allow_empty
+            @allow_blank = allow_blank
+
+            @format = format
+          end
+
+          #
+          # Specifies whether the param may accept empty values.
+          #
+          # @return [::Boolean]
+          #
+          # @api private
+          #
+          def allow_empty?
+            @allow_empty
+          end
+
+          #
+          # Specifies whether the param may accept blank values.
+          #
+          # @return [::Boolean]
+          #
+          # @api private
+          #
+          def allow_blank?
+            @allow_blank
+          end
+
+          #
+          # Validates the given value.
+          #
+          # @param [Object] value
+          #   The given value to validate.
+          #
+          # @return [::String]
+          #   The coerced String.
+          #
+          # @raise [ValidationError]
+          #   The given value was not a String and did not define a `#to_s`
+          #   method, or was a String that did not match {#format}.
+          #
+          # @api private
+          #
+          def coerce(value)
+            case value
+            when Enumerable
+              raise(ValidationError,"cannot convert an Enumerable into a String (#{value.inspect})")
+            else
+              unless value.respond_to?(:to_s)
+                raise(ValidationError,"value does not define a #to_s method (#{value.inspect})")
+              end
+
+              string = value.to_s
+
+              if @format && string !~ @format
+                raise(ValidationError,"does not match the format (#{string.inspect})")
+              elsif (string.empty? && !allow_empty?)
+                raise(ValidationError,"value cannot be empty")
+              elsif (string =~ /\A\s+\z/ && !allow_blank?)
+                raise(ValidationError,"value cannot contain all whitespace (#{string.inspect})")
+              end
+
+              return string
+            end
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/core/params/types/type.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2021-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-core is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# ronin-core is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-core.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/core/params/exceptions'
+
+module Ronin
+  module Core
+    module Params
+      module Types
+        #
+        # The base type for all command-line argument types.
+        #
+        # @api private
+        #
+        class Type
+
+          #
+          # The default coerce method.
+          #
+          # @param [Object] value
+          #   The value to coerce.
+          #
+          # @return [Object]
+          #   The coerced value.
+          #
+          # @raise [ValidationError]
+          #   The given value was invalid.
+          #
+          # @abstract
+          #
+          def coerce(value)
+            raise(NotImplementedError,"#{self.class}##{__method__} method was not implemented")
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/core/params/types/uri.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2021-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-core is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# ronin-core is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-core.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/core/params/types/type'
+
+require 'uri'
+
+module Ronin
+  module Core
+    module Params
+      module Types
+        #
+        # Represents a URL type.
+        #
+        class URI < Type
+
+          #
+          # Parses the String value.
+          #
+          # @param [::String, ::URI, Object] value
+          #   The String value to coerce.
+          #
+          # @return [::URI]
+          #   The coerced URI value.
+          #
+          # @raise [ValidationError]
+          #   The given value was invalid.
+          #
+          # @api private
+          #
+          def coerce(value)
+            case value
+            when ::URI then value
+            when ::String
+              if value.empty?
+                raise(ValidationError,"value must not be empty")
+              end
+
+              unless value =~ /\A[a-z]+:/
+                raise(ValidationError,"value must start with a 'scheme:' (#{value.inspect})")
+              end
+
+              begin
+                ::URI.parse(value)
+              rescue ::URI::InvalidURIError
+                raise(ValidationError,"value is not a valid URI (#{value.inspect})")
+              end
+            else
+              raise(ValidationError,"value must be either a String or a URI (#{value.inspect})")
+            end
+          end
+
+        end
+      end
+    end
+  end
+end