ward 0.1.0

data/features/step_definitions/external_validation_steps.rb

@@ -0,0 +1,69 @@
+#
+# The steps in this file are used to test objects
+# which don't include the Validation module.
+#
+
+def validator_set
+  if @validator_set.nil?
+    if @validator_set_definition.nil?
+      raise 'No validator set defined'
+    else
+      @validator_set = Ward::ValidatorSet.build do |object|
+        eval(Array(@validator_set_definition).join("\n"))
+      end
+    end
+  end
+
+  @validator_set
+end
+
+Transform %r{^'(\w+)' scenario$} do |scenario|
+  scenario.to_sym
+end
+
+Given %r{(?:using )?a validation set like} do |definition|
+  @validator_set_definition = definition
+end
+
+Then %r{^the validation set should pass$} do
+  validator_set.valid?(defined_object).should be_true
+  validator_set.validate(defined_object).should be_pass
+end
+
+Then %r{^the validation set should fail$} do
+  validator_set.valid?(defined_object).should be_false
+  validator_set.validate(defined_object).should be_fail
+end
+
+Then %r{^the validation set should pass when using the ('\w+' scenario)$} do |scenario|
+  validator_set.valid?(defined_object, scenario).should be_true
+  validator_set.validate(defined_object, scenario).should be_pass
+end
+
+Then %r{^the validation set should fail when using the ('\w+' scenario)$} do |scenario|
+  validator_set.valid?(defined_object, scenario).should be_false
+  validator_set.validate(defined_object, scenario).should be_fail
+end
+
+Then %r{^there should be no validation errors$} do
+  validator_set.validate(defined_object).errors.should be_empty
+end
+
+Then %r{^the error on '([^']+)' should be '([^']+)'$} do |attribute, msg|
+  result = validator_set.validate(defined_object)
+
+  if msg[0].chr == '/' and msg[-1].chr == '/'
+    # Regexp.
+    result.errors.on(attribute.to_sym).length.should == 1
+    result.errors.on(attribute.to_sym).first.should =~ eval(msg)
+  else
+    # Exact string match.
+    result.errors.on(attribute.to_sym).should == [msg]
+  end
+end
+
+Then %r{^there should be (\S+) validation errors? on '([^']+)'$} do |number, attribute|
+  result = validator_set.validate(defined_object)
+  number = 0 if number == 'no'
+  (result.errors.on(attribute.to_sym) || []).size.should == number.to_i
+end

data/features/step_definitions/generic_validation_steps.rb

@@ -0,0 +1,33 @@
+#
+# Generic Validators =========================================================
+#
+# These steps allow us to write less specific scenarios which simply state
+# that an attribute should or should not be valid, without having to worry
+# what a valid or invalid value actually is.
+#
+# They are used in conjunction with the "the instance '<attribute>' attribute
+# is (in)?valid" steps.
+#
+# We accomplish this by testing that an attribute is equal to the string
+# "valid" -- any other value causes a failure.
+#
+
+When %r{^validating the ('\w+' attribute)$} do |attribute|
+  @validator_set_definition ||= []
+  @validator_set_definition << "object.#{attribute}.is.equal_to('valid')"
+end
+
+When %r{^validating the ('\w+' attribute) in the ('\w+' scenario)$} do |attribute, scenario|
+  @validator_set_definition ||= []
+  @validator_set_definition <<
+    "object.#{attribute}.is.equal_to('valid').scenario(:#{scenario})"
+end
+
+Given %r{^the instance ('\w+' attribute) is valid$} do |attribute|
+  When %{the instance '#{attribute}' attribute is '"valid"'}
+end
+
+Given %r{^the instance ('\w+' attribute) is invalid$} do |attribute|
+  When %{the instance '#{attribute}' attribute is '"invalid"'}
+end
+

data/features/step_definitions/object_definition_steps.rb

@@ -0,0 +1,43 @@
+#
+# The steps in this file are used to build classes and
+# objects which are later validated.
+#
+
+def object_builder
+  # Returns the ObjectBuilder instance for the current feature.
+  @object_builder ||= Ward::Spec::ObjectBuilder.new
+end
+
+def defined_object
+  # Create an oject with the named attributes and values.
+  object_builder.to_instance
+end
+
+Transform %r{^'(\w+[!\?]?)' attribute$} do |attribute|
+  attribute.to_sym
+end
+
+Given %r{^a class with an? ('\w+[!\?]?' attribute)$} do |attribute|
+  Given "the class also has a '#{attribute}' attribute"
+end
+
+Given %r{^the class also has an? ('\w+[!\?]?' attribute)$} do |attribute|
+  object_builder.attributes << attribute
+end
+
+Given %r{^the instance ('\w+[!\?]?' attribute) is '(.*)'$} do |attribute, value|
+  unless object_builder.attributes.include?(attribute)
+    raise "The #{attribute.inspect} attribute was not defined"
+  end
+
+  value = "''" if value =~ /^\s*$/ # Empty string.
+
+  # Attempt to evaluate the value. If the evaluation fails we assume that it
+  # is a string which should be used literally.
+  object_builder.values[attribute] =
+    begin eval(value) ; rescue NameError ; value ; end
+end
+
+Given %r{^the class has behaviour like$} do |behaviour|
+  object_builder.behaviours << behaviour
+end

data/features/support/env.rb

@@ -0,0 +1,12 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '/../../lib'))
+
+require 'time' # Used in the CloseTo matcher features.
+
+require 'spec'
+require 'spec/expectations'
+
+require 'ward'
+require 'ward/spec'
+
+require File.join(File.dirname(__FILE__), '/object_builder')
+require File.join(File.dirname(__FILE__), '/struct')

data/features/support/object_builder.rb

@@ -0,0 +1,33 @@
+module Ward
+  module Spec
+    # An object which allows new attributes and behaviour to be easily
+    # declared, and for validations to be added one at a time.
+    class ObjectBuilder
+
+      attr_reader :attributes, :values, :behaviours
+
+      def initialize
+        @attributes, @values, @behaviours = [], {}, []
+      end
+
+      # Create an oject with the named attributes and values.
+      #
+      # @return [Ward::Spec::Struct]
+      #
+      def to_instance
+        @attributes = [:__placeholder__] if @attributes.empty?
+
+        instance = Ward::Spec::Struct.new(*@attributes).new(
+          *@attributes.map { |attribute| @values[attribute] })
+
+        unless @behaviours.empty?
+          metaclass = (class << instance; self; end)
+          @behaviours.each { |behaviour| metaclass.class_eval(behaviour) }
+        end
+
+        instance
+      end
+
+    end # ObjectBuilder
+  end # Spec
+end # Ward

data/features/support/struct.rb

@@ -0,0 +1,38 @@
+module Ward
+  module Spec
+    # Used in the object definition steps; provides a version of Struct which
+    # does not respond to length or size, and allows the use of predicate and
+    # bang methods.
+    class Struct < ::Struct
+
+      undef_method :length
+      undef_method :size
+
+      def self.new(*orig_attributes)
+        attributes, aliases = [], {}
+
+        orig_attributes.each do |attribute|
+          case attribute.to_s
+            when /^(.+)!$/
+              attributes << "#{$1}_bang".to_sym
+              aliases["#{$1}_bang"] = attribute
+            when /^(.+)\?$/
+              attributes << "#{$1}_predicate".to_sym
+              aliases["#{$1}_predicate"] = attribute
+            else
+              attributes << attribute
+          end
+        end
+
+        struct_class = super(*attributes)
+
+        struct_class.class_eval(aliases.map do |plain, pretty|
+          "alias_method(:#{pretty}, :#{plain}) ; private(:#{plain})"
+        end.join("\n"))
+
+        struct_class
+      end
+
+    end # Struct
+  end # Spec
+end # Ward

data/lang/en.yml

@@ -0,0 +1,56 @@
+---
+
+  generic:
+    inclusive_conjunction: 'and'
+    exclusive_conjunction: 'or'
+    list_seperator:        ','
+
+  acceptance:
+    positive: '%{context} should be accepted'
+    negative: '%{context} should not be accepted'
+
+  close_to:
+    positive: '%{context} should be within %{delta} of %{expected}'
+    negative: '%{context} should not be within %{delta} of %{expected}'
+
+  equal_to:
+    positive: '%{context} should be %{expected}'
+    negative: '%{context} should not be %{expected}'
+
+  exclude:
+    positive: '%{context} should not be one of %{expected}'
+    negative: '%{context} should be one of %{expected}'
+
+  has:
+    eql:
+      positive: '%{context} should have %{expected} %{collection}'
+      negative: '%{context} should not have %{expected} %{collection}'
+    lte:
+      positive: '%{context} should have at most %{expected} %{collection}'
+      negative: '%{context} should not have at most %{expected} %{collection}'
+    gte:
+      positive: '%{context} should have at least %{expected} %{collection}'
+      negative: '%{context} should not have at least %{expected} %{collection}'
+    between:
+      positive: '%{context} should have between %{lower} and %{upper} %{collection}'
+      negative: '%{context} should not have between %{lower} and %{upper} %{collection}'
+
+  include:
+    positive: '%{context} should be %{expected}'
+    negative: '%{context} should not be %{expected}'
+
+  match:
+    positive: '%{context} format is invalid'
+    negative: '%{context} format is invalid'
+
+  nil:
+    positive: '%{context} should be nil'
+    negative: '%{context} should not be nil'
+
+  present:
+    positive: '%{context} should be present'
+    negative: '%{context} should not be present'
+
+  satisfy:
+    positive: '%{context} is invalid'
+    negative: '%{context} is invalid'

data/lib/ward.rb

@@ -0,0 +1,26 @@
+require 'yaml'
+
+# Add Ruby 1.9-style string interpolation.
+require 'active_support/core_ext/string/interpolation'
+
+# Load the ActiveSupport inflector without the String extensions methods.
+require 'active_support/inflector/inflections'
+require 'active_support/inflector/transliterate'
+require 'active_support/inflector/methods'
+require 'active_support/inflections'
+
+# On with the library...
+require 'ward/support'
+require 'ward/context'
+require 'ward/context_chain'
+require 'ward/dsl'
+require 'ward/errors'
+require 'ward/matchers'
+require 'ward/validator'
+require 'ward/validator_set'
+require 'ward/version'
+
+module Ward
+  # Raise when a validator couldn't be built as something was missing.
+  class IncompleteValidator < StandardError; end
+end

data/lib/ward/context.rb

@@ -0,0 +1,70 @@
+module Ward
+  # A class which represents "somewhere" from which a value can be retrieved
+  # for validation.
+  #
+  # A context initialized with a +:length+ attribute assumes that the value
+  # for validation can be retrieved by calling +length+ on the target object.
+  #
+  class Context
+
+    # Returns the name of the attribute to be validated.
+    #
+    # @return [Symbol]
+    #
+    attr_reader :attribute
+
+    # Returns the 'natural name' of the attribute.
+    #
+    # This name is used when generating error messages, since you probably
+    # don't want you end users to be presented with (occasionally) obscure
+    # attribute names.
+    #
+    # @example
+    #   :name     # => Name
+    #   :a_field  # => A field
+    #   :post_id  # => Post
+    #
+    # @return [String]
+    #
+    attr_reader :natural_name
+
+    # Creates a new validator instance.
+    #
+    # @param [#to_sym] attribute
+    #   The name of the attribute to be validated.
+    # @param [*] *context_args
+    #   Arguments to be used when calling the context.
+    # @param [Block] context_block
+    #   A block to be used when calling the context.
+    #
+    def initialize(attribute, *context_args, &context_block)
+      @attribute = attribute.to_sym
+      @context_args, @context_block = context_args, context_block
+
+      @natural_name =
+        ActiveSupport::Inflector.humanize(@attribute.to_s).downcase
+    end
+
+    # Returns the value of the context for the given +target+ object.
+    #
+    # @example
+    #
+    #   Context.new(:length).value('abc')
+    #   # => 3
+    #
+    #   Context.new(:length_as_string) do |target|
+    #     target.length.to_s
+    #   end.value('abc')
+    #   # => '3'
+    #
+    # @param [Object] target
+    #   The object from which the value is to be retrieved.
+    #
+    # @return [Object]
+    #
+    def value(target)
+      target.__send__(@attribute, *@context_args, &@context_block)
+    end
+
+  end # Context
+end # Ward

data/lib/ward/context_chain.rb

@@ -0,0 +1,87 @@
+module Ward
+  # ContextChain combines one or more {Context} instances in order to be able
+  # to retrieve values from composed objects.
+  #
+  # For example, if the chain contains two contexts, the first with a +length+
+  # attribute, and the second with a +to_s+ attribute, the chain would resolve
+  # to calling +target.length.to_s+ in order to retrieve a value for
+  # validation.
+  #
+  class ContextChain
+
+    # Creates a new ContextChain instance.
+    #
+    def initialize
+      @contexts = []
+    end
+
+    # Returns the name of the attribute to be validated.
+    #
+    # Returns the attribute for the first context. If the chain is empty,
+    # :base is always returned.
+    #
+    # @return [Symbol]
+    #
+    # @see Context#attribute
+    #
+    def attribute
+      @contexts.empty? ? :base : @contexts.first.attribute
+    end
+
+    # Returns the 'natural name' of the contained contexts.
+    #
+    # @return [String]
+    #
+    # @see Context#natural_name
+    #
+    def natural_name
+      @contexts.map { |context| context.natural_name }.join(' ')
+    end
+
+    # Returns the value of the chain for the given +target+ object.
+    #
+    # @param [Object] target
+    #   The object from which the value is to be retrieved.
+    #
+    # @return [Object]
+    #
+    def value(target)
+      if @contexts.size > 1
+        resolved = @contexts[0..-2].inject(target) do |intermediate, context|
+          context.value(intermediate) unless intermediate.nil?
+        end
+
+        raise ArgumentError,
+          "Couldn't retrieve a value for #{natural_name.downcase}; " \
+          "something along the way evaluated to nil" if resolved.nil?
+
+        @contexts.last.value(resolved)
+      elsif @contexts.size == 1
+        @contexts.first.value(target)
+      else
+        target
+      end
+    end
+
+    # Returns the contexts contained in the chain as an Array.
+    #
+    # @return [Array<Ward::Context>]
+    #   An array containing the contexts.
+    #
+    def to_a
+      @contexts.dup
+    end
+
+    # Adds a new context to the end of the chain.
+    #
+    # @param [Ward::Context] context
+    #   The context to be added to the chain.
+    #
+    def push(context)
+      @contexts << context
+    end
+
+    alias_method :<<, :push
+
+  end # ContextChain
+end # Ward