ward 0.1.0

data/lib/ward/matchers/include.rb

@@ -0,0 +1,54 @@
+module Ward
+  module Matchers
+    # Tests whether the validation value is contained in the expected value.
+    #
+    # The expected value can be anything which responds to +include?+; if it
+    # returns true, the matcher will pass.
+    #
+    # @example Person role is either :admin or :staff
+    #
+    #   class Person
+    #     validate do |person|
+    #       person.role.is.in([:admin, :staff])
+    #     end
+    #   end
+    #
+    class Include < Matcher
+
+      # Creates a new Include matcher instance.
+      #
+      # @param [#include?] expected
+      #   The expected value for the matcher.
+      #
+      def initialize(expected = nil)
+        raise ArgumentError,
+          'The Include matcher requires that a value which responds ' \
+          'to #include? is supplied' unless expected.respond_to?(:include?)
+
+        super
+      end
+
+      # Returns whether the given value is included in the expected value.
+      #
+      # @param [#include?] actual
+      #   The validation value.
+      #
+      # @return [Boolean]
+      #
+      def matches?(actual)
+        @expected.include?(actual)
+      end
+
+      # Adds extra information to the error message.
+      #
+      # @param  [String] error
+      # @return [String]
+      #
+      def customise_error_values(values)
+        values[:expected] = Ward::Errors.format_exclusive_list(@expected)
+        values
+      end
+
+    end # Include
+  end # Matchers
+end # Ward

data/lib/ward/matchers/match.rb

@@ -0,0 +1,29 @@
+module Ward
+  module Matchers
+    # Tests whether the validation value matches the expected value with a
+    # regular expression.
+    #
+    # @example
+    #
+    #   class Person
+    #     validate do |person|
+    #       person.name.matches(/^Michael (Scarn|Scott)$/)
+    #     end
+    #   end
+    #
+    class Match < Matcher
+
+      # Returns whether the given value matches the expected value.
+      #
+      # @param [#include?] actual
+      #   The validation value.
+      #
+      # @return [Boolean]
+      #
+      def matches?(actual)
+        actual.match(@expected)
+      end
+
+    end # Match
+  end # Matchers
+end # Ward

data/lib/ward/matchers/matcher.rb

@@ -0,0 +1,68 @@
+module Ward
+  module Matchers
+    # A base class used for creating custom matchers.
+    #
+    # @abstract
+    #
+    class Matcher
+
+      # Returns the expected value.
+      #
+      # @return [Object]
+      #
+      attr_reader :expected
+
+      # Returns any extra arguments given to the matcher.
+      #
+      # @return [Array]
+      #
+      attr_reader :extra_args
+
+      # Creates a new matcher instance.
+      #
+      # @param [Object] expected
+      #   The expected value for the matcher.
+      #
+      def initialize(expected = nil, *extra_args)
+        @expected   = expected
+        @extra_args = extra_args
+      end
+
+      # Returns whether the given value matches the expected value.
+      #
+      # @param [Object] actual
+      #   The validation value.
+      #
+      # @return [Boolean]
+      #
+      # @abstract
+      #
+      def matches?(actual)
+        true
+      end
+
+      # Allows matcher subclasses to change -- or add values to -- the hash
+      # whose values are interpolated with the error string.
+      #
+      # @param [Hash]
+      #   The standard values which are interpolated with the error string;
+      #   contains :context and :expected keys.
+      #
+      # @return [Hash{Symbol => String}]
+      #
+      def customise_error_values(values)
+        values
+      end
+
+      # Determines the key to be used to find error messages in lang files.
+      #
+      # @return [String]
+      #
+      def self.error_id
+        @error_id ||= ActiveSupport::Inflector.underscore(
+          ActiveSupport::Inflector.demodulize(to_s))
+      end
+
+    end # Matcher
+  end # Matchers
+end # Ward

data/lib/ward/matchers/nil.rb

@@ -0,0 +1,30 @@
+module Ward
+  module Matchers
+    # Tests whether the validation value is nil.
+    #
+    # @todo Remove once the predicate matcher DSL is available.
+    #
+    # @example
+    #
+    #   class AverageDogWalker
+    #     validate do |walker|
+    #       walker.common_sense.is.nil  # Sigh.
+    #     end
+    #   end
+    #
+    class Nil < Matcher
+
+      # Returns whether the given value is nil.
+      #
+      # @param [Object] actual
+      #   The validation value.
+      #
+      # @return [Boolean]
+      #
+      def matches?(actual)
+        actual.nil?
+      end
+
+    end # Nil
+  end # Matchers
+end # Ward

data/lib/ward/matchers/predicate.rb

@@ -0,0 +1,31 @@
+module Ward
+  module Matchers
+    # Tests that a predicate method responds with true.
+    #
+    # @example Validating that the predicate method responds with true.
+    #
+    #   class Person
+    #     validate do |person|
+    #       person.is.important?
+    #     end
+    #   end
+    #
+    class Predicate < Matcher
+
+      # Returns whether the given value is responds true to the predicate.
+      #
+      # @param [Object] actual
+      #   The validation value.
+      #
+      # @return [Boolean]
+      #
+      def matches?(actual)
+        raise ArgumentError, "#{actual.inspect} does not respond " \
+          "to #{expected}" unless actual.respond_to?(@expected)
+
+        actual.__send__(@expected)
+      end
+
+    end # Predicate
+  end # Matchers
+end # Ward

data/lib/ward/matchers/present.rb

@@ -0,0 +1,56 @@
+module Ward
+  module Matchers
+    # Tests whether the validation value is present.
+    #
+    # A "present" value is one which:
+    #
+    #   * is a non-blank string, containing more than just whitespace
+    #   * responds to #empty? and returns false
+    #   * does not evaluate to false (i.e. not nil or false)
+    #
+    # This is equivalent to ActiveSupport's +blank?+ extension methods but
+    # note that +blank?+ is not actually used; if you define +blank?+ on a
+    # class which is provided to the matcher it will not be called.
+    #
+    # @todo
+    #   Once the predicate matcher is available, amend the class documentation
+    #   to provide an example of how to call +blank?+ explicitly.
+    #
+    # @example Validating that the name attribute is present
+    #
+    #   class Person
+    #     validate do |person|
+    #       person.name.is.present
+    #     end
+    #   end
+    #
+    # @example Validating that the job attribute is not present :(
+    #
+    #   class Person
+    #     validate do |person|
+    #       person.job.is_not.present
+    #     end
+    #   end
+    #
+    class Present < Matcher
+
+      # Returns whether the given value is present.
+      #
+      # @param [Object] actual
+      #   The validation value.
+      #
+      # @return [Boolean]
+      #
+      def matches?(actual)
+        if actual.kind_of?(String)
+          actual.match(/\S/)
+        elsif actual.respond_to?(:empty?)
+          not actual.empty?
+        else
+          actual
+        end
+      end
+
+    end # Present
+  end # Matchers
+end # Ward

data/lib/ward/matchers/satisfy.rb

@@ -0,0 +1,65 @@
+module Ward
+  module Matchers
+    # Tests whether the validation value satisfies the given block.
+    #
+    # If the block returns any value other than false, the matcher will assume
+    # that the match passed.
+    #
+    # Alternatively, you may pass a Symbol which identifies a method name; the
+    # method will be run with it's return value used to determine if the
+    # matcher passed.
+    #
+    # Adding an explict error message is advised, since the message generated
+    # by Ward isn't very helpful: "... is invalid".
+    #
+    # @example Matching with a block
+    #
+    #   class Record
+    #     validate do |record|
+    #       record.name.satisfies do |value, record|
+    #         value == 'Michael Scarn'
+    #       end
+    #     end
+    #   end
+    #
+    # @example With a runtime error message
+    #
+    #   class Record
+    #     validate do |record|
+    #       record.name.satisfies do |value, record|
+    #         value == 'Michael Scarn' || [false, "Ooooh noooo"]
+    #       end
+    #     end
+    #   end
+    #
+    class Satisfy < Matcher
+
+      # Creates a new matcher instance.
+      #
+      # @param [Object] expected
+      #   The expected value for the matcher.
+      #
+      def initialize(expected = nil, *extra_args, &block)
+        super(block, *extra_args)
+      end
+
+      # Returns whether the given value is satisfied by the expected block.
+      #
+      # @param [Object] actual
+      #   The validation value.
+      # @param [Object] record
+      #   The full record.
+      #
+      # @return [Boolean]
+      #
+      def matches?(actual, record = nil)
+        if @expected.arity != 1
+          @expected.call(actual, record)
+        else
+          @expected.call(actual)
+        end
+      end
+
+    end # Satisfy
+  end # Matchers
+end # Ward

data/lib/ward/spec.rb

@@ -0,0 +1,17 @@
+#
+# The 'spec' directory contains various reuseable helpers for use with RSpec.
+#
+# The helpers are _not_ loaded when doing +require 'ward'+; if you wish to
+# use these helpers -- perhaps for testing your own custom validations -- you
+# must:
+#
+#   require 'ward'
+#   require 'ward/spec'
+#
+
+require 'ward/spec/matcher_matcher'
+
+module Ward
+  # Provides helpers and matchers for use in RSpec examples.
+  module Spec; end
+end

data/lib/ward/spec/matcher_matcher.rb

@@ -0,0 +1,114 @@
+module Ward
+  module Spec
+    # Since Ward matchers are permitted to return either false, or an Array
+    # whose first member is false, to indicate a failure, determining the
+    # status of a match attempt relies in you knowing this in advance:
+    #
+    #     result, error = matcher.matches?(value)
+    #     result.should be_false
+    #
+    # The helpers within the MatcherMatcher module simplify this situation:
+    #
+    #     matcher.should pass_matcher_with(value)
+    #     matcher.should fail_matcher_with(value)
+    #
+    # The +fail_matcher_with+ helper also provides the ability to check the
+    # error message returned by the matcher:
+    #
+    #     matcher.should fail_matcher_with(value, :too_short)
+    #
+    module MatcherMatcher
+
+      # Formats error messages for spec failures.
+      #
+      # @param [String, Symbol] result
+      #   Did you expect a :pass or :fail?
+      # @param [Ward::Matchers::Matcher] matcher
+      #   The matcher instance which was used for the expectation.
+      # @param [Object] value
+      #   The actual value which was supplied to the Ward matcher.
+      #
+      # @return [String]
+      #
+      def self.error_message(result, matcher, value)
+        status = if result.to_sym == :pass then 'failed' else 'passed' end
+
+        expected = unless matcher.expected.nil?
+          "expected: #{matcher.expected.inspect}, "
+        end
+
+        "expected #{matcher.class.inspect} matcher to #{result}, but it " \
+        "#{status} (#{expected}actual: #{value.inspect})"
+      end
+
+      # An RSpec matcher which tests that the Ward matcher passes with a
+      # particular value.
+      #
+      ::Spec::Matchers.define :pass_matcher_with do |value|
+        match do |matcher|
+          case result = matcher.matches?(value)
+            when false, nil then false
+            when Array      then !! result.first
+            else                 true
+          end
+        end
+
+        failure_message_for_should do |matcher|
+          Ward::Spec::MatcherMatcher.error_message(:pass, matcher, value)
+        end
+
+        failure_message_for_should_not do |matcher|
+          Ward::Spec::MatcherMatcher.error_message(:fail, matcher, value)
+        end
+      end
+
+      # An RSpec matcher which tests that the Ward matcher fails with a
+      # particular value.
+      #
+      ::Spec::Matchers.define :fail_matcher_with do |value|
+        # Allows further customisation of the matcher, asserting that a
+        # particular error message was returned along with the failure. Using
+        # this with +should_not+ makes little sense.
+        #
+        # @param [Symbol, String] expected_error
+        #
+        def with_error(expected_error)
+          @expected_error = expected_error
+          self
+        end
+
+        match do |matcher|
+          result, error = matcher.matches?(value)
+
+          if @expected_error and not error.eql?(@expected_error)
+            @actual_error = error
+            false
+          elsif result == false || result.nil?
+            true
+          else
+            false
+          end
+        end
+
+        failure_message_for_should do |matcher|
+          if @actual_error
+            expected = unless matcher.expected.nil?
+              "expected: #{matcher.expected.inspect}, "
+            end
+
+            "expected #{matcher.class.inspect} matcher to fail with error " \
+            "#{@expected_error.inspect}, but it failed with " \
+            "#{@actual_error.inspect} (#{expected}actual: #{value.inspect})"
+          else
+            Ward::Spec::MatcherMatcher.error_message(:fail, matcher, value)
+          end
+        end
+
+        failure_message_for_should_not do |matcher|
+          Ward::Spec::MatcherMatcher.error_message(:pass, matcher, value)
+        end
+      end
+
+    end # MatcherMatcher
+  end # Spec
+end # Ward