protocol 0.9.0 → 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: cd98524da174341f1dc25b039f03b5ad05adfdc8
+  data.tar.gz: b94806b796960a8413af5b89dd0d6d150db9e174
+SHA512:
+  metadata.gz: 61bc4d85d2fc9f9e08f66eaed176f890ba848cbdd5197708abc86d15992321dafe651d3c007e09e497b600dcfdf54f0585f44a33e22c71319c9aa5857a19592a
+  data.tar.gz: c78f6dde5b37c2fe123b19cc799c64492f50e9d889b370640bc60c1462c4fb5df49f815a9b015458b69c938d130870a3551fc28d42db7b6664be9c4de65f2781

data/.gitignore

@@ -0,0 +1,6 @@
+.*.sw[pon]
+.AppleDouble
+.rvmrc
+Gemfile.lock
+coverage
+pkg

data/.travis.yml

@@ -0,0 +1,11 @@
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - ruby-head
+  - rbx-19mode
+  - jruby-19mode
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: jruby-19mode
+

data/Gemfile

@@ -0,0 +1,7 @@
+# vim: set filetype=ruby et sw=2 ts=2:
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'utils'

data/{doc-main.txt → README.rdoc}

@@ -1,4 +1,4 @@
-== Protocol - Method Protocol Specifications in Ruby 
+== Protocol - Method Protocol Specifications in Ruby
 
 === Author
 
@@ -57,11 +57,11 @@ An example of a conforming class is the class +Ary+:
    def initialize
      @ary = [1, 2, 3]
    end
- 
+
    def each(&block)
      @ary.each(&block)
    end
- 
+
    conform_to Enumerating
  end
 
@@ -84,13 +84,13 @@ like this:
   Locking = Protocol do
     specification # not necessary, because Protocol defaults to specification
                   # mode already
-  
+
     def lock() end
-    
+
     def unlock() end
-  
+
     implementation
-  
+
     def synchronize
       lock
       begin
@@ -134,7 +134,7 @@ implemtented methods, to make block based locking possbile:
  mutex.synchronize do
    puts "Synchronized with '#{file.path}'."
  end
- 
+
 Now it's easy to swap the implementation to a memory based mutex
 implementation instead:
 
@@ -198,15 +198,15 @@ shows how:
      postcondition { top === x }
      postcondition { result === myself }
    end
- 
+
    def top() end
- 
+
    def size() end
- 
+
    def empty?()
      postcondition { size === 0 ? result : !result }
    end
- 
+
    def pop()
      s = size
      precondition { not empty? }

data/Rakefile

@@ -1,101 +1,41 @@
-begin
-  require 'rake/gempackagetask'
-rescue LoadError
-end
-require 'rake/clean'
-require 'rbconfig'
-include Config
-
-PKG_NAME = 'protocol'
-PKG_VERSION = File.read('VERSION').chomp
-PKG_FILES = FileList['**/*'].exclude(/(CVS|\.svn|pkg|coverage)/)
-CLEAN.include 'coverage', 'doc', Dir['benchmarks/data/*.*']
-
-desc "Installing library"
-task :install  do
-  ruby 'install.rb'
-end
-
-desc "Creating documentation"
-task :doc do
-  ruby 'make_doc.rb'
-end
+# vim: set filetype=ruby et sw=2 ts=2:
 
-desc "Testing library"
-task :test  do
-  ruby '-Ilib tests/test_protocol.rb'
-end
-
-desc "Testing library (coverage)"
-task :coverage  do
-  sh 'rcov -Ilib tests/test_protocol.rb'
-end
+require 'gem_hadar'
 
-if defined? Gem
-  spec_src =<<GEM
-# -*- encoding: utf-8 -*-
-Gem::Specification.new do |s|
-    s.name = '#{PKG_NAME}'
-    s.version = '#{PKG_VERSION}'
-    s.files = #{PKG_FILES.to_a.sort.inspect}
-    s.summary = 'Method Protocols for Ruby Classes'
-    s.description = <<EOT
+GemHadar do
+    name                 'protocol'
+    author               'Florian Frank'
+    email                'flori@ping.de'
+    homepage             "http://flori.github.com/#{name}"
+    summary              'Method Protocols for Ruby Classes'
+    description <<EOT
 This library offers an implementation of protocols against which you can check
 the conformity of your classes or instances of your classes. They are a bit
 like Java Interfaces, but as mixin modules they can also contain already
 implemented methods. Additionaly you can define preconditions/postconditions
 for methods specified in a protocol.
 EOT
-
-    s.require_path = 'lib'
-    s.add_dependency 'ParseTree', '~> 3.0'
-    s.add_dependency 'ruby_parser', '~> 2.0'
-
-    s.has_rdoc = true
-    s.rdoc_options << '--main' << 'doc-main.txt'
-    s.extra_rdoc_files << 'doc-main.txt'
-    s.test_files << 'tests/test_protocol.rb'
-
-    s.author = "Florian Frank"
-    s.email = "flori@ping.de"
-    s.homepage = "http://#{PKG_NAME}.rubyforge.org"
-    s.rubyforge_project = "#{PKG_NAME}"
-  end
-GEM
-
-  desc 'Create a gemspec file'
-  task :gemspec do
-    File.open("#{PKG_NAME}.gemspec", 'w') do |f|
-      f.puts spec_src
+  test_dir               'tests'
+  ignore                 '.*.sw[pon]', 'pkg', 'Gemfile.lock', 'coverage', '.rvmrc', '.AppleDouble'
+  readme                 'README.rdoc'
+  dependency             'ruby_parser', '~> 3.0'
+  development_dependency 'simplecov'
+
+  install_library do
+    file = 'lib/protocol.rb'
+    dest = CONFIG["sitelibdir"]
+    install(file, dest)
+
+    dest = File.join(CONFIG["sitelibdir"], 'protocol')
+    mkdir_p dest
+    for file in Dir['lib/protocol/*.rb']
+      install(file, dest)
     end
-  end
-
-  spec = eval(spec_src)
-  Rake::GemPackageTask.new(spec) do |pkg|
-    pkg.need_tar = true
-    pkg.package_files += PKG_FILES
-  end
-end
 
-desc m = "Writing version information for #{PKG_VERSION}"
-task :version do
-  puts m
-  File.open(File.join('lib', 'protocol', 'version.rb'), 'w') do |v|
-    v.puts <<EOT
-module Protocol
-  # Protocol version
-  VERSION         = '#{PKG_VERSION}'
-  VERSION_ARRAY   = VERSION.split(/\\./).map { |x| x.to_i } # :nodoc:
-  VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
-  VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:
-  VERSION_BUILD   = VERSION_ARRAY[2] # :nodoc:
-end
-EOT
+    dest = File.join(CONFIG["sitelibdir"], 'protocol', 'method_parser')
+    mkdir_p dest
+    for file in Dir['lib/protocol/method_parser/*.rb']
+      install(file, dest)
+    end
   end
 end
-
-desc "Default task"
-task :default => [ :version, :gemspec, :test ]
-
-desc "Prepare a release"
-task :release => [  :clean, :version, :gemspec, :package ]

data/VERSION

@@ -1 +1 @@
-0.9.0
+1.0.0

data/benchmarks/method_parser.rb

@@ -8,6 +8,9 @@ class MethodParserBenchmark < Bullshit::RepeatCase
 
   class Foo
     def foo(a, b = nil, *c)
+      if false then ; end
+      if false then ; end
+      if false then ; end
       yield
     end
   end

data/examples/assignments.rb

@@ -0,0 +1,59 @@
+#!/usr/bin/env ruby
+
+require 'protocol'
+
+Assignable = Protocol do
+  def assign_to(assignee)
+    Assignee =~ assignee
+  end
+end
+
+Assignee = Protocol do
+end
+
+Assignments = Protocol do
+  implementation
+
+  def assignments
+    @assignable ||= []
+  end
+
+  def add(assignable)
+    Assignable =~ assignable
+    assignments << assignable
+    self
+  end
+
+  def assign(assignable, assignee)
+    Assignable =~ assignable
+    Assignee =~ assignee
+    assignable.assign_to(assignee)
+    add(assignable)
+  end
+end
+
+class Task
+  def assign_to(assignee)
+    @assignee = assignee
+  end
+
+  conform_to Assignable
+end
+
+class Project
+  conform_to Assignments
+  conform_to Assignee
+end
+
+class User
+  conform_to Assignments
+  conform_to Assignee
+end
+
+p Project.new.assign(Task.new, User.new)
+p Project.new.assign(Task.new, Object.new)
+begin
+  Project.new.assign(Object.new, Task.new)
+rescue Protocol::CheckError => e
+  p e
+end

data/examples/game.rb

@@ -2,7 +2,7 @@ require 'protocol'
 
 # Small example of the template method pattern with Protocol. (I think, it was
 # inspired by this wikipedia article:
-# http://en.wikipedia.org/wiki/Template_method_pattern 
+# http://en.wikipedia.org/wiki/Template_method_pattern
 Gaming = Protocol do
   # defaults to specification mode
 

data/examples/hello_world_patternitis.rb

@@ -17,7 +17,7 @@ MessageBodyProtocol = Protocol do
   def configure(obj)
     precondition { obj.respond_to? :to_str }
   end
-  
+
   def send(message_strategy)
     MessageStrategyProtocol =~ message_strategy
     precondition { payload.respond_to? :to_str }

data/examples/locking.rb

@@ -5,7 +5,7 @@ Locking = Protocol do
                 # mode already
 
   def lock() end
-  
+
   def unlock() end
 
   implementation

data/lib/protocol/descriptor.rb

@@ -0,0 +1,34 @@
+module Protocol
+  # This class encapsulates the protocol description, to check the classes
+  # against, if the Class#conform_to method is called with the protocol constant
+  # as an argument.
+  class Descriptor
+    # Creates a new Protocol::Descriptor object.
+    def initialize(protocol)
+      @protocol = protocol
+      @messages = {}
+    end
+
+    # Addes a new Protocol::Message instance to this Protocol::Descriptor
+    # object.
+    def add_message(message)
+      @messages.key?(message.name) and raise SpecificationError,
+        "A message named #{message.name} was already defined in #@protocol"
+      @messages[message.name] = message
+    end
+
+    # Return all the messages stored in this Descriptor instance.
+    def messages
+      @messages.values
+    end
+
+    # Returns a string representation of this Protocol::Descriptor object.
+    def inspect
+      "#<#{self.class}(#@protocol)>"
+    end
+
+    def to_s
+      messages * ', '
+    end
+  end
+end

data/lib/protocol/errors.rb

@@ -0,0 +1,95 @@
+module Protocol
+  # The base class for protocol errors.
+  class ProtocolError < StandardError; end
+
+  # This exception is raise if an error was encountered while defining a
+  # protocol specification.
+  class SpecificationError < ProtocolError; end
+
+  # Marker module for all exceptions related to check errors.
+  module CheckError; end
+
+  # If a protocol check failes this exception is raised.
+  class BaseCheckError < ProtocolError
+    include CheckError
+
+    def initialize(protocol_message, message)
+      super(message)
+      @protocol_message = protocol_message
+    end
+
+    # Returns the Protocol::Message object, that caused this CheckError to be
+    # raised.
+    attr_reader :protocol_message
+
+    def to_s
+      "#{protocol_message}: #{super}"
+    end
+
+    def inspect
+      "#<#{self.class.name}: #{to_s}>"
+    end
+  end
+
+  # This exception is raised if a method was not implented in a class, that was
+  # required to conform to the checked protocol.
+  class NotImplementedErrorCheckError < BaseCheckError; end
+
+  # This exception is raised if a method implented in a class didn't have the
+  # required arity, that was required to conform to the checked protocol.
+  class ArgumentErrorCheckError < BaseCheckError; end
+
+  # This exception is raised if a method implented in a class didn't have the
+  # expected block argument, that was required to conform to the checked
+  # protocol.
+  class BlockCheckError < BaseCheckError; end
+
+  # This exception is raised if a precondition check failed (the yielded
+  # block returned a non-true value) in a protocol description.
+  class PreconditionCheckError < BaseCheckError; end
+
+  # This exception is raised if a postcondition check failed (the yielded block
+  # returned a non-true value) in a protocol description.
+  class PostconditionCheckError < BaseCheckError; end
+
+  # This exception collects CheckError exceptions and mixes in Enumerable for
+  # further processing of them.
+  class CheckFailed < ProtocolError
+    include CheckError
+
+    def initialize(*errors)
+      @errors = errors
+    end
+
+    attr_reader :errors
+
+    # Return true, if this CheckFailed doesn't contain any errors (yet).
+    # Otherwise false is returned.
+    def empty?
+      errors.empty?
+    end
+
+    # Add +check_error+ to this CheckFailed instance.
+    def <<(check_error)
+      @errors << check_error
+      self
+    end
+
+    # Iterate over all errors of this CheckFailed instance and pass each one to
+    # +block+.
+    def each_error(&block)
+      errors.each(&block)
+    end
+
+    alias each each_error
+    include Enumerable
+
+    def to_s
+      errors * "|"
+    end
+
+    def inspect
+      "#<#{self.class.name}: #{errors.map { |e| e.inspect} * '|'}"
+    end
+  end
+end

data/lib/protocol/message.rb

@@ -0,0 +1,219 @@
+module Protocol
+  # A Message consists of the name of the message (=method name), and the
+  # method argument's arity.
+  class Message
+    include Comparable
+
+    # Creates a Message instance named +name+, with the arity +arity+.
+    # If +arity+ is nil, the arity isn't checked during conformity tests.
+    def initialize(protocol, name, arity = nil, block_expected = false)
+      name = name.to_s
+      @protocol, @name, @arity, @block_expected =
+        protocol, name, arity, !!block_expected
+    end
+
+    # The protocol this message was defined in.
+    attr_reader :protocol
+
+    # Name of this message.
+    attr_reader :name
+
+    # Arity of this message = the number of arguments.
+    attr_accessor :arity
+
+    # Set to true if this message should expect a block.
+    def block_expected=(block_expected)
+      @block_expected = !!block_expected
+    end
+
+    # Returns true if this message is expected to include a block argument.
+    def block_expected?
+      @block_expected
+    end
+
+    # Message order is alphabetic name order.
+    def <=>(other)
+      name <=> other.name
+    end
+
+    # Returns true if this message equals the message +other+.
+    def ==(other)
+      name == other.name && arity == other.arity
+    end
+
+    # Returns the shortcut for this message of the form "methodname(arity)".
+    def shortcut
+      "#{name}(#{arity}#{block_expected? ? '&' : ''})"
+    end
+
+    # Return a string representation of this message, in the form
+    # Protocol#name(arity).
+    def to_s
+      "#{protocol.name}##{shortcut}"
+    end
+
+    # Concatenates a method signature as ruby code to the +result+ string and
+    # returns it.
+    def to_ruby(result = '')
+      if arity
+        result << "  def #{name}("
+        args = if arity >= 0
+          (1..arity).map { |i| "x#{i}" }
+        else
+          (1..~arity).map { |i| "x#{i}" } << '*rest'
+        end
+        if block_expected?
+          args << '&block'
+        end
+        result << args * ', '
+        result << ") end\n"
+      else
+        result << "  understand :#{name}\n"
+      end
+    end
+
+    # The class +klass+ is checked against this Message instance. A CheckError
+    # exception will called, if either a required method isn't found in the
+    # +klass+, or it doesn't have the required arity (if a fixed arity was
+    # demanded).
+    def check(object, checked)
+      check_message = object.is_a?(Class) ? :check_class : :check_object
+      if checked.key?(name)
+        true
+      else
+        checked[name] = __send__(check_message, object)
+      end
+    end
+
+    private
+
+    # Check class +klass+ against this Message instance, and raise a CheckError
+    # exception if necessary.
+    def check_class(klass)
+      unless klass.method_defined?(name)
+        raise NotImplementedErrorCheckError.new(self,
+            "method '#{name}' not implemented in #{klass}")
+      end
+      check_method = klass.instance_method(name)
+      if arity and (check_arity = check_method.arity) != arity
+        raise ArgumentErrorCheckError.new(self,
+              "wrong number of arguments for protocol"\
+              " in method '#{name}' (#{check_arity} for #{arity}) of #{klass}")
+      end
+      if block_expected?
+        modul = Utilities.find_method_module(name, klass.ancestors)
+        parser = MethodParser.new(modul, name)
+        parser.block_arg? or raise BlockCheckError.new(self,
+          "expected a block argument for #{klass}")
+      end
+      arity and wrap_method(klass)
+      true
+    end
+
+    # :stopdoc:
+    MyArray = Array.dup # Hack to make checking against Array possible.
+    # :startdoc:
+
+    def wrap_method(klass)
+      check_name = "__protocol_check_#{name}"
+      if klass.method_defined?(check_name)
+        inner_name = "__protocol_inner_#{name}"
+        unless klass.method_defined?(inner_name)
+          args =
+            if arity >= 0
+              (1..arity).map { |i| "x#{i}," }
+            else
+              (1..~arity).map { |i| "x#{i}," } << '*rest,'
+            end.join
+          wrapped_call = %{
+            alias_method :'#{inner_name}', :'#{name}'
+
+            def precondition
+              yield or
+                raise Protocol::PreconditionCheckError.new(
+                  ObjectSpace._id2ref(#{__id__}),
+                  "precondition failed for \#{self.class}")
+            end unless method_defined?(:precondition)
+
+            def postcondition(&block)
+              post_name = "__protocol_#{klass.__id__.abs}_postcondition__"
+              (Thread.current[post_name][-1] ||= Protocol::Postcondition.new(
+                self)).__add__ block
+            end unless method_defined?(:postcondition)
+
+            def #{name}(#{args} &block)
+              result = nil
+              post_name = "__protocol_#{klass.__id__.abs}_postcondition__"
+              (Thread.current[post_name] ||= MyArray.new) << nil
+              __send__('#{check_name}', #{args} &block)
+              if postcondition = Thread.current[post_name].last
+                begin
+                  reraised = false
+                  result = __send__('#{inner_name}', #{args} &block)
+                  postcondition.__result__= result
+                rescue Protocol::PostconditionCheckError => e
+                  reraised = true
+                  raise e
+                ensure
+                  unless reraised
+                    postcondition.__check__ or
+                      raise Protocol::PostconditionCheckError.new(
+                        ObjectSpace._id2ref(#{__id__}),
+                        "postcondition failed for \#{self.class}, result = " +
+                        result.inspect)
+                  end
+                end
+              else
+                result = __send__('#{inner_name}', #{args} &block)
+              end
+              result
+            rescue Protocol::CheckError => e
+              case ObjectSpace._id2ref(#{__id__}).protocol.mode
+              when :error
+                raise e
+              when :warning
+                warn e
+              end
+            ensure
+              Thread.current[post_name].pop
+              Thread.current[post_name].empty? and
+                Thread.current[post_name] = nil
+            end
+          }
+          klass.class_eval wrapped_call
+        end
+      end
+    end
+
+    # Check object +object+ against this Message instance, and raise a
+    # CheckError exception if necessary.
+    def check_object(object)
+      if !object.respond_to?(name)
+        raise NotImplementedErrorCheckError.new(self,
+            "method '#{name}' not responding in #{object}")
+      end
+      check_method = object.method(name)
+      if arity and (check_arity = check_method.arity) != arity
+        raise ArgumentErrorCheckError.new(self,
+            "wrong number of arguments for protocol"\
+            " in method '#{name}' (#{check_arity} for #{arity}) of #{object}")
+      end
+      if block_expected?
+        if object.singleton_methods(false).map { |m| m.to_s } .include?(name)
+          parser = MethodParser.new(object, name, true)
+        else
+          ancestors = object.class.ancestors
+          modul = Utilities.find_method_module(name, ancestors)
+          parser = MethodParser.new(modul, name)
+        end
+        parser.block_arg? or raise BlockCheckError.new(self,
+          "expected a block argument for #{object}:#{object.class}")
+      end
+      if arity and not protocol === object
+        object.extend protocol
+        wrap_method(class << object ; self ; end)
+      end
+      true
+    end
+  end
+end