clarion-given 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3840491d2082a82d4fdcf8c2006cb192b754f7264096259f2133defd6360ef0e
+  data.tar.gz: 0c487c45718dd66c3b68033d676174358a97d971d9b413bbcb30240d3d3a0be1
+SHA512:
+  metadata.gz: a1d23a9499b1856f62e7b9510b8eba10412dac9f4ebfa646ceee331d0a0852b925329a06e190a6361c8296f47e4d2f81c9273986e5cdec82909da6c8c89fbe73
+  data.tar.gz: 6cba9eba9739126417bd1513572399131525989b7b26d1b5ad8af1db73a07398ee93f5fdb1d56e8b092354f98f9f86fd4784e3a2a5d9a893b4c2e879f6ee3095

data/lib/given/assertions.rb

@@ -0,0 +1,71 @@
+require 'given/natural_assertion'
+require 'given/line_extractor'
+
+module Given
+  module Assertions
+
+    def self.enable_asserts(enabled=true)
+      @enable_asserts = enabled
+    end
+
+    def self.enable_preconditions(enabled=true)
+      @enable_preconditions = enabled
+    end
+
+    def self.enable_postconditions(enabled=true)
+      @enable_postconditions = enabled
+    end
+
+    def self.asserts?
+      @enable_asserts
+    end
+
+    def self.preconditions?
+      @enable_preconditions
+    end
+
+    def self.postconditions?
+      @enable_postconditions
+    end
+
+    def self.enable_all(enabled=true)
+      enable_asserts enabled
+      enable_preconditions enabled
+      enable_postconditions enabled
+    end
+
+    enable_all
+
+    AssertError = Class.new(StandardError)
+    PreconditionError = Class.new(AssertError)
+    PostconditionError = Class.new(AssertError)
+
+    def Assert(&block)
+      return nil unless Given::Assertions.asserts?
+      unless block.call
+        na = Given::NaturalAssertion.new("Assert", block, self, Given::LineExtractor.new)
+        raise AssertError, na.message
+      end
+    end
+
+    def Precondition(&block)
+      return nil unless Given::Assertions.preconditions?
+      if block.call
+        true
+      else
+        na = Given::NaturalAssertion.new("Precondition", block, self, Given::LineExtractor.new)
+        raise PreconditionError, na.message
+      end
+    end
+
+    def Postcondition(&block)
+      return nil unless Given::Assertions.preconditions?
+      if block.call
+        true
+      else
+        na = Given::NaturalAssertion.new("Postcondition", block, self, Given::LineExtractor.new)
+        raise PostconditionError, na.message
+      end
+    end
+  end
+end

data/lib/given/binary_operation.rb

@@ -0,0 +1,34 @@
+module Given
+
+  class BinaryOperation
+    BINARY_EXPLAINATIONS = {
+      :==  => "to equal",
+      :!=  => "to not equal",
+      :<   => "to be less than",
+      :<=  => "to be less or equal to",
+      :>   => "to be greater than",
+      :>=  => "to be greater or equal to",
+      :=~  => "to match",
+      :!~  => "to not match",
+      :=== => "to be matched by",
+    }
+
+    attr_reader :left, :operator, :right
+
+    def initialize(left, operator, right)
+      @left = left
+      @operator = operator
+      @right = right
+    end
+
+    def explain
+      BINARY_EXPLAINATIONS[operator]
+    end
+
+    def self.parse(sexp)
+      return nil unless sexp.first == :binary
+      new(sexp[1], sexp[2], sexp[3])
+    end
+  end
+
+end

data/lib/given/core.rb

@@ -0,0 +1,11 @@
+
+# Require all the core features
+
+require 'given/version'
+require 'given/module_methods'
+require 'given/file_cache'
+require 'given/line_extractor'
+require 'given/extensions'
+require 'given/fuzzy_number'
+require 'given/failure'
+require 'given/failure_matcher'

data/lib/given/evaluator.rb

@@ -0,0 +1,52 @@
+
+module Given
+  class EvalErr
+    def initialize(str)
+      @string = str
+    end
+    def size
+      inspect.size
+    end
+    def to_s
+      @string
+    end
+    def inspect
+      @string
+    end
+  end
+
+  class Evaluator
+    def initialize(example, block)
+      @example = example
+      @block = block
+    end
+
+    def eval_string(exp_string)
+      limit_length(eval_in_context(exp_string).inspect)
+    rescue StandardError => ex
+      EvalErr.new("#{ex.class}: #{ex.message}")
+    end
+
+    def location
+      Given.location_of(@block)
+    end
+
+    private
+
+    MAX_INSPECT_SIZE = 2000
+
+    def limit_length(string)
+      if string.size > MAX_INSPECT_SIZE
+        string[0..MAX_INSPECT_SIZE] + " (...truncated...)"
+      else
+        string
+      end
+    end
+
+    def eval_in_context(exp_string)
+      exp_proc = "proc { #{exp_string} }"
+      blk = eval(exp_proc, @block.binding)
+      @example.instance_eval(&blk)
+    end
+  end
+end

data/lib/given/ext/numeric.rb

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+
+module Given
+  module Ext
+    module Numeric
+
+      def ±(del=nil)
+        result = Given::Fuzzy::FuzzyNumber.new(self)
+        result.delta(del) if del
+        result
+      end
+
+      def ‰(percentage=nil)
+        result = Given::Fuzzy::FuzzyNumber.new(self)
+        result.percent(percentage) if percentage
+        result
+      end
+
+      def €(neps=nil)
+        result = Given::Fuzzy::FuzzyNumber.new(self)
+        result.epsilon(neps) if neps
+        result
+      end
+
+    end
+  end
+end
+
+class Numeric
+  include Given::Ext::Numeric
+end

data/lib/given/extensions.rb

@@ -0,0 +1,277 @@
+require 'given/module_methods'
+require 'given/natural_assertion'
+require 'given/failure'
+
+module Given
+
+  # Provide run-time instance methods to support Given infrastructure.
+  # All the methods in this module are considered private and
+  # implementation-specific, and should not be directly called by the
+  # application developer.
+  #
+  # By convention, these private instance specific methods are
+  # prefixed with _gvn_ to avoid name collisions with application
+  # methods defined in a spec.
+  #
+  # (Note that private class methods are prefixed with _Gvn_ and
+  # private instance methods are prefixed with _gvn_).
+  #
+  module InstanceExtensions   # :nodoc:
+
+    # List of containing contexts in order from innermost to
+    # outermost.
+    def _gvn_inner_contexts    # :nodoc:
+      self.class.ancestors.select { |context|
+        context.respond_to?(:_Gvn_givens)
+      }
+    end
+
+    # List of containing contexts in order from outermost to
+    # innermost.
+    def _gvn_contexts          # :nodoc:
+      _gvn_inner_contexts.reverse
+    end
+
+    # Return the context information for keyword from the innermost
+    # defining context.
+    def _gvn_info(keyword)     # :nodoc:
+      _gvn_inner_contexts.each do |context|
+        h = context._Gvn_context_info
+        if h.has_key?(keyword)
+          return h[keyword]
+        end
+      end
+      nil
+    end
+
+    # Should a natural assertion failure message be generated?
+    #
+    # A natural assertion failure message is generated if the
+    # assertion has non-empty content. The configuration options for
+    # natural assertions are checked and applied accordingly.
+    #
+    def _gvn_need_na_message?(nassert) # :nodoc:
+      return false unless nassert.has_content?
+      _gvn_na_configured?
+    end
+
+    # Return the configuration value for natural assertions.
+    #
+    # If natural assertions are not configured in the contexts, use
+    # the global configuration value.
+    def _gvn_na_configured?    # :nodoc:
+      info_value = _gvn_info(:natural_assertions_enabled)
+      info_value.nil? ? Given.natural_assertions_enabled? : info_value
+    end
+
+    # Establish all the Given preconditions the current and
+    # surrounding describe/context blocks, starting with the
+    # outermost context.
+    def _gvn_establish_givens  # :nodoc:
+      return if defined?(@_gvn_ran) && @_gvn_ran
+      @_gvn_ran = true
+      _gvn_contexts.each do |context|
+        context._Gvn_givens.each do |block|
+          instance_eval(&block)
+        end
+      end
+    end
+
+    # Check all the invariants in the current and surrounding
+    # describe/context blocks, starting with the outermost context.
+    def _gvn_check_invariants  # :nodoc:
+      _gvn_contexts.each do |context|
+        context._Gvn_invariants.each do |block|
+          _gvn_evaluate("Invariant", block)
+        end
+      end
+    end
+
+    def _gvn_check_ands  # :nodoc:
+      return if self.class._Gvn_context_info[:and_ran]
+      self.class._Gvn_and_blocks.each do |block|
+        _gvn_evaluate("And", block)
+      end
+      self.class._Gvn_context_info[:and_ran] = true
+    end
+
+    # Implement the run-time semantics of the Then clause.
+    def _gvn_then(&block)      # :nodoc:
+      _gvn_establish_givens
+      _gvn_check_invariants
+      _gvn_evaluate("Then", block)
+      _gvn_check_ands
+    end
+
+    # Determine of the natural assertion pass/fail status of the block
+    def _gvn_block_passed?(block) # :nodoc:
+      passed = instance_eval(&block)
+      passed = passed.to_bool if passed.respond_to?(:to_bool)
+      passed
+    end
+
+    # Evaluate a Then, And, or Invariant assertion.
+    def _gvn_evaluate(clause_type, block)   # :nodoc:
+      Given.start_evaluation
+      passed = _gvn_block_passed?(block)
+      if ! Given.explicit_assertions? && _gvn_na_configured?
+        _gvn_naturally_assert(clause_type, block, passed)
+      end
+    end
+
+    # Naturally assert the block (based on +passed+).
+    def _gvn_naturally_assert(clause_type, block, passed)
+      Given.count_assertion
+      unless passed
+        nassert = NaturalAssertion.new(clause_type, block, self, self.class._Gvn_lines)
+        Given.fail_with nassert.message if _gvn_need_na_message?(nassert)
+      end
+    end
+  end
+
+  # Provide run-time class methods to support Given infrastructure.
+  # Methods that begin with _Gvn_ are considered private and
+  # implementation specific, and should not be directly called by
+  # appliation code. Other methods without the _Gvn_ prefix are public
+  # and intended for use by the application developer.
+  #
+  # (Note that private class methods are prefixed with _Gvn_ and
+  # private instance methods are prefixed with _gvn_).
+  #
+  module ClassExtensions
+
+    # List of all givens directly in the current describe/context
+    # block.
+    def _Gvn_givens            # :nodoc:
+      @_Gvn_givens ||= []
+    end
+
+    # List of all invariants directly in the current
+    # describe/context block.
+    def _Gvn_invariants        # :nodoc:
+      @_Gvn_invariants ||= []
+    end
+
+    # List of the and blocks directly in the current describe/context
+    # block.
+    def _Gvn_and_blocks         # :nodoc:
+      @_Gvn_and_blocks ||= []
+    end
+
+    # Context information ofr the current describe/context block.
+    def _Gvn_context_info       # :nodoc:
+      @_Gvn_context_info ||= {}
+    end
+
+    # Line extractor for the context.
+    def _Gvn_lines              # :nodoc:
+      @_Gvn_lines ||= LineExtractor.new
+    end
+
+    # Trigger the evaluation of a Given! block by referencing its
+    # name.
+    def _Gvn_trigger_given(name) # :nodoc:
+      Proc.new { send(name) }
+    end
+
+    # Declare a "given" of the current specification.  If the given
+    # is named, the block will be lazily evaluated the first time
+    # the given is mentioned by name in the specification.  If the
+    # given is unnamed, the block is evaluated for side effects
+    # every time the specification is executed.
+    #
+    # :call-seq:
+    #   Given(:name) { ... code ... }
+    #   Given { ... code ... }
+    #
+    def Given(*args, &block)
+      if args.first.is_a?(Symbol)
+        let(args.first, &block)
+      else
+        _Gvn_givens << block
+      end
+    end
+
+    # Declare a named given of the current specification.  Similar
+    # to the named version of the "Given" command, except that the
+    # block is always evaluated.
+    #
+    # :call-seq:
+    #   Given!(:name) { ... code ... }
+    #
+    def Given!(name, &block)
+      let(name, &block)
+      _Gvn_givens << _Gvn_trigger_given(name)
+    end
+
+    # Declare the code that is under test.
+    #
+    # :call-seq:
+    #   When(:named_result) { ... code_under_test ... }
+    #   When { ... code_under_test ... }
+    #
+    def When(*args, &block)
+      if args.first.is_a?(Symbol)
+        _Gvn_when_actions_with_capture(args.first, block)
+      else
+        _Gvn_when_actions(block)
+      end
+    end
+
+    # Normal When clause actions.
+    def _Gvn_when_actions(block)        # :nodoc:
+      _Gvn_before do
+        _gvn_establish_givens
+        instance_eval(&block)
+      end
+    end
+
+    # Normal When clause actions except that exceptions are captured
+    # in a Failure object.
+    def _Gvn_when_actions_with_capture(name, block) # :nodoc:
+      let(name) do
+        Failure.capture(Given.pending_error) do
+          _gvn_establish_givens
+          instance_eval(&block)
+        end
+      end
+      _Gvn_before do __send__(name) end
+    end
+
+    # Provide an assertion about the specification.
+    #
+    # Then supplies an assertion that should be true after all the
+    # Given and When blocks have been run. All invariants in scope
+    # will be checked before the Then block is run.
+    #
+    # :call-seq:
+    #   Then { ... assertion ... }
+    #
+    def Then(opts={}, &block)
+      on_eval = opts.fetch(:on_eval, "_gvn_then")
+      file, line = Given.location_of(block)
+      description = _Gvn_lines.line(file, line) unless Given.source_caching_disabled
+      cmd = description ? "it(description)" : "specify"
+      eval %{#{cmd} do #{on_eval}(&block) end}, binding, file, line
+      _Gvn_context_info[:then_defined] = true
+    end
+
+    # Establish an invariant that must be true for all Then blocks
+    # in the current (and nested) scopes.
+    def Invariant(&block)
+      _Gvn_invariants << block
+    end
+
+    # Provide an assertion that shares setup with a peer Then command.
+    def And(&block)
+      fail "And defined without a Then" unless _Gvn_context_info[:then_defined]
+      _Gvn_and_blocks << block
+    end
+
+    # Configure the use of natural assertions in this context.
+    def use_natural_assertions(enabled=true)
+      Given.ok_to_use_natural_assertions(enabled)
+      _Gvn_context_info[:natural_assertions_enabled] = enabled
+    end
+  end
+end

data/lib/given/failure.rb

@@ -0,0 +1,80 @@
+
+module Given
+
+  # Failure objects will raise the given exception whenever you try
+  # to send it *any* message.
+  class Failure < BasicObject
+    undef_method :==, :!=, :!
+
+    # Evaluate a block. If an exception is raised, capture it in a
+    # Failure object. Explicitly listed exceptions are passed thru
+    # without capture.
+    def self.capture(*exceptions)
+      begin
+        yield
+      rescue *exceptions => ex
+        raise
+      rescue ::Exception => ex
+        new(ex)
+      end
+    end
+
+    # Create a failure object that will rethrow the given exception
+    # whenever an undefined method is called.
+    def initialize(exception)
+      @exception = exception
+    end
+
+    # Failure objects will respond to #is_a?.
+    def is_a?(klass)
+      klass == Failure
+    end
+
+    # Failure objects may be compared for equality. If the comparison
+    # object is not a matcher, then the exception is re-raised.
+    def ==(other)
+      if failure_matcher?(other)
+        other.matches?(self)
+      else
+        die
+      end
+    end
+
+    # Failure objects may be compared for in-equality. If the comparison
+    # object is not a matcher, then the exception is re-raised.
+    def !=(other)
+      if failure_matcher?(other)
+        other.does_not_match?(self)
+      else
+        die
+      end
+    end
+
+    # Most methods will just re-raise the captured exception.
+    def method_missing(sym, *args, &block)
+      die
+    end
+
+    # Report that we respond to a limited number of methods.
+    def respond_to?(method_symbol)
+      method_symbol == :call ||
+        method_symbol == :== ||
+        method_symbol == :!= ||
+        method_symbol == :is_a? ||
+        method_symbol == :to_bool
+    end
+
+    private
+
+    # Re-raise the captured exception.
+    def die
+      ::Kernel.raise @exception
+    end
+
+    # Is the comparison object a failure matcher?
+    def failure_matcher?(other)
+      other.respond_to?(:matches?) && other.respond_to?(:does_not_match?)
+    end
+  end
+
+end

data/lib/given/failure_matcher.rb

@@ -0,0 +1,100 @@
+module Given
+
+  class FailureMatcher
+    def initialize(exception_class, message_pattern)
+      @no_pattern = false
+      @expected_exception_class = exception_class
+      @expected_message_pattern = message_pattern
+      if @expected_message_pattern.nil?
+        @expected_message_pattern = //
+        @no_pattern = true
+      elsif @expected_message_pattern.is_a?(String)
+        @expected_message_pattern =
+          Regexp.new("\\A" + Regexp.quote(@expected_message_pattern) + "\\z")
+      end
+    end
+
+    def ==(other)
+      if other.respond_to?(:call)
+        matches?(other)
+      else
+        super
+      end
+    end
+
+    def !=(other)
+      if other.respond_to?(:call)
+        does_not_match?(other)
+      else
+        super
+      end
+    end
+
+    def matches?(possible_failure)
+      if possible_failure.respond_to?(:call)
+        match_or_fail(possible_failure)
+      else
+        Given.fail_with("#{description}, but nothing failed")
+      end
+    end
+
+    def does_not_match?(possible_failure)
+      if possible_failure.respond_to?(:call)
+        mismatch_or_fail(possible_failure)
+      else
+        true
+      end
+    end
+
+    def inspect
+      result = "<Failure on #{@expected_exception_class}"
+      result << " matching #{@expected_message_pattern.inspect}" unless @no_pattern
+      result << ">"
+    end
+
+    private
+
+    def match_or_fail(possible_failure)
+      ex = extract_exception(possible_failure)
+      match_exception(ex) ||
+        Given.fail_with("#{description}, but got #{ex.inspect}")
+    end
+
+    def mismatch_or_fail(possible_failure)
+      ex = extract_exception(possible_failure)
+      (! match_exception(ex)) ||
+        Given.fail_with("#{unexpected_description}, but got #{ex.inspect}")
+    end
+
+    def match_exception(ex)
+      ex.is_a?(@expected_exception_class) && @expected_message_pattern =~ ex.message
+    end
+
+    def extract_exception(possible_failure)
+      possible_failure.call
+      Given.fail_with("Expected an exception")
+      return nil
+    rescue Exception => ex
+      return ex
+    end
+
+    def description
+      result = "Expected failure with #{@expected_exception_class}"
+      result << " matching #{@expected_message_pattern.inspect}" unless @no_pattern
+      result
+    end
+
+    def unexpected_description
+      result = "Did not expect failure with #{@expected_exception_class}"
+      result << " matching #{@expected_message_pattern.inspect}" unless @no_pattern
+      result
+    end
+  end
+
+  module FailureMethod
+    def Failure(exception_class=Exception, message_pattern=nil)
+      FailureMatcher.new(exception_class, message_pattern)
+    end
+  end
+
+end

data/lib/given/file_cache.rb

@@ -0,0 +1,18 @@
+
+module Given
+  class FileCache
+    def initialize
+      @lines = {}
+    end
+
+    def get(file_name)
+      @lines[file_name] ||= read_lines(file_name)
+    end
+
+    private
+
+    def read_lines(file_name)
+      open(file_name, "r:UTF-8") { |f| f.readlines }
+    end
+  end
+end