clack 0.6.2 → 0.7.0

data/lib/clack/validators.rb

@@ -12,6 +12,12 @@ module Clack
   #   Clack.text(message: "Email?", validate: Clack::Validators.format(/@/, "Must be an email"))
   #   Clack.password(message: "Password?", validate: Clack::Validators.min_length(8))
   #
+  # @example Shorthand shapes (resolved by {Validators.resolve})
+  #   Clack.text(message: "Slug?", validate: /\A[a-z0-9-]+\z/)      # Regexp, "Invalid format"
+  #   Clack.text(message: "Email?", validate: :email)               # zero-argument built-in
+  #   Clack.text(message: "User?", validate: [:required, /\A\w+\z/]) # combined, first failure wins
+  #   Clack.text(message: "User?", validate: {required: "Name needed", /\A\w+\z/ => "Word chars only"})
+  #
   # @example Database validation (blocking I/O)
   #   Clack.text(
   #     message: "Email?",
@@ -32,7 +38,64 @@ module Clack
   #   )
   #
   module Validators
+    # Built-ins reachable by a bare Symbol (+validate: :email+) or as a Hash key with a
+    # custom message (+validate: {email: "Bad email"}+). Each takes only an optional message.
+    #
+    # Shortcuts are typed against the prompt's value: +:future_date+ and +:past_date+
+    # expect a Date (the +date+ prompt); +:path_exists+, +:directory_exists+, and
+    # +:file_exists_warning+ expect a path String (+text+ or +path+); +:required+,
+    # +:email+, +:url+, and +:integer+ work on any string-ish value.
+    SHORTCUTS = %i[
+      required email url integer path_exists directory_exists
+      future_date past_date file_exists_warning
+    ].freeze
+
+    # Built-ins that need arguments, so a bare Symbol can't name them. Consulted only to
+    # raise a pointed "needs arguments" error instead of "Unknown validator".
+    PARAMETERIZED = %i[min_length max_length format one_of in_range date_range combine as_warning].freeze
+    private_constant :PARAMETERIZED
+
     class << self
+      # Normalize the +validate:+ option into a callable, or nil.
+      #
+      # Accepted shapes:
+      # - +nil+ or +false+: no validation
+      # - +Regexp+: {format} with the default "Invalid format" message
+      # - +Symbol+: a zero-argument built-in listed in {SHORTCUTS}
+      # - +Array+: {combine} of each entry, resolved recursively; +nil+ or +false+ entries are dropped
+      # - +Hash+: +Regexp+ or +Symbol+ keys mapped to a custom message, checked in
+      #   insertion order. A String message makes the entry an error; a {Clack::Warning}
+      #   message makes it a soft check (wrapped with {as_warning})
+      # - anything responding to +#call+: returned unchanged
+      #
+      # {Core::Prompt#initialize} calls this, so a bad validator raises when the prompt
+      # is built rather than when the user presses Enter.
+      #
+      # @param validator [Regexp, Symbol, Array, Hash, #call, nil, false] the +validate:+ option value to normalize
+      # @return [#call, nil] the validator, or nil when no validation was requested
+      # @raise [ArgumentError] for unknown Symbols, built-ins that need arguments,
+      #   malformed Hash entries, or any other unsupported type
+      #
+      # @example
+      #   Clack::Validators.resolve(/\A\d+\z/).call("abc")        # => "Invalid format"
+      #   Clack::Validators.resolve(:email).call("nope")          # => "Must be a valid email address"
+      #   Clack::Validators.resolve({required: "Name needed"}).call("")  # => "Name needed"
+      #   Clack::Validators.resolve("oops")                       # raises ArgumentError
+      def resolve(validator)
+        case validator
+        when nil, false then nil
+        when Regexp then format(validator)
+        when Symbol then resolve_symbol(validator)
+        when Array then combine(*validator)
+        when Hash then combine(*validator.map { |shape, message| resolve_with_message(shape, message) })
+        else
+          return validator if validator.respond_to?(:call)
+
+          raise ArgumentError,
+            "Validate must be a Regexp, Symbol, Array, Hash, or respond to #call, got #{validator.class}"
+        end
+      end
+
       # Validates that the input is not empty.
       #
       # @param message [String] Custom error message
@@ -102,12 +165,19 @@ module Clack
         end
       end
 
-      # Combines multiple validators. Returns the first error message, or nil if all pass.
+      # Combines multiple validators. Returns the first error or warning, or nil if all pass.
+      # Each argument is normalized with {resolve}, so Regexps, Symbols, nested Arrays,
+      # and Hashes are accepted alongside procs. +nil+ or +false+ entries are ignored.
       #
-      # @param validators [Array<Proc>] Validators to combine
-      # @return [Proc] Combined validator proc
+      # @param validators [Array<Proc, Regexp, Symbol, Array, Hash, nil, false>] validators to combine
+      # @return [Proc] combined validator proc
+      # @raise [ArgumentError] if any entry can't be resolved
+      #
+      # @example
+      #   Clack::Validators.combine(:required, /\A\d+\z/, Clack::Validators.in_range(1..65535))
       def combine(*validators)
-        ->(value) { first_failing_validation(validators, value) }
+        resolved = validators.map { |validator| resolve(validator) }.compact
+        ->(value) { first_failing_validation(resolved, value) }
       end
 
       # Common email format validator.
@@ -184,9 +254,12 @@ module Clack
 
       # Convert any validator to return a warning instead of an error.
       # Warnings allow the user to proceed with confirmation.
+      # The argument is normalized with {resolve}, so +as_warning(:email)+ and
+      # +as_warning(/\A[a-z]+\z/)+ work.
       #
-      # @param validator [Proc] Original validator
-      # @return [Proc] Validator that returns Warning instead of String
+      # @param validator [Proc, Regexp, Symbol, Array, Hash] original validator
+      # @return [Proc] validator that returns Warning instead of String
+      # @raise [ArgumentError] if validator is nil or false, or can't be resolved
       #
       # @example
       #   # Make max_length a warning instead of error
@@ -196,9 +269,16 @@ module Clack
       #       Clack::Validators.max_length(100, "Bio is quite long")
       #     )
       #   )
+      #
+      # @example Shorthand shapes
+      #   Clack::Validators.as_warning(:email)
+      #   Clack::Validators.as_warning(/\A[a-z]+\z/)
       def as_warning(validator)
+        raise ArgumentError, "as_warning needs a validator, got #{validator.inspect}" unless validator
+
+        resolved = resolve(validator)
         lambda do |value|
-          result = validator.call(value)
+          result = resolved.call(value)
           next if result.nil?
 
           result.is_a?(Clack::Warning) ? result : Clack::Warning.new(result)
@@ -214,6 +294,55 @@ module Clack
         end
         nil
       end
+
+      # Only names on the SHORTCUTS allowlist reach public_send (never respond_to?),
+      # so :resolve or :to_s can't be smuggled in as a validator.
+      def resolve_symbol(name, *args)
+        return public_send(name, *args) if SHORTCUTS.include?(name)
+
+        if PARAMETERIZED.include?(name)
+          raise ArgumentError,
+            "Validator #{name.inspect} needs arguments; pass Clack::Validators.#{name}(...) instead"
+        end
+
+        raise ArgumentError,
+          "Unknown validator: #{name.inspect}. Available: #{SHORTCUTS.map(&:inspect).join(", ")}"
+      end
+
+      # A Hash entry. A Warning message is unwrapped to its String, the built-in is
+      # constructed with that String, and the result is wrapped with as_warning. Passing
+      # the Warning object itself as the message would nest a Warning inside a Warning
+      # for built-ins that already return one (file_exists_warning).
+      def resolve_with_message(shape, message)
+        case message
+        when String then build_with_message(shape, message)
+        when Clack::Warning then as_warning(build_with_message(shape, warning_text(message)))
+        else
+          raise ArgumentError,
+            "Validate Hash values must be a String or Clack::Warning message, got #{message.class}"
+        end
+      end
+
+      # The String carried by a Warning Hash value. Clack.warning always takes a String,
+      # but Clack::Warning.new(nil) is constructible and would otherwise hand a nil message
+      # to the built-in, silently producing a check that always passes.
+      def warning_text(warning)
+        text = warning.message
+        return text if text.is_a?(String)
+
+        raise ArgumentError,
+          "Validate Hash values must be a String or Clack::Warning message, got Clack::Warning(#{text.class})"
+      end
+
+      def build_with_message(shape, message)
+        case shape
+        when Regexp then format(shape, message)
+        when Symbol then resolve_symbol(shape, message)
+        else
+          raise ArgumentError,
+            "Validate Hash keys must be a Regexp or a validator Symbol, got #{shape.class}"
+        end
+      end
     end
   end
 end

data/lib/clack/version.rb

@@ -2,5 +2,5 @@
 
 module Clack
   # Current gem version.
-  VERSION = "0.6.2"
+  VERSION = "0.7.0"
 end