ward 0.1.0

data/lib/ward/support.rb

@@ -0,0 +1,7 @@
+require 'ward/support/basic_object'
+require 'ward/support/result'
+
+module Ward
+  # Support classes.
+  module Support; end
+end # Ward

data/lib/ward/support/basic_object.rb

@@ -0,0 +1,55 @@
+module Ward
+  module Support
+    # Used by the DSL classes. Provides a BasicObject implementation for
+    # Ruby versions older than 1.9.
+    #
+    # From Sequel, with modifications to support RSpec.
+    #
+    class BasicObject
+
+      # Lookup missing constants in ::Object
+      def self.const_missing(name)
+        ::Object.const_get(name)
+      end
+
+      if RUBY_VERSION < '1.9.0'
+        # If on Ruby 1.8, create a Ward::BasicObject class that is similar to
+        # the Ruby 1.9 BasicObject class. This is used as the basis for the
+        # DSL classes.
+        (instance_methods - %w( __id__ __send__ instance_eval == equal?
+              should should_not )).each do |method|
+          undef_method(method.to_sym)
+        end
+      end
+
+    end # BasicObject
+  end # Support
+end # Ward
+
+#
+#  Sequel License:
+#
+#    Copyright (c) 2007-2008 Sharon Rosner
+#    Copyright (c) 2008-2010 Jeremy Evans
+#
+#    Permission is hereby granted, free of charge, to any person
+#    obtaining a copy of this software and associated documentation
+#    files (the "Software"), to deal in the Software without
+#    restriction, including without limitation the rights to use,
+#    copy, modify, merge, publish, distribute, sublicense, and/or
+#    sell copies of the Software, and to permit persons to whom the
+#    Software is furnished to do so, subject to the following
+#    conditions:
+#
+#    The above copyright notice and this permission notice shall be
+#    included in all copies or substantial portions of the Software.
+#
+#    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+#    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+#    OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+#    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
+#    ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+#    CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+#    CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+#    THE SOFTWARE.
+#

data/lib/ward/support/result.rb

@@ -0,0 +1,49 @@
+module Ward
+  module Support
+    # Used when validating objects which don't include the Validation
+    # module. Contains the results of running a ValidatorSet against a record,
+    # and any errors which occurred.
+    #
+    #
+    class Result
+
+      # Returns the errors which were found when validating.
+      #
+      # An Errors instance will always be returned, even if there were no
+      # errors with the record.
+      #
+      # @return [Ward:Errors]
+      #
+      attr_reader :errors
+
+      # Creates a new Result instance.
+      #
+      # @param [Ward::Errors] errors
+      #   The errors which were found by the validations.
+      #
+      def initialize(errors)
+        @errors = errors
+        @result = errors.empty?
+      end
+
+      # Returns true if the validations passed.
+      #
+      # @return [Boolean]
+      #
+      def pass?
+        @result
+      end
+
+      alias_method :valid?, :pass?
+
+      # Returns true if the validations failed.
+      #
+      # @return [Boolean]
+      #
+      def fail?
+        not pass?
+      end
+
+    end # Result
+  end # Support
+end # Ward

data/lib/ward/validator.rb

@@ -0,0 +1,147 @@
+module Ward
+  # Pairs a context (or chain) with a matcher.
+  #
+  class Validator
+
+    # Returns the context.
+    #
+    # @return [Ward::ContextChain, Ward::Context]
+    #
+    attr_reader :context
+
+    # Returns the matcher.
+    #
+    # @return [Ward::Matchers::Matcher]
+    #
+    attr_reader :matcher
+
+    # The scenarios under which the validator will be run.
+    #
+    # @return [Enumerable<Symbol>]
+    #
+    attr_reader :scenarios
+
+    # An override to the default message.
+    #
+    # If set, this message will always be used if the validation fails,
+    # regardless of whether it is used as a positive or negative assertion.
+    #
+    # @return [Hash, String, nil]
+    #   Returns a Hash if the user wishes to use a different message depending
+    #   on the error state of the matcher (certain matchers, like Has, return
+    #   a different error depending on what went wrong), a String if an
+    #   explicit error message is set, or nil if no error message is set (in
+    #   which case the default error for the matcher will be used).
+    #
+    attr_reader :message
+
+    # Creates a new Validator.
+    #
+    # @param [Ward::ContextChain, Ward::Context] context
+    #   The context to be used to fetch the value for the matcher.
+    # @param [Ward::Matchers::Matcher] matcher
+    #   A matcher to be used to validate the context value.
+    # @param [Hash] options
+    #   Extra options used to customise the Validator.
+    #
+    # @option options [Symbol, Array<Symbol>] :scenarios
+    #   An array of scenarios in which this validator should be run
+    # @option options [Hash{Symbol => String}, String] :message
+    #   The error message to be used if the validator fails (see
+    #   DSL::ValidationBuilder#message).
+    # @option options [String] :context_name
+    #   The name to be used for the context when generating error messages.
+    #
+    def initialize(context, matcher, options = {})
+      @context, @matcher = context, matcher
+      @scenarios = Array(options[:scenarios] || :default).freeze
+      @negative = options[:negative] || false
+      @message  = options[:message].freeze
+      @context_name = options[:context_name].freeze
+    end
+
+    # Determines if the validator is valid for the given record.
+    #
+    # The return value deviates from the ValidatorSet API -- where #valid?
+    # returns only a boolean value -- but that's fine since you shouldn't be
+    # calling Validator#valid? in your applications anyway. :)
+    #
+    # @param [Object] record
+    #   The object whose attribute is to be validated.
+    #
+    # @return [Array<Boolean, {nil, String, Symbol}>]
+    #   Returns an array with two elements. The first is always either true or
+    #   false, indicating whether the validator passed, and the second is the
+    #   raw error message returned by the matcher.
+    #
+    def validate(record)
+      # If the matches? method on the matcher takes two arguments, send in the
+      # record as well as the value.
+      result = if @matcher.method(:matches?).arity != 1
+        @matcher.matches?(@context.value(record), record)
+      else
+        @matcher.matches?(@context.value(record))
+      end
+
+      result, error = if defined?(Rubinius)
+        # Rubinius treats any value which responds to #to_a as being
+        # array-like, thus multiple assignment breaks if the matcher returns
+        # such an object.
+        result.is_a?(Array) ? result : [result].flatten
+      else
+        result
+      end
+
+      (!! result) ^ negative? ? [ true, nil ] : [ false, error_for(error) ]
+    end
+
+    # Returns if the validator should be run as part of the given scenario.
+    #
+    # @param [Symbol] scenario
+    #   A name identifying the scenario.
+    #
+    # @return [Boolean]
+    #
+    def scenario?(scenario)
+      @scenarios.include?(scenario)
+    end
+
+    # Returns if the validator expects that the matcher _not_ match.
+    #
+    # Use with the +is_not+ and +does_not+ DSL keyword.
+    #
+    # @return [Boolean]
+    #
+    def negative?
+      @negative
+    end
+
+    private
+
+    # Returns the error message when the matcher fails.
+    #
+    # If the validator has a message defined, it will always be used in
+    # preference over any error returned by the matcher, or defiend in the
+    # language files.
+    #
+    # @param  [nil, Symbol, String] key
+    # @return [String]
+    #
+    # @see Ward::Errors.error_for
+    # @see Ward::Matchers::Matcher#format_error
+    #
+    def error_for(key)
+      initial = @message || Ward::Errors.error_for(matcher, negative?, key)
+
+      error = initial % matcher.customise_error_values(
+        :expected => matcher.expected,
+        :context  => @context_name || context.natural_name)
+
+      error.strip!
+      error[0] = error[0].chr.upcase
+
+      error
+    end
+
+  end
+end # Ward

data/lib/ward/validator_set.rb

@@ -0,0 +1,115 @@
+module Ward
+  # Holds one or more Validators which are associated with a particular class.
+  #
+  # This class is considered part of Ward's semi-public API; which is to say
+  # that it's methods should not be called in end-user applications, but are
+  # available for library and plugin authors who wish to extend it's
+  # functionality.
+  #
+  # @example Retrieving the validators for a class.
+  #   MyClass.validators # => #<ValidatorSet [#<Validator>, ...]>
+  #
+  class ValidatorSet
+
+    # Builds a ValidatorSet using the given block.
+    #
+    # 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.
+    #
+    # @return [Ward::ValidatorSet]
+    #
+    def self.build(set = nil, &block)
+      Ward::DSL::ValidationBlock.new(set, &block).to_validator_set
+    end
+
+    include Enumerable
+
+    # Creates a new ValidatorSet.
+    #
+    # @param [Enumerable<Ward::Validator>] validators
+    #   An optional collection of validators.
+    #
+    def initialize(validators = [])
+      @validators = validators
+    end
+
+    # Determines if all of the contained validators are valid for the given
+    # record in the given scenario.
+    #
+    # @param [Object] record
+    #   The object whose validations are to be run.
+    # @param [Symbol] scenario
+    #   A name identifying the scenario.
+    #
+    # @return [Boolean]
+    #   Returns true if the record validated, otherwise returns false.
+    #
+    def valid?(record, scenario = :default)
+      inject(true) do |result, validator|
+        (! validator.scenario?(scenario) or
+          validator.validate(record).first) and result
+      end
+    end
+
+    # A more useful version of #valid?
+    #
+    # Whereas #valid? simply returns true or false indicating whether the
+    # validations passed, #validate returns a Ward::Support::Result instance
+    # which describes the outcome of running the validators, and encapsulates
+    # any errors messages which resulted.
+    #
+    # @param [Object] record
+    #   The object whose validations are to be run.
+    # @param [Symbol] scenario
+    #   A name identifying the scenario.
+    #
+    # @return [Ward::Support::Result]
+    #
+    def validate(record, scenario = :default)
+      errors = Ward::Errors.new
+
+      @validators.each do |validator|
+        next unless validator.scenario?(scenario)
+        result, error = validator.validate(record)
+        errors.add(validator.context, error) unless result == true
+      end
+
+      Support::Result.new(errors)
+    end
+
+    # Iterates through each validator in the set.
+    #
+    # @yield [validator] Yields each validator in turn.
+    # @yieldparam [Ward::Validator]
+    #
+    def each(&block)
+      @validators.each(&block)
+    end
+
+    # Adds a new validator to set.
+    #
+    # @param [Ward::Validator] validator
+    #   The validator to be added to the set.
+    #
+    def push(validator)
+      @validators << validator
+    end
+
+    alias_method :<<, :push
+
+    # Adds the validators contained in +other+ to the receiving set.
+    #
+    # @param [Ward::ValidatorSet] set
+    #   The validator set whose validators are to be added to the receiver.
+    #
+    #
+    def merge!(other)
+      @validators |= other.to_a
+      self
+    end
+
+  end # ValidatorSet
+end # Ward

data/lib/ward/version.rb

@@ -0,0 +1,3 @@
+module Ward
+  VERSION = File.read(File.expand_path('../../../VERSION', __FILE__)).strip
+end

data/spec/lib/has_matcher_relativity_examples.rb

@@ -0,0 +1,15 @@
+share_examples_for 'Has matcher relativity method' do
+  before(:all) do
+    @expectation ||= [5]
+    @matcher = Ward::Matchers::Has.new
+    @return = @matcher.__send__(@method, *@expectation)
+  end
+
+  it 'should return the matcher' do
+    @return.should == @matcher
+  end
+
+  it "should set the matcher relativity" do
+    @matcher.relativity.should == @relativity
+  end
+end

data/spec/lib/have_public_method_defined.rb

@@ -0,0 +1,22 @@
+# Ensures that a given class has a particular public instance method defined
+# without instantiation. Works around Ruby 1.8 and 1.9 differences.
+#
+::Spec::Matchers.define :have_public_method_defined do |value|
+  match do |klass|
+    klass.public_method_defined?(value.to_sym)
+  end
+
+  description do
+    "should have public instance method defined ##{value.to_s}"
+  end
+
+  failure_message_for_should do |klass|
+    "expected #{klass.inspect} to define public instance method " \
+    "#{value.inspect}, but it didn't"
+  end
+
+  failure_message_for_should_not do |klass|
+    "expected #{klass.inspect} to not define public instance method " \
+    "#{value.inspect}, but it did"
+  end
+end

data/spec/rcov.opts

@@ -0,0 +1,8 @@
+--exclude "spec"
+--exclude "activesupport"
+--exclude "rcov"
+--sort coverage
+--callsites
+--xrefs
+--profile
+--text-summary

data/spec/spec.opts

@@ -0,0 +1,4 @@
+--colour
+--loadby random
+--format progress
+--backtrace

data/spec/spec_helper.rb

@@ -0,0 +1,19 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'date' # Used in the CloseTo matcher spec.
+
+require 'rubygems'
+require 'spec'
+require 'spec/autorun'
+
+require 'ward'
+require 'ward/spec'
+
+# Spec libraries.
+spec_libs = Dir.glob(File.expand_path(File.dirname(__FILE__)) + '/lib/**/*.rb')
+spec_libs.each { |file| require file }
+
+Spec::Runner.configure do |config|
+
+end