ward 0.1.0

data/lib/ward/dsl.rb

@@ -0,0 +1,7 @@
+require 'ward/dsl/validation_block'
+require 'ward/dsl/validation_builder'
+
+module Ward
+  # Classes which provide the Ward validator DSL.
+  module DSL; end
+end # Ward

data/lib/ward/dsl/validation_block.rb

@@ -0,0 +1,73 @@
+module Ward
+  module DSL
+    # Creates one or more validators using a block.
+    #
+    # @see Ward::ValidatorSet.build
+    #
+    # @example
+    #
+    #   # Builds a validation set with two validators
+    #   #
+    #   #   * One for "author.name" and the EqualTo matcher.
+    #   #   * One for "title" with the Match matcher.
+    #
+    #   ValidationBlock.new do |object|
+    #     object.author.name.is.equal_to('Michael Scarn')
+    #     object.title.match(/something/)
+    #   end
+    #
+    class ValidationBlock < Support::BasicObject
+
+      # Creates a new ValidationBlock instance.
+      #
+      # NOTE: Providing an existing ValidatorSet will result in a copy of that
+      # set being mutated; the original will not be changed.
+      #
+      # @param [Ward::ValidatorSet] set
+      #   A ValidatorSet to which the built validators should be added.
+      #
+      def initialize(set = nil, &block)
+        @set = if set.nil? then Ward::ValidatorSet.new else set.dup end
+        run(&block) if block
+      end
+
+      # Returns the ValidatorSet created by the DSL.
+      #
+      # @return [Ward::ValidatorSet]
+      #
+      def to_validator_set
+        @set
+      end
+
+      private
+
+      # Runs a block, creating the appropriate validators.
+      #
+      # @todo Ensure that each matcher was correctly set up.
+      #
+      def run
+        @builders = []
+        yield self
+        @set.merge!(@builders.map { |builder| builder.to_validator })
+        @builders = nil
+      end
+
+      # Provides the DSL.
+      #
+      # Will take the given message and creates a new ValidationBuilder.
+      #
+      # @return [Ward::DSL::ValidationBuilder]
+      #   Returns the created builder.
+      #
+      def method_missing(method, *extra_args, &block)
+        raise 'ValidationBlock can only be used when provided ' \
+          'with a block' if @builders.nil?
+
+        builder = ValidationBuilder.new.__send__(method, *extra_args, &block)
+        @builders.push(builder)
+        builder
+      end
+
+    end # ValidationBlock
+  end # DSL
+end # Ward

data/lib/ward/dsl/validation_builder.rb

@@ -0,0 +1,190 @@
+module Ward
+  module DSL
+    # Creates a single {Validator}. Any message received which doesn't
+    # correspond with a matcher will be assumed to be part of the context.
+    #
+    # @example
+    #
+    #   # Builds a validation whose context is "author.name" and uses the
+    #   # EqualTo matcher to ensure that the "author.name" is "Michel Scarn".
+    #
+    #   ValidationBuilder.new.author.name.is.equal_to('Michael Scarn')
+    #
+    class ValidationBuilder < Support::BasicObject
+
+      # Creates a new ValidationBuilder instance.
+      #
+      def initialize
+        @context = Ward::ContextChain.new
+        @matcher, @message, @scenarios, @negative = nil, nil, nil, false
+      end
+
+      # Sets the error message to be used if the validation fails.
+      #
+      # This can be one of three possibilities:
+      #
+      #   * A Hash. If the matcher used returns a different error state in
+      #     order to provide more details about what failed (such as the Has
+      #     matcher), you may provide a hash with custom error messages for
+      #     each error state.
+      #
+      #   * A String which will be used whenever the validation fails,
+      #     regardless of what went wrong.
+      #
+      #   * nil (default). The validation will use the default error message
+      #     for the matcher.
+      #
+      # @param [Hash{Symbol => String}, String, nil] message
+      #
+      # @return [Ward::DSL::ValidatorBuilder]
+      #   Returns self.
+      #
+      # @example Setting an explicit error message.
+      #
+      #   validate do |person|
+      #     person.name.is.present.message('You must enter a name!')
+      #   end
+      #
+      # @example Setting an explicit error message with a Hash.
+      #
+      #   validate do |person|
+      #     person.name.length.is(1..50).message(
+      #       :too_short => "Your name must be at least 1 character long",
+      #       :too_long  => "That's an interesting name!"
+      #     )
+      #   end
+      #
+      def message(message)
+        @message = message
+        self
+      end
+
+      # Sets the name to be used for the context in error messages.
+      #
+      # When Ward generates error messages for you, it determines the
+      # 'context name' by joining the method names; for example 'name.length'
+      # becomes 'name length'.
+      #
+      # This isn't much use if you want to support languages other than
+      # English in your application, so the 'context' method allows you to set
+      # a custom string to be used. You may provide a String, in which case it
+      # will be used literally, a Hash of +language => String+, or a Symbol
+      # identifying a string to be used from a language file.
+      #
+      # See the localisation documentation for more examples.
+      #
+      def context(name)
+        @context_name = name
+        self
+      end
+
+      # Sets the scenarios under which the built validator should run.
+      #
+      # @param [Symbol, ...] scenarios
+      #   The scenarios as Symbols.
+      #
+      # @return [Ward::DSL::ValidatorBuilder]
+      #   Returns self.
+      #
+      def scenarios(*scenarios)
+        @scenarios = scenarios.flatten
+        self
+      end
+
+      alias_method :scenario, :scenarios
+
+      # Adds an attribute to the context chain.
+      #
+      # Useful your classes have attribute which you want to validate, and
+      # their name conflicts with a method on the validator DSL (e.g.
+      # "message").
+      #
+      # @param [Symbol] attribute
+      #   The attribute to be validated.
+      #
+      # @return [Ward::DSL::ValidatorBuilder]
+      #   Returns self.
+      #
+      def attribute(attribute, *args, &block)
+        @context << Ward::Context.new(attribute, *args, &block)
+        self
+      end
+
+      # Set this as a positive expectation. Can be omitted.
+      #
+      # @example
+      #   object.name.is.blank
+      #
+      # @return [Ward::DSL::ValidatorBuilder]
+      #   Returns self.
+      #
+      def is(*args)
+        equal_to(*args) unless args.empty?
+        self
+      end
+
+      # Set this as a negative expectation.
+      #
+      # @example
+      #   object.name.is_not.blank
+      #
+      # @return [Ward::DSL::ValidatorBuilder]
+      #   Returns self.
+      #
+      def is_not(*args)
+        @negative = true
+        is(*args)
+      end
+
+      alias_method :does_not, :is_not
+
+      # Provides the DSL.
+      #
+      # Will take the given message and use it to customise the matcher (if
+      # one is set), set a matcher, or extend the context.
+      #
+      # @return [Ward::DSL::ValidatorBuilder]
+      #   Returns self.
+      #
+      def method_missing(method, *args, &block)
+        # I'd normally shy away from using method_missing, but there's no
+        # good alternative here since a user may register their own matchers
+        # later in the load process.
+
+        if @matcher
+          @matcher.__send__(method, *args, &block)
+        elsif Ward::Matchers.matchers.has_key?(method)
+          @matcher = Ward::Matchers.matchers[method].new(*args, &block)
+        elsif method.to_s =~ /\?$/
+          @matcher = Ward::Matchers::Predicate.new(method, *args, &block)
+        else
+          attribute(method, *args, &block)
+        end
+
+        self
+      end
+
+      # Converts the builder to a Validator instance.
+      #
+      # @return [Ward::Validator]
+      #
+      # @raise [IncompleteValidation]
+      #   An IncompleteValidationError will be raised if builder does not have
+      #   all of the needed information in order to create the necessary
+      #   validation (for example, if no matcher has been set).
+      #
+      # @todo
+      #   More descriptive error messages.
+      #
+      def to_validator
+        raise Ward::IncompleteValidator,
+          'Validator was missing a matcher' if @matcher.nil?
+
+        Ward::Validator.new(@context, @matcher, :message => @message,
+          :scenarios => @scenarios, :negative => @negative,
+          :context_name => @context_name)
+      end
+
+    end # Validate
+  end # DSL
+end # Ward

data/lib/ward/errors.rb

@@ -0,0 +1,213 @@
+module Ward
+  # Holds errors associated with a valid? call.
+  #
+  class Errors
+
+    include Enumerable
+
+    class << self
+
+      # Returns a localisation message.
+      #
+      # @param [keys] String
+      #   The key of the message to be returned from the current language
+      #   file.
+      #
+      # @return [String, nil]
+      #   Returns the message or nil if it couldn't be found.
+      #
+      # @example
+      #
+      #   Ward::Errors.message('has.eql.positive')
+      #   # => '%{context} should have %{expected} %{collection}'
+      #
+      # @example Passing multiple keys as fallbacks.
+      #
+      #   Ward::Errors.message(
+      #     'does.not.exist', 'has.eql.negative', 'has.eql.positive')
+      #
+      #   # => '%{context} should not have %{expected} %{collection}'
+      #
+      def message(*keys)
+        messages[ keys.detect { |key| messages.has_key?(key) } ]
+      end
+
+      # Returns the unformatted error message for a matcher.
+      #
+      # @param [Ward::Matchers::Matcher] matcher
+      #   The matcher.
+      # @param [Boolean] negative
+      #   Whether to return a negative message, rather than a positive.
+      # @param [nil, Symbol, String] key
+      #   If a string is supplied, +error_for+ will assume that the string
+      #   should be used as the error. A symbol will be assumed to be a 'key'
+      #   from the language file, while nil will result in the validator using
+      #   the default error message for the matcher.
+      #
+      # @return [String]
+      #
+      def error_for(matcher, negative, key = nil)
+        return key if key.is_a?(String)
+
+        language_key = if key.nil?
+          "#{matcher.class.error_id}."
+        else
+          "#{matcher.class.error_id}.#{key}."
+        end
+
+        language_key << (negative ? 'negative' : 'positive')
+
+        message(language_key) || '%{context} is invalid'
+      end
+
+      # Receives an array and formats it nicely, assuming that only one value
+      # is expected.
+      #
+      # @example One member
+      #   format_exclusive_list([1]) # => '1'
+      #
+      # @example Two members
+      #   format_exclusive_list([1, 2]) # => '1 or 2'
+      #
+      # @example Many members
+      #   format_exclusive_list([1, 2, 3]) # => '1, 2, or 3'
+      #
+      # @param [Enumerable] list
+      #   The list to be formatted.
+      #
+      # @return [String]
+      #
+      def format_exclusive_list(list)
+        format_list(list, message('generic.exclusive_conjunction'))
+      end
+
+      # Receives an array and formats it nicely, assuming that all values are
+      # expected.
+      #
+      # @example One member
+      #   format_inclusive_list([1]) # => '1'
+      #
+      # @example Two members
+      #   format_inclusive_list([1, 2]) # => '1 and 2'
+      #
+      # @example Many members
+      #   format_inclusive_list([1, 2, 3]) # => '1, 2, and 3'
+      #
+      # @param [Enumerable] list
+      #   The list to be formatted.
+      #
+      # @return [String]
+      #
+      def format_inclusive_list(list)
+        format_list(list, message('generic.inclusive_conjunction'))
+      end
+
+      private
+
+      # Formats a list.
+      #
+      # @see Ward::Errors.format_exclusive_list
+      # @see Ward::Errors.format_inclusive_list
+      #
+      def format_list(list, conjunction)
+        case list.size
+          when 0 then ''
+          when 1 then list.first.to_s
+          when 2 then "#{list.first.to_s} #{conjunction} #{list.last.to_s}"
+          else
+            as_strings = list.map { |value| value.to_s }
+            as_strings[-1] = "#{conjunction} #{as_strings[-1]}"
+            as_strings.join("#{message('generic.list_seperator')} ")
+        end
+      end
+
+      # Returns the en-US error message hash. TEMPORARY.
+      #
+      # @return [Hash]
+      #
+      def messages
+        @error_messages ||= normalise_messages(YAML.load(
+          File.read(File.expand_path('../../../lang/en.yml', __FILE__)) ))
+      end
+
+      # Transforms a hash of messages to a single hash using dot notation.
+      #
+      def normalise_messages(messages, transformed = {}, key_prefix = '')
+        messages.each do |key, value|
+          item_key = key_prefix.empty? ? key : "#{key_prefix}.#{key}"
+
+          if value.is_a?(Hash)
+            normalise_messages(value, transformed, item_key)
+          else
+            transformed[item_key] = value
+          end
+        end
+
+        transformed
+      end
+
+    end # class << self
+
+    # Creates a new Errors instance.
+    #
+    def initialize
+      @errors = {}
+    end
+
+    # Adds an error message to the instance.
+    #
+    # @param [Symbol, Ward::Context, Ward::ContextChain] attribute
+    #   The attribute or context for the error.
+    # @param [String] message
+    #   The error message to add.
+    #
+    # @return [String]
+    #   Returns the error message which was set.
+    #
+    # @todo
+    #   Support symbols for i18n.
+    #
+    def add(attribute, message)
+      if attribute.kind_of?(Context) or attribute.kind_of?(ContextChain)
+        attribute = attribute.attribute
+      end
+
+      @errors[attribute] ||= []
+      @errors[attribute] << message
+      message
+    end
+
+    # Returns an array of the errors present on an an attribute.
+    #
+    # @param [Symbol] attribute
+    #   The attribute whose errors you wish to retrieve.
+    #
+    # @return [Array]
+    #   Returns the error messages for an attribute, or nil if there are none.
+    #
+    def on(attribute)
+      @errors[attribute]
+    end
+
+    # Iterates through each attribute and the errors.
+    #
+    # @yieldparam [Symbol] attribute
+    #   The attribute name.
+    # @yieldparam [Array, nil] messages
+    #   An array with each error message for the attribute, or nil if the
+    #   attribute has no errors.
+    #
+    def each(&block)
+      @errors.each(&block)
+    end
+
+    # Returns if there are no errors contained.
+    #
+    # @return [Boolean]
+    #
+    def empty?
+      @errors.empty?
+    end
+
+  end # Errors
+end # Ward