remarkable 3.0.0 → 3.0.1

data/README

@@ -1,2 +1,199 @@
-Remarkable
-==========
+= Remarkable
+
+This is the core package of Remarkable. It provides a DSL for creating matchers
+with I18n support, decoupling messages from matcher's logic and adding rspec
+extra features.
+
+== Macros
+
+Each matcher in Remarkable is also available as a macro. So this matcher:
+
+  it { should validate_presence_of(:name) }
+
+Can also be written as:
+
+  should_validate_presence_of :name
+
+Remarkable adds the possibility to disable macros. So as you could do:
+
+  xit { should validate_presence_of(:name) }
+
+You can also do:
+
+  xshould_validate_presence_of :name
+
+And it will show in your specs output:
+
+  "Example disabled: require name to be set"
+
+== Pending macros
+
+In Rspec you can mark some examples as pending:
+
+  it "should have one manager" do
+    pending("create managers resource")
+  end
+
+  it "should validate associated manager" do
+    pending("create managers resource")
+  end
+
+To allow this to work with macros, we created the pending group:
+
+  pending "create managers resource" do
+    should_have_one :manager
+    should_validate_associated :manager
+  end
+
+This outputs the same as above.
+
+== I18n
+
+All matchers come with I18n support. You can find an example locale file under
+the locale folder of each project.
+
+To change the locale, you have first to add your locale file:
+
+  Remarkable.add_locale 'path/to/my_locale.yml'
+
+And then:
+
+  Remarkable.locale = :my_locale
+
+Internationalization is powered by the I18n gem. If you are using it with Rails,
+it will use the built in gem, otherwise you will have to install the gem by hand:
+
+  gem sources -a http://gems.github.com
+  sudo gem install svenfuchs-i18n
+
+== Creating you own matcher
+
+Create a new matcher is easy. Let's create validate_inclusion_of matcher for
+ActiveRecord as an example. A first matcher version would be:
+
+module Remarkable
+  module ActiveRecord
+    module Matchers
+      class ValidateInclusionOfMatcher < Remarkable::ActiveRecord::Base
+        arguments :attribute
+        assertion :is_valid?
+
+        optional :in
+        optional :allow_blank, :allow_nil, :default => true
+
+        protected
+
+          def is_valid?
+            @options[:in].each do |value|
+              @subject.send(:"#{@attribute}=", value)
+              return false, :value => value unless @subject.valid?
+            end
+            true
+          end
+      end
+
+      def validate_inclusion_of(*args)
+        ValidateInclusionOfMatcher.new(*args).spec(self)
+      end
+    end
+  end
+end
+
+This creates a matcher which requires one attribute and has :in, :allow_blank
+and :allow_nil as options. So you can call the matcher in the following way:
+
+  should_validate_inclusion_of :size, :in => %w(S M L XL)
+  should_validate_inclusion_of :size, :in => %w(S M L XL), :allow_blank => true
+
+  it { should validate_inclusion_of(:size, :in => %w(S M L XL)).allow_nil(true) }
+  it { should validate_inclusion_of(:size, :in => %w(S M L XL)).allow_nil }
+
+  it { should validate_inclusion_of(:size, :in => %w(S M L XL)) }
+  it { should validate_inclusion_of(:size, :in => %w(S M L XL), :allow_nil => true) }
+
+The assertions methods (in this case, :is_valid?) makes the matcher pass when
+it returns true and fail when returns false.
+
+As you noticed, the matcher doesn't have any message on it. You add them on I18n
+file. A file for this example would be:
+
+  remarkable:
+    active_record:
+      validate_inclusion_of:
+        description: "validate inclusion of {{attribute}}"
+        expectations:
+          is_valid: "to be valid when {{attribute}} is {{value}}"
+        optionals:
+          in:
+            positive: "in {{inspect}}"
+          allow_nil:
+            positive: "allowing nil values"
+            negative: "not allowing nil values"
+          allow_blank:
+            positive: "allowing blank values"
+            negative: "allowing blank values"
+
+The optionals are just added to the description message when they are supplied.
+Look some description messages examples:
+
+  should_validate_inclusion_of :size, :in => %w(S M L XL)
+  #=> should validate inclusion of size in ["S", "M", "L", "XL"]
+
+  should_validate_inclusion_of :size, :in => %w(S M L XL), :allow_nil => true
+  #=> should validate inclusion of size in ["S", "M", "L", "XL"] and allowing nil values
+
+  should_validate_inclusion_of :size, :in => %w(S M L XL), :allow_nil => false
+  #=> should validate inclusion of size in ["S", "M", "L", "XL"] and not allowing nil values
+
+Please notice that the arguments are available as interpolation option, as well
+as the optionals.
+
+The expectations message are set whenever one of the assertions returns false.
+In this case, whenever the assertion fails, we are also returning a hash, with
+the value that failed:
+
+  return false, :value => value
+
+This will tell remarkable to make value as interpolation option too.
+
+Whenever you create all your matchers, you tell remarkable to add them to the
+desired rspec example group:
+
+  Remarkable.include_matchers!(Remarkable::ActiveRecord, Spec::Example::ExampleGroup)
+
+== Working with collections
+
+Finally, Remarkable also makes easy to deal with collections. The same matcher
+could be easily extended to accept a collection of attributes instead of just one:
+
+    should_validate_inclusion_of :first_size, :second_size, :in => %w(S M L XL)
+
+For this we have just those two lines:
+
+    arguments :attribute
+    assertion :is_valid?
+
+For:
+
+    arguments :collection => :attributes, :as => :attribute
+    collection_assertion :is_valid?
+
+This means that the collection will be kept in the @attributes instance variable
+and for each value in the collection, it will run the :is_valid? assertion.
+
+Whenever running the assertion, it will also set the @attribute (in singular)
+variable. In your I18n files, you just need to change your description:
+
+      validate_inclusion_of:
+        description: "validate inclusion of {{attributes}}"
+
+And this will output:
+
+  should_validate_inclusion_of :first_size, :second_size, :in => %w(S M L XL)
+  #=> should validate inclusion of first size and second size in ["S", "M", "L", "XL"]
+
+== More
+
+This is just an overview of the API. You can add extra options to interpolation
+by overwriting the interpolation_options methods, you can add callbacks after
+initialize your matcher or before asserting and much more!

data/lib/remarkable.rb

@@ -11,10 +11,8 @@ require File.join(dir, 'remarkable', 'macros')
 require File.join(dir, 'remarkable', 'pending')
 require File.join(dir, 'remarkable', 'core_ext', 'array')
 
-# Loads rspec files only if spec is defined
 if defined?(Spec)
   require File.join(dir, 'remarkable', 'rspec')
 end
 
-# Add Remarkable default locale file
 Remarkable.add_locale File.join(dir, '..', 'locale', 'en.yml')

data/lib/remarkable/base.rb

@@ -2,15 +2,16 @@ module Remarkable
   class Base
     include Remarkable::Messages
     extend  Remarkable::DSL
-
+
+    # Optional to provide spec binding to matchers.
     def spec(binding)
       @spec = binding
       self
     end
 
-    private
+    protected
 
-      # Returns the subject class if it's not one.
+      # Returns the subject class unless it's a class object.
       def subject_class
         nil unless @subject
         @subject.is_a?(Class) ? @subject : @subject.class
@@ -25,7 +26,7 @@ module Remarkable
 
       # Iterates over the collection given yielding the block and return false
       # if any of them also returns false.
-      def assert_matcher_for(collection)
+      def assert_matcher_for(collection) #:nodoc:
         collection.each do |item|
           return false unless yield(item)
         end
@@ -39,7 +40,7 @@ module Remarkable
       #   assert_contains(['a', '1'], 'a') => passes
       #   assert_contains(['a', '1'], /not there/) => fails
       #
-      def assert_contains(collection, x) # :nodoc:
+      def assert_contains(collection, x)
         collection = [collection] unless collection.is_a?(Array)
 
         case x

data/lib/remarkable/dsl.rb

@@ -10,20 +10,19 @@ module Remarkable
       :matcher_collection_assertions, :before_assert_callbacks, :after_initialize_callbacks
     ] unless self.const_defined?(:ATTR_READERS)
 
-    def self.extended(base)
-      # Load modules
+    def self.extended(base) #:nodoc:
       base.extend Assertions
       base.send :include, Callbacks
       base.send :include, Matches
       base.send :include, Optionals
 
-      # Set the default value for matcher_arguments
+      # Initialize matcher_arguments hash with names as an empty array
       base.instance_variable_set('@matcher_arguments', { :names => [] })
     end
 
     # Make Remarkable::Base DSL inheritable.
     #
-    def inherited(base)
+    def inherited(base) #:nodoc:
       base.class_eval do
         class << self
           attr_reader *ATTR_READERS

data/lib/remarkable/dsl/assertions.rb

@@ -24,7 +24,7 @@ module Remarkable
         # validate_presence_of is a matcher declared as:
         #
         #   class ValidatePresenceOfMatcher < Remarkable::Base
-        #     arguments :collection => :attributes
+        #     arguments :collection => :attributes, :as => :attribute
         #   end
         #
         # In this case, Remarkable provides an API that enables you to easily
@@ -107,7 +107,7 @@ END
         # For example, validate_presence_of can be written as:
         #
         #   class ValidatePresenceOfMatcher < Remarkable::Base
-        #     arguments :collection => :attributes
+        #     arguments :collection => :attributes, :as => :attribute
         #     collection_assertions :allow_nil?
         #
         #     protected
@@ -168,8 +168,7 @@ END
         end
         alias :assertion :assertions
 
-        # Class method that accepts a block or a Hash that will overwrite
-        # instance method default_options.
+        # Class method that accepts a block or a hash to set matcher's default options.
         #
         def default_options(hash = {}, &block)
           if block_given?

data/lib/remarkable/dsl/callbacks.rb

@@ -2,13 +2,13 @@ module Remarkable
   module DSL
     module Callbacks
 
-      def self.included(base)
+      def self.included(base) #:nodoc:
         base.extend ClassMethods
       end
 
       module ClassMethods
         protected
-          # Class method that accepts a block which is called after initialization.
+          # Class method that accepts a block or a symbol which is called after initialization.
           #
           def after_initialize(symbol=nil, &block)
             if block_given?
@@ -18,7 +18,7 @@ module Remarkable
             end
           end
 
-          # Class method that accepts a block which is called before assertion.
+          # Class method that accepts a block or a symbol which is called before assertion.
           #
           def before_assert(symbol=nil, &block)
             if block_given?
@@ -29,7 +29,7 @@ module Remarkable
           end
       end
 
-      def run_after_initialize_callbacks
+      def run_after_initialize_callbacks #:nodoc:
         self.class.after_initialize_callbacks.each do |method|
           if method.is_a?(Proc)
             instance_eval &method
@@ -39,7 +39,7 @@ module Remarkable
         end
       end
 
-      def run_before_assert_callbacks
+      def run_before_assert_callbacks #:nodoc:
         self.class.before_assert_callbacks.each do |method|
           if method.is_a?(Proc)
             instance_eval &method

data/lib/remarkable/dsl/matches.rb

@@ -3,7 +3,7 @@ module Remarkable
     module Matches
 
       # For each instance under the collection declared in <tt>arguments</tt>,
-      # this method will call each method declared in <tt>assertions</tt>.
+      # this method will call each method declared in <tt>collection_assertions</tt>.
       #
       # As an example, let's assume you have the following matcher:
       #
@@ -49,14 +49,8 @@ module Remarkable
           {}
         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.
+        # Overwrites default_i18n_options to provide arguments and optionals
+        # to interpolation options.
         #
         # If you still need to provide more other interpolation options, you can
         # do that in two ways:
@@ -76,7 +70,7 @@ module Remarkable
         #
         # In both cases, :real_value will be available as interpolation option.
         #
-        def default_i18n_options
+        def default_i18n_options #:nodoc:
           i18n_options = {}
 
           @options.each do |key, value|
@@ -95,13 +89,11 @@ module Remarkable
           i18n_options.update(super)
         end
 
-        # Methods that return collection_name and object_name as a Hash for
-        # interpolation.
+        # Method responsible to add collection as interpolation.
         #
-        def collection_interpolation
+        def collection_interpolation #:nodoc:
           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}")
@@ -115,15 +107,15 @@ module Remarkable
           options
         end
 
-        # Helper that send the methods given and create a expectation message if
-        # any returns false.
+        # Send the assertion methods given and create a expectation message
+        # if any of those methods 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)
+        def send_methods_and_generate_message(methods) #:nodoc:
           methods.each do |method|
             bool, hash = send(method)
 

data/lib/remarkable/dsl/optionals.rb

@@ -4,7 +4,7 @@ module Remarkable
 
       OPTIONAL_KEYS = [ :positive, :negative, :not_given ]
 
-      def self.included(base)
+      def self.included(base) #:nodoc:
         base.extend ClassMethods
       end
 
@@ -111,7 +111,7 @@ module Remarkable
       # Overwrites description to support optionals. Check <tt>optional</tt> for
       # more information.
       #
-      def description(options={})
+      def description(options={}) #:nodoc:
         message = super(options)
         message.strip!
 

data/lib/remarkable/macros.rb

@@ -3,7 +3,7 @@ module Remarkable
 
     protected
 
-      def method_missing(method_id, *args, &block)
+      def method_missing(method_id, *args, &block) #:nodoc:
         if method_id.to_s =~ /^(should_not|should)_(.+)/
           should_or_should_not_method_missing($1, $2, caller, *args, &block)
         elsif method_id.to_s =~ /^x(should_not|should)_(.+)/
@@ -13,7 +13,7 @@ module Remarkable
         end
       end
 
-      def should_or_should_not_method_missing(should_or_should_not, method, calltrace, *args, &block)
+      def should_or_should_not_method_missing(should_or_should_not, method, calltrace, *args, &block) #:nodoc:
         it {
           begin
             send(should_or_should_not, send(method, *args, &block))
@@ -24,7 +24,7 @@ module Remarkable
         }
       end
 
-      def disabled_method_missing(should_or_should_not, method, *args, &block)
+      def disabled_method_missing(should_or_should_not, method, *args, &block) #:nodoc:
         description = get_description_from_matcher(should_or_should_not, method, *args, &block)
         xexample(description)
       end
@@ -33,7 +33,7 @@ module Remarkable
       # deduct the description from the matcher name, but it will be shown in
       # english.
       #
-      def get_description_from_matcher(should_or_should_not, method, *args, &block)
+      def get_description_from_matcher(should_or_should_not, method, *args, &block) #:nodoc:
         verb = should_or_should_not.to_s.gsub('_', ' ')
 
         desc = Remarkable::Matchers.send(method, *args, &block).spec(self).description

data/lib/remarkable/matchers.rb

@@ -6,7 +6,6 @@ module Remarkable
 
   # Helper that includes required Remarkable modules into the given klass.
   def self.include_matchers!(base, klass)
-    # Add Remarkable macros core module
     klass.send :extend, Remarkable::Macros
 
     if defined?(base::Matchers)

data/lib/remarkable/pending.rb

@@ -7,7 +7,7 @@ module Remarkable
         PendingSandbox.new(description, self).instance_eval(&block)
       end
 
-      class PendingSandbox < Struct.new(:description, :spec)
+      class PendingSandbox < Struct.new(:description, :spec) #:nodoc:
         include Macros
 
         def example(mather_description=nil)

data/lib/remarkable/rspec.rb

@@ -2,7 +2,7 @@
 #
 module Spec #:nodoc:
   module Matchers #:nodoc:
-    # Provides I18n on should and should_not.
+    # Overwrites to provide I18n on should and should_not.
     #
     def self.generated_description
       return nil if last_should.nil?
@@ -13,7 +13,7 @@ module Spec #:nodoc:
 
   module Example #:nodoc:
     module ExampleGroupMethods #:nodoc:
-      # Provides I18n on example disabled message.
+      # Overwrites to provide I18n on example disabled message.
       #
       def xexample(description=nil, opts={}, &block)
         disabled = Remarkable.t 'remarkable.core.example_disabled', :default => 'Example disabled'

data/lib/remarkable/version.rb

@@ -1,3 +1,3 @@
 module Remarkable
-  VERSION = '3.0.0' unless self.const_defined?('VERSION')
+  VERSION = '3.0.1' unless self.const_defined?('VERSION')
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: remarkable
 version: !ruby/object:Gem::Version 
-  version: 3.0.0
+  version: 3.0.1
 platform: ruby
 authors: 
 - Carlos Brando
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-04-09 00:00:00 +02:00
+date: 2009-04-10 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency