remarkable 3.0.0

data/CHANGELOG

@@ -0,0 +1,16 @@
+# v3.0.0
+
+* Added Remarkable::Matchers. Now you can include your Remarkable matchers and
+  macros in test unit as well.
+
+    class Test::Unit::TestCase
+      include Spec::Matchers
+      include Remarkable::Matchers
+      extend  Remarkable::Macros
+    end
+
+* Added pending and disabled macros
+* Added I18n
+* Added DSL core structure
+* Added macros core structure
+* Added matchers core structure

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Carlos Brando
+
+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 OR COPYRIGHT HOLDERS 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/README

@@ -0,0 +1,2 @@
+Remarkable
+==========

data/lib/remarkable/base.rb

@@ -0,0 +1,54 @@
+module Remarkable
+  class Base
+    include Remarkable::Messages
+    extend  Remarkable::DSL
+
+    def spec(binding)
+      @spec = binding
+      self
+    end
+
+    private
+
+      # Returns the subject class if it's not one.
+      def subject_class
+        nil unless @subject
+        @subject.is_a?(Class) ? @subject : @subject.class
+      end
+
+      # Returns the subject name based on its class. If the class respond to
+      # human_name (which is usually localized) returns it.
+      def subject_name
+        nil unless @subject
+        subject_class.respond_to?(:human_name) ? subject_class.human_name : subject_class.name
+      end
+
+      # Iterates over the collection given yielding the block and return false
+      # if any of them also returns false.
+      def assert_matcher_for(collection)
+        collection.each do |item|
+          return false unless yield(item)
+        end
+        true
+      end
+
+      # Asserts that the given collection contains item x. If x is a regular
+      # expression, ensure that at least one element from the collection matches x.
+      #
+      #   assert_contains(['a', '1'], /\d/) => passes
+      #   assert_contains(['a', '1'], 'a') => passes
+      #   assert_contains(['a', '1'], /not there/) => fails
+      #
+      def assert_contains(collection, x) # :nodoc:
+        collection = [collection] unless collection.is_a?(Array)
+
+        case x
+          when Regexp
+            collection.detect { |e| e =~ x }
+          else
+            collection.include?(x)
+        end
+      end
+
+  end
+end

data/lib/remarkable/core_ext/array.rb

@@ -0,0 +1,19 @@
+module Remarkable # :nodoc:
+  module CoreExt
+    module Array
+      # Extracts options from a set of arguments. Removes and returns the last
+      # element in the array if it's a hash, otherwise returns a blank hash.
+      #
+      #   def options(*args)
+      #     args.extract_options!
+      #   end
+      #
+      #   options(1, 2)           # => {}
+      #   options(1, 2, :a => :b) # => {:a=>:b}
+      def extract_options!
+        last.is_a?(::Hash) ? pop : {}
+      end
+    end
+  end
+end
+Array.send :include, Remarkable::CoreExt::Array

data/lib/remarkable/dsl/assertions.rb

@@ -0,0 +1,184 @@
+module Remarkable
+  module DSL
+    module Assertions
+
+      protected
+
+        # It sets the arguments your matcher receives on initialization.
+        #
+        #   arguments :name, :range
+        #
+        # Which is roughly the same as:
+        #
+        #   def initialize(name, range, options = {})
+        #     @name    = name
+        #     @range   = range
+        #     @options = options
+        #   end
+        #
+        # But most of the time your matchers iterates through a collection,
+        # such as a collection of attributes in the case below:
+        #
+        #   @product.should validate_presence_of(:title, :name)
+        #
+        # validate_presence_of is a matcher declared as:
+        #
+        #   class ValidatePresenceOfMatcher < Remarkable::Base
+        #     arguments :collection => :attributes
+        #   end
+        #
+        # In this case, Remarkable provides an API that enables you to easily
+        # assert each item of the collection. Let's check more examples:
+        #
+        #   should allow_values_for(:email, "jose@valim.com", "carlos@brando.com")
+        #
+        # Is declared as:
+        #
+        #   arguments :attribute, :collection => :good_values, :as => :good_value
+        #
+        # And this is the same as:
+        #
+        #   class AllowValuesForMatcher < Remarkable::Base
+        #     def initialize(attribute, *good_values)
+        #       @attribute = attribute
+        #       @options = default_options.merge(good_values.extract_options!)
+        #       @good_values = good_values
+        #     end
+        #   end
+        #
+        # Now, the collection is @good_values. In each assertion method we will
+        # have a @good_value variable (in singular) instantiated with the value
+        # to assert.
+        #
+        # Finally, if your matcher deals with blocks, you can also set them as
+        # option:
+        #
+        #   arguments :name, :block => :builder
+        #
+        # It will be available under the instance variable @builder.
+        #
+        def arguments(*names)
+          options = names.extract_options!
+          args = names.dup
+
+          @matcher_arguments[:names] = names
+
+          if collection = options.delete(:collection)
+            @matcher_arguments[:collection] = collection
+
+            if options[:as]
+              @matcher_arguments[:as] = options.delete(:as)
+            else
+              raise ArgumentError, 'You gave me :collection as option but have not give me :as as well'
+            end
+
+            args          << "*#{collection}"
+            get_options    = "#{collection}.extract_options!"
+            set_collection = "@#{collection} = #{collection}"
+          else
+            args          << 'options={}'
+            get_options    = 'options'
+            set_collection = ''
+          end
+
+          if block = options.delete(:block)
+            @matcher_arguments[:block] = block
+            args  << "&#{block}"
+            names << block
+          end
+
+          assignments = names.map do |name|
+            "@#{name} = #{name}"
+          end.join("\n  ")
+
+          class_eval <<-END, __FILE__, __LINE__
+def initialize(#{args.join(',')})
+  #{assignments}
+  @options = default_options.merge(#{get_options})
+  #{set_collection}
+  run_after_initialize_callbacks
+end
+END
+        end
+
+        # Call it to declare your collection assertions. Every method given will
+        # iterate through the whole collection given in <tt>:arguments</tt>.
+        #
+        # For example, validate_presence_of can be written as:
+        #
+        #   class ValidatePresenceOfMatcher < Remarkable::Base
+        #     arguments :collection => :attributes
+        #     collection_assertions :allow_nil?
+        #
+        #     protected
+        #       def allow_nil?
+        #         # matcher logic
+        #       end
+        #   end
+        #
+        # Then we call it as:
+        #
+        #   should validate_presence_of(:email, :password)
+        #
+        # For each attribute given, it will call the method :allow_nil which
+        # contains the matcher logic. As stated in <tt>arguments</tt>, those
+        # attributes will be available under the instance variable @argument
+        # and the matcher subject is available under the instance variable
+        # @subject.
+        #
+        # If a block is given, it will create a method with the name given.
+        # So we could write the same class as above just as:
+        #
+        #   class ValidatePresenceOfMatcher < Remarkable::Base
+        #     arguments :collection => :attributes
+        #
+        #     collection_assertion :allow_nil? do
+        #       # matcher logic
+        #     end
+        #   end
+        #
+        # Those methods should return true if it pass or false if it fails. When
+        # it fails, it will use I18n API to find the proper failure message:
+        #
+        #   expectations:
+        #     allow_nil: allowed the value to be nil
+        #     allow_blank: allowed the value to be blank
+        #
+        # Or you can set the message in the instance variable @expectation in the
+        # assertion method if you don't want to rely on I18n API.
+        #
+        # As you might have noticed from the examples above, this method is also
+        # aliased as <tt>collection_assertion</tt>.
+        #
+        def collection_assertions(*methods, &block)
+          define_method methods.last, &block if block_given?
+          @matcher_collection_assertions += methods
+        end
+        alias :collection_assertion :collection_assertions
+
+        # In contrast to <tt>collection_assertions</tt>, the methods given here
+        # are called just once. In other words, it does not iterate through the
+        # collection given in arguments.
+        #
+        # It also accepts blocks and is aliased as assertion.
+        #
+        def assertions(*methods, &block)
+          define_method methods.last, &block if block_given?
+          @matcher_single_assertions += methods
+        end
+        alias :assertion :assertions
+
+        # Class method that accepts a block or a Hash that will overwrite
+        # instance method default_options.
+        #
+        def default_options(hash = {}, &block)
+          if block_given?
+            define_method :default_options, &block
+          else
+            class_eval "def default_options; #{hash.inspect}; end"
+          end
+        end
+
+    end
+  end
+end

data/lib/remarkable/dsl/callbacks.rb

@@ -0,0 +1,54 @@
+module Remarkable
+  module DSL
+    module Callbacks
+
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+        protected
+          # Class method that accepts a block which is called after initialization.
+          #
+          def after_initialize(symbol=nil, &block)
+            if block_given?
+              @after_initialize_callbacks << block
+            elsif symbol
+              @after_initialize_callbacks << symbol
+            end
+          end
+
+          # Class method that accepts a block which is called before assertion.
+          #
+          def before_assert(symbol=nil, &block)
+            if block_given?
+              @before_assert_callbacks << block
+            elsif symbol
+              @before_assert_callbacks << symbol
+            end
+          end
+      end
+
+      def run_after_initialize_callbacks
+        self.class.after_initialize_callbacks.each do |method|
+          if method.is_a?(Proc)
+            instance_eval &method
+          elsif method.is_a?(Symbol)
+            send(method)
+          end
+        end
+      end
+
+      def run_before_assert_callbacks
+        self.class.before_assert_callbacks.each do |method|
+          if method.is_a?(Proc)
+            instance_eval &method
+          elsif method.is_a?(Symbol)
+            send(method)
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/remarkable/dsl/matches.rb

@@ -0,0 +1,142 @@
+module Remarkable
+  module DSL
+    module Matches
+
+      # For each instance under the collection declared in <tt>arguments</tt>,
+      # this method will call each method declared in <tt>assertions</tt>.
+      #
+      # As an example, let's assume you have the following matcher:
+      #
+      #   arguments  :collection => :attributes
+      #   assertions :allow_nil?, :allow_blank?
+      #
+      # For each attribute in @attributes, we will set the instance variable
+      # @attribute and then call allow_nil? and allow_blank?. Assertions should
+      # return true if it pass or false if it fails. When it fails, it will use
+      # I18n API to find the proper failure message:
+      #
+      #   expectations:
+      #     allow_nil?: allowed the value to be nil
+      #     allow_blank?: allowed the value to be blank
+      #
+      # Or you can set the message in the instance variable @expectation in the
+      # assertion method if you don't want to rely on I18n API.
+      #
+      # This method also call the methods declared in single_assertions. Which
+      # work the same way as assertions, except it doesn't loop for each value in
+      # the collection.
+      #
+      # It also provides a before_assert callback that you might want to use it
+      # to manipulate the subject before the assertions start.
+      #
+      def matches?(subject)
+        @subject = subject
+
+        run_before_assert_callbacks
+
+        send_methods_and_generate_message(self.class.matcher_single_assertions) &&
+        assert_matcher_for(instance_variable_get("@#{self.class.matcher_arguments[:collection]}") || []) do |value|
+          instance_variable_set("@#{self.class.matcher_arguments[:as]}", value)
+          send_methods_and_generate_message(self.class.matcher_collection_assertions)
+        end
+      end
+
+      protected
+
+        # Overwrite to provide default options.
+        #
+        def default_options
+          {}
+        end
+
+        # Overwrites default_i18n_options to provide collection interpolation,
+        # arguments and optionals to interpolation options.
+        #
+        # Their are appended in the reverse order above. So if you have an optional
+        # with the same name as an argument, the argument overwrites the optional.
+        #
+        # All values are provided calling inspect, so what you will have in your
+        # I18n available for interpolation is @options[:allow_nil].inspect.
+        #
+        # If you still need to provide more other interpolation options, you can
+        # do that in two ways:
+        #
+        # 1. Overwrite interpolation_options:
+        #
+        #   def interpolation_options
+        #     { :real_value => real_value }
+        #   end
+        #
+        # 2. Return a hash from your assertion method:
+        #
+        #   def my_assertion
+        #     return true if real_value == expected_value
+        #     return false, :real_value => real_value
+        #   end
+        #
+        # In both cases, :real_value will be available as interpolation option.
+        #
+        def default_i18n_options
+          i18n_options = {}
+
+          @options.each do |key, value|
+            i18n_options[key] = value.inspect
+          end if @options
+
+          # Also add arguments as interpolation options.
+          self.class.matcher_arguments[:names].each do |name|
+            i18n_options[name] = instance_variable_get("@#{name}").inspect
+          end
+
+          # Add collection interpolation options.
+          i18n_options.update(collection_interpolation)
+
+          # Add default options (highest priority). They should not be overwritten.
+          i18n_options.update(super)
+        end
+
+        # Methods that return collection_name and object_name as a Hash for
+        # interpolation.
+        #
+        def collection_interpolation
+          options = {}
+
+          # Add collection to options
+          if collection_name = self.class.matcher_arguments[:collection]
+            collection_name = collection_name.to_sym
+            collection = instance_variable_get("@#{collection_name}")
+            options[collection_name] = array_to_sentence(collection) if collection
+
+            object_name = self.class.matcher_arguments[:as].to_sym
+            object = instance_variable_get("@#{object_name}")
+            options[object_name] = object if object
+          end
+
+          options
+        end
+
+        # Helper that send the methods given and create a expectation message if
+        # any returns false.
+        #
+        # Since most assertion methods ends with an question mark and it's not
+        # readable in yml files, we remove question and exclation marks at the
+        # end of the method name before translating it. So if you have a method
+        # called is_valid? on I18n yml file we will check for a key :is_valid.
+        #
+        def send_methods_and_generate_message(methods)
+          methods.each do |method|
+            bool, hash = send(method)
+
+            unless bool
+              @expectation ||= Remarkable.t "expectations.#{method.to_s.gsub(/(\?|\!)$/, '')}",
+                                            default_i18n_options.merge(hash || {})
+              return false
+            end
+          end
+
+          return true
+        end
+
+    end
+  end
+end