lookout 2.3.0 → 3.0.0

data/Rakefile

@@ -1,9 +1,24 @@
 # -*- coding: utf-8 -*-
 
-$:.unshift File.expand_path('../lib', __FILE__)
-require 'lookout/rake/tasks'
+require 'inventory-rake-1.0'
 
-Lookout::Rake::Tasks::Test.new do |t|
-  ENV['LOOKOUT_DO_NOT_FILTER_BACKTRACE'] = ''
+load File.expand_path('../lib/lookout-3.0/version.rb', __FILE__)
+
+Inventory::Rake::Tasks.define Lookout::Version, :gem => proc{ |_, s|
+  s.author = 'Nikolai Weibull'
+  s.email = 'now@bitwi.se'
+  s.homepage = 'https://github.com/now/lookout'
+}
+
+Inventory::Rake::Tasks.unless_installing_dependencies do
+  require 'lookout-rake-3.0'
+  Lookout::Rake::Tasks::Test.new do |t|
+    ENV['LOOKOUT_DO_NOT_FILTER_BACKTRACE'] = ''
+  end
+
+  require 'inventory-rake-tasks-yard-1.0'
+  Inventory::Rake::Tasks::YARD.new do |t|
+    t.options += %w'--plugin yard-heuristics-1.0 --plugin yard-value-1.0'
+    t.globals[:source_code_url] = 'https://github.com/now/%s/blob/v%s/%%s#L%%d' % [t.inventory.package, t.inventory]
+  end
 end
-Lookout::Rake::Tasks::Gem.new

data/lib/lookout-3.0.rb

@@ -0,0 +1,138 @@
+# -*- coding: utf-8 -*-
+
+# Main namespace of the Lookout library.
+#
+# {Expectations} is the main entry point to the library, representing the
+# “Expectations” keyword in expectation files and allowing such files to be
+# loaded, enumerating the {Expect} blocks found in such files.  Each such block
+# has an {Expected} value that’s an {Actual} result wrapper, a {Literal}, an
+# expected {Output}, an expected {Warning}, an expected method {Reception}, or
+# any {::Object} really, which it’ll compare to the actual result of executing
+# the block, reporting any {Difference}s – which may, in turn, be shown as
+# {Diff}s – as its {Result}.
+#
+# To help out, {Stub stub} and {Mock mock} objects may be created.
+# Furthermore, all ::Objects have been extended to support easy creation of
+# expected method {Reception}s, using a simple {Object domain-specific
+# language} that uses {Aphonic} receivers to gather the necessary information.
+#
+# To avoid failing while trying to report failures, non-failing access to
+# {Exception}s and {Inspect}ions of objects is used, as well as making sure to
+# {Encode} any output properly.
+#
+# There’s a command-line interface defined in {Interfaces::Commandline} that can
+# be used by other interfaces that want to invoke Lookout on a set of files.
+# It’s used by the {http://disu.se/software/lookout-rake Lookout-Rake} library.
+#
+# Plugins should place their namespace under the {Lookout::Plugins} namespace.
+module Lookout
+  class << self
+    def location(location)
+      return nil, nil unless match = /\A(.*):(\d+)(?::in .*)?\z/.match(location)
+      [match[1], match[2].to_i]
+    end
+  end
+
+  load File.expand_path('../lookout-3.0/version.rb', __FILE__)
+  Version.load
+end
+
+# Adds keyword methods “to” and “not” and #to_lookout_expected for Objects.
+class Object
+  # @return [Lookout::Object::To] A wrapper around the receiver that handles
+  # “to” keywords, such as “receive”
+  def to; Lookout::Object::To.new(self) end
+
+  # @return [Lookout::Object::To] A wrapper around the receiver that handles
+  # “not” keywords, such as “to”, that’ll then handle “receive”
+  def not; Lookout::Object::Not.new(self) end
+
+  # @return [Lookout::Expected::Object] A wrapper around the receiver, making
+  #   it an expected value
+  def to_lookout_expected; Lookout::Expected::Object.new(self) end
+end
+
+# Adds #to_lookout_expected to Arrays for better difference reports.
+class Array
+  # @return [Lookout::Expected::Array] A wrapper around the receiver, making
+  #   it an expected value
+  def to_lookout_expected; Lookout::Expected::Array.new(self) end
+end
+
+# Adds #to_lookout_expected to TrueClasses (`true`) for better difference
+# reports.
+class TrueClass
+  # @return [Lookout::Expected::TrueClass] A wrapper around the receiver,
+  #   making it an expected value
+  def to_lookout_expected; Lookout::Expected::TrueClass.new(self) end
+end
+
+# Adds #to_lookout_expected to FalseClasses (`false`) for better difference
+# reports.
+class FalseClass
+  # @return [Lookout::Expected::FalseClass] A wrapper around the receiver,
+  #   making it an expected value
+  def to_lookout_expected; Lookout::Expected::FalseClass.new(self) end
+end
+
+# Adds #to_lookout_expected to Hashes for better difference reports.
+class Hash
+  # @return [Lookout::Expected::Hash] A wrapper around the receiver, making it
+  #   an expected value
+  def to_lookout_expected; Lookout::Expected::Hash.new(self) end
+end
+
+# Adds #to_lookout_expected to Modules for better difference reports.
+class Module
+  # @return [Lookout::Expected::Module] A wrapper around the receiver, making
+  #   it an expected value
+  def to_lookout_expected; Lookout::Expected::Module.new(self) end
+end
+
+# Adds #to_lookout_expected to Ranges for better difference reports.
+class Range
+  # @return [Lookout::Expected::Range] A wrapper around the receiver, making it
+  #   an expected value
+  def to_lookout_expected; Lookout::Expected::Range.new(self) end
+end
+
+# Adds #to_lookout_expected to Regexps for better difference reports.
+class Regexp
+  # @return [Lookout::Expected::Regexps] A wrapper around the receiver, making
+  #   it an expected value
+  def to_lookout_expected; Lookout::Expected::Regexp.new(self) end
+end
+
+# Adds #to_lookout_expected to Exceptions and their classes for better
+# difference reports.
+class Exception
+  class << self
+    # @return [Lookout::Expected::Classes::Exception] A wrapper around the
+    #   receiver, making it an expected value
+    def to_lookout_expected; Lookout::Expected::Classes::Exception.new(self) end
+  end
+
+  # @return [Lookout::Expected::Exception] A wrapper around the receiver,
+  #   making it an expected value
+  def to_lookout_expected; Lookout::Expected::Exception.new(self) end
+end
+
+# Adds #to_lookout_expected to Strings for better difference reports.
+class String
+  # @return [Lookout::Expected::String] A wrapper around the receiver, making
+  #   it an expected value
+  def to_lookout_expected; Lookout::Expected::String.new(self) end
+end
+
+# Adds #to_lookout_expected to Symbols for query method expectations and better
+# difference reports.
+class Symbol
+  # @return [Lookout::Expected::Smybol] A wrapper around the receiver, making
+  #   it an expected value
+  def to_lookout_expected; Lookout::Expected::Symbol.new(self) end
+end
+
+def Expectations(&block)
+  Lookout::Expectations.evaluate Lookout.location(caller.first).first, &block
+  self
+end

data/lib/lookout-3.0/actual.rb

@@ -0,0 +1,30 @@
+# -*- coding: utf-8 -*-
+
+# Stands in for the actual result of the {Lookout::Expect expect block},
+# allowing a query method to call on the actual result to be set up and checked
+# after the expect block returns.  Used by
+# {Lookout::Expectations::Context#result}.
+class Lookout::Actual < Lookout::Aphonic
+  # @return [Actual::Not] A result stand-in that’s the inversion of the
+  #   receiver
+  def not; Lookout::Actual::Not.new end
+
+  # Method for improving readability of query method set-up.
+  # @return [self]
+  def to; self end
+
+  # Method for improving readability of query method set-up.
+  # @return [self]
+  def be; self end
+
+  # Method for improving readability of query method set-up.
+  # @return [self]
+  def have; self end
+
+  private
+
+  # @param (see Method#initialize)
+  # @return [Method] A method wrapper that’ll call METHOD with ARGS and BLOCK
+  #   when called
+  def method_missing(method, *args, &block) Method.new(method, *args, &block) end
+end

data/lib/lookout-3.0/actual/method.rb

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+
+# Proxies a method for later invocation on the actual result.  The method
+# information is stored and used when this method is {#call}ed, which passes it
+# along to the given actual result.
+class Lookout::Actual::Method
+  # Proxies METHOD, passing in ARGS and BLOCK when {#call}ed.
+  # @param [Symbol] method
+  # @param [Object, …] args
+  Value(:method, :'*args', :'&block')
+
+  # @param [Object] actual
+  # @return [Object] The result of invoking the method with the given arguments
+  #   on the ACTUAL result
+  def call(actual) actual.__send__(method, *args, &block) end
+
+  # @return [Expected::Lookout::Actual::Method] An expected value wrapper of
+  #   the receiver
+  def to_lookout_expected; Lookout::Expected::Lookout::Actual::Method.new(self) end
+
+  # @return A string of the form “#_method_(_args_){ … }”, depending on if any
+  #   arguments or block has been given
+  def to_s
+    ['#',
+     method,
+     args.empty? ? '' : '(%s)' % Lookout::Inspect.args(*args),
+     block ? '{ … }' : ''].join('')
+  end
+
+  alias inspect to_s
+end

data/lib/lookout-3.0/actual/not.rb

@@ -0,0 +1,13 @@
+# -*- coding: utf-8 -*-
+
+# Inverts {Actual}.  Allows a query method to call on the actual result to be
+# set up and its inversion checked after the expect block returns.
+class Lookout::Actual::Not < Lookout::Actual
+  # @return [Actual] A result stand-in that’s the inversion of the receiver
+  def not; Lookout::Actual.new end
+
+  private
+
+  # (see Lookout::Actual#method_missing)
+  def method_missing(method, *args, &block); Method.new(method, *args, &block) end
+end

data/lib/lookout-3.0/actual/not/method.rb

@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+
+# Proxies a method for later invocation on the actual result.  The method
+# information is stored and used when this method is {#call}ed, which passes it
+# along to the given actual result.
+class Lookout::Actual::Not::Method < Lookout::Actual::Method
+  # @return [Expected::Lookout::Actual::Not::Method] An expected value wrapper
+  #   of the receiver
+  def to_lookout_expected; Lookout::Expected::Lookout::Actual::Not::Method.new(self) end
+end

data/lib/lookout-3.0/aphonic.rb

@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+
+# Class that only responds to `#__send__` and #object_id.  Useful for DSLs and
+# classes that make use of #method_missing.  Things are set
+# up so that if methods are added to Kernel, Object, or Method after the
+# initial set-up, such methods will similarly be {.silence}d.
+class Lookout::Aphonic
+  Methods = [:__send__, :object_id]
+  Methods << :__id__ if RUBY_VERSION < '1.9' # Ruby 1.8 warns if __id__ is undefined
+
+  class << self
+    # Undefines METHOD unless it’s on the short-list of methods to keep.
+    # @param [Symbol] method
+    # @return [self]
+    def silence(method)
+      undef_method method if
+        instance_methods.include?(RUBY_VERSION < '1.9' ? method.to_s : method.to_sym) and
+        not Methods.include? method.to_sym
+      self
+    end
+  end
+
+  instance_methods.each(&method(:silence))
+end
+
+[Kernel, Object].each do |object|
+  object.instance_eval{ class << self; self; end }.instance_eval do
+    method_added = method(:method_added)
+    define_method :method_added do |name|
+      result = method_added.call(name)
+      Lookout::Aphonic.silence name if self == object
+      result
+    end
+  end
+end
+
+class Module
+  append_features = instance_method(:append_features)
+  define_method :append_features do |mod|
+    result = append_features.bind(self).call(mod)
+    instance_methods.each{ |name| Lookout::Aphonic.silence name } if mod == Object
+    result
+  end
+end

data/lib/lookout-3.0/diff.rb

@@ -0,0 +1,29 @@
+# -*- coding: utf-8 -*-
+
+# Namespace for the “diff” subsystem.  Includes various algorithms for
+# generating “diffs” and output formats for displaying them.  Used by
+# {Difference} to generate meaningful “diffs” of objects.
+#
+# A “diff” is a {Operations sequence} of {Operation}s that describe how to turn
+# an old/original/from version of a structure, such as an {::Array}, to a
+# new/new/to version of that structure.  For example, if the old version of an
+# Array is [1, 2, 3] and the new version of that array is [1, 2, 3, 4], then
+# the “diff” is a sequence of operations containing one operation, the
+# {Operations::Insert insertion} of the element 4 at the end of the Array.
+#
+# A “diff” is generated by one of various {Algorithms} that calculate optimal
+# sequences of operations, for some definition of “optimal”.  A common goal is
+# to provide the shortest sequence of operations necessary, but providing a
+# sequence that “feels natural” to a human is often also a priority.  The
+# algorithms work by looking for {Match}es between {Slice}s of the sequences
+# and then turning the information provided by these matches into the
+# operations that describe the changes that need to be made.
+#
+# “Diffs” can be turned into quite a few different textual {Formats} for
+# display to a human.  Such formats may {Group} together related {Groups} of
+# operations, focusing the display on the actual differences.
+#
+# You can find more information about “diffs” at
+# {http://en.wikipedia.org/wiki/Diff}.
+module Lookout::Diff
+end

data/lib/{lookout → lookout-3.0}/diff/algorithms.rb

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
 
+# Namespace for “diff” algorithms.
 module Lookout::Diff::Algorithms
-  autoload :Difflib, 'lookout/diff/algorithms/difflib'
 end

data/lib/lookout-3.0/diff/algorithms/difflib.rb

@@ -0,0 +1,62 @@
+# -*- coding: utf-8 -*-
+
+# The difflib algorithm is based on the algorithm employed by the difflib
+# library for Python, which is, in turn, based on an algorithm by Ratcliff and
+# Obershelp, see {http://docs.python.org/library/difflib.html}.
+#
+# It’s implemented as an Enumerable over the {Match}es between two sequences.
+# There are very few requirements on these sequences (see {#initialize}), which
+# makes this implementation useful for a wide class of objects.
+class Lookout::Diff::Algorithms::Difflib
+  # Initializes the algorithm to generate matches between the OLD and NEW
+  # versions of the indexable sequences.  The sequences must be indexable by
+  # {::Range}s and Integers with the semantics that, for example, {::Array}s
+  # have, and their elements must also respond to #hash and #==.
+  #
+  # A block may be given to determine what elements in NEW are to be ignored.
+  # This can be used to, for example, ignore whitespace differences.
+  #
+  # @param [#each, #[]] old
+  # @param [#each, #[]] new
+  # @yield [?]
+  # @yieldparam element
+  # @yieldreturn [Boolean]
+  Value(:old, :new, :'&ignorable')
+  include Enumerable
+
+  # @overload
+  #   Enumerates the matches between the two sequences.  There’ll always be at
+  #   least one match yielded, the {Match#empty? empty} one at the end of the
+  #   sequences.
+  #
+  #   @yieldparam [Match] match
+  # @overload
+  #   @return [Enumerator<Match>] An Enumerator over the matches between the
+  #     two sequences
+  def each
+    return enum_for(__method__) unless block_given?
+    current = Lookout::Diff::Match.new(Lookout::Diff::Slice.new(old, 0...0),
+                                       Lookout::Diff::Slice.new(new, 0...0))
+    stack = [Position.origin(old, new, &ignorable)]
+    until stack.empty?
+      case item = stack.pop
+      when Position
+        match = item.match
+        next if match.empty?
+        stack.push item.begin_after(match) if item.end_after? match
+        stack.push match
+        stack.push item.end_before(match) if item.begin_before? match
+      when Lookout::Diff::Match
+        if current.touch? item
+          current += item
+        else
+          yield current unless current.empty?
+          current = item
+        end
+      end
+    end
+    yield current unless current.empty?
+    yield current.at(old.size...old.size, new.size...new.size)
+    self
+  end
+end

data/lib/lookout-3.0/diff/algorithms/difflib/position.rb

@@ -0,0 +1,63 @@
+# -*- coding: utf-8 -*-
+
+# Keeps track of a position into the two sequences currently being “diffed” of
+# the difflib algorithm and generates matches and new positions based on this
+# position.
+#
+# @private
+class Lookout::Diff::Algorithms::Difflib::Position
+  Value(:old, :new, :junk)
+
+  class << self
+    def origin(old, new)
+      new = New.new(new)
+      new(Lookout::Diff::Slice.new(old),
+          new,
+          block_given? ? new.indexes.reduce({}){ |j, (k, _)| j[k] = yield(k); j } : {})
+    end
+  end
+
+  def match; junk.empty? ? leftmost_longest : expand(expand(leftmost_longest, false), true) end
+  def begin_before?(match) old.begin_before? match.old and new.begin_before? match.new end
+  def end_after?(match) old.end_after? match.old and new.end_after? match.new end
+  def begin_after(match) self.class.new(old.begin_after(match.old), new.begin_after(match.new), junk) end
+  def end_before(match) self.class.new(old.end_before(match.old), new.end_before(match.new), junk) end
+  def inspect; '#<%s %p,%p>' % [self.class, old, new] end
+
+  private
+
+  def leftmost_longest
+    match = Lookout::Diff::Match.new(@old.at(0...0), @new.at(0...0))
+    sizes = Hash.new(0)
+    @old.each_with_index do |item, old|
+      _sizes = Hash.new(0)
+      @new.each_index(item) do |new|
+        size = _sizes[new] = sizes[new - 1] + 1
+        match = match.at(old - size + 1..old,
+                         new - size + 1..new) if size > match.size
+      end unless junk[item]
+      sizes = _sizes
+    end
+    match
+  end
+
+  def expand(match, junking)
+    old_begin, new_begin = match.old.begin, match.new.begin
+    while old_begin > old.begin and new_begin > new.begin and
+          junk[new[new_begin - 1]] ^ !junking and
+          old[old_begin - 1] == new[new_begin - 1]
+      old_begin -= 1
+      new_begin -= 1
+    end
+
+    old_end, new_end = match.old.end, match.new.end
+    while old_end + 1 <= old.end and new_end + 1 <= new.end and
+          junk[new[new_end + 1]] ^ !junking and
+          old[old_end + 1] == new[new_end + 1]
+      old_end += 1
+      new_end += 1
+    end
+
+    match.at(old_begin..old_end, new_begin..new_end)
+  end
+end