dwolla_swagger 1.0.5 → 1.0.6

data/vendor/bundle/ruby/2.2.0/gems/rspec-core-3.4.1/lib/rspec/core/formatters/snippet_extractor.rb

@@ -0,0 +1,143 @@
+RSpec::Support.require_rspec_core "source"
+
+module RSpec
+  module Core
+    module Formatters
+      # @private
+      class SnippetExtractor
+        NoSuchFileError = Class.new(StandardError)
+        NoSuchLineError = Class.new(StandardError)
+
+        def self.extract_line_at(file_path, line_number)
+          source = source_from_file(file_path)
+          line = source.lines[line_number - 1]
+          raise NoSuchLineError unless line
+          line
+        end
+
+        def self.source_from_file(path)
+          raise NoSuchFileError unless File.exist?(path)
+          RSpec.world.source_cache.source_from_file(path)
+        end
+
+        if RSpec::Support::RubyFeatures.ripper_supported?
+          NoExpressionAtLineError = Class.new(StandardError)
+
+          PAREN_TOKEN_TYPE_PAIRS = {
+            :on_lbracket    => :on_rbracket,
+            :on_lparen      => :on_rparen,
+            :on_lbrace      => :on_rbrace,
+            :on_heredoc_beg => :on_heredoc_end
+          }
+
+          attr_reader :source, :beginning_line_number, :max_line_count
+
+          def self.extract_expression_lines_at(file_path, beginning_line_number, max_line_count=nil)
+            if max_line_count == 1
+              [extract_line_at(file_path, beginning_line_number)]
+            else
+              source = source_from_file(file_path)
+              new(source, beginning_line_number, max_line_count).expression_lines
+            end
+          end
+
+          def initialize(source, beginning_line_number, max_line_count=nil)
+            @source = source
+            @beginning_line_number = beginning_line_number
+            @max_line_count = max_line_count
+          end
+
+          def expression_lines
+            line_range = line_range_of_expression
+
+            if max_line_count && line_range.count > max_line_count
+              line_range = (line_range.begin)..(line_range.begin + max_line_count - 1)
+            end
+
+            source.lines[(line_range.begin - 1)..(line_range.end - 1)]
+          rescue SyntaxError, NoExpressionAtLineError
+            [self.class.extract_line_at(source.path, beginning_line_number)]
+          end
+
+          private
+
+          def line_range_of_expression
+            @line_range_of_expression ||= begin
+              line_range = line_range_of_location_nodes_in_expression
+              initial_unclosed_parens = unclosed_paren_tokens_in_line_range(line_range)
+              unclosed_parens = initial_unclosed_parens
+
+              until (initial_unclosed_parens & unclosed_parens).empty?
+                line_range = (line_range.begin)..(line_range.end + 1)
+                unclosed_parens = unclosed_paren_tokens_in_line_range(line_range)
+              end
+
+              line_range
+            end
+          end
+
+          def unclosed_paren_tokens_in_line_range(line_range)
+            tokens = FlatMap.flat_map(line_range) do |line_number|
+              source.tokens_by_line_number[line_number]
+            end
+
+            tokens.each_with_object([]) do |token, unclosed_tokens|
+              if PAREN_TOKEN_TYPE_PAIRS.keys.include?(token.type)
+                unclosed_tokens << token
+              else
+                index = unclosed_tokens.rindex do |unclosed_token|
+                  PAREN_TOKEN_TYPE_PAIRS[unclosed_token.type] == token.type
+                end
+                unclosed_tokens.delete_at(index) if index
+              end
+            end
+          end
+
+          def line_range_of_location_nodes_in_expression
+            line_numbers = expression_node.each_with_object(Set.new) do |node, set|
+              set << node.location.line if node.location
+            end
+
+            line_numbers.min..line_numbers.max
+          end
+
+          def expression_node
+            raise NoExpressionAtLineError if location_nodes_at_beginning_line.empty?
+
+            @expression_node ||= begin
+              common_ancestor_nodes = location_nodes_at_beginning_line.map do |node|
+                node.each_ancestor.to_a
+              end.reduce(:&)
+
+              common_ancestor_nodes.find { |node| expression_outmost_node?(node) }
+            end
+          end
+
+          def expression_outmost_node?(node)
+            return true unless node.parent
+            return false if node.type.to_s.start_with?('@')
+            ![node, node.parent].all? do |n|
+              # See `Ripper::PARSER_EVENTS` for the complete list of sexp types.
+              type = n.type.to_s
+              type.end_with?('call') || type.start_with?('method_add_')
+            end
+          end
+
+          def location_nodes_at_beginning_line
+            source.nodes_by_line_number[beginning_line_number]
+          end
+        else
+          # :nocov:
+          def self.extract_expression_lines_at(file_path, beginning_line_number, *)
+            [extract_line_at(file_path, beginning_line_number)]
+          end
+          # :nocov:
+        end
+
+        def self.least_indentation_from(lines)
+          lines.map { |line| line[/^[ \t]*/] }.min
+        end
+      end
+    end
+  end
+end

data/vendor/bundle/ruby/2.2.0/gems/rspec-core-3.4.1/lib/rspec/core/formatters.rb

@@ -0,0 +1,255 @@
+RSpec::Support.require_rspec_support "directory_maker"
+# ## Built-in Formatters
+#
+# * progress (default) - Prints dots for passing examples, `F` for failures, `*`
+#                        for pending.
+# * documentation - Prints the docstrings passed to `describe` and `it` methods
+#                   (and their aliases).
+# * html
+# * json - Useful for archiving data for subsequent analysis.
+#
+# The progress formatter is the default, but you can choose any one or more of
+# the other formatters by passing with the `--format` (or `-f` for short)
+# command-line option, e.g.
+#
+#     rspec --format documentation
+#
+# You can also send the output of multiple formatters to different streams, e.g.
+#
+#     rspec --format documentation --format html --out results.html
+#
+# This example sends the output of the documentation formatter to `$stdout`, and
+# the output of the html formatter to results.html.
+#
+# ## Custom Formatters
+#
+# You can tell RSpec to use a custom formatter by passing its path and name to
+# the `rspec` commmand. For example, if you define MyCustomFormatter in
+# path/to/my_custom_formatter.rb, you would type this command:
+#
+#     rspec --require path/to/my_custom_formatter.rb --format MyCustomFormatter
+#
+# The reporter calls every formatter with this protocol:
+#
+# * To start
+#   * `start(StartNotification)`
+# * Once per example group
+#   * `example_group_started(GroupNotification)`
+# * Once per example
+#   * `example_started(ExampleNotification)`
+# * One of these per example, depending on outcome
+#   * `example_passed(ExampleNotification)`
+#   * `example_failed(FailedExampleNotification)`
+#   * `example_pending(ExampleNotification)`
+# * Optionally at any time
+#   * `message(MessageNotification)`
+# * At the end of the suite
+#   * `stop(ExamplesNotification)`
+#   * `start_dump(NullNotification)`
+#   * `dump_pending(ExamplesNotification)`
+#   * `dump_failures(ExamplesNotification)`
+#   * `dump_summary(SummaryNotification)`
+#   * `seed(SeedNotification)`
+#   * `close(NullNotification)`
+#
+# Only the notifications to which you subscribe your formatter will be called
+# on your formatter. To subscribe your formatter use:
+# `RSpec::Core::Formatters#register` e.g.
+#
+# `RSpec::Core::Formatters.register FormatterClassName, :example_passed, :example_failed`
+#
+# We recommend you implement the methods yourself; for simplicity we provide the
+# default formatter output via our notification objects but if you prefer you
+# can subclass `RSpec::Core::Formatters::BaseTextFormatter` and override the
+# methods you wish to enhance.
+#
+# @see RSpec::Core::Formatters::BaseTextFormatter
+# @see RSpec::Core::Reporter
+module RSpec::Core::Formatters
+  autoload :DocumentationFormatter,   'rspec/core/formatters/documentation_formatter'
+  autoload :HtmlFormatter,            'rspec/core/formatters/html_formatter'
+  autoload :FallbackMessageFormatter, 'rspec/core/formatters/fallback_message_formatter'
+  autoload :ProgressFormatter,        'rspec/core/formatters/progress_formatter'
+  autoload :ProfileFormatter,         'rspec/core/formatters/profile_formatter'
+  autoload :JsonFormatter,            'rspec/core/formatters/json_formatter'
+  autoload :BisectFormatter,          'rspec/core/formatters/bisect_formatter'
+  autoload :ExceptionPresenter,       'rspec/core/formatters/exception_presenter'
+
+  # Register the formatter class
+  # @param formatter_class [Class] formatter class to register
+  # @param notifications [Symbol, ...] one or more notifications to be
+  #   registered to the specified formatter
+  #
+  # @see RSpec::Core::Formatters::BaseFormatter
+  def self.register(formatter_class, *notifications)
+    Loader.formatters[formatter_class] = notifications
+  end
+
+  # @api private
+  #
+  # `RSpec::Core::Formatters::Loader` is an internal class for
+  # managing formatters used by a particular configuration. It is
+  # not expected to be used directly, but only through the configuration
+  # interface.
+  class Loader
+    # @api private
+    #
+    # Internal formatters are stored here when loaded.
+    def self.formatters
+      @formatters ||= {}
+    end
+
+    # @api private
+    def initialize(reporter)
+      @formatters = []
+      @reporter = reporter
+      self.default_formatter = 'progress'
+    end
+
+    # @return [Array] the loaded formatters
+    attr_reader :formatters
+
+    # @return [Reporter] the reporter
+    attr_reader :reporter
+
+    # @return [String] the default formatter to setup, defaults to `progress`
+    attr_accessor :default_formatter
+
+    # @private
+    def setup_default(output_stream, deprecation_stream)
+      add default_formatter, output_stream if @formatters.empty?
+
+      unless @formatters.any? { |formatter| DeprecationFormatter === formatter }
+        add DeprecationFormatter, deprecation_stream, output_stream
+      end
+
+      unless existing_formatter_implements?(:message)
+        add FallbackMessageFormatter, output_stream
+      end
+
+      return unless RSpec.configuration.profile_examples?
+
+      @reporter.setup_profiler
+
+      return if existing_formatter_implements?(:dump_profile)
+
+      add RSpec::Core::Formatters::ProfileFormatter, output_stream
+    end
+
+    # @private
+    def add(formatter_to_use, *paths)
+      formatter_class = find_formatter(formatter_to_use)
+
+      args = paths.map { |p| p.respond_to?(:puts) ? p : file_at(p) }
+
+      if !Loader.formatters[formatter_class].nil?
+        formatter = formatter_class.new(*args)
+        register formatter, notifications_for(formatter_class)
+      elsif defined?(RSpec::LegacyFormatters)
+        formatter = RSpec::LegacyFormatters.load_formatter formatter_class, *args
+        register formatter, formatter.notifications
+      else
+        call_site = "Formatter added at: #{::RSpec::CallerFilter.first_non_rspec_line}"
+
+        RSpec.warn_deprecation <<-WARNING.gsub(/\s*\|/, ' ')
+          |The #{formatter_class} formatter uses the deprecated formatter
+          |interface not supported directly by RSpec 3.
+          |
+          |To continue to use this formatter you must install the
+          |`rspec-legacy_formatters` gem, which provides support
+          |for legacy formatters or upgrade the formatter to a
+          |compatible version.
+          |
+          |#{call_site}
+        WARNING
+      end
+    end
+
+  private
+
+    def find_formatter(formatter_to_use)
+      built_in_formatter(formatter_to_use) ||
+      custom_formatter(formatter_to_use)   ||
+      (raise ArgumentError, "Formatter '#{formatter_to_use}' unknown - " \
+                            "maybe you meant 'documentation' or 'progress'?.")
+    end
+
+    def register(formatter, notifications)
+      return if duplicate_formatter_exists?(formatter)
+      @reporter.register_listener formatter, *notifications
+      @formatters << formatter
+      formatter
+    end
+
+    def duplicate_formatter_exists?(new_formatter)
+      @formatters.any? do |formatter|
+        formatter.class == new_formatter.class && formatter.output == new_formatter.output
+      end
+    end
+
+    def existing_formatter_implements?(notification)
+      @reporter.registered_listeners(notification).any?
+    end
+
+    def built_in_formatter(key)
+      case key.to_s
+      when 'd', 'doc', 'documentation'
+        DocumentationFormatter
+      when 'h', 'html'
+        HtmlFormatter
+      when 'p', 'progress'
+        ProgressFormatter
+      when 'j', 'json'
+        JsonFormatter
+      when 'bisect'
+        BisectFormatter
+      end
+    end
+
+    def notifications_for(formatter_class)
+      formatter_class.ancestors.inject(::RSpec::Core::Set.new) do |notifications, klass|
+        notifications.merge Loader.formatters.fetch(klass) { ::RSpec::Core::Set.new }
+      end
+    end
+
+    def custom_formatter(formatter_ref)
+      if Class === formatter_ref
+        formatter_ref
+      elsif string_const?(formatter_ref)
+        begin
+          formatter_ref.gsub(/^::/, '').split('::').inject(Object) { |a, e| a.const_get e }
+        rescue NameError
+          require(path_for(formatter_ref)) ? retry : raise
+        end
+      end
+    end
+
+    def string_const?(str)
+      str.is_a?(String) && /\A[A-Z][a-zA-Z0-9_:]*\z/ =~ str
+    end
+
+    def path_for(const_ref)
+      underscore_with_fix_for_non_standard_rspec_naming(const_ref)
+    end
+
+    def underscore_with_fix_for_non_standard_rspec_naming(string)
+      underscore(string).sub(%r{(^|/)r_spec($|/)}, '\\1rspec\\2')
+    end
+
+    # activesupport/lib/active_support/inflector/methods.rb, line 48
+    def underscore(camel_cased_word)
+      word = camel_cased_word.to_s.dup
+      word.gsub!(/::/, '/')
+      word.gsub!(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+      word.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+      word.tr!("-", "_")
+      word.downcase!
+      word
+    end
+
+    def file_at(path)
+      RSpec::Support::DirectoryMaker.mkdir_p(File.dirname(path))
+      File.new(path, 'w')
+    end
+  end
+end

data/vendor/bundle/ruby/2.2.0/gems/rspec-core-3.4.1/lib/rspec/core/hooks.rb

@@ -0,0 +1,638 @@
+module RSpec
+  module Core
+    # Provides `before`, `after` and `around` hooks as a means of
+    # supporting common setup and teardown. This module is extended
+    # onto {ExampleGroup}, making the methods available from any `describe`
+    # or `context` block and included in {Configuration}, making them
+    # available off of the configuration object to define global setup
+    # or teardown logic.
+    module Hooks
+      # @api public
+      #
+      # @overload before(&block)
+      # @overload before(scope, &block)
+      #   @param scope [Symbol] `:example`, `:context`, or `:suite`
+      #     (defaults to `:example`)
+      # @overload before(scope, conditions, &block)
+      #   @param scope [Symbol] `:example`, `:context`, or `:suite`
+      #     (defaults to `:example`)
+      #   @param conditions [Hash]
+      #     constrains this hook to examples matching these conditions e.g.
+      #     `before(:example, :ui => true) { ... }` will only run with examples
+      #     or groups declared with `:ui => true`.
+      # @overload before(conditions, &block)
+      #   @param conditions [Hash]
+      #     constrains this hook to examples matching these conditions e.g.
+      #     `before(:example, :ui => true) { ... }` will only run with examples
+      #     or groups declared with `:ui => true`.
+      #
+      # @see #after
+      # @see #around
+      # @see ExampleGroup
+      # @see SharedContext
+      # @see SharedExampleGroup
+      # @see Configuration
+      #
+      # Declare a block of code to be run before each example (using `:example`)
+      # or once before any example (using `:context`). These are usually
+      # declared directly in the {ExampleGroup} to which they apply, but they
+      # can also be shared across multiple groups.
+      #
+      # You can also use `before(:suite)` to run a block of code before any
+      # example groups are run. This should be declared in {RSpec.configure}.
+      #
+      # Instance variables declared in `before(:example)` or `before(:context)`
+      # are accessible within each example.
+      #
+      # ### Order
+      #
+      # `before` hooks are stored in three scopes, which are run in order:
+      # `:suite`, `:context`, and `:example`. They can also be declared in
+      # several different places: `RSpec.configure`, a parent group, the current
+      # group. They are run in the following order:
+      #
+      #     before(:suite)    # Declared in RSpec.configure.
+      #     before(:context)  # Declared in RSpec.configure.
+      #     before(:context)  # Declared in a parent group.
+      #     before(:context)  # Declared in the current group.
+      #     before(:example)  # Declared in RSpec.configure.
+      #     before(:example)  # Declared in a parent group.
+      #     before(:example)  # Declared in the current group.
+      #
+      # If more than one `before` is declared within any one scope, they are run
+      # in the order in which they are declared.
+      #
+      # ### Conditions
+      #
+      # When you add a conditions hash to `before(:example)` or
+      # `before(:context)`, RSpec will only apply that hook to groups or
+      # examples that match the conditions. e.g.
+      #
+      #     RSpec.configure do |config|
+      #       config.before(:example, :authorized => true) do
+      #         log_in_as :authorized_user
+      #       end
+      #     end
+      #
+      #     describe Something, :authorized => true do
+      #       # The before hook will run in before each example in this group.
+      #     end
+      #
+      #     describe SomethingElse do
+      #       it "does something", :authorized => true do
+      #         # The before hook will run before this example.
+      #       end
+      #
+      #       it "does something else" do
+      #         # The hook will not run before this example.
+      #       end
+      #     end
+      #
+      # Note that filtered config `:context` hooks can still be applied
+      # to individual examples that have matching metadata. Just like
+      # Ruby's object model is that every object has a singleton class
+      # which has only a single instance, RSpec's model is that every
+      # example has a singleton example group containing just the one
+      # example.
+      #
+      # ### Warning: `before(:suite, :with => :conditions)`
+      #
+      # The conditions hash is used to match against specific examples. Since
+      # `before(:suite)` is not run in relation to any specific example or
+      # group, conditions passed along with `:suite` are effectively ignored.
+      #
+      # ### Exceptions
+      #
+      # When an exception is raised in a `before` block, RSpec skips any
+      # subsequent `before` blocks and the example, but runs all of the
+      # `after(:example)` and `after(:context)` hooks.
+      #
+      # ### Warning: implicit before blocks
+      #
+      # `before` hooks can also be declared in shared contexts which get
+      # included implicitly either by you or by extension libraries. Since
+      # RSpec runs these in the order in which they are declared within each
+      # scope, load order matters, and can lead to confusing results when one
+      # before block depends on state that is prepared in another before block
+      # that gets run later.
+      #
+      # ### Warning: `before(:context)`
+      #
+      # It is very tempting to use `before(:context)` to speed things up, but we
+      # recommend that you avoid this as there are a number of gotchas, as well
+      # as things that simply don't work.
+      #
+      # #### Context
+      #
+      # `before(:context)` is run in an example that is generated to provide
+      # group context for the block.
+      #
+      # #### Instance variables
+      #
+      # Instance variables declared in `before(:context)` are shared across all
+      # the examples in the group. This means that each example can change the
+      # state of a shared object, resulting in an ordering dependency that can
+      # make it difficult to reason about failures.
+      #
+      # #### Unsupported RSpec constructs
+      #
+      # RSpec has several constructs that reset state between each example
+      # automatically. These are not intended for use from within
+      # `before(:context)`:
+      #
+      #   * `let` declarations
+      #   * `subject` declarations
+      #   * Any mocking, stubbing or test double declaration
+      #
+      # ### other frameworks
+      #
+      # Mock object frameworks and database transaction managers (like
+      # ActiveRecord) are typically designed around the idea of setting up
+      # before an example, running that one example, and then tearing down. This
+      # means that mocks and stubs can (sometimes) be declared in
+      # `before(:context)`, but get torn down before the first real example is
+      # ever run.
+      #
+      # You _can_ create database-backed model objects in a `before(:context)`
+      # in rspec-rails, but it will not be wrapped in a transaction for you, so
+      # you are on your own to clean up in an `after(:context)` block.
+      #
+      # @example before(:example) declared in an {ExampleGroup}
+      #
+      #     describe Thing do
+      #       before(:example) do
+      #         @thing = Thing.new
+      #       end
+      #
+      #       it "does something" do
+      #         # Here you can access @thing.
+      #       end
+      #     end
+      #
+      # @example before(:context) declared in an {ExampleGroup}
+      #
+      #     describe Parser do
+      #       before(:context) do
+      #         File.open(file_to_parse, 'w') do |f|
+      #           f.write <<-CONTENT
+      #             stuff in the file
+      #           CONTENT
+      #         end
+      #       end
+      #
+      #       it "parses the file" do
+      #         Parser.parse(file_to_parse)
+      #       end
+      #
+      #       after(:context) do
+      #         File.delete(file_to_parse)
+      #       end
+      #     end
+      #
+      # @note The `:example` and `:context` scopes are also available as
+      #       `:each` and `:all`, respectively. Use whichever you prefer.
+      # @note The `:scope` alias is only supported for hooks registered on
+      #       `RSpec.configuration` since they exist independently of any
+      #       example or example group.
+      def before(*args, &block)
+        hooks.register :append, :before, *args, &block
+      end
+
+      alias_method :append_before, :before
+
+      # Adds `block` to the front of the list of `before` blocks in the same
+      # scope (`:example`, `:context`, or `:suite`).
+      #
+      # See {#before} for scoping semantics.
+      def prepend_before(*args, &block)
+        hooks.register :prepend, :before, *args, &block
+      end
+
+      # @api public
+      # @overload after(&block)
+      # @overload after(scope, &block)
+      #   @param scope [Symbol] `:example`, `:context`, or `:suite` (defaults to
+      #     `:example`)
+      # @overload after(scope, conditions, &block)
+      #   @param scope [Symbol] `:example`, `:context`, or `:suite` (defaults to
+      #     `:example`)
+      #   @param conditions [Hash]
+      #     constrains this hook to examples matching these conditions e.g.
+      #     `after(:example, :ui => true) { ... }` will only run with examples
+      #     or groups declared with `:ui => true`.
+      # @overload after(conditions, &block)
+      #   @param conditions [Hash]
+      #     constrains this hook to examples matching these conditions e.g.
+      #     `after(:example, :ui => true) { ... }` will only run with examples
+      #     or groups declared with `:ui => true`.
+      #
+      # @see #before
+      # @see #around
+      # @see ExampleGroup
+      # @see SharedContext
+      # @see SharedExampleGroup
+      # @see Configuration
+      #
+      # Declare a block of code to be run after each example (using `:example`)
+      # or once after all examples n the context (using `:context`). See
+      # {#before} for more information about ordering.
+      #
+      # ### Exceptions
+      #
+      # `after` hooks are guaranteed to run even when there are exceptions in
+      # `before` hooks or examples. When an exception is raised in an after
+      # block, the exception is captured for later reporting, and subsequent
+      # `after` blocks are run.
+      #
+      # ### Order
+      #
+      # `after` hooks are stored in three scopes, which are run in order:
+      # `:example`, `:context`, and `:suite`. They can also be declared in
+      # several different places: `RSpec.configure`, a parent group, the current
+      # group. They are run in the following order:
+      #
+      #     after(:example) # Declared in the current group.
+      #     after(:example) # Declared in a parent group.
+      #     after(:example) # Declared in RSpec.configure.
+      #     after(:context) # Declared in the current group.
+      #     after(:context) # Declared in a parent group.
+      #     after(:context) # Declared in RSpec.configure.
+      #     after(:suite)   # Declared in RSpec.configure.
+      #
+      # This is the reverse of the order in which `before` hooks are run.
+      # Similarly, if more than one `after` is declared within any one scope,
+      # they are run in reverse order of that in which they are declared.
+      #
+      # @note The `:example` and `:context` scopes are also available as
+      #       `:each` and `:all`, respectively. Use whichever you prefer.
+      # @note The `:scope` alias is only supported for hooks registered on
+      #       `RSpec.configuration` since they exist independently of any
+      #       example or example group.
+      def after(*args, &block)
+        hooks.register :prepend, :after, *args, &block
+      end
+
+      alias_method :prepend_after, :after
+
+      # Adds `block` to the back of the list of `after` blocks in the same
+      # scope (`:example`, `:context`, or `:suite`).
+      #
+      # See {#after} for scoping semantics.
+      def append_after(*args, &block)
+        hooks.register :append, :after, *args, &block
+      end
+
+      # @api public
+      # @overload around(&block)
+      # @overload around(scope, &block)
+      #   @param scope [Symbol] `:example` (defaults to `:example`)
+      #     present for syntax parity with `before` and `after`, but
+      #     `:example`/`:each` is the only supported value.
+      # @overload around(scope, conditions, &block)
+      #   @param scope [Symbol] `:example` (defaults to `:example`)
+      #     present for syntax parity with `before` and `after`, but
+      #     `:example`/`:each` is the only supported value.
+      #   @param conditions [Hash] constrains this hook to examples matching
+      #     these conditions e.g. `around(:example, :ui => true) { ... }` will
+      #     only run with examples or groups declared with `:ui => true`.
+      # @overload around(conditions, &block)
+      #   @param conditions [Hash] constrains this hook to examples matching
+      #     these conditions e.g. `around(:example, :ui => true) { ... }` will
+      #     only run with examples or groups declared with `:ui => true`.
+      #
+      # @yield [Example] the example to run
+      #
+      # @note the syntax of `around` is similar to that of `before` and `after`
+      #   but the semantics are quite different. `before` and `after` hooks are
+      #   run in the context of of the examples with which they are associated,
+      #   whereas `around` hooks are actually responsible for running the
+      #   examples. Consequently, `around` hooks do not have direct access to
+      #   resources that are made available within the examples and their
+      #   associated `before` and `after` hooks.
+      #
+      # @note `:example`/`:each` is the only supported scope.
+      #
+      # Declare a block of code, parts of which will be run before and parts
+      # after the example. It is your responsibility to run the example:
+      #
+      #     around(:example) do |ex|
+      #       # Do some stuff before.
+      #       ex.run
+      #       # Do some stuff after.
+      #     end
+      #
+      # The yielded example aliases `run` with `call`, which lets you treat it
+      # like a `Proc`. This is especially handy when working with libaries
+      # that manage their own setup and teardown using a block or proc syntax,
+      # e.g.
+      #
+      #     around(:example) {|ex| Database.transaction(&ex)}
+      #     around(:example) {|ex| FakeFS(&ex)}
+      #
+      def around(*args, &block)
+        hooks.register :prepend, :around, *args, &block
+      end
+
+      # @private
+      # Holds the various registered hooks.
+      def hooks
+        @hooks ||= HookCollections.new(self, FilterableItemRepository::UpdateOptimized)
+      end
+
+    private
+
+      # @private
+      class Hook
+        attr_reader :block, :options
+
+        def initialize(block, options)
+          @block = block
+          @options = options
+        end
+      end
+
+      # @private
+      class BeforeHook < Hook
+        def run(example)
+          example.instance_exec(example, &block)
+        end
+      end
+
+      # @private
+      class AfterHook < Hook
+        def run(example)
+          example.instance_exec(example, &block)
+        rescue Support::AllExceptionsExceptOnesWeMustNotRescue => ex
+          example.set_exception(ex)
+        end
+      end
+
+      # @private
+      class AfterContextHook < Hook
+        def run(example)
+          example.instance_exec(example, &block)
+        rescue Support::AllExceptionsExceptOnesWeMustNotRescue => e
+          # TODO: Come up with a better solution for this.
+          RSpec.configuration.reporter.message <<-EOS
+
+An error occurred in an `after(:context)` hook.
+  #{e.class}: #{e.message}
+  occurred at #{e.backtrace.first}
+
+EOS
+        end
+      end
+
+      # @private
+      class AroundHook < Hook
+        def execute_with(example, procsy)
+          example.instance_exec(procsy, &block)
+          return if procsy.executed?
+          Pending.mark_skipped!(example,
+                                "#{hook_description} did not execute the example")
+        end
+
+        if Proc.method_defined?(:source_location)
+          def hook_description
+            "around hook at #{Metadata.relative_path(block.source_location.join(':'))}"
+          end
+        else # for 1.8.7
+          # :nocov:
+          def hook_description
+            "around hook"
+          end
+          # :nocov:
+        end
+      end
+
+      # @private
+      #
+      # This provides the primary API used by other parts of rspec-core. By hiding all
+      # implementation details behind this facade, it's allowed us to heavily optimize
+      # this, so that, for example, hook collection objects are only instantiated when
+      # a hook is added. This allows us to avoid many object allocations for the common
+      # case of a group having no hooks.
+      #
+      # This is only possible because this interface provides a "tell, don't ask"-style
+      # API, so that callers _tell_ this class what to do with the hooks, rather than
+      # asking this class for a list of hooks, and then doing something with them.
+      class HookCollections
+        def initialize(owner, filterable_item_repo_class)
+          @owner                      = owner
+          @filterable_item_repo_class = filterable_item_repo_class
+          @before_example_hooks       = nil
+          @after_example_hooks        = nil
+          @before_context_hooks       = nil
+          @after_context_hooks        = nil
+          @around_example_hooks       = nil
+        end
+
+        def register_globals(host, globals)
+          parent_groups = host.parent_groups
+
+          process(host, parent_groups, globals, :before, :example, &:options)
+          process(host, parent_groups, globals, :after,  :example, &:options)
+          process(host, parent_groups, globals, :around, :example, &:options)
+
+          process(host, parent_groups, globals, :before, :context, &:options)
+          process(host, parent_groups, globals, :after,  :context, &:options)
+        end
+
+        def register_global_singleton_context_hooks(example, globals)
+          parent_groups = example.example_group.parent_groups
+
+          process(example, parent_groups, globals, :before, :context) { {} }
+          process(example, parent_groups, globals, :after,  :context) { {} }
+        end
+
+        def register(prepend_or_append, position, *args, &block)
+          scope, options = scope_and_options_from(*args)
+
+          if scope == :suite
+            # TODO: consider making this an error in RSpec 4. For SemVer reasons,
+            # we are only warning in RSpec 3.
+            RSpec.warn_with "WARNING: `#{position}(:suite)` hooks are only supported on " \
+                            "the RSpec configuration object. This " \
+                            "`#{position}(:suite)` hook, registered on an example " \
+                            "group, will be ignored."
+            return
+          end
+
+          hook = HOOK_TYPES[position][scope].new(block, options)
+          ensure_hooks_initialized_for(position, scope).__send__(prepend_or_append, hook, options)
+        end
+
+        # @private
+        #
+        # Runs all of the blocks stored with the hook in the context of the
+        # example. If no example is provided, just calls the hook directly.
+        def run(position, scope, example_or_group)
+          return if RSpec.configuration.dry_run?
+
+          if scope == :context
+            run_owned_hooks_for(position, :context, example_or_group)
+          else
+            case position
+            when :before then run_example_hooks_for(example_or_group, :before, :reverse_each)
+            when :after  then run_example_hooks_for(example_or_group, :after,  :each)
+            when :around then run_around_example_hooks_for(example_or_group) { yield }
+            end
+          end
+        end
+
+        SCOPES = [:example, :context]
+
+        SCOPE_ALIASES = { :each => :example, :all => :context }
+
+        HOOK_TYPES = {
+          :before => Hash.new { BeforeHook },
+          :after  => Hash.new { AfterHook  },
+          :around => Hash.new { AroundHook }
+        }
+
+        HOOK_TYPES[:after][:context] = AfterContextHook
+
+      protected
+
+        EMPTY_HOOK_ARRAY = [].freeze
+
+        def matching_hooks_for(position, scope, example_or_group)
+          repository = hooks_for(position, scope) { return EMPTY_HOOK_ARRAY }
+
+          # It would be nice to not have to switch on type here, but
+          # we don't want to define `ExampleGroup#metadata` because then
+          # `metadata` from within an individual example would return the
+          # group's metadata but the user would probably expect it to be
+          # the example's metadata.
+          metadata = case example_or_group
+                     when ExampleGroup then example_or_group.class.metadata
+                     else example_or_group.metadata
+                     end
+
+          repository.items_for(metadata)
+        end
+
+        def all_hooks_for(position, scope)
+          hooks_for(position, scope) { return EMPTY_HOOK_ARRAY }.items_and_filters.map(&:first)
+        end
+
+        def run_owned_hooks_for(position, scope, example_or_group)
+          matching_hooks_for(position, scope, example_or_group).each do |hook|
+            hook.run(example_or_group)
+          end
+        end
+
+        def processable_hooks_for(position, scope, host)
+          if scope == :example
+            all_hooks_for(position, scope)
+          else
+            matching_hooks_for(position, scope, host)
+          end
+        end
+
+      private
+
+        def hooks_for(position, scope)
+          if position == :before
+            scope == :example ? @before_example_hooks : @before_context_hooks
+          elsif position == :after
+            scope == :example ? @after_example_hooks : @after_context_hooks
+          else # around
+            @around_example_hooks
+          end || yield
+        end
+
+        def ensure_hooks_initialized_for(position, scope)
+          if position == :before
+            if scope == :example
+              @before_example_hooks ||= @filterable_item_repo_class.new(:all?)
+            else
+              @before_context_hooks ||= @filterable_item_repo_class.new(:all?)
+            end
+          elsif position == :after
+            if scope == :example
+              @after_example_hooks ||= @filterable_item_repo_class.new(:all?)
+            else
+              @after_context_hooks ||= @filterable_item_repo_class.new(:all?)
+            end
+          else # around
+            @around_example_hooks ||= @filterable_item_repo_class.new(:all?)
+          end
+        end
+
+        def process(host, parent_groups, globals, position, scope)
+          hooks_to_process = globals.processable_hooks_for(position, scope, host)
+          return if hooks_to_process.empty?
+
+          hooks_to_process -= FlatMap.flat_map(parent_groups) do |group|
+            group.hooks.all_hooks_for(position, scope)
+          end
+          return if hooks_to_process.empty?
+
+          repository = ensure_hooks_initialized_for(position, scope)
+          hooks_to_process.each { |hook| repository.append hook, (yield hook) }
+        end
+
+        def scope_and_options_from(*args)
+          return :suite if args.first == :suite
+          scope = extract_scope_from(args)
+          meta  = Metadata.build_hash_from(args, :warn_about_example_group_filtering)
+          return scope, meta
+        end
+
+        def extract_scope_from(args)
+          if known_scope?(args.first)
+            normalized_scope_for(args.shift)
+          elsif args.any? { |a| a.is_a?(Symbol) }
+            error_message = "You must explicitly give a scope " \
+              "(#{SCOPES.join(", ")}) or scope alias " \
+              "(#{SCOPE_ALIASES.keys.join(", ")}) when using symbols as " \
+              "metadata for a hook."
+            raise ArgumentError.new error_message
+          else
+            :example
+          end
+        end
+
+        def known_scope?(scope)
+          SCOPES.include?(scope) || SCOPE_ALIASES.keys.include?(scope)
+        end
+
+        def normalized_scope_for(scope)
+          SCOPE_ALIASES[scope] || scope
+        end
+
+        def run_example_hooks_for(example, position, each_method)
+          owner_parent_groups.__send__(each_method) do |group|
+            group.hooks.run_owned_hooks_for(position, :example, example)
+          end
+        end
+
+        def run_around_example_hooks_for(example)
+          hooks = FlatMap.flat_map(owner_parent_groups) do |group|
+            group.hooks.matching_hooks_for(:around, :example, example)
+          end
+
+          return yield if hooks.empty? # exit early to avoid the extra allocation cost of `Example::Procsy`
+
+          initial_procsy = Example::Procsy.new(example) { yield }
+          hooks.inject(initial_procsy) do |procsy, around_hook|
+            procsy.wrap { around_hook.execute_with(example, procsy) }
+          end.call
+        end
+
+        if respond_to?(:singleton_class) && singleton_class.ancestors.include?(singleton_class)
+          def owner_parent_groups
+            @owner.parent_groups
+          end
+        else # Ruby < 2.1 (see https://bugs.ruby-lang.org/issues/8035)
+          # :nocov:
+          def owner_parent_groups
+            @owner_parent_groups ||= [@owner] + @owner.parent_groups
+          end
+          # :nocov:
+        end
+      end
+    end
+  end
+end