cmdx 1.0.0 → 1.1.0

data/lib/cmdx/coercion_registry.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Registry for managing type coercion definitions and execution within tasks.
+  #
+  # This registry handles the registration and execution of coercions that convert
+  # parameter values from one type to another, supporting both built-in types and
+  # custom coercion logic.
+  class CoercionRegistry
+
+    # The internal hash storing coercion definitions.
+    #
+    # @return [Hash] hash containing coercion type keys and coercion class/callable values
+    attr_reader :registry
+
+    # Initializes a new coercion registry with default type coercions.
+    #
+    # Sets up the registry with built-in coercions for standard Ruby types
+    # including primitives, numerics, dates, and collections.
+    #
+    # @return [CoercionRegistry] a new coercion registry instance
+    #
+    # @example Creating a new registry
+    #   registry = CoercionRegistry.new
+    #   registry.registry[:string] # => Coercions::String
+    def initialize
+      @registry = {
+        array: Coercions::Array,
+        big_decimal: Coercions::BigDecimal,
+        boolean: Coercions::Boolean,
+        complex: Coercions::Complex,
+        date: Coercions::Date,
+        datetime: Coercions::DateTime,
+        float: Coercions::Float,
+        hash: Coercions::Hash,
+        integer: Coercions::Integer,
+        rational: Coercions::Rational,
+        string: Coercions::String,
+        time: Coercions::Time,
+        virtual: Coercions::Virtual
+      }
+    end
+
+    # Registers a custom coercion for a specific type.
+    #
+    # @param type [Symbol] the type identifier for the coercion
+    # @param coercion [Object] the coercion callable (class, proc, symbol, or string)
+    #
+    # @return [CoercionRegistry] returns self for method chaining
+    #
+    # @example Registering a custom coercion class
+    #   registry.register(:uuid, UUIDCoercion)
+    #
+    # @example Registering a proc coercion
+    #   registry.register(:upcase, ->(value, options) { value.to_s.upcase })
+    #
+    # @example Chaining registrations
+    #   registry.register(:custom1, MyCoercion).register(:custom2, AnotherCoercion)
+    def register(type, coercion)
+      registry[type] = coercion
+      self
+    end
+
+    # Executes a coercion for the specified type and value.
+    #
+    # @param task [Task] the task instance executing the coercion
+    # @param type [Symbol] the coercion type to execute
+    # @param value [Object] the value to be coerced
+    # @param options [Hash] additional options for the coercion
+    #
+    # @return [Object] the coerced value
+    #
+    # @raise [UnknownCoercionError] when the coercion type is not registered
+    #
+    # @example Coercing a string to integer
+    #   registry.call(task, :integer, "42")
+    #   # => 42
+    #
+    # @example Coercing with options
+    #   registry.call(task, :array, "a,b,c", delimiter: ",")
+    #   # => ["a", "b", "c"]
+    def call(task, type, value, options = {})
+      raise UnknownCoercionError, "unknown coercion #{type}" unless registry.key?(type)
+
+      case coercion = registry[type]
+      when Symbol, String, Proc
+        task.cmdx_try(coercion, value, options)
+      else
+        coercion.call(value, options)
+      end
+    end
+
+  end
+end

data/lib/cmdx/coercions/array.rb

@@ -2,47 +2,29 @@
 
 module CMDx
   module Coercions
-    # Coerces values to Array type.
+    # Coercion class for converting values to arrays.
     #
-    # The Array coercion converts parameter values to Array objects,
-    # with special handling for JSON-formatted strings and general
-    # array conversion using Ruby's Array() method.
-    #
-    # @example Basic array coercion
-    #   class ProcessOrderTask < CMDx::Task
-    #     optional :tags, type: :array, default: []
-    #     optional :item_ids, type: :array
-    #   end
-    #
-    # @example Coercion behavior
-    #   Coercions::Array.call([1, 2, 3])      # => [1, 2, 3]
-    #   Coercions::Array.call("hello")        # => ["hello"]
-    #   Coercions::Array.call('["a","b"]')    # => ["a", "b"] (JSON)
-    #   Coercions::Array.call('[1,2,3]')      # => [1, 2, 3] (JSON)
-    #   Coercions::Array.call(nil)            # => []
-    #   Coercions::Array.call(42)             # => [42]
-    #
-    # @see ParameterValue Parameter value coercion
-    # @see Parameter Parameter type definitions
-    module Array
+    # This coercion handles conversion of various types to arrays, with special
+    # handling for JSON-formatted strings that start with "[".
+    class Array < Coercion
 
-      module_function
-
-      # Coerce a value to Array.
+      # Converts the given value to an array.
+      #
+      # @param value [Object] the value to convert to an array
+      # @param _options [Hash] optional configuration (currently unused)
+      #
+      # @return [Array] the converted array value
       #
-      # If the value is a JSON-formatted string (starts with '['), it will
-      # be parsed as JSON. Otherwise, it uses Ruby's Array() method for
-      # general array conversion.
+      # @raise [JSON::ParserError] if value is a JSON string that cannot be parsed
+      # @raise [TypeError] if the value cannot be converted to an array
       #
-      # @param value [Object] value to coerce to array
-      # @param _options [Hash] coercion options (unused)
-      # @return [Array] coerced array value
-      # @raise [JSON::ParserError] if JSON parsing fails
+      # @example Converting a JSON string
+      #   Coercions::Array.call('["a", "b", "c"]') #=> ["a", "b", "c"]
       #
-      # @example
-      #   Coercions::Array.call("test")         # => ["test"]
-      #   Coercions::Array.call('["a","b"]')    # => ["a", "b"]
-      #   Coercions::Array.call([1, 2])         # => [1, 2]
+      # @example Converting other values
+      #   Coercions::Array.call("hello") #=> ["hello"]
+      #   Coercions::Array.call(123) #=> [123]
+      #   Coercions::Array.call(nil) #=> []
       def call(value, _options = {})
         if value.is_a?(::String) && value.start_with?("[")
           JSON.parse(value)

data/lib/cmdx/coercions/big_decimal.rb

@@ -2,45 +2,33 @@
 
 module CMDx
   module Coercions
-    # Coerces values to BigDecimal type.
+    # Coercion class for converting values to BigDecimal.
     #
-    # The BigDecimal coercion converts parameter values to BigDecimal objects
-    # for high-precision decimal arithmetic. Supports configurable precision
-    # and handles various numeric input formats.
-    #
-    # @example Basic BigDecimal coercion
-    #   class ProcessOrderTask < CMDx::Task
-    #     required :total_amount, type: :big_decimal
-    #     optional :tax_rate, type: :big_decimal, precision: 4
-    #   end
-    #
-    # @example Coercion behavior
-    #   Coercions::BigDecimal.call("123.45")          # => #<BigDecimal:...,'0.12345E3',18(27)>
-    #   Coercions::BigDecimal.call(42)                # => #<BigDecimal:...,'0.42E2',9(18)>
-    #   Coercions::BigDecimal.call("0.333333", precision: 6)  # Custom precision
-    #
-    # @see ParameterValue Parameter value coercion
-    # @see Parameter Parameter type definitions
-    module BigDecimal
+    # This coercion handles conversion of various types to BigDecimal with
+    # configurable precision. It provides precise decimal arithmetic capabilities
+    # for financial calculations and other use cases requiring exact decimal representation.
+    class BigDecimal < Coercion
 
-      # Default precision for BigDecimal calculations
-      # @return [Integer] default precision value
       DEFAULT_PRECISION = 14
 
-      module_function
-
-      # Coerce a value to BigDecimal.
+      # Converts the given value to a BigDecimal.
+      #
+      # @param value [Object] the value to convert to a BigDecimal
+      # @param options [Hash] optional configuration
+      # @option options [Integer] :precision the precision for the BigDecimal (defaults to 14)
+      #
+      # @return [BigDecimal] the converted BigDecimal value
+      #
+      # @raise [CoercionError] if the value cannot be converted to a BigDecimal
+      #
+      # @example Converting a string
+      #   Coercions::BigDecimal.call('123.45') #=> #<BigDecimal:...,'0.12345E3',18(27)>
       #
-      # @param value [Object] value to coerce to BigDecimal
-      # @param options [Hash] coercion options
-      # @option options [Integer] :precision decimal precision (default: 14)
-      # @return [BigDecimal] coerced BigDecimal value
-      # @raise [CoercionError] if coercion fails
+      # @example Converting with custom precision
+      #   Coercions::BigDecimal.call('123.456789', precision: 10) #=> #<BigDecimal:...,'0.123456789E3',18(27)>
       #
-      # @example
-      #   Coercions::BigDecimal.call("123.45")                    # => BigDecimal with default precision
-      #   Coercions::BigDecimal.call("0.333", precision: 10)      # => BigDecimal with custom precision
-      #   Coercions::BigDecimal.call(42.5)                        # => BigDecimal from float
+      # @example Converting an integer
+      #   Coercions::BigDecimal.call(100) #=> #<BigDecimal:...,'0.1E3',9(18)>
       def call(value, options = {})
         BigDecimal(value, options[:precision] || DEFAULT_PRECISION)
       rescue ArgumentError, TypeError

data/lib/cmdx/coercions/boolean.rb

@@ -2,53 +2,34 @@
 
 module CMDx
   module Coercions
-    # Coerces values to Boolean type (true/false).
+    # Coercion class for converting values to booleans.
     #
-    # The Boolean coercion converts parameter values to true or false
-    # based on string pattern matching for common boolean representations.
-    # It handles various textual representations of true and false values.
-    #
-    # @example Basic boolean coercion
-    #   class ProcessOrderTask < CMDx::Task
-    #     optional :send_email, type: :boolean, default: true
-    #     optional :is_urgent, type: :boolean, default: false
-    #   end
-    #
-    # @example Coercion behavior
-    #   Coercions::Boolean.call("true")     # => true
-    #   Coercions::Boolean.call("yes")      # => true
-    #   Coercions::Boolean.call("1")        # => true
-    #   Coercions::Boolean.call("false")    # => false
-    #   Coercions::Boolean.call("no")       # => false
-    #   Coercions::Boolean.call("0")        # => false
-    #   Coercions::Boolean.call("invalid")  # => raises CoercionError
-    #
-    # @see ParameterValue Parameter value coercion
-    # @see Parameter Parameter type definitions
-    module Boolean
+    # This coercion handles conversion of various string representations to
+    # boolean values, supporting common true/false variations like "yes/no",
+    # "1/0", and "t/f".
+    class Boolean < Coercion
 
-      # Pattern matching false-like values (case insensitive)
-      # @return [Regexp] regex for falsey string values
       FALSEY = /^(false|f|no|n|0)$/i
-
-      # Pattern matching true-like values (case insensitive)
-      # @return [Regexp] regex for truthy string values
       TRUTHY = /^(true|t|yes|y|1)$/i
 
-      module_function
-
-      # Coerce a value to Boolean.
+      # Converts the given value to a boolean.
+      #
+      # @param value [Object] the value to convert to a boolean
+      # @param _options [Hash] optional configuration (currently unused)
+      #
+      # @return [Boolean] the converted boolean value
+      #
+      # @raise [CoercionError] if the value cannot be converted to a boolean
       #
-      # @param value [Object] value to coerce to boolean
-      # @param _options [Hash] coercion options (unused)
-      # @return [Boolean] coerced boolean value (true or false)
-      # @raise [CoercionError] if value cannot be coerced to boolean
+      # @example Converting truthy values
+      #   Coercions::Boolean.call('true') #=> true
+      #   Coercions::Boolean.call('yes') #=> true
+      #   Coercions::Boolean.call('1') #=> true
       #
-      # @example
-      #   Coercions::Boolean.call("yes")    # => true
-      #   Coercions::Boolean.call("False")  # => false
-      #   Coercions::Boolean.call("1")      # => true
-      #   Coercions::Boolean.call("0")      # => false
+      # @example Converting falsey values
+      #   Coercions::Boolean.call('false') #=> false
+      #   Coercions::Boolean.call('no') #=> false
+      #   Coercions::Boolean.call('0') #=> false
       def call(value, _options = {})
         case value.to_s.downcase
         when FALSEY then false

data/lib/cmdx/coercions/complex.rb

@@ -2,41 +2,28 @@
 
 module CMDx
   module Coercions
-    # Coerces values to Complex type.
+    # Coercion class for converting values to complex numbers.
     #
-    # The Complex coercion converts parameter values to Complex number objects
-    # using Ruby's built-in Complex() method, with proper error handling
-    # for values that cannot be converted to complex numbers.
-    #
-    # @example Basic complex coercion
-    #   class MathTask < CMDx::Task
-    #     required :complex_number, type: :complex
-    #     optional :coefficient, type: :complex, default: Complex(1, 0)
-    #   end
-    #
-    # @example Coercion behavior
-    #   Coercions::Complex.call("1+2i")      # => (1+2i)
-    #   Coercions::Complex.call("3-4i")      # => (3-4i)
-    #   Coercions::Complex.call(5)           # => (5+0i)
-    #   Coercions::Complex.call("invalid")   # => raises CoercionError
-    #
-    # @see ParameterValue Parameter value coercion
-    # @see Parameter Parameter type definitions
-    module Complex
-
-      module_function
+    # This coercion handles conversion of various types to complex numbers,
+    # including strings, integers, floats, and other numeric types.
+    class Complex < Coercion
 
-      # Coerce a value to Complex.
+      # Converts the given value to a complex number.
+      #
+      # @param value [Object] the value to convert to a complex number
+      # @param _options [Hash] optional configuration (currently unused)
+      #
+      # @return [Complex] the converted complex number value
+      #
+      # @raise [CoercionError] if the value cannot be converted to a complex number
       #
-      # @param value [Object] value to coerce to complex number
-      # @param _options [Hash] coercion options (unused)
-      # @return [Complex] coerced complex number value
-      # @raise [CoercionError] if coercion fails
+      # @example Converting numeric values
+      #   Coercions::Complex.call(5) #=> (5+0i)
+      #   Coercions::Complex.call(3.14) #=> (3.14+0i)
       #
-      # @example
-      #   Coercions::Complex.call("1+2i")    # => (1+2i)
-      #   Coercions::Complex.call(42)        # => (42+0i)
-      #   Coercions::Complex.call("3.5-2i")  # => (3.5-2i)
+      # @example Converting string representations
+      #   Coercions::Complex.call("2+3i") #=> (2+3i)
+      #   Coercions::Complex.call("1-2i") #=> (1-2i)
       def call(value, _options = {})
         Complex(value)
       rescue ArgumentError, TypeError

data/lib/cmdx/coercions/date.rb

@@ -2,54 +2,35 @@
 
 module CMDx
   module Coercions
-    # Coerces values to Date type.
+    # Coercion class for converting values to Date objects.
     #
-    # The Date coercion converts parameter values to Date objects
-    # with support for date parsing, custom format strings, and
-    # automatic handling of date-like objects.
-    #
-    # @example Basic date coercion
-    #   class ProcessOrderTask < CMDx::Task
-    #     required :order_date, type: :date
-    #     optional :delivery_date, type: :date, format: "%Y-%m-%d"
-    #   end
-    #
-    # @example Coercion behavior
-    #   Coercions::Date.call("2023-12-25")                    # => Date object
-    #   Coercions::Date.call("25/12/2023", format: "%d/%m/%Y") # Custom format
-    #   Coercions::Date.call(Time.now)                        # => Date (from Time)
-    #   Coercions::Date.call("invalid")                       # => raises CoercionError
-    #
-    # @see ParameterValue Parameter value coercion
-    # @see Parameter Parameter type definitions
-    module Date
+    # This coercion handles conversion of various types to Date objects, with support
+    # for custom date formats and automatic detection of date-like objects.
+    class Date < Coercion
 
-      # Date-compatible class names that are passed through unchanged
-      # @return [Array<String>] class names that represent date-like objects
       ANALOG_TYPES = %w[Date DateTime Time].freeze
 
-      module_function
-
-      # Coerce a value to Date.
+      # Converts the given value to a Date object.
+      #
+      # @param value [Object] the value to convert to a Date
+      # @param options [Hash] optional configuration
+      # @option options [String] :strptime custom date format for parsing
+      #
+      # @return [Date] the converted Date object
+      #
+      # @raise [CoercionError] if the value cannot be converted to a Date
       #
-      # Handles multiple input formats:
-      # - Date, DateTime, Time objects (returned as Date)
-      # - String with custom format (parsed using strptime)
-      # - String with standard format (parsed using Date.parse)
+      # @example Converting a string with default parsing
+      #   Coercions::Date.call('2023-12-25') #=> #<Date: 2023-12-25>
       #
-      # @param value [Object] value to coerce to date
-      # @param options [Hash] coercion options
-      # @option options [String] :format custom date format string
-      # @return [Date] coerced date value
-      # @raise [CoercionError] if coercion fails
+      # @example Converting with custom format
+      #   Coercions::Date.call('25/12/2023', strptime: '%d/%m/%Y') #=> #<Date: 2023-12-25>
       #
-      # @example
-      #   Coercions::Date.call("2023-12-25")                      # => Date
-      #   Coercions::Date.call("25/12/2023", format: "%d/%m/%Y")  # => Date with custom format
-      #   Coercions::Date.call(Time.now)                          # => Date from Time
+      # @example Converting existing date-like objects
+      #   Coercions::Date.call(DateTime.now) #=> #<Date: 2023-12-25>
       def call(value, options = {})
         return value if ANALOG_TYPES.include?(value.class.name)
-        return ::Date.strptime(value, options[:format]) if options[:format]
+        return ::Date.strptime(value, options[:strptime]) if options[:strptime]
 
         ::Date.parse(value)
       rescue TypeError, ::Date::Error

data/lib/cmdx/coercions/date_time.rb

@@ -2,54 +2,37 @@
 
 module CMDx
   module Coercions
-    # Coerces values to DateTime type.
+    # Coercion class for converting values to DateTime objects.
     #
-    # The DateTime coercion converts parameter values to DateTime objects
-    # with support for datetime parsing, custom format strings, and
-    # automatic handling of date/time-like objects.
-    #
-    # @example Basic datetime coercion
-    #   class ProcessOrderTask < CMDx::Task
-    #     required :order_datetime, type: :date_time
-    #     optional :delivery_datetime, type: :date_time, format: "%Y-%m-%d %H:%M:%S"
-    #   end
-    #
-    # @example Coercion behavior
-    #   Coercions::DateTime.call("2023-12-25T14:30:00")                    # => DateTime object
-    #   Coercions::DateTime.call("25/12/2023 2:30 PM", format: "%d/%m/%Y %l:%M %p") # Custom format
-    #   Coercions::DateTime.call(Time.now)                                 # => DateTime (from Time)
-    #   Coercions::DateTime.call("invalid")                                # => raises CoercionError
-    #
-    # @see ParameterValue Parameter value coercion
-    # @see Parameter Parameter type definitions
-    module DateTime
+    # This coercion handles conversion of various types to DateTime objects,
+    # with support for custom date/time formats and automatic detection of
+    # analog types (Date, DateTime, Time).
+    class DateTime < Coercion
 
-      # DateTime-compatible class names that are passed through unchanged
-      # @return [Array<String>] class names that represent datetime-like objects
       ANALOG_TYPES = %w[Date DateTime Time].freeze
 
-      module_function
-
-      # Coerce a value to DateTime.
+      # Converts the given value to a DateTime object.
+      #
+      # @param value [Object] the value to convert to a DateTime
+      # @param options [Hash] optional configuration
+      # @option options [String] :strptime custom format string for parsing
+      #
+      # @return [DateTime] the converted DateTime object
+      #
+      # @raise [CoercionError] if the value cannot be converted to a DateTime
       #
-      # Handles multiple input formats:
-      # - Date, DateTime, Time objects (returned as-is)
-      # - String with custom format (parsed using strptime)
-      # - String with standard format (parsed using DateTime.parse)
+      # @example Converting a date string
+      #   Coercions::DateTime.call('2023-12-25') #=> #<DateTime: 2023-12-25T00:00:00+00:00>
       #
-      # @param value [Object] value to coerce to datetime
-      # @param options [Hash] coercion options
-      # @option options [String] :format custom datetime format string
-      # @return [DateTime] coerced datetime value
-      # @raise [CoercionError] if coercion fails
+      # @example Converting with a custom format
+      #   Coercions::DateTime.call('25/12/2023', strptime: '%d/%m/%Y') #=> #<DateTime: 2023-12-25T00:00:00+00:00>
       #
-      # @example
-      #   Coercions::DateTime.call("2023-12-25T14:30:00")                      # => DateTime
-      #   Coercions::DateTime.call("25/12/2023 14:30", format: "%d/%m/%Y %H:%M") # => DateTime with custom format
-      #   Coercions::DateTime.call(Time.now)                                    # => DateTime from Time
+      # @example Passing through existing DateTime objects
+      #   dt = DateTime.now
+      #   Coercions::DateTime.call(dt) #=> dt (unchanged)
       def call(value, options = {})
         return value if ANALOG_TYPES.include?(value.class.name)
-        return ::DateTime.strptime(value, options[:format]) if options[:format]
+        return ::DateTime.strptime(value, options[:strptime]) if options[:strptime]
 
         ::DateTime.parse(value)
       rescue TypeError, ::Date::Error

data/lib/cmdx/coercions/float.rb

@@ -2,44 +2,31 @@
 
 module CMDx
   module Coercions
-    # Coerces values to Float type.
+    # Coercion class for converting values to floats.
     #
-    # The Float coercion converts parameter values to Float objects
-    # using Ruby's built-in Float() method, with proper error handling
-    # for values that cannot be converted to floating-point numbers.
-    #
-    # @example Basic float coercion
-    #   class ProcessOrderTask < CMDx::Task
-    #     required :price, type: :float
-    #     optional :discount_rate, type: :float, default: 0.0
-    #   end
-    #
-    # @example Coercion behavior
-    #   Coercions::Float.call("123.45")   # => 123.45
-    #   Coercions::Float.call("1.5e2")    # => 150.0 (scientific notation)
-    #   Coercions::Float.call(42)         # => 42.0
-    #   Coercions::Float.call("invalid")  # => raises CoercionError
-    #
-    # @see ParameterValue Parameter value coercion
-    # @see Parameter Parameter type definitions
-    module Float
-
-      module_function
+    # This coercion handles conversion of various types to float values using
+    # Ruby's built-in Float() method.
+    class Float < Coercion
 
-      # Coerce a value to Float.
+      # Converts the given value to a float.
+      #
+      # @param value [Object] the value to convert to a float
+      # @param _options [Hash] optional configuration (currently unused)
+      #
+      # @return [Float] the converted float value
+      #
+      # @raise [CoercionError] if the value cannot be converted to a float
       #
-      # @param value [Object] value to coerce to float
-      # @param _options [Hash] coercion options (unused)
-      # @return [Float] coerced float value
-      # @raise [CoercionError] if coercion fails
+      # @example Converting numeric strings
+      #   Coercions::Float.call("3.14") #=> 3.14
+      #   Coercions::Float.call("42") #=> 42.0
       #
-      # @example
-      #   Coercions::Float.call("123.45")  # => 123.45
-      #   Coercions::Float.call(42)        # => 42.0
-      #   Coercions::Float.call("1e3")     # => 1000.0
+      # @example Converting other numeric types
+      #   Coercions::Float.call(42) #=> 42.0
+      #   Coercions::Float.call(3.14) #=> 3.14
       def call(value, _options = {})
         Float(value)
-      rescue ArgumentError, TypeError
+      rescue ArgumentError, RangeError, TypeError
         raise CoercionError, I18n.t(
           "cmdx.coercions.into_a",
           type: "float",