remarkable 3.0.8 → 3.0.9

data/lib/remarkable/dsl/callbacks.rb

@@ -8,7 +8,16 @@ module Remarkable
 
       module ClassMethods
         protected
-          # Class method that accepts a block or a symbol which is called after initialization.
+          # Class method that accepts a block or a symbol which is called after
+          # initialization.
+          #
+          # == Examples
+          #
+          #   after_initialize :evaluate_given_blocks
+          #
+          #   after_initialize do
+          #     # code
+          #   end
           #
           def after_initialize(symbol=nil, &block)
             if block_given?
@@ -18,7 +27,16 @@ module Remarkable
             end
           end
 
-          # Class method that accepts a block or a symbol which is called before assertion.
+          # Class method that accepts a block or a symbol which is called before
+          # running assertions.
+          #
+          # == Examples
+          #
+          #   before_assert :evaluate_given_blocks
+          #
+          #   before_assert do
+          #     # code
+          #   end
           #
           def before_assert(symbol=nil, &block)
             if block_given?

data/lib/remarkable/dsl/optionals.rb

@@ -1,5 +1,102 @@
 module Remarkable
-  module DSL
+  module DSL
+    # This module is responsable for create optional handlers and providing macro
+    # configration blocks. Consider the matcher below:
+    #
+    #   class AllowValuesForMatcher < Remarkable::ActiveRecord::Base
+    #     arguments :collection => :attributes, :as => :attribute
+    #
+    #     optional :message
+    #     optional :in, :splat => true
+    #     optional :allow_nil, :allow_blank, :default => true
+    #   end
+    #
+    # This allow the matcher to be called as:
+    #
+    #   it { should allow_values_for(:email).in("jose.valim@gmail.com", "jose@another.com").message(:invalid).allow_nil }
+    #
+    # It also allow macros to be configured with blocks:
+    #
+    #   should_allow_values_for :email do |m|
+    #     m.message :invalid
+    #     m.allow_nil
+    #     m.in "jose.valim@gmail.com"
+    #     m.in "jose@another.com"
+    #   end
+    #
+    # Which could be also writen as:
+    #
+    #   should_allow_values_for :email do |m|
+    #     m.message = :invalid
+    #     m.allow_nil = true
+    #     m.in = [ "jose.valim@gmail.com", "jose@another.com" ]
+    #   end
+    #
+    # The difference between the them are: 1) optional= always require an argument
+    # even if :default is given. 2) optional= always overwrite all previous values
+    # even if :splat is given.
+    #
+    # Blocks can be also given when :block => true is set:
+    #
+    #   should_set_session :user_id do |m|
+    #     m.to { @user.id }
+    #   end
+    #
+    # == I18n
+    #
+    # Optionals will be included in description messages if you assign them
+    # properly on your locale file. If you have a validate_uniqueness_of
+    # matcher with the following on your locale file:
+    #
+    #   description: validate uniqueness of {{attributes}}
+    #   optionals:
+    #     scope:
+    #       positive: scoped to {{inspect}}
+    #     case_sensitive:
+    #       positive: case sensitive
+    #       negative: case insensitive
+    #
+    # When invoked like below will generate the following messages:
+    #
+    #   validate_uniqueness_of :project_id, :scope => :company_id
+    #   #=> "validate uniqueness of project_id scoped to :company_id"
+    #
+    #   validate_uniqueness_of :project_id, :scope => :company_id, :case_sensitive => true
+    #   #=> "validate uniqueness of project_id scoped to :company_id and case sensitive"
+    #
+    #   validate_uniqueness_of :project_id, :scope => :company_id, :case_sensitive => false
+    #   #=> "validate uniqueness of project_id scoped to :company_id and case insensitive"
+    #
+    # == Interpolation options
+    #
+    # The default interpolation options available are "inspect" and "value". Whenever
+    # you use :splat => true, it also adds a new interpolation option called {{sentence}}.
+    #
+    # Given the following matcher call:
+    #
+    #   validate_uniqueness_of :id, :scope => [ :company_id, :project_id ]
+    #
+    # The following yml setting and outputs are:
+    #
+    #    scope:
+    #      positive: scoped to {{inspect}}
+    #      # Outputs: "validate uniqueness of project_id scoped to [ :company_id, :project_id ]"
+    #
+    #      positive: scoped to {{value}}
+    #      # Outputs: "validate uniqueness of project_id scoped to company_idproject_id"
+    #
+    #      positive: scoped to {{value}}
+    #      # Outputs: "validate uniqueness of project_id scoped to company_id and project_id"
+    #
+    # == Interpolation keys
+    #
+    # Three keys are available to be used in I18n files and control how optionals
+    # are appended to your description:
+    #
+    #   * <tt>positive</tt> - When the optional is given and it evaluates to true (everything but false and nil).
+    #   * <tt>negative</tt> - When the optional is given and it evaluates to false (false or nil).
+    #   * <tt>not_given</tt> - When the optional is not given.
+    #
     module Optionals
 
       OPTIONAL_KEYS = [ :positive, :negative, :not_given ]
@@ -12,81 +109,66 @@ module Remarkable
 
         protected
 
-          # Creates optional handlers for matchers dynamically. The following
-          # statement:
+          # Creates optional handlers for matchers dynamically.
           #
-          #   optional :range, :default => 0..10
-          #
-          # Will generate:
-          #
-          #   def range(value=0..10)
-          #     @options ||= {}
-          #     @options[:range] = value
-          #     self
-          #   end
-          #
-          # Options:
+          # == Options
           #
           # * <tt>:default</tt> - The default value for this optional
           # * <tt>:alias</tt>  - An alias for this optional
-          # * <tt>:splat</tt>  - Should be true if you expects multiple arguments
-          #
-          # Examples:
-          #
-          #   optional :name, :title
-          #   optional :range, :default => 0..10, :alias => :within
-          #
-          # Optionals will be included in description messages if you assign them
-          # properly on your locale file. If you have a validate_uniqueness_of
-          # matcher with the following on your locale file:
-          #
-          #   description: validate uniqueness of {{attributes}}
-          #   optionals:
-          #     scope:
-          #       positive: scoped to {{value}}
-          #     case_sensitive:
-          #       positive: case sensitive
-          #       negative: case insensitive
-          #
-          # When invoked like below will generate the following messages:
-          #
-          #   validate_uniqueness_of :project_id, :scope => :company_id
-          #   #=> "validate uniqueness of project_id scoped to company_id"
-          #
-          #   validate_uniqueness_of :project_id, :scope => :company_id, :case_sensitive => true
-          #   #=> "validate uniqueness of project_id scoped to company_id and case sensitive"
+          # * <tt>:splat</tt>  - Should be true if you expects multiple arguments
+          # * <tt>:block</tt>  - Tell this optional can also receive blocks
           #
-          #   validate_uniqueness_of :project_id, :scope => :company_id, :case_sensitive => false
-          #   #=> "validate uniqueness of project_id scoped to company_id and case insensitive"
+          # == Examples
           #
-          # The interpolation options available are "value" and "inspect". Where
-          # the first is the optional value transformed into a string and the
-          # second is the inspected value.
+          #   class AllowValuesForMatcher < Remarkable::ActiveRecord::Base
+          #     arguments :collection => :attributes, :as => :attribute
           #
-          # Three keys are available to be used in I18n files and control how
-          # optionals are appended to your description:
-          #
-          #   * <tt>positive</tt> - When the optional is given and it evaluates to true (everything but false and nil).
-          #   * <tt>negative</tt> - When the optional is given and it evaluates to false (false or nil).
-          #   * <tt>not_given</tt> - When the optional is not given.
+          #     optional :message
+          #     optional :in, :splat => true
+          #     optional :allow_nil, :allow_blank, :default => true
+          #   end
           #
           def optionals(*names)
-            options = names.extract_options!
-            @matcher_optionals += names
+            options = names.extract_options!
 
-            splat   = options[:splat]   ? '*' : ''
-            default = options[:default] ? "=#{options[:default].inspect}" : ""
+            @matcher_optionals += names
+            default = options[:default] ? "=#{options[:default].inspect}" : nil
+
+            block = if options[:block]
+              @matcher_optionals_block += names 
+              default ||= "=nil"
+              ', &block'
+            else
+              nil
+            end
+
+            splat = if options[:splat]
+              @matcher_optionals_splat += names
+              '*'
+            else
+              nil
+            end
 
             names.each do |name|
               class_eval <<-END, __FILE__, __LINE__
-                def #{name}(#{splat}value#{default})
-                  @options ||= {}
-                  @options[:#{name}] = value
+                def #{name}(#{splat}value#{default}#{block})
+                  @options ||= {}
+                  #{"@options[:#{name}] ||= []" if splat}
+                  @options[:#{name}] #{:+ if splat}= #{"block ||" if block} value
                   self
+                end
+                def #{name}=(value)
+                  @options ||= {}
+                  @options[:#{name}] = value
+                  self
                 end
               END
-            end
-            class_eval "alias_method(:#{options[:alias]}, :#{names.last})" if options[:alias]
+            end
+
+            class_eval %{
+              alias :#{options[:alias]} :#{names.last}
+              alias :#{options[:alias]}= :#{names.last}=
+            } if options[:alias]
 
             # Call unique to avoid duplicate optionals.
             @matcher_optionals.uniq!
@@ -94,8 +176,8 @@ module Remarkable
           alias :optional :optionals
 
           # Instead of appending, prepend optionals to the beginning of optionals
-          # array. This is important because this decide how the description
-          # message is generated.
+          # array. This is important because the optionals declaration order 
+          # changes how the description message is generated.
           #
           def prepend_optionals(*names)
             current_optionals  = @matcher_optionals.dup
@@ -117,14 +199,20 @@ module Remarkable
 
         optionals = self.class.matcher_optionals.map do |optional|
           if @options.key?(optional)
-            value = @options[optional]
-            defaults = [ (value ? :positive : :negative) ]
+            value = @options[optional]
 
+            defaults = [ (value ? :positive : :negative) ]
             # If optional is a symbol and it's not any to any of the reserved symbols, search for it also
             defaults.unshift(value) if value.is_a?(Symbol) && !OPTIONAL_KEYS.include?(value)
             defaults << ''
 
             options = { :default => defaults, :inspect => value.inspect, :value => value.to_s }
+
+            if self.class.matcher_optionals_splat.include?(optional)
+              value = [ value ] unless Array === value
+              options[:sentence] = array_to_sentence(value, true)
+            end
+
             translate_optionals_with_namespace(optional, defaults.shift, options)
           else
             translate_optionals_with_namespace(optional, :not_given, :default => '')

data/lib/remarkable/i18n.rb

@@ -1,30 +1,53 @@
-# This is a wrapper for I18n default functionality
-module Remarkable
+module Remarkable
+  # This is a wrapper for I18n default functionality.
+  #
+  # Remarkable shouldn't rely on I18n default locale, because it might change
+  # throughout tests. So it's Remarkable responsibility to hold its own locale
+  # and send it to I18n.
+  #
   module I18n
 
-    # Add locale files to I18n and to load path, if it exists.
+    # Add locale files to I18n and to load path, if it exists.
+    #
+    # == Examples
+    #
+    #   Remarkable.add_locale "path/to/locale"
+    #
     def add_locale(*locales)
       ::I18n.backend.load_translations *locales
       ::I18n.load_path += locales if ::I18n.respond_to?(:load_path)
     end
 
-    # Set Remarkable locale (which is not necessarily the same as the application)
+    # Set Remarkable own locale.
+    #
+    # == Examples
+    #
+    #   Remarkable.locale = :en
+    #
     def locale=(locale)
       @@locale = locale
     end
 
-    # Get Remarkable locale (which is not necessarily the same as the application)
+    # Get Remarkable own locale.
+    #
+    # == Examples
+    #
+    #   Remarkable.locale = :en
+    #   Remarkable.locale #=> :en
+    #
     def locale
       @@locale
     end
 
-    # Wrapper for translation
+    # Wrapper for I18n.translate
+    #
     def translate(string, options = {})
       ::I18n.translate string, { :locale => @@locale }.merge(options)
     end
     alias :t :translate
 
-    # Wrapper for localization
+    # Wrapper for I18n.localize
+    #
     def localize(object, options = {})
       ::I18n.localize object, { :locale => @@locale }.merge(options)
     end

data/lib/remarkable/macros.rb

@@ -1,4 +1,7 @@
-module Remarkable
+module Remarkable
+  # This class is responsable for converting matchers to macros. You shouldn't
+  # worry with what happens here, because it happens automatically.
+  #
   module Macros
 
     protected

data/lib/remarkable/matchers.rb

@@ -4,15 +4,23 @@ module Remarkable
   # to include matchers in Test::Unit as well.
   module Matchers; end
 
-  # Helper that includes required Remarkable modules into the given klass.
-  def self.include_matchers!(base, klass)
-    klass.send :extend, Remarkable::Macros
+  # Helper that includes required Remarkable modules into the given klass.
+  #
+  # If the module to be included responds to :after_include, it's called with the
+  # target as argument.
+  #
+  def self.include_matchers!(base, target)
+    target.send :extend, Remarkable::Macros
 
     if defined?(base::Matchers)
-      klass.send :include, base::Matchers
+      target.send :include, base::Matchers
 
       Remarkable::Matchers.send :extend, base::Matchers
       Remarkable::Matchers.send :include, base::Matchers
+    end
+
+    if base.respond_to?(:after_include)
+      base.after_include(target)
     end
   end
 end

data/lib/remarkable/messages.rb

@@ -1,4 +1,7 @@
-module Remarkable
+module Remarkable
+  # Holds the methods required by rspec for each matcher plus a collection of
+  # helpers to deal with I18n.
+  #
   module Messages
 
     # Provides a default description message. Overwrite it if needed.
@@ -77,10 +80,12 @@ module Remarkable
 
       # Converts an array to a sentence
       #
-      def array_to_sentence(array)
+      def array_to_sentence(array, inspect=false)
         words_connector     = Remarkable.t 'remarkable.core.helpers.words_connector'
         two_words_connector = Remarkable.t 'remarkable.core.helpers.two_words_connector'
         last_word_connector = Remarkable.t 'remarkable.core.helpers.last_word_connector'
+
+        array.map!{|i| i.inspect} if inspect
 
         case array.length
           when 0

data/lib/remarkable/pending.rb

@@ -2,7 +2,16 @@ module Remarkable
   module Macros
 
     protected
-
+
+      # Adds a pending block to your specs.
+      #
+      # == Examples
+      #
+      #   pending 'create manager resource' do
+      #     should_have_one :manager
+      #     should_validate_associated :manager
+      #   end
+      #
       def pending(description='TODO', &block)
         PendingSandbox.new(description, self).instance_eval(&block)
       end

data/lib/remarkable/rspec.rb

@@ -1,5 +1,3 @@
-# Hacks into rspec to provide I18n.
-#
 module Spec #:nodoc:
   module Matchers #:nodoc:
     # Overwrites to provide I18n on should and should_not.

data/lib/remarkable/version.rb

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