lookout 2.3.0 → 3.0.0

data/lib/lookout-3.0/encode.rb

@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+
+# Encodes objects as UTF-8-encoded Strings.  This is done by calling String
+# with the object as the argument and then calling #encode on the result, if
+# the result responds to it.  This is primarily useful for compatibility
+# between Ruby 1.8 and 1.9.
+class Lookout::Encode
+  # Encodes OBJECT as an UTF-8-encoded String.
+  # @param [#to_s] object
+  Value(:object)
+
+  # @return [String] An UTF-8-encoded String representation of the object
+  def call
+    string = String(object)
+    return string unless (string.respond_to?(:encode) rescue true)
+    string.encode('UTF-8')
+  end
+
+  alias to_s call
+end

data/lib/lookout-3.0/exception.rb

@@ -0,0 +1,79 @@
+# -*- coding: utf-8 -*-
+
+# Provides non-failing access to some of {::Exception}’s methods.  Used in
+# subsystems where unhandled failure isn’t an option, such as {Inspect} and
+# {Results::Error}.  Also uses {Encode} so that all strings are ready for
+# output.
+class Lookout::Exception
+  # Provides non-failing access to EXCEPTION’s message, backtrace, and type.
+  # @param [::Exception] exception
+  Value(:exception)
+
+  # @return [String] The UTF-8-encoded exception message or the UTF-8-encoded
+  #   exception message of any exception that was raised while trying to retrieve
+  #   it
+  def message
+    @message ||= encode(begin
+                          String(exception.message)
+                        rescue => e
+                          'cannot retrieve error message: %s' %
+                            encode((String(e) rescue
+                                    'and cannot retrieve error message for error that generated that error either; giving up'))
+                        end)
+  end
+
+  alias to_s message
+
+  # @return [String] A heuristically generated UTF-8-encoded exception message
+  #   “header”, possibly containing the exception message and the exception’s
+  #   class’ name
+  def header
+    # Chomping off a \n here isn’t 100 percent compatible with how Ruby 1.9
+    # does it, but it simplifies the code and also makes the output better if
+    # the message is a lone \n.
+    message = (Lookout::Encode.new(String(exception.message)).call rescue '').chomp("\n")
+    if RuntimeError == type and message.empty?
+      'unhandled exception'
+    elsif message.empty?
+      type_name
+    elsif type_name.empty? or type_name.start_with? '#'
+      message
+    else
+      before, newline, after = message.partition("\n")
+      [before, ' (', type_name, ')', newline, after].join('')
+    end
+  end
+
+  # @return [Backtrace] A non-failing backtrace wrapper of the exception
+  #   backtrace
+  def backtrace; @backtrace ||= Backtrace.from(exception) end
+
+  # @return [#name, #inspect] Either the exception’s class or an {Unknown}
+  #   wrapper around the exception that was raised while trying to determine
+  #   the class
+  def type; @type ||= begin exception.class; rescue => e; Unknown.new(e) end end
+
+  # @return [String] The UTF-8-encoded name of the exception’s class
+  def type_name
+    @type_name ||= begin
+                      Lookout::Encode.new(type.name).call
+                    rescue => e
+                     'cannot determine name of class of exception: %s' %
+                       self.class.new(e)
+                    end
+  end
+
+  # @return [String] The {#header} and {#backtrace} separated by a newline
+  def format; [header, "\n", backtrace].join('') end
+
+  private
+
+  def encode(message)
+    Lookout::Encode.new(message).call
+  rescue => e
+    'cannot encode error message for output: %s%s' %
+      [(Lookout::Encode.new(String(e)).call rescue
+        'and cannot encode error message for error that generated that error for output either; giving up'),
+       ('; dumping instead: %s' % [message.dump] rescue '')]
+  end
+end

data/lib/lookout-3.0/exception/backtrace.rb

@@ -0,0 +1,65 @@
+# -*- coding: utf-8 -*-
+
+# Provides non-failing access to an exception backtrace.  The backtrace entries
+# are {Encode}d for output and the backtrace may be filtered to not include
+# entries from inside Lookout.
+class Lookout::Exception::Backtrace
+  class << self
+    # @param [::Exception] exception
+    # @return [Backtrace] A backtrace wrapper of EXCEPTION’s backtrace,
+    #   trimmed if EXCEPTION is a SystemStackError, and empty if the
+    #   backtrace can’t be retrieved
+    def from(exception)
+      new(nil == exception ? nil : (exception.backtrace rescue nil),
+          SystemStackError === exception)
+    end
+  end
+
+  # Wraps BACKTRACE and optionally TRIM the backtrace to only contain a couple
+  # of leading and trailing entries and FILTER out entries from inside Lookout.
+  # @param [Array<String>] backtrace
+  # @param [Boolean] trim
+  # @param [Boolean] filter
+  Value(:backtrace, :trim, :filter)
+  def initialize(backtrace, trim, filter = ENV['LOOKOUT_DO_NOT_FILTER_BACKTRACE'].nil?)
+    super(if nil == backtrace
+            []
+          elsif String === backtrace or Array === backtrace
+            (String === backtrace ? [backtrace] : backtrace).map{ |line|
+              begin
+                Lookout::Encode.new(line).call
+              rescue => e
+                '(cannot retrieve backtrace entry: %s)' %
+                  Lookout::Exception.new(e)
+              end
+            }
+          else
+            ['(backtrace is not an Array of String: %s)' %
+             Lookout::Inspect.new(backtrace, 'backtrace')]
+          end, trim, filter)
+  end
+
+  # @return The concatenation of the backtrace entries
+  def to_s
+    trimmed(filtered.map{ |location| ["\tfrom ", location].join('') }).join("\n")
+  end
+
+  private
+
+  def filtered; (filter and (before or outside)) or backtrace end
+  def before; nilify(backtrace.take_while{ |location| not reject? location }) end
+  def outside; nilify(backtrace.reject{ |location| reject? location }) end
+  def nilify(backtrace) backtrace.empty? ? nil : backtrace end
+  def reject?(location) location.start_with? Root end
+
+  def trimmed(locations)
+    return locations unless trim and locations.length > Head + Tail + 5
+    locations[0...Head] +
+      ["\t ... %d levels ..." % (locations.length - Head - Tail)] +
+      locations[-Tail..-1]
+  end
+
+  Root = File.expand_path('../../..', __FILE__)
+  Head = 8
+  Tail = 5
+end

data/lib/lookout-3.0/exception/unknown.rb

@@ -0,0 +1,25 @@
+# -*- coding: utf-8 -*-
+
+# Wraps an exception that was raised while trying to determine an exception’s
+# class to make it behave like an exception class.
+class Lookout::Exception::Unknown
+  # Wraps the EXCEPTION that was raised while trying to determine an
+  # exception’s class.
+  # @param [::Exception] exception
+  Value(:exception)
+
+  # @raise [RuntimeError] Containing a message explaining that the exception’s
+  #   class couldn’t be determined and why that is so
+  def name; raise message end
+
+  # @return The message explaining that the exception’s class couldn’t be
+  #   determined and why that is so
+  def inspect; '(%s)' % message end
+
+  private
+
+  def message
+    @message ||= 'cannot determine class of exception: %s' %
+      Lookout::Exception.new(exception)
+  end
+end

data/lib/lookout-3.0/expect.rb

@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*-
+
+# Function-like namespace for type-specific expect blocks.  Represents the
+# “expect” keyword in expectation files.  Used by {Expectations::Context}.
+#
+# {Object} is the base class for all classes defined under this namespace, so
+# look to it for guidance.
+module Lookout::Expect
+  class << self
+    # Wraps the creation of an {Object} or one of its sub-classes by
+    # dispatching #to_lookout_expected on the _expected_ value and then calling
+    #  #expect on the result, passing the expanded path to the FILE
+    # containing the expectation, the LINE in _file_ on which the expectation
+    # is defined, and the BLOCK to evaluate for the actual result.
+    #
+    # If #to_lookout_expected raises NoMethodError, the result will be an
+    # {Object}, so that at least something gets set up.
+    #
+    # @param [::Object] expected
+    # @param [::String] file
+    # @param [::Integer] line
+    # @return [Object] The result of calling
+    #   _expected_#to_lookout_expected#expect(FILE, LINE, &BLOCK)
+    def expect(expected, file, line, &block)
+      begin
+        expected.to_lookout_expected
+      rescue ::NoMethodError
+        ::Lookout::Expected::Object.new(expected)
+      end.expect(file, line, &block)
+    end
+  end
+end

data/lib/lookout-3.0/expect/classes.rb

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+
+# Namespace for expect blocks for types under the {Expected::Classes}
+# namespace.
+module Lookout::Expect::Classes
+end

data/lib/lookout-3.0/expect/classes/exception.rb

@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+
+# Expect block of {Expected::Classes::Exception}s.
+class Lookout::Expect::Classes::Exception < Lookout::Expect::Object
+  # Evaluates the expect block and checks the first raised Exception’s class
+  # against the expected Exception class.  If no exception is raised, the
+  # actual result is checked against the expected value.
+  # @return [Results::Error] If the raised exception’s class isn’t equal to or
+  #   a descendant of the expected result class
+  # @return [Results::Success] If the raised exception’s class is equal to or a
+  #   descendant of the expected result class
+  # @return (see Object#check)
+  def call
+    begin
+      result = evaluate_block
+    rescue expected.expected
+      return Lookout::Results::Success.new(file, line)
+    rescue Exception => e
+      exception = Lookout::Exception.new(e)
+      return Lookout::Results::Error.
+        new(file, line, expected.difference(exception.type).message, exception)
+    end
+    check(result)
+  rescue Exception => e
+    Lookout::Results::Error.new(file, line, nil, Lookout::Exception.new(e))
+  end
+end

data/lib/lookout-3.0/expect/exception.rb

@@ -0,0 +1,30 @@
+# -*- coding: utf-8 -*-
+
+# Expect block of {Expected::Exception}s.
+class Lookout::Expect::Exception < Lookout::Expect::Object
+  # Evaluates the expect block and checks the first raised Exception against
+  # the expected Exception.  If no exception is raised, the actual result is
+  # checked against the expected value.
+  # @return [Results::Error] If the raised exception isn’t of the same class as
+  #   that of the expected result
+  # @return (see Object#check)
+  def call
+    begin
+      result = evaluate_block
+    rescue Exception => actual
+      exception = Lookout::Exception.new(actual)
+      expected_class = expected.expected.class rescue Exception
+      actual_class = exception.type
+      return ((expected_class == actual_class) rescue false) ?
+        check(actual) :
+        Lookout::Results::Error.
+          new(file,
+              line,
+              expected_class.to_lookout_expected.difference(actual_class).message,
+              exception)
+    end
+    check(result)
+  rescue Exception => e
+    Lookout::Results::Error.new(file, line, nil, Lookout::Exception.new(e))
+  end
+end

data/lib/lookout-3.0/expect/object.rb

@@ -0,0 +1,54 @@
+# -*- coding: utf-8 -*-
+
+# Expect block of {Expected::Object}s.  This is the base expect
+# block class and may be subclassed if some special equality checking needs to
+# be performed, if the execution environment needs to be set up in some way
+# before the expect block is executed, or if the expect block should receive
+# other arguments than the default (being the expected value).
+class Lookout::Expect::Object
+  # Sets up the expect block on LINE in FILE (the expanded path) to expect the
+  # value that EXPECTED wraps, and using the block’s result as the actual
+  # result to pass to {Expected::Object#difference} when {#call}ed.
+  # @param [Expected::Object] expected The expected value wrapper
+  # @param [::String] file The expanded path to the file containing the expectation
+  # @param [::Integer] line The line in {#file} on which the expectation is defined
+  # @yieldparam [::Object] expected
+  # @yieldreturn [::Object]
+  Value(:expected, :file, :line, :'&block', :comparable => [:file, :line])
+  include Comparable
+
+  # Evaluates the expect block and checks for differences between its result
+  # and the expected value.
+  # @return [Results::Error] If an Exception is raised
+  # @return (see #check)
+  def call
+    check(evaluate_block)
+  rescue Exception => e
+    Lookout::Results::Error.new(file, line, nil, Lookout::Exception.new(e))
+  end
+
+  private
+
+  # @param [::Object, …] args
+  # @return [::Object] The actual result of evaluating the expect block in the
+  #   proper context, passing ARGS, which defaults to the expected value, to it
+  # @see Context
+  def evaluate_block(*args)
+    (args.empty? ?
+     Context.new(expected.expected, &block) :
+     Context.new(*args, &block)).evaluate
+  end
+
+  # Checks for differences between the ACTUAL result of evaluating the expect
+  # block and the expected value.
+  # @param [::Object] actual
+  # @return [Results::Success] If there are no differences between the actual
+  #   result and the expected value
+  # @return [Results::Failure] If there are differences between the actual
+  #   result and the expected value
+  def check(actual)
+    (difference = expected.difference(actual)) ?
+      Lookout::Results::Failure.new(file, line, difference) :
+      Lookout::Results::Success.new(file, line)
+  end
+end

data/lib/lookout-3.0/expect/object/context.rb

@@ -0,0 +1,149 @@
+# -*- coding: utf-8 -*-
+
+# Context in which expect blocks are evaluated.  Plug-ins may add private
+# methods to this class to make them available to expect blocks.
+class Lookout::Expect::Object::Context
+  # Evaluates BLOCK inside this context, passing ARGS to it, when {#evaluate}d.
+  # @param [::Object, …] args
+  def initialize(*args, &block)
+    @args, @block = args, block
+  end
+
+  # @return [::Object, nil] The result of evaluating the block or nil if
+  #   there’s no block
+  def evaluate
+    instance_exec(*@args, &@block) if @block
+  end
+
+  private
+
+  # @overload stub(object, methods)
+  #   Sets up stubs on OBJECT for each method name key in METHODS to its value
+  #   definition during the execution of the given block.  If the value of the
+  #   key is a Proc it’ll be used as the method definition.  Otherwise, the
+  #   method definition will be set up to return the value.
+  #   @param [::Object] object
+  #   @param [Hash<Symbol,Object>] methods
+  #   @yieldparam [::Object] object
+  #   @return [::Object] The result of the block
+  # @overload stub(methods = {})
+  #   @param [Hash<Symbol,::Object>] methods
+  #   @return [Lookout::Stub::Object] A stub object set up with METHODS
+  def stub(object = {}, methods = nil)
+    return Lookout::Stub.new(object) unless methods
+    recursion = proc{ |ms|
+      return yield(object) if ms.empty?
+      name, value = ms[0].first.to_sym, ms[0].last
+      (Kernel == object ? object : (class << object; self; end)).module_exec{
+        visibility, own =
+          private_method_defined?(name) ? [:private, private_instance_methods(false)] :
+          protected_method_defined?(name) ? [:protected, protected_instance_methods(false)] :
+          public_method_defined?(name) ? [nil, instance_methods(false)] : [nil, []]
+        unbound = own.include?(RUBY_VERSION < '1.9' ? name.to_s : name) ?
+          instance_method(name) : nil
+        Lookout::Stub.define self, name, value
+        send visibility, name if visibility
+        begin
+          recursion.call(ms[1..-1])
+        ensure
+          remove_method name
+          if unbound
+            define_method name, unbound
+            send visibility, name if visibility
+          end
+        end
+      }
+    }
+    recursion.call(methods.to_a)
+  end
+
+  # Sets GLOBAL to VALUE during the execution of the given block, yielding the
+  # OVERRIDDEN value.
+  # @param [Symbol] global
+  # @param [::Object] value
+  # @yieldparam [::Object] overridden
+  # @return [::Object] The result of the block
+  # @raise [ArgumentError] If GLOBAL isn’t the name of a global variable
+  def with_global(global, value)
+    symbol = global.to_sym
+    raise ArgumentError,
+      'no such global variable: %s' % global unless
+        global_variables.include?(RUBY_VERSION < '1.9' ? symbol.to_s : symbol)
+    saved = eval(symbol.to_s)
+    eval '%s = value' % symbol
+    begin
+      yield saved
+    ensure
+      eval '%s = saved' % symbol
+    end
+  end
+
+  # Sets `$VERBOSE` to VERBOSE during the execution of the given block.
+  # @param [true, false, nil] verbose
+  # @yield
+  # @return [::Object] The result of the block
+  def with_verbose(verbose = true)
+    with_global :$VERBOSE, verbose do
+      yield
+    end
+  end
+
+  # Sets the constant identified by (the possibly qualified) NAME to VALUE
+  # during the execution of the given block.  If NAME is qualified, any
+  # intermediate modules that aren’t defined will be set to new {Module}s.
+  # These modules will be removed once the block returns.
+  # @param [String] name
+  # @param [::Object] value
+  # @yield
+  # @return [::Object] The result of the block
+  def with_const(name, value)
+    missing = nil
+    parts = name.split('::', -1)
+    parts = parts[1..-1] if parts.first.empty?
+    raise NameError, 'illegal constant name: %s' % name if
+      parts.empty? or parts.first.empty? or parts.last.empty?
+    begin
+      parent = parts[0..-2].reduce(Object){ |o, e|
+        begin
+          if RUBY_VERSION < '1.9'
+            # This is racy, but unavoidable.
+            raise NameError unless o.const_defined? e
+            o.const_get(e)
+          else
+            o.const_get(e, false)
+          end
+        rescue NameError
+          missing = [o, e] unless missing
+          o.const_set(e, Module.new)
+        end
+      }
+      saved = parent.const_get(parts.last) unless missing
+      parent.const_set(parts.last, value)
+      begin
+        yield
+      ensure
+        parent.const_set(parts.last, saved) unless missing
+      end
+    ensure
+      missing.first.__send__(:remove_const, missing.last) if missing
+    end
+  end
+
+  # Sets environment variables defined in ENV during the execution of the given
+  # block.
+  # @param [Hash] env
+  # @yield
+  # @return [::Object] The result of the block
+  def with_env(env = {})
+    saved = ENV.select{ |key, _| env.include? key }
+    saved = Hash[*saved.flatten] if RUBY_VERSION < '1.9'
+    missing = env.reject{ |key, _| ENV.include? key }
+    begin
+      ENV.update env
+      yield
+    ensure
+      ENV.update saved
+      ENV.delete_if{ |key, _| missing.include? key }
+    end
+  end
+end