cmdx 1.0.0 → 1.1.0

data/lib/cmdx/validators/format.rb

@@ -2,102 +2,48 @@
 
 module CMDx
   module Validators
-    # Format validator for parameter validation using regular expressions.
+    # Validator class for format validation using regular expressions.
     #
-    # The Format validator validates parameter values against regular expression
-    # patterns. It supports both positive matching (with) and negative matching
-    # (without) patterns, and can combine both for complex format validation.
-    #
-    # @example Basic format validation with positive pattern
-    #   class ProcessUserTask < CMDx::Task
-    #     required :email, format: { with: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i }
-    #     required :phone, format: { with: /\A\d{3}-\d{3}-\d{4}\z/ }
-    #   end
-    #
-    # @example Format validation with negative pattern
-    #   class ProcessContentTask < CMDx::Task
-    #     required :username, format: { without: /\A(admin|root|system)\z/i }
-    #     required :content, format: { without: /spam|viagra/i }
-    #   end
-    #
-    # @example Combined positive and negative patterns
-    #   class ProcessUserTask < CMDx::Task
-    #     required :password, format: {
-    #       with: /\A(?=.*[a-z])(?=.*[A-Z])(?=.*\d).{8,}\z/,  # Strong password
-    #       without: /password|123456/i  # Common weak patterns
-    #     }
-    #   end
-    #
-    # @example Custom error message
-    #   class ProcessUserTask < CMDx::Task
-    #     required :email, format: {
-    #       with: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i,
-    #       message: "must be a valid email address"
-    #     }
-    #   end
-    #
-    # @example Format validation behavior
-    #   # Positive pattern matching
-    #   Format.call("user@example.com", format: { with: /@/ })     # passes
-    #   Format.call("invalid-email", format: { with: /@/ })        # raises ValidationError
-    #
-    #   # Negative pattern matching
-    #   Format.call("username", format: { without: /admin/ })      # passes
-    #   Format.call("admin", format: { without: /admin/ })         # raises ValidationError
-    #
-    # @see CMDx::Parameter Parameter validation integration
-    # @see CMDx::ValidationError Raised when validation fails
-    module Format
+    # This validator ensures that a value matches or doesn't match specified
+    # regular expression patterns. It supports both positive matching (with)
+    # and negative matching (without) patterns, which can be used independently
+    # or in combination.
+    class Format < Validator
 
-      module_function
-
-      # Validates that a parameter value matches the specified format patterns.
-      #
-      # Validates the value against the provided regular expression patterns.
-      # Supports positive matching (with), negative matching (without), or both.
-      # The value must match all specified conditions to pass validation.
+      # Validates that the given value matches the specified format pattern(s).
       #
-      # @param value [String] The parameter value to validate
-      # @param options [Hash] Validation configuration options
-      # @option options [Hash] :format Format validation configuration
-      # @option options [Regexp] :format.with Pattern the value must match
-      # @option options [Regexp] :format.without Pattern the value must not match
-      # @option options [String] :format.message Custom error message
+      # @param value [Object] the value to validate
+      # @param options [Hash] validation options containing format configuration
+      # @option options [Hash] :format format validation configuration
+      # @option options [Regexp] :format.with pattern the value must match
+      # @option options [Regexp] :format.without pattern the value must not match
+      # @option options [String] :format.message custom error message
       #
       # @return [void]
-      # @raise [ValidationError] If value doesn't match the format requirements
       #
-      # @example Successful positive pattern validation
-      #   Format.call("user@example.com", format: { with: /@/ })
-      #   # => passes without error
+      # @raise [ValidationError] if the value doesn't match the format requirements
       #
-      # @example Failed positive pattern validation
-      #   Format.call("invalid-email", format: { with: /@/ })
-      #   # => raises ValidationError: "is an invalid format"
+      # @example Validating with a positive pattern
+      #   Validators::Format.call("user123", format: { with: /\A[a-z]+\d+\z/ })
+      #   # => nil (no error raised)
       #
-      # @example Successful negative pattern validation
-      #   Format.call("username", format: { without: /admin/ })
-      #   # => passes without error
+      # @example Validating with a negative pattern
+      #   Validators::Format.call("admin", format: { without: /admin|root/ })
+      #   # raises ValidationError: "is an invalid format"
       #
-      # @example Failed negative pattern validation
-      #   Format.call("admin", format: { without: /admin/ })
-      #   # => raises ValidationError: "is an invalid format"
+      # @example Validating with both patterns
+      #   Validators::Format.call("user123", format: { with: /\A[a-z]+\d+\z/, without: /admin|root/ })
+      #   # => nil (no error raised)
       #
-      # @example Combined pattern validation
-      #   Format.call("StrongPass123", format: {
-      #     with: /\A(?=.*[a-z])(?=.*[A-Z])(?=.*\d).{8,}\z/,
-      #     without: /password/i
-      #   })
-      #   # => passes without error
+      # @example Invalid format with positive pattern
+      #   Validators::Format.call("123abc", format: { with: /\A[a-z]+\d+\z/ })
+      #   # raises ValidationError: "is an invalid format"
       #
-      # @example Custom error message
-      #   Format.call("weak", format: {
-      #     with: /\A.{8,}\z/,
-      #     message: "must be at least 8 characters"
-      #   })
-      #   # => raises ValidationError: "must be at least 8 characters"
+      # @example Using a custom message
+      #   Validators::Format.call("123abc", format: { with: /\A[a-z]+\d+\z/, message: "Username must start with letters" })
+      #   # raises ValidationError: "Username must start with letters"
       def call(value, options = {})
-        valid = case options[:format]
+        valid = case options
                 in { with: with, without: without }
                   value.match?(with) && !value.match?(without)
                 in { with: with }
@@ -110,7 +56,7 @@ module CMDx
 
         return if valid
 
-        raise ValidationError, options.dig(:format, :message) || I18n.t(
+        raise ValidationError, options[:message] || I18n.t(
           "cmdx.validators.format",
           default: "is an invalid format"
         )

data/lib/cmdx/validators/inclusion.rb

@@ -2,106 +2,50 @@
 
 module CMDx
   module Validators
-    # Inclusion validator for parameter validation against allowed values.
+    # Validator class for including values within a specified set.
     #
-    # The Inclusion validator ensures that parameter values ARE within a
-    # specified set of allowed values. It supports both array-based inclusion
-    # (specific values) and range-based inclusion (value ranges).
-    #
-    # @example Basic inclusion validation with array
-    #   class ProcessOrderTask < CMDx::Task
-    #     required :status, inclusion: { in: ['pending', 'processing', 'completed'] }
-    #     required :priority, inclusion: { in: [1, 2, 3, 4, 5] }
-    #   end
-    #
-    # @example Range-based inclusion
-    #   class ProcessUserTask < CMDx::Task
-    #     required :age, inclusion: { in: 18..120 }  # Valid age range
-    #     required :score, inclusion: { within: 0..100 }  # Percentage score
-    #   end
-    #
-    # @example Custom error messages
-    #   class ProcessOrderTask < CMDx::Task
-    #     required :status, inclusion: {
-    #       in: ['pending', 'processing', 'completed'],
-    #       of_message: "must be a valid order status"
-    #     }
-    #     required :age, inclusion: {
-    #       in: 18..120,
-    #       in_message: "must be between %{min} and %{max} years old"
-    #     }
-    #   end
-    #
-    # @example Boolean field validation
-    #   class ProcessUserTask < CMDx::Task
-    #     required :active, inclusion: { in: [true, false] }  # Proper boolean validation
-    #     required :role, inclusion: { in: ['admin', 'user', 'guest'] }
-    #   end
-    #
-    # @example Inclusion validation behavior
-    #   # Array inclusion
-    #   Inclusion.call("pending", inclusion: { in: ['pending', 'active'] })     # passes
-    #   Inclusion.call("cancelled", inclusion: { in: ['pending', 'active'] })   # raises ValidationError
-    #
-    #   # Range inclusion
-    #   Inclusion.call(25, inclusion: { in: 18..65 })  # passes
-    #   Inclusion.call(15, inclusion: { in: 18..65 })  # raises ValidationError
-    #
-    # @see CMDx::Validators::Exclusion For validating values must not be in a set
-    # @see CMDx::Parameter Parameter validation integration
-    # @see CMDx::ValidationError Raised when validation fails
-    module Inclusion
-
-      extend self
+    # This validator ensures that a value is included in a given array or range
+    # of allowed values. It supports both discrete value inclusion and range-based
+    # inclusion validation.
+    class Inclusion < Validator
 
-      # Validates that a parameter value is in the allowed set.
-      #
-      # Checks that the value is present in the specified array or range
-      # of allowed values. Raises ValidationError if the value is not found
-      # in the inclusion set.
-      #
-      # @param value [Object] The parameter value to validate
-      # @param options [Hash] Validation configuration options
-      # @option options [Hash] :inclusion Inclusion validation configuration
-      # @option options [Array, Range] :inclusion.in Values/range to include
-      # @option options [Array, Range] :inclusion.within Alias for :in
-      # @option options [String] :inclusion.of_message Error message for array inclusion
-      # @option options [String] :inclusion.in_message Error message for range inclusion
-      # @option options [String] :inclusion.within_message Alias for :in_message
-      # @option options [String] :inclusion.message General error message override
+      # Validates that the given value is included in the inclusion set.
+      #
+      # @param value [Object] the value to validate
+      # @param options [Hash] validation options containing inclusion configuration
+      # @option options [Hash] :inclusion inclusion validation configuration
+      # @option options [Array, Range] :inclusion.in the values to include
+      # @option options [Array, Range] :inclusion.within alias for :in
+      # @option options [String] :inclusion.message custom error message
+      # @option options [String] :inclusion.of_message custom error message for array inclusion
+      # @option options [String] :inclusion.in_message custom error message for range inclusion
+      # @option options [String] :inclusion.within_message alias for :in_message
       #
       # @return [void]
-      # @raise [ValidationError] If value is not found in the inclusion set
-      #
-      # @example Array inclusion validation
-      #   Inclusion.call("active", inclusion: { in: ['active', 'pending'] })
-      #   # => passes without error
-      #
-      # @example Failed array inclusion
-      #   Inclusion.call("cancelled", inclusion: { in: ['active', 'pending'] })
-      #   # => raises ValidationError: "must be one of: \"active\", \"pending\""
-      #
-      # @example Range inclusion validation
-      #   Inclusion.call(25, inclusion: { in: 18..65 })
-      #   # => passes without error
-      #
-      # @example Failed range inclusion
-      #   Inclusion.call(15, inclusion: { in: 18..65 })
-      #   # => raises ValidationError: "must be within 18 and 65"
-      #
-      # @example Boolean validation
-      #   Inclusion.call(true, inclusion: { in: [true, false] })
-      #   # => passes without error
-      #
-      # @example Custom error messages
-      #   Inclusion.call("invalid", inclusion: {
-      #     in: ['valid', 'pending'],
-      #     of_message: "status must be valid or pending"
-      #   })
-      #   # => raises ValidationError: "status must be valid or pending"
+      #
+      # @raise [ValidationError] if the value is not found in the inclusion set
+      #
+      # @example Including from an array
+      #   Validators::Inclusion.call("user", inclusion: { in: ["user", "admin"] })
+      #   # => nil (no error raised)
+      #
+      # @example Including from a range
+      #   Validators::Inclusion.call(5, inclusion: { in: 1..10 })
+      #   # => nil (no error raised)
+      #
+      # @example Invalid inclusion from array
+      #   Validators::Inclusion.call("guest", inclusion: { in: ["user", "admin"] })
+      #   # raises ValidationError: "must be one of: \"user\", \"admin\""
+      #
+      # @example Invalid inclusion from range
+      #   Validators::Inclusion.call(15, inclusion: { in: 1..10 })
+      #   # raises ValidationError: "must be within 1 and 10"
+      #
+      # @example Using a custom message
+      #   Validators::Inclusion.call("guest", inclusion: { in: ["user", "admin"], message: "Invalid role selected" })
+      #   # raises ValidationError: "Invalid role selected"
       def call(value, options = {})
-        values = options.dig(:inclusion, :in) ||
-                 options.dig(:inclusion, :within)
+        values = options[:in] || options[:within]
 
         if values.is_a?(Range)
           raise_within_validation_error!(values.begin, values.end, options) unless values.cover?(value)
@@ -112,15 +56,21 @@ module CMDx
 
       private
 
-      # Raises validation error for array-based inclusion violations.
+      # Raises a validation error for array-based inclusion.
+      #
+      # @param values [Array] the allowed values
+      # @param options [Hash] validation options
+      #
+      # @return [void]
       #
-      # @param values [Array] The allowed values array
-      # @param options [Hash] Validation options containing error messages
-      # @raise [ValidationError] With formatted error message
+      # @raise [ValidationError] always raised with appropriate message
+      #
+      # @example
+      #   raise_of_validation_error!(["user", "admin"], {})
+      #   # raises ValidationError: "must be one of: \"user\", \"admin\""
       def raise_of_validation_error!(values, options)
-        values  = values.map(&:inspect).join(", ")
-        message = options.dig(:inclusion, :of_message) ||
-                  options.dig(:inclusion, :message)
+        values  = values.map(&:inspect).join(", ") unless values.nil?
+        message = options[:of_message] || options[:message]
         message %= { values: } unless message.nil?
 
         raise ValidationError, message || I18n.t(
@@ -130,16 +80,21 @@ module CMDx
         )
       end
 
-      # Raises validation error for range-based inclusion violations.
+      # Raises a validation error for range-based inclusion.
+      #
+      # @param min [Object] the minimum value of the range
+      # @param max [Object] the maximum value of the range
+      # @param options [Hash] validation options
+      #
+      # @return [void]
+      #
+      # @raise [ValidationError] always raised with appropriate message
       #
-      # @param min [Object] Range minimum value
-      # @param max [Object] Range maximum value
-      # @param options [Hash] Validation options containing error messages
-      # @raise [ValidationError] With formatted error message
+      # @example
+      #   raise_within_validation_error!(1, 10, {})
+      #   # raises ValidationError: "must be within 1 and 10"
       def raise_within_validation_error!(min, max, options)
-        message = options.dig(:inclusion, :in_message) ||
-                  options.dig(:inclusion, :within_message) ||
-                  options.dig(:inclusion, :message)
+        message = options[:in_message] || options[:within_message] || options[:message]
         message %= { min:, max: } unless message.nil?
 
         raise ValidationError, message || I18n.t(