cmdx 0.5.0 → 1.0.0

data/lib/cmdx/coercions/complex.rb

@@ -2,10 +2,41 @@
 
 module CMDx
   module Coercions
+    # Coerces values to Complex type.
+    #
+    # 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
 
+      # Coerce a value to Complex.
+      #
+      # @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
+      #   Coercions::Complex.call("1+2i")    # => (1+2i)
+      #   Coercions::Complex.call(42)        # => (42+0i)
+      #   Coercions::Complex.call("3.5-2i")  # => (3.5-2i)
       def call(value, _options = {})
         Complex(value)
       rescue ArgumentError, TypeError

data/lib/cmdx/coercions/date.rb

@@ -2,12 +2,51 @@
 
 module CMDx
   module Coercions
+    # Coerces values to Date type.
+    #
+    # 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
 
+      # 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.
+      #
+      # 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)
+      #
+      # @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
+      #   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
       def call(value, options = {})
         return value if ANALOG_TYPES.include?(value.class.name)
         return ::Date.strptime(value, options[:format]) if options[:format]

data/lib/cmdx/coercions/date_time.rb

@@ -2,12 +2,51 @@
 
 module CMDx
   module Coercions
+    # Coerces values to DateTime type.
+    #
+    # 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
 
+      # 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.
+      #
+      # 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)
+      #
+      # @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
+      #   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
       def call(value, options = {})
         return value if ANALOG_TYPES.include?(value.class.name)
         return ::DateTime.strptime(value, options[:format]) if options[:format]

data/lib/cmdx/coercions/float.rb

@@ -2,10 +2,41 @@
 
 module CMDx
   module Coercions
+    # Coerces values to Float type.
+    #
+    # 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
 
+      # Coerce a value to 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
+      #   Coercions::Float.call("123.45")  # => 123.45
+      #   Coercions::Float.call(42)        # => 42.0
+      #   Coercions::Float.call("1e3")     # => 1000.0
       def call(value, _options = {})
         Float(value)
       rescue ArgumentError, TypeError

data/lib/cmdx/coercions/hash.rb

@@ -2,10 +2,47 @@
 
 module CMDx
   module Coercions
+    # Coerces values to Hash type.
+    #
+    # The Hash coercion converts parameter values to Hash objects
+    # with support for various input formats including JSON strings,
+    # arrays (converted to hash), and Rails parameters.
+    #
+    # @example Basic hash coercion
+    #   class ProcessOrderTask < CMDx::Task
+    #     optional :metadata, type: :hash, default: {}
+    #     optional :options, type: :hash
+    #   end
+    #
+    # @example Coercion behavior
+    #   Coercions::Hash.call({a: 1})              # => {a: 1}
+    #   Coercions::Hash.call('{"a":1,"b":2}')     # => {"a"=>1, "b"=>2} (JSON)
+    #   Coercions::Hash.call([:a, 1, :b, 2])     # => {:a=>1, :b=>2} (Array)
+    #   Coercions::Hash.call("invalid")           # => raises CoercionError
+    #
+    # @see ParameterValue Parameter value coercion
+    # @see Parameter Parameter type definitions
     module Hash
 
       extend self
 
+      # Coerce a value to Hash.
+      #
+      # Supports multiple input formats:
+      # - Hash objects (returned as-is)
+      # - ActionController::Parameters (returned as-is)
+      # - JSON strings starting with '{' (parsed as JSON)
+      # - Arrays (converted using Hash[*array])
+      #
+      # @param value [Object] value to coerce to hash
+      # @param _options [Hash] coercion options (unused)
+      # @return [Hash] coerced hash value
+      # @raise [CoercionError] if coercion fails
+      #
+      # @example
+      #   Coercions::Hash.call({key: "value"})      # => {key: "value"}
+      #   Coercions::Hash.call('{"a": 1}')          # => {"a" => 1}
+      #   Coercions::Hash.call([:a, 1, :b, 2])     # => {:a => 1, :b => 2}
       def call(value, _options = {})
         case value.class.name
         when "Hash", "ActionController::Parameters"
@@ -23,6 +60,11 @@ module CMDx
 
       private
 
+      # Raise a standardized coercion error.
+      #
+      # @return [void]
+      # @raise [CoercionError] always raises coercion error
+      # @api private
       def raise_coercion_error!
         raise CoercionError, I18n.t(
           "cmdx.coercions.into_a",

data/lib/cmdx/coercions/integer.rb

@@ -2,10 +2,42 @@
 
 module CMDx
   module Coercions
+    # Coerces values to Integer type.
+    #
+    # The Integer coercion converts parameter values to Integer objects
+    # using Ruby's built-in Integer() method, with proper error handling
+    # for values that cannot be converted.
+    #
+    # @example Basic integer coercion
+    #   class ProcessOrderTask < CMDx::Task
+    #     required :order_id, type: :integer
+    #     optional :quantity, type: :integer, default: 1
+    #   end
+    #
+    # @example Coercion behavior
+    #   Coercions::Integer.call("123")     # => 123
+    #   Coercions::Integer.call("0x10")    # => 16 (hex)
+    #   Coercions::Integer.call("0b1010")  # => 10 (binary)
+    #   Coercions::Integer.call(45.7)      # => 45 (truncated)
+    #   Coercions::Integer.call("invalid") # => raises CoercionError
+    #
+    # @see ParameterValue Parameter value coercion
+    # @see Parameter Parameter type definitions
     module Integer
 
       module_function
 
+      # Coerce a value to Integer.
+      #
+      # @param value [Object] value to coerce to integer
+      # @param _options [Hash] coercion options (unused)
+      # @return [Integer] coerced integer value
+      # @raise [CoercionError] if coercion fails
+      #
+      # @example
+      #   Coercions::Integer.call("123")   # => 123
+      #   Coercions::Integer.call(45.9)    # => 45
+      #   Coercions::Integer.call("0xFF")  # => 255
       def call(value, _options = {})
         Integer(value)
       rescue ArgumentError, TypeError

data/lib/cmdx/coercions/rational.rb

@@ -2,10 +2,41 @@
 
 module CMDx
   module Coercions
+    # Coerces values to Rational type.
+    #
+    # The Rational coercion converts parameter values to Rational number objects
+    # using Ruby's built-in Rational() method, with proper error handling
+    # for values that cannot be converted to rational numbers.
+    #
+    # @example Basic rational coercion
+    #   class MathTask < CMDx::Task
+    #     required :fraction, type: :rational
+    #     optional :ratio, type: :rational, default: Rational(1, 2)
+    #   end
+    #
+    # @example Coercion behavior
+    #   Coercions::Rational.call("1/2")      # => (1/2)
+    #   Coercions::Rational.call("3/4")      # => (3/4)
+    #   Coercions::Rational.call(0.5)        # => (1/2)
+    #   Coercions::Rational.call("invalid")  # => raises CoercionError
+    #
+    # @see ParameterValue Parameter value coercion
+    # @see Parameter Parameter type definitions
     module Rational
 
       module_function
 
+      # Coerce a value to Rational.
+      #
+      # @param value [Object] value to coerce to rational number
+      # @param _options [Hash] coercion options (unused)
+      # @return [Rational] coerced rational number value
+      # @raise [CoercionError] if coercion fails
+      #
+      # @example
+      #   Coercions::Rational.call("1/2")    # => (1/2)
+      #   Coercions::Rational.call(0.75)     # => (3/4)
+      #   Coercions::Rational.call("3.5")    # => (7/2)
       def call(value, _options = {})
         Rational(value)
       rescue ArgumentError, TypeError

data/lib/cmdx/coercions/string.rb

@@ -2,10 +2,41 @@
 
 module CMDx
   module Coercions
+    # Coerces values to String type.
+    #
+    # The String coercion converts parameter values to String objects
+    # using Ruby's built-in String() method, which handles various
+    # input types safely.
+    #
+    # @example Basic string coercion
+    #   class ProcessOrderTask < CMDx::Task
+    #     required :order_id, type: :string
+    #     optional :notes, type: :string
+    #   end
+    #
+    # @example Coercion behavior
+    #   Coercions::String.call(123)        # => "123"
+    #   Coercions::String.call(:symbol)    # => "symbol"
+    #   Coercions::String.call(true)       # => "true"
+    #   Coercions::String.call(nil)        # => ""
+    #   Coercions::String.call([1, 2])     # => "12" (array to_s)
+    #
+    # @see ParameterValue Parameter value coercion
+    # @see Parameter Parameter type definitions
     module String
 
       module_function
 
+      # Coerce a value to String.
+      #
+      # @param value [Object] value to coerce to string
+      # @param _options [Hash] coercion options (unused)
+      # @return [String] coerced string value
+      # @raise [CoercionError] if coercion fails
+      #
+      # @example
+      #   Coercions::String.call(123)    # => "123"
+      #   Coercions::String.call(:test)  # => "test"
       def call(value, _options = {})
         String(value)
       end

data/lib/cmdx/coercions/time.rb

@@ -2,12 +2,51 @@
 
 module CMDx
   module Coercions
+    # Coerces values to Time type.
+    #
+    # The Time coercion converts parameter values to Time objects
+    # with support for time parsing, custom format strings, and
+    # automatic handling of time-like objects.
+    #
+    # @example Basic time coercion
+    #   class ProcessOrderTask < CMDx::Task
+    #     required :created_at, type: :time
+    #     optional :scheduled_at, type: :time, format: "%Y-%m-%d %H:%M:%S"
+    #   end
+    #
+    # @example Coercion behavior
+    #   Coercions::Time.call("2023-12-25 14:30:00")                      # => Time object
+    #   Coercions::Time.call("25/12/2023 2:30 PM", format: "%d/%m/%Y %l:%M %p") # Custom format
+    #   Coercions::Time.call(Date.today)                                 # => Time (from Date)
+    #   Coercions::Time.call("invalid")                                  # => raises CoercionError
+    #
+    # @see ParameterValue Parameter value coercion
+    # @see Parameter Parameter type definitions
     module Time
 
+      # Time-compatible class names that are passed through unchanged
+      # @return [Array<String>] class names that represent time-like objects
       ANALOG_TYPES = %w[Date DateTime Time].freeze
 
       module_function
 
+      # Coerce a value to Time.
+      #
+      # Handles multiple input formats:
+      # - Date, DateTime, Time objects (returned as-is)
+      # - String with custom format (parsed using strptime)
+      # - String with standard format (parsed using Time.parse)
+      #
+      # @param value [Object] value to coerce to time
+      # @param options [Hash] coercion options
+      # @option options [String] :format custom time format string
+      # @return [Time] coerced time value
+      # @raise [CoercionError] if coercion fails
+      #
+      # @example
+      #   Coercions::Time.call("2023-12-25 14:30:00")                        # => Time
+      #   Coercions::Time.call("25/12/2023 14:30", format: "%d/%m/%Y %H:%M") # => Time with custom format
+      #   Coercions::Time.call(DateTime.now)                                 # => Time from DateTime
       def call(value, options = {})
         return value if ANALOG_TYPES.include?(value.class.name)
         return ::Time.strptime(value, options[:format]) if options[:format]

data/lib/cmdx/coercions/virtual.rb

@@ -2,10 +2,41 @@
 
 module CMDx
   module Coercions
+    # Virtual coercion that returns values unchanged.
+    #
+    # The Virtual coercion is a pass-through that returns the input value
+    # without any transformation. This is useful for parameters that should
+    # not undergo type coercion or when you want to preserve the original
+    # value type and structure.
+    #
+    # @example Virtual coercion usage
+    #   class ProcessOrderTask < CMDx::Task
+    #     required :order  # defaults to virtual type
+    #     optional :metadata, type: :virtual
+    #     optional :config, type: :virtual
+    #   end
+    #
+    # @example Coercion behavior
+    #   Coercions::Virtual.call("string")     # => "string"
+    #   Coercions::Virtual.call(123)          # => 123
+    #   Coercions::Virtual.call([1, 2, 3])    # => [1, 2, 3]
+    #   Coercions::Virtual.call({a: 1})       # => {a: 1}
+    #   Coercions::Virtual.call(nil)          # => nil
+    #
+    # @see ParameterValue Parameter value coercion
+    # @see Parameter Parameter type definitions (defaults to virtual)
     module Virtual
 
       module_function
 
+      # Return the value unchanged (no coercion).
+      #
+      # @param value [Object] value to pass through unchanged
+      # @param _options [Hash] coercion options (unused)
+      # @return [Object] the original value without modification
+      #
+      # @example
+      #   Coercions::Virtual.call(anything)  # => anything
       def call(value, _options = {})
         value
       end