ward 0.1.0

data/lib/ward/matchers.rb

@@ -0,0 +1,97 @@
+require 'ward/matchers/matcher'
+require 'ward/matchers/acceptance'
+require 'ward/matchers/close_to'
+require 'ward/matchers/equal_to'
+require 'ward/matchers/has'
+require 'ward/matchers/include'
+require 'ward/matchers/match'
+require 'ward/matchers/nil'
+require 'ward/matchers/predicate'
+require 'ward/matchers/present'
+require 'ward/matchers/satisfy'
+
+module Ward
+  # Matchers are used to determine whether a particular value is valid.
+  #
+  # Any class instance can be a validator so long as it responds to #matches?;
+  # the #matches? method should take at least one argument which will be the
+  # value of the object being validated. The matcher should then return a
+  # true-like value if the match is successful or either nil, false, or an
+  # array whose first member is false, if the match was not successful.
+  #
+  # In the event that your matcher returns an array, the second member will be
+  # used as the error message.
+  #
+  module Matchers
+
+    # Registers a matcher and it's slug.
+    #
+    # A matcher can be registered with as many slugs as desired.
+    #
+    # @param [Symbol, #to_sym] slug
+    #   A slug which will be used by the DSL in order to assign a context to
+    #   a matcher.
+    # @param [Ward::Matchers::Matcher] matcher
+    #   The matcher to be registered.
+    #
+    # @example Registering the Acceptance handler to be used with :accepted
+    #
+    #   Matchers.register(:accepted, Matchers::Acceptance)
+    #
+    #   # The Acceptance matcher can now be used like so...
+    #
+    #   validate do |form|
+    #     form.acceptable_use_policy.is.accepted
+    #     form.acceptable_use_policy.is_not.accepted
+    #   end
+    #
+    # @example Registering the Has matcher twice.
+    #
+    #   Matchers.register(:has, Matchers::Acceptance)
+    #
+    #   validate do |post|
+    #     post.has(1).author
+    #   end
+    #
+    #   # This provides access to the Has matcher, but "does_not.has" doesn't
+    #   # make much sense. So, we register the Has matcher a second time with
+    #   # a slug which make sense when used in the negative.
+    #
+    #   Matchers.register(:have, Matchers::Acceptance)
+    #
+    #   validate do |post|
+    #     form.does_not.have(1).author
+    #   end
+    #
+    #   # Much better.
+    #
+    def self.register(slug, matcher)
+      matchers[slug.to_sym] = matcher
+    end
+
+    # Returns the registered matchers.
+    #
+    # @return [Hash{Symbol => Ward::Matchers::Matcher}]
+    #
+    def self.matchers
+      @matchers ||= {}
+    end
+
+    # Register the built-in matchers.
+
+    register :accepted,      Acceptance
+    register :close_to,      CloseTo
+    register :equal_to,      EqualTo
+    register :has,           Has
+    register :have,          Has
+    register :included_in,   Include
+    register :matches,       Match
+    register :match,         Match
+    register :nil,           Nil
+    register :one_of,        Include
+    register :present,       Present
+    register :satisfies,     Satisfy
+    register :satisfy,       Satisfy
+
+  end # Matchers
+end # Ward

data/lib/ward/matchers/acceptance.rb

@@ -0,0 +1,43 @@
+module Ward
+  module Matchers
+    # Tests whether the validation value is accepted.
+    #
+    # An "accepted" value one which is exactly true, "t", "true", "1", "y",
+    # or "yes".
+    #
+    # @example
+    #
+    #   class Person
+    #     validate do |person|
+    #       person.name.is.accepted
+    #     end
+    #   end
+    #
+    class Acceptance < Matcher
+
+      # Creates a new matcher instance.
+      #
+      # @param [Object] expected
+      #   The expected value for the matcher.
+      #
+      def initialize(expected = nil, *extra_args)
+        expected = Array(expected || %w( t true y yes 1 ) + [1])
+        @include_matcher = Include.new(expected)
+
+        super(expected, *extra_args)
+      end
+
+      # Returns whether the given value is accepted.
+      #
+      # @param [Object] actual
+      #   The validation value.
+      #
+      # @return [Boolean]
+      #
+      def matches?(actual)
+        actual == true or @include_matcher.matches?(actual)
+      end
+
+    end # Acceptance
+  end # Matchers
+end # Ward

data/lib/ward/matchers/close_to.rb

@@ -0,0 +1,60 @@
+module Ward
+  module Matchers
+    # Tests whether the validation value is within the delta of the expected
+    # value.
+    #
+    # @example Validating that the estimate attribute is 10 (+- 5).
+    #
+    #   class Price
+    #     validate do |price|
+    #       price.estimate.is.close_to(10, 5)
+    #     end
+    #   end
+    #
+    class CloseTo < Matcher
+
+      # Creates a new CloseTo matcher instance.
+      #
+      # @param [Numeric] expected
+      #   The expected value for the matcher.
+      # @param [Numeric] delta
+      #   The the acceptable range by which the actual value can deviate.
+      #
+      def initialize(expected, delta, *extra_args)
+        raise ArgumentError,
+          'The CloseTo matcher requires that the +expected+ value ' \
+          'responds to +-+' unless expected.respond_to?(:-)
+
+        raise ArgumentError,
+          'The CloseTo matcher requires that a Numeric +delta+ value ' \
+          'is supplied' unless delta.kind_of?(Numeric)
+
+        super(expected, *extra_args)
+
+        @delta = delta
+      end
+
+      # Returns whether the given value is close to the expected value.
+      #
+      # @param [Object] actual
+      #   The validation value.
+      #
+      # @return [Boolean]
+      #
+      def matches?(actual)
+        (actual - @expected).abs <= @delta
+      end
+
+      # Adds extra information to the error message.
+      #
+      # @param  [String] error
+      # @return [String]
+      #
+      def customise_error_values(values)
+        values[:delta] = @delta
+        values
+      end
+
+    end # CloseTo
+  end # Matchers
+end # Ward

data/lib/ward/matchers/equal_to.rb

@@ -0,0 +1,33 @@
+module Ward
+  module Matchers
+    # Tests whether the validation value is equal in value to -- but not
+    # necessarily the same object as -- the expected value.
+    #
+    # @example
+    #
+    #   class Person
+    #     validate do |person|
+    #       person.name.is.equal_to('Michael Scarn')
+    #     end
+    #   end
+    #
+    # @todo
+    #   Once the validator DSL is is available, amend the class documentation
+    #   to provide an example of how to call +is+ and +is_not+ with a value.
+    #
+    class EqualTo < Matcher
+
+      # Returns whether the given value is equal to the expected value.
+      #
+      # @param [Object] actual
+      #   The validation value.
+      #
+      # @return [Boolean]
+      #
+      def matches?(actual)
+        actual.eql?(@expected)
+      end
+
+    end # EqualTo
+  end # Matchers
+end # Ward

data/lib/ward/matchers/has.rb

@@ -0,0 +1,283 @@
+module Ward
+  module Matchers
+    # Tests whether the actual value is a collection with the expected number
+    # of members, or contains a collection with the expected number of
+    # members.
+    #
+    # @example Setting the exact size for a collection
+    #
+    #   class Author
+    #     validate do |author|
+    #       # All mean the same thing.
+    #       author.has(5).posts
+    #       author.has.exactly(5).posts
+    #     end
+    #   end
+    #
+    # @example Setting the minimum size for a collection
+    #
+    #   class Author
+    #     validate do |author|
+    #       # All mean the same thing.
+    #       author.has.at_least(5).posts
+    #       author.has.gte(5).posts
+    #
+    #       author.has.greater_than(4).posts
+    #       author.has.more_than(4).posts
+    #       author.has.gt(4).posts
+    #     end
+    #   end
+    #
+    # @example Setting the maximum size for a collection
+    #
+    #   class Author
+    #     validate do |author|
+    #       # All mean the same thing.
+    #       author.has.at_most(5).posts
+    #       author.has.lte(5).posts
+    #
+    #       author.has.less_than(6).posts
+    #       author.has.fewer_than(6).posts
+    #       author.has.lt(6).posts
+    #     end
+    #   end
+    #
+    # @example Setting a range of acceptable sizes for a collection
+    #
+    #   class Author
+    #     validate do |author|
+    #       # All mean the same thing.
+    #       author.has.between(1..5).posts
+    #       author.has.between(1, 5).posts
+    #     end
+    #   end
+    #
+    class Has < Matcher
+
+      # The name of the collection whose size is being checked.
+      #
+      # @return [Symbol, nil]
+      #   nil indicates that no collection name has been set, and the matcher
+      #   will attempt to call +size+ or +length+ on the collection owner.
+      #
+      attr_reader :collection_name
+
+      # Returns how to test the length of the collection.
+      #
+      # @return [Symbol]
+      #
+      attr_reader :relativity
+
+      # Creates a new matcher instance.
+      #
+      # If no expected value is provided, the matcher will default to
+      # expecting that the collection has at_least(1).
+      #
+      # @param [Object] expected
+      #   The expected value for the matcher.
+      #
+      def initialize(expected = nil, *extra_args)
+        case expected
+          when Range   then super ; between(expected)
+          when Numeric then super ; eql(expected)
+          when :no     then super ; eql(0)
+          else              super(1, *extra_args) ; @relativity = :gte
+        end
+      end
+
+      # Returns whether the given value is satisfied by the expected block.
+      #
+      # @param [Object] collection
+      #   The collection or the collection owner.
+      #
+      # @return [Boolean]
+      #
+      def matches?(collection)
+        unless @collection_name.nil?
+          if collection.respond_to?(@collection_name)
+            collection = collection.__send__(@collection_name)
+          elsif collection.respond_to?(@plural_collection_name)
+            collection = collection.__send__(@plural_collection_name)
+          end
+        end
+
+        if collection.respond_to?(:length)
+          actual = collection.length
+        elsif collection.respond_to?(:size)
+          actual = collection.size
+        else
+          raise RuntimeError,
+            'The given value is not a collection (it does not respond to ' \
+            '#length or #size)'
+        end
+
+        result = case @relativity
+          when :eql, nil then actual == (@expected == :no ? 0 : @expected)
+          when :lte      then actual <=  @expected
+          when :gte      then actual >=  @expected
+          when :between  then @expected.include?(actual)
+        end
+
+        [result, @relativity || :eql]
+      end
+
+      # Sets that the collection should be smaller than the expected value.
+      #
+      # @param [Numeric] n
+      #   The maximum size of the collection + 1.
+      #
+      # @return [Ward::Matchers::Has]
+      #   Returns self.
+      #
+      def lt(n)
+        set_relativity(:lte, n - 1)
+      end
+
+      alias_method :fewer_than, :lt
+      alias_method :less_than,  :lt
+
+      # Sets that the collection should be no larger than the expected value.
+      #
+      # @param [Numeric] n
+      #   The maximum size of the collection.
+      #
+      # @return [Ward::Matchers::Has]
+      #   Returns self.
+      #
+      def lte(n)
+        set_relativity(:lte, n)
+      end
+
+      alias_method :at_most, :lte
+
+      # Sets that the collection should be the exact size of the expectation.
+      #
+      # @param [Numeric] n
+      #   The exact expected size of the collection.
+      #
+      # @return [Ward::Matchers::Has]
+      #   Returns self.
+      #
+      def eql(n)
+        set_relativity(:eql, n)
+      end
+
+      alias_method :exactly, :eql
+
+      # Sets that the collection should be no smaller than the expected value.
+      #
+      # @param [Numeric] n
+      #   The minimum size of the collection.
+      #
+      # @return [Ward::Matchers::Has]
+      #   Returns self.
+      #
+      def gte(n)
+        set_relativity(:gte, n)
+      end
+
+      alias_method :at_least, :gte
+
+      # Sets that the collection should be greater than the expected value.
+      #
+      # @param [Numeric] n
+      #   The minimum size of the collection - 1.
+      #
+      # @return [Ward::Matchers::Has]
+      #   Returns self.
+      #
+      def gt(n)
+        set_relativity(:gte, n + 1)
+      end
+
+      alias_method :greater_than, :gt
+      alias_method :more_than,    :gt
+
+      # Sets that the collection size should be between two values.
+      #
+      # @param [Range, Numeric] n
+      #   The lowest boundary for the collection size. Alternatively, a range
+      #   specifying the acceptable size of the collection.
+      # @param [Numeric] upper
+      #   The lowest boundary for the collection size. Omit if a range is
+      #   supplied as the first argument.
+      #
+      # @return [Ward::Matchers::Has]
+      #   Returns self.
+      #
+      def between(n, upper = nil)
+        if n.kind_of?(Range)
+          set_relativity(:between, n)
+        elsif upper.nil?
+          raise ArgumentError,
+            'You must supply an upper boundary for the collection size'
+        else
+          set_relativity(:between, (n..upper))
+        end
+      end
+
+      # Adds extra information to the error message.
+      #
+      # @param  [String] error
+      # @return [String]
+      #
+      def customise_error_values(values)
+        values[:collection] = @collection_desc || 'items'
+
+        if @relativity == :between
+          values[:lower] = @expected.first
+          values[:upper] = @expected.last
+        end
+
+        values
+      end
+
+      private
+
+      # Sets the collection name to be used by the matcher.
+      #
+      # @return [Ward::Matchers::Has]
+      #   Returns self.
+      #
+      # @todo
+      #   Capture args and block to be used when fetching the collection.
+      #
+      def method_missing(method, *args, &block)
+        @collection_desc = ActiveSupport::Inflector.humanize(method).downcase
+
+        @collection_desc = ActiveSupport::Inflector.singularize(
+          @collection_desc) if @expected == 1
+
+        unless method == :characters and ''.respond_to?(:characters)
+          @collection_name, @plural_collection_name =
+            method, ActiveSupport::Inflector.pluralize(method.to_s).to_sym
+        end
+
+        self
+      end
+
+      # Sets the relativity and the expected value.
+      #
+      # Also marks that a relativity has been set, preventing another one from
+      # being set in the future.
+      #
+      # @param [Symbol] relativity
+      #   The relativity to set.
+      # @param [Numeric] expected
+      #   The expected value to set.
+      #
+      # @return [Ward::Matchers::Has]
+      #   Returns self.
+      #
+      def set_relativity(relativity, expected)
+        raise RuntimeError,
+          "A relativity (#{@relativity}) was already set; you cannot " \
+          "set another" if @relativity_set
+
+        @relativity, @expected, @relativity_set = relativity, expected, true
+        self
+      end
+
+    end # Has
+  end # Matchers
+end # Ward