opal-rspec-cj 0.4.4

data/vendor_lib/rspec/core/memoized_helpers.rb

@@ -0,0 +1,431 @@
+module RSpec
+  module Core
+    module MemoizedHelpers
+      # @note `subject` was contributed by Joe Ferris to support the one-liner
+      #   syntax embraced by shoulda matchers:
+      #
+      #       describe Widget do
+      #         it { should validate_presence_of(:name) }
+      #       end
+      #
+      #   While the examples below demonstrate how to use `subject`
+      #   explicitly in examples, we recommend that you define a method with
+      #   an intention revealing name instead.
+      #
+      # @example
+      #
+      #   # explicit declaration of subject
+      #   describe Person do
+      #     subject { Person.new(:birthdate => 19.years.ago) }
+      #     it "should be eligible to vote" do
+      #       subject.should be_eligible_to_vote
+      #       # ^ ^ explicit reference to subject not recommended
+      #     end
+      #   end
+      #
+      #   # implicit subject => { Person.new }
+      #   describe Person do
+      #     it "should be eligible to vote" do
+      #       subject.should be_eligible_to_vote
+      #       # ^ ^ explicit reference to subject not recommended
+      #     end
+      #   end
+      #
+      #   # one-liner syntax - should is invoked on subject
+      #   describe Person do
+      #     it { should be_eligible_to_vote }
+      #   end
+      #
+      # @note Because `subject` is designed to create state that is reset between
+      #   each example, and `before(:all)` is designed to setup state that is
+      #   shared across _all_ examples in an example group, `subject` is _not_
+      #   intended to be used in a `before(:all)` hook. RSpec 2.13.1 prints
+      #   a warning when you reference a `subject` from `before(:all)` and we plan
+      #   to have it raise an error in RSpec 3.
+      #
+      # @see #should
+      def subject
+        __memoized.fetch(:subject) do
+          __memoized[:subject] = begin
+            described = described_class || self.class.description
+            Class === described ? described.new : described
+          end
+        end
+      end
+
+      # When `should` is called with no explicit receiver, the call is
+      # delegated to the object returned by `subject`. Combined with an
+      # implicit subject this supports very concise expressions.
+      #
+      # @example
+      #
+      #   describe Person do
+      #     it { should be_eligible_to_vote }
+      #   end
+      #
+      # @see #subject
+      def should(matcher=nil, message=nil)
+        RSpec::Expectations::PositiveExpectationHandler.handle_matcher(subject, matcher, message)
+      end
+
+      # Just like `should`, `should_not` delegates to the subject (implicit or
+      # explicit) of the example group.
+      #
+      # @example
+      #
+      #   describe Person do
+      #     it { should_not be_eligible_to_vote }
+      #   end
+      #
+      # @see #subject
+      def should_not(matcher=nil, message=nil)
+        RSpec::Expectations::NegativeExpectationHandler.handle_matcher(subject, matcher, message)
+      end
+
+      private
+
+      # @private
+      def __memoized
+        @__memoized ||= {}
+      end
+
+      # Used internally to customize the behavior of the
+      # memoized hash when used in a `before(:all)` hook.
+      #
+      # @private
+      class AllHookMemoizedHash
+        def self.isolate_for_all_hook(example_group_instance)
+          hash = self
+
+          example_group_instance.instance_eval do
+            @__memoized = hash
+
+            begin
+              yield
+            ensure
+              @__memoized = nil
+            end
+          end
+        end
+
+        def self.fetch(key, &block)
+          description = if key == :subject
+            "subject"
+          else
+            "let declaration `#{key}`"
+          end
+
+          raise <<-EOS
+#{description} accessed in #{article} #{hook_expression} hook at:
+  #{CallerFilter.first_non_rspec_line}
+
+`let` and `subject` declarations are not intended to be called
+in #{article} #{hook_expression} hook, as they exist to define state that
+is reset between each example, while #{hook_expression} exists to
+#{hook_intention}.
+EOS
+        end
+
+        class Before < self
+          def self.hook_expression
+            "`before(:all)`"
+          end
+
+          def self.article
+            "a"
+          end
+
+          def self.hook_intention
+            "define state that is shared across examples in an example group"
+          end
+        end
+
+        class After < self
+          def self.hook_expression
+            "`after(:all)`"
+          end
+
+          def self.article
+            "an"
+          end
+
+          def self.hook_intention
+            "cleanup state that is shared across examples in an example group"
+          end
+        end
+      end
+
+      def self.included(mod)
+        mod.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Generates a method whose return value is memoized after the first
+        # call. Useful for reducing duplication between examples that assign
+        # values to the same local variable.
+        #
+        # @note `let` _can_ enhance readability when used sparingly (1,2, or
+        #   maybe 3 declarations) in any given example group, but that can
+        #   quickly degrade with overuse. YMMV.
+        #
+        # @note `let` uses an `||=` conditional that has the potential to
+        #   behave in surprising ways in examples that spawn separate threads,
+        #   though we have yet to see this in practice. You've been warned.
+        #
+        # @note Because `let` is designed to create state that is reset between
+        #   each example, and `before(:all)` is designed to setup state that is
+        #   shared across _all_ examples in an example group, `let` is _not_
+        #   intended to be used in a `before(:all)` hook. RSpec 2.13.1 prints
+        #   a warning when you reference a `let` from `before(:all)` and we plan
+        #   to have it raise an error in RSpec 3.
+        #
+        # @example
+        #
+        #   describe Thing do
+        #     let(:thing) { Thing.new }
+        #
+        #     it "does something" do
+        #       # first invocation, executes block, memoizes and returns result
+        #       thing.do_something
+        #
+        #       # second invocation, returns the memoized value
+        #       thing.should be_something
+        #     end
+        #   end
+        def let(name, &block)
+          # We have to pass the block directly to `define_method` to
+          # allow it to use method constructs like `super` and `return`.
+          raise "#let or #subject called without a block" if block.nil?
+          MemoizedHelpers.module_for(self).send(:define_method, name, &block)
+
+          # Apply the memoization. The method has been defined in an ancestor
+          # module so we can use `super` here to get the value.
+          if block.arity == 1
+            define_method(name) { __memoized.fetch(name) { |k| __memoized[k] = super(RSpec.current_example, &nil) } }
+          else
+            define_method(name) { __memoized.fetch(name) { |k| __memoized[k] = super(&nil) } }
+          end
+        end
+
+        # Just like `let`, except the block is invoked by an implicit `before`
+        # hook. This serves a dual purpose of setting up state and providing a
+        # memoized reference to that state.
+        #
+        # @example
+        #
+        #   class Thing
+        #     def self.count
+        #       @count ||= 0
+        #     end
+        #
+        #     def self.count=(val)
+        #       @count += val
+        #     end
+        #
+        #     def self.reset_count
+        #       @count = 0
+        #     end
+        #
+        #     def initialize
+        #       self.class.count += 1
+        #     end
+        #   end
+        #
+        #   describe Thing do
+        #     after(:each) { Thing.reset_count }
+        #
+        #     context "using let" do
+        #       let(:thing) { Thing.new }
+        #
+        #       it "is not invoked implicitly" do
+        #         Thing.count.should eq(0)
+        #       end
+        #
+        #       it "can be invoked explicitly" do
+        #         thing
+        #         Thing.count.should eq(1)
+        #       end
+        #     end
+        #
+        #     context "using let!" do
+        #       let!(:thing) { Thing.new }
+        #
+        #       it "is invoked implicitly" do
+        #         Thing.count.should eq(1)
+        #       end
+        #
+        #       it "returns memoized version on first invocation" do
+        #         thing
+        #         Thing.count.should eq(1)
+        #       end
+        #     end
+        #   end
+        def let!(name, &block)
+          let(name, &block)
+          before { __send__(name) }
+        end
+
+        # Declares a `subject` for an example group which can then be the
+        # implicit receiver (through delegation) of calls to `should`.
+        #
+        # Given a `name`, defines a method with that name which returns the
+        # `subject`. This lets you declare the subject once and access it
+        # implicitly in one-liners and explicitly using an intention revealing
+        # name.
+        #
+        # @param [String,Symbol] name used to define an accessor with an
+        #   intention revealing name
+        # @param block defines the value to be returned by `subject` in examples
+        #
+        # @example
+        #
+        #   describe CheckingAccount, "with $50" do
+        #     subject { CheckingAccount.new(Money.new(50, :USD)) }
+        #     it { should have_a_balance_of(Money.new(50, :USD)) }
+        #     it { should_not be_overdrawn }
+        #   end
+        #
+        #   describe CheckingAccount, "with a non-zero starting balance" do
+        #     subject(:account) { CheckingAccount.new(Money.new(50, :USD)) }
+        #     it { should_not be_overdrawn }
+        #     it "has a balance equal to the starting balance" do
+        #       account.balance.should eq(Money.new(50, :USD))
+        #     end
+        #   end
+        #
+        # @see MemoizedHelpers#should
+        def subject(name=nil, &block)
+          if name
+            let(name, &block)
+            alias_method :subject, name
+
+            self::NamedSubjectPreventSuper.send(:define_method, name) do
+              raise NotImplementedError, "`super` in named subjects is not supported"
+            end
+          else
+            let(:subject, &block)
+          end
+        end
+
+        # Just like `subject`, except the block is invoked by an implicit `before`
+        # hook. This serves a dual purpose of setting up state and providing a
+        # memoized reference to that state.
+        #
+        # @example
+        #
+        #   class Thing
+        #     def self.count
+        #       @count ||= 0
+        #     end
+        #
+        #     def self.count=(val)
+        #       @count += val
+        #     end
+        #
+        #     def self.reset_count
+        #       @count = 0
+        #     end
+        #
+        #     def initialize
+        #       self.class.count += 1
+        #     end
+        #   end
+        #
+        #   describe Thing do
+        #     after(:each) { Thing.reset_count }
+        #
+        #     context "using subject" do
+        #       subject { Thing.new }
+        #
+        #       it "is not invoked implicitly" do
+        #         Thing.count.should eq(0)
+        #       end
+        #
+        #       it "can be invoked explicitly" do
+        #         subject
+        #         Thing.count.should eq(1)
+        #       end
+        #     end
+        #
+        #     context "using subject!" do
+        #       subject!(:thing) { Thing.new }
+        #
+        #       it "is invoked implicitly" do
+        #         Thing.count.should eq(1)
+        #       end
+        #
+        #       it "returns memoized version on first invocation" do
+        #         subject
+        #         Thing.count.should eq(1)
+        #       end
+        #     end
+        #   end
+        def subject!(name=nil, &block)
+          subject(name, &block)
+          before { subject }
+        end
+      end
+
+      # @api private
+      #
+      # Gets the LetDefinitions module. The module is mixed into
+      # the example group and is used to hold all let definitions.
+      # This is done so that the block passed to `let` can be
+      # forwarded directly on to `define_method`, so that all method
+      # constructs (including `super` and `return`) can be used in
+      # a `let` block.
+      #
+      # The memoization is provided by a method definition on the
+      # example group that supers to the LetDefinitions definition
+      # in order to get the value to memoize.
+      def self.module_for(example_group)
+        get_constant_or_yield(example_group, :LetDefinitions) do
+          mod = Module.new do
+            include Module.new {
+              example_group.const_set(:NamedSubjectPreventSuper, self)
+            }
+          end
+
+          example_group.const_set(:LetDefinitions, mod)
+          mod
+        end
+      end
+
+      # @api private
+      def self.define_helpers_on(example_group)
+        example_group.send(:include, module_for(example_group))
+      end
+
+      if Module.method(:const_defined?).arity == 1 # for 1.8
+        # @api private
+        #
+        # Gets the named constant or yields.
+        # On 1.8, const_defined? / const_get do not take into
+        # account the inheritance hierarchy.
+        def self.get_constant_or_yield(example_group, name)
+          if example_group.const_defined?(name)
+            example_group.const_get(name)
+          else
+            yield
+          end
+        end
+      else
+        # @api private
+        #
+        # Gets the named constant or yields.
+        # On 1.9, const_defined? / const_get take into account the
+        # the inheritance by default, and accept an argument to
+        # disable this behavior. It's important that we don't
+        # consider inheritance here; each example group level that
+        # uses a `let` should get its own `LetDefinitions` module.
+        def self.get_constant_or_yield(example_group, name)
+          if example_group.const_defined?(name, (check_ancestors = false))
+            example_group.const_get(name, check_ancestors)
+          else
+            yield
+          end
+        end
+      end
+    end
+  end
+end

data/vendor_lib/rspec/core/metadata.rb

@@ -0,0 +1,313 @@
+module RSpec
+  module Core
+    # Each ExampleGroup class and Example instance owns an instance of
+    # Metadata, which is Hash extended to support lazy evaluation of values
+    # associated with keys that may or may not be used by any example or group.
+    #
+    # In addition to metadata that is used internally, this also stores
+    # user-supplied metadata, e.g.
+    #
+    #     describe Something, :type => :ui do
+    #       it "does something", :slow => true do
+    #         # ...
+    #       end
+    #     end
+    #
+    # `:type => :ui` is stored in the Metadata owned by the example group, and
+    # `:slow => true` is stored in the Metadata owned by the example. These can
+    # then be used to select which examples are run using the `--tag` option on
+    # the command line, or several methods on `Configuration` used to filter a
+    # run (e.g. `filter_run_including`, `filter_run_excluding`, etc).
+    #
+    # @see Example#metadata
+    # @see ExampleGroup.metadata
+    # @see FilterManager
+    # @see Configuration#filter_run_including
+    # @see Configuration#filter_run_excluding
+    class Metadata < Hash
+
+      def self.relative_path(line)
+        line = line.sub(File.expand_path("."), ".")
+        line = line.sub(/\A([^:]+:\d+)$/, '\\1')
+        return nil if line == '-e:1'
+        line
+      rescue SecurityError
+        nil
+      end
+
+      # @private
+      # Used internally to build a hash from an args array.
+      # Symbols are converted into hash keys with a value of `true`.
+      # This is done to support simple tagging using a symbol, rather
+      # than needing to do `:symbol => true`.
+      def self.build_hash_from(args)
+        hash = args.last.is_a?(Hash) ? args.pop : {}
+
+        while args.last.is_a?(Symbol)
+          hash[args.pop] = true
+        end
+
+        hash
+      end
+
+      module MetadataHash
+
+        # @private
+        # Supports lazy evaluation of some values. Extended by
+        # ExampleMetadataHash and GroupMetadataHash, which get mixed in to
+        # Metadata for ExampleGroups and Examples (respectively).
+        def [](key)
+          store_computed(key) unless has_key?(key)
+          super
+        end
+
+        def fetch(key, *args)
+          store_computed(key) unless has_key?(key)
+          super
+        end
+
+        private
+
+        def store_computed(key)
+          case key
+          when :location
+            store(:location, location)
+          when :file_path, :line_number
+            file_path, line_number = file_and_line_number
+            store(:file_path, file_path)
+            store(:line_number, line_number)
+          when :execution_result
+            store(:execution_result, {})
+          when :describes, :described_class
+            klass = described_class
+            store(:described_class, klass)
+            # TODO (2011-11-07 DC) deprecate :describes as a key
+            store(:describes, klass)
+          when :full_description
+            store(:full_description, full_description)
+          when :description
+            store(:description, build_description_from(*self[:description_args]))
+          when :description_args
+            store(:description_args, [])
+          end
+        end
+
+        def location
+          "#{self[:file_path]}:#{self[:line_number]}"
+        end
+
+        def file_and_line_number
+          first_caller_from_outside_rspec =~ /(.+?):(\d+)(|:\d+)/
+          return [Metadata::relative_path($1), $2.to_i]
+        end
+
+        def first_caller_from_outside_rspec
+          self[:caller].detect {|l| l !~ /\/lib\/rspec\/core/}
+        end
+
+        def method_description_after_module?(parent_part, child_part)
+          return false unless parent_part.is_a?(Module)
+          child_part =~ /^(#|::|\.)/
+        end
+
+        def build_description_from(first_part = '', *parts)
+          description, _ = parts.inject([first_part.to_s, first_part]) do |(desc, last_part), this_part|
+            this_part = this_part.to_s
+            this_part = (' ' + this_part) unless method_description_after_module?(last_part, this_part)
+            [(desc + this_part), this_part]
+          end
+
+          description
+        end
+      end
+
+      # Mixed in to Metadata for an Example (extends MetadataHash) to support
+      # lazy evaluation of some values.
+      module ExampleMetadataHash
+        include MetadataHash
+
+        def described_class
+          self[:example_group].described_class
+        end
+
+        def full_description
+          build_description_from(self[:example_group][:full_description], *self[:description_args])
+        end
+      end
+
+      # Mixed in to Metadata for an ExampleGroup (extends MetadataHash) to
+      # support lazy evaluation of some values.
+      module GroupMetadataHash
+        include MetadataHash
+
+        def described_class
+          container_stack.each do |g|
+            [:described_class, :describes].each do |key|
+              if g.has_key?(key)
+                value = g[key]
+                return value unless value.nil?
+              end
+            end
+          end
+
+          container_stack.reverse.each do |g|
+            candidate = g[:description_args].first
+            return candidate unless String === candidate || Symbol === candidate
+          end
+
+          nil
+        end
+
+        def full_description
+          build_description_from(*FlatMap.flat_map(container_stack.reverse) {|a| a[:description_args]})
+        end
+
+        def container_stack
+          @container_stack ||= begin
+                                 groups = [group = self]
+                                 while group.has_key?(:example_group)
+                                   groups << group[:example_group]
+                                   group = group[:example_group]
+                                 end
+                                 groups
+                               end
+        end
+      end
+
+      def initialize(parent_group_metadata=nil)
+        if parent_group_metadata
+          update(parent_group_metadata)
+          store(:example_group, {:example_group => parent_group_metadata[:example_group].extend(GroupMetadataHash)}.extend(GroupMetadataHash))
+        else
+          store(:example_group, {}.extend(GroupMetadataHash))
+        end
+
+        yield self if block_given?
+      end
+
+      # @private
+      def process(*args)
+        user_metadata = args.last.is_a?(Hash) ? args.pop : {}
+        ensure_valid_keys(user_metadata)
+
+        self[:example_group].store(:description_args, args)
+        self[:example_group].store(:caller, user_metadata.delete(:caller) || caller)
+
+        update(user_metadata)
+      end
+
+      # @private
+      def for_example(description, user_metadata)
+        dup.extend(ExampleMetadataHash).configure_for_example(description, user_metadata)
+      end
+
+      # @private
+      def any_apply?(filters)
+        filters.any? {|k,v| filter_applies?(k,v)}
+      end
+
+      # @private
+      def all_apply?(filters)
+        filters.all? {|k,v| filter_applies?(k,v)}
+      end
+
+      # @private
+      def filter_applies?(key, value, metadata=self)
+        return metadata.filter_applies_to_any_value?(key, value) if Array === metadata[key] && !(Proc === value)
+        return metadata.line_number_filter_applies?(value)       if key == :line_numbers
+        return metadata.location_filter_applies?(value)          if key == :locations
+        return metadata.filters_apply?(key, value)               if Hash === value
+
+        return false unless metadata.has_key?(key)
+
+        case value
+        when Regexp
+          metadata[key] =~ value
+        when Proc
+          case value.arity
+          when 0 then value.call
+          when 2 then value.call(metadata[key], metadata)
+          else value.call(metadata[key])
+          end
+        else
+          metadata[key].to_s == value.to_s
+        end
+      end
+
+      # @private
+      def filters_apply?(key, value)
+        value.all? {|k, v| filter_applies?(k, v, self[key])}
+      end
+
+      # @private
+      def filter_applies_to_any_value?(key, value)
+        self[key].any? {|v| filter_applies?(key, v, {key => value})}
+      end
+
+      # @private
+      def location_filter_applies?(locations)
+        # it ignores location filters for other files
+        line_number = example_group_declaration_line(locations)
+        line_number ? line_number_filter_applies?(line_number) : true
+      end
+
+      # @private
+      def line_number_filter_applies?(line_numbers)
+        preceding_declaration_lines = line_numbers.map {|n| RSpec.world.preceding_declaration_line(n)}
+        !(relevant_line_numbers & preceding_declaration_lines).empty?
+      end
+
+      protected
+
+      def configure_for_example(description, user_metadata)
+        store(:description_args, [description]) if description
+        store(:caller, user_metadata.delete(:caller) || caller)
+        update(user_metadata)
+      end
+
+      private
+
+      RESERVED_KEYS = [
+        :description,
+        :example_group,
+        :execution_result,
+        :file_path,
+        :full_description,
+        :line_number,
+        :location
+      ]
+
+      def ensure_valid_keys(user_metadata)
+        RESERVED_KEYS.each do |key|
+          if user_metadata.has_key?(key)
+            raise <<-EOM
+            #{"*"*50}
+:#{key} is not allowed
+
+RSpec reserves some hash keys for its own internal use,
+including :#{key}, which is used on:
+
+            #{CallerFilter.first_non_rspec_line}.
+
+Here are all of RSpec's reserved hash keys:
+
+            #{RESERVED_KEYS.join("\n  ")}
+            #{"*"*50}
+            EOM
+          end
+        end
+      end
+
+      def example_group_declaration_line(locations)
+        locations[File.expand_path(self[:example_group][:file_path])] if self[:example_group]
+      end
+
+      # TODO - make this a method on metadata - the problem is
+      # metadata[:example_group] is not always a kind of GroupMetadataHash.
+      def relevant_line_numbers(metadata=self)
+        [metadata[:line_number]] + (metadata[:example_group] ? relevant_line_numbers(metadata[:example_group]) : [])
+      end
+
+    end
+  end
+end