protocol 0.8.0

data/Rakefile

@@ -0,0 +1,75 @@
+# vim: set et sw=2 ts=2:
+
+begin
+  require 'rake/gempackagetask'
+rescue LoadError
+end
+require 'rbconfig'
+
+include Config
+
+PKG_NAME = 'protocol'
+PKG_VERSION = File.read('VERSION').chomp
+PKG_FILES = FileList['**/*'].exclude(/(CVS|\.svn|pkg|coverage)/)
+
+desc "Installing library"
+task :install  do
+  ruby 'install.rb'
+end
+
+desc "Creating documentation"
+task :doc do
+  ruby 'make_doc.rb'
+end
+
+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
+
+desc "Clean created files"
+task :clean do
+  rm_rf %w[doc coverage]
+end
+
+desc "Prepare a release"
+task :release => [ :test, :clean, :package ]
+
+if defined? Gem
+  spec = Gem::Specification.new do |s|
+    s.name = PKG_NAME
+    s.version = PKG_VERSION
+    s.files = PKG_FILES
+    s.summary = 'Method Protocols for Ruby Classes'
+    s.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', '>= 2.0.2'
+
+    s.has_rdoc = true
+    s.rdoc_options << '--title' << s.summary <<
+      '-S'
+    s.test_files << 'tests/test_protocol.rb'
+
+    s.author = "Florian Frank"
+    s.email = "flori@ping.de"
+    s.homepage = "http://protocol.rubyforge.org"
+    s.rubyforge_project = "protocol"
+  end
+
+  Rake::GemPackageTask.new(spec) do |pkg|
+    pkg.need_tar = true
+    pkg.package_files += PKG_FILES
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+0.8.0

data/examples/comparing.rb

@@ -0,0 +1,37 @@
+require 'protocol/core'
+
+class Person
+  def initialize(name, size)
+    @name, @size = name, size
+  end
+
+  attr_reader :name, :size
+
+  def <=>(other)
+    size <=> other.size
+  end
+
+  conform_to Comparing
+end
+
+goliath = Person.new 'Goliath', 2_60
+david = Person.new 'David', 1_40
+symbol = Person.new 'The artist formerly known as Prince', 1_40
+
+david < goliath   # => true
+david >= goliath  # => false
+david == symbol   # => true
+
+begin
+  class NoPerson
+    def initialize(name, size)
+      @name, @size = name, size
+    end
+
+    attr_reader :name, :size
+
+    conform_to Comparing
+  end
+rescue Protocol::CheckFailed => e
+  e.to_s # => "Comparing#<=>(1): method '<=>' not implemented in NoPerson"
+end

data/examples/enumerating.rb

@@ -0,0 +1,47 @@
+require 'protocol/core'
+
+begin
+  class FailAry
+    def initialize
+      @ary = [1, 2, 3]
+    end
+
+    def each()
+    end
+
+    conform_to Enumerating
+  end
+rescue Protocol::CheckFailed => e
+  e.to_s # => "Enumerating#each(0&): expected a block argument for FailAry"
+end
+
+class Ary
+  def initialize
+    @ary = [1, 2, 3]
+  end
+
+  def each(&block)
+    @ary.each(&block)
+  end
+
+  conform_to Enumerating
+end
+
+Ary.new.map { |x| x * x }        # => [1, 4, 9]
+Ary.conform_to?(Enumerating)     # => true
+Ary.new.conform_to?(Enumerating) # => true
+
+Enumerating.check_failure :none
+
+class FailAry2
+  def initialize
+    @ary = [1, 2, 3]
+  end
+
+  def each() end
+
+  conform_to Enumerating
+end
+
+FailAry2.conform_to?(Enumerating)     # => false
+FailAry2.new.conform_to?(Enumerating) # => false

data/examples/game.rb

@@ -0,0 +1,81 @@
+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 
+Gaming = Protocol do
+  # defaults to specification mode
+
+  # Initialize the game before entering the game loop.
+  def initialize_game()
+  end
+
+  implementation # switch to implemetation mode
+
+  attr_accessor :player_count
+
+  attr_accessor :current_player
+
+  specification # switch back to specification mode
+
+  # Make the next move with player +player+.
+  def make_move(player)
+    player.is_a? Fixnum and player >= 0 or
+      raise TypeError, "player #{player.class} is not a Fixnum >= 0"
+  end
+
+  # Return true if the game is over.
+  def game_over?()
+  end
+
+  # Output the winner of the game after +game_over?+ returned true.
+  def output_winner()
+  end
+
+  implementation # switch to implemetation mode again
+
+  # Play the game with +player_count+ players.
+  def play(player_count)
+    self.player_count = player_count
+    self.current_player = 0
+    initialize_game
+    loop do
+      make_move current_player
+      game_over? and break
+      self.current_player = (current_player + 1) % player_count
+    end
+    output_winner
+  end
+end
+
+class GuessGame
+  def initialize_game
+    @winner = nil
+    @move = 0
+    @secret_number = 1 + rand(10)
+  end
+
+  def make_move(player)
+    @move += 1
+    @guess = 1 + rand(10)
+    puts "#@move. Player ##{player}'s move: number = #{@guess}?"
+  end
+
+  def game_over?
+    if @guess == @secret_number
+      @winner = current_player
+      true
+    else
+      false
+    end
+  end
+
+  def output_winner
+    puts "The winner is player ##@winner, the secret number was #@secret_number!"
+  end
+
+  conform_to Gaming
+end
+game = GuessGame.new
+game.play 2
+game.play 3

data/examples/hello_world_patternitis.rb

@@ -0,0 +1,77 @@
+#!/usr/bin/env ruby
+# This example is loosely based on a joke posted by MillionthMonkey on
+# slashdot: http://ask.slashdot.org/comments.pl?sid=250311&cid=19862863
+# Nonetheless, it demonstrates some features of the protocol library pretty
+# nicely.
+
+require 'protocol'
+require 'singleton'
+
+MessageStrategyProtocol = Protocol do
+  def send_message() end
+end
+
+MessageBodyProtocol = Protocol do
+  attr_reader :payload
+
+  def configure(obj)
+    precondition { obj.respond_to? :to_str }
+  end
+  
+  def send(message_strategy)
+    MessageStrategyProtocol =~ message_strategy
+    precondition { payload.respond_to? :to_str }
+    postcondition { result == :done }
+  end
+end
+
+class MessageBody
+  attr_reader :payload
+
+  def configure(obj)
+    @payload = obj
+  end
+
+  def send(message_strategy)
+    message_strategy.send_message
+    :done
+  end
+
+  conform_to MessageBodyProtocol
+end
+
+StrategyFactoryProtocol = Protocol do
+  def create_strategy(message_body)
+    MessageBodyProtocol =~ message_body
+  end
+end
+
+class DefaultFactory
+  include Singleton
+
+  def create_strategy(message_body)
+    Class.new do
+      define_method(:send_message) do ||
+        puts message_body.payload
+      end
+
+      conform_to MessageStrategyProtocol
+    end.new
+  end
+
+  conform_to StrategyFactoryProtocol
+end
+
+class HelloWorld
+  def self.main(*args)
+    message_body = MessageBody.new
+    message_body.configure "Hello World!"
+    factory = DefaultFactory.instance
+    strategy = factory.create_strategy message_body
+    message_body.send strategy
+  end
+end
+
+if $0 == __FILE__
+  HelloWorld.main(*ARGV)
+end

data/examples/indexing.rb

@@ -0,0 +1,27 @@
+require 'protocol'
+
+Indexing = Protocol {
+  check_failure :error
+
+  understand :[]
+
+  understand :[]=
+}
+
+if $0 == __FILE__
+  class Array
+    conform_to Indexing
+  end
+
+  class Hash
+    conform_to Indexing
+  end
+
+  begin
+    class Proc
+      conform_to Indexing
+    end
+  rescue Protocol::CheckFailed => e
+    e.to_s # => "Indexing#[]=(): method '[]=' not implemented in Proc"
+  end
+end

data/examples/locking.rb

@@ -0,0 +1,111 @@
+require 'protocol'
+
+Locking = Protocol do
+  specification # not necessary, because Protocol defaults to specification
+                # mode already
+
+  def lock() end
+  
+  def unlock() end
+
+  implementation
+
+  def synchronize
+    lock
+    begin
+      yield
+    ensure
+      unlock
+    end
+  end
+end
+
+if $0 == __FILE__
+  require 'thread'
+  require 'tempfile'
+
+  class FileMutex
+    def initialize
+      @tempfile = Tempfile.new 'file-mutex'
+    end
+
+    def path
+      @tempfile.path
+    end
+
+    def lock
+      puts "Locking '#{path}'."
+      @tempfile.flock File::LOCK_EX
+    end
+
+    def unlock
+      puts "Unlocking '#{path}'."
+      @tempfile.flock File::LOCK_UN
+    end
+
+    conform_to Locking
+  end
+
+  FileMutex.conform_to? Locking     # => true
+  FileMutex.new.conform_to? Locking # => true
+
+  # Outputs something like:
+  #  Locking '...'.
+  #  Synchronized with '...'..
+  #  Unlocking '...'.
+  mutex = FileMutex.new
+  mutex.synchronize do
+    puts "Synchronized with '#{mutex.path}'."
+  end
+
+  class MemoryMutex
+    def initialize
+      @mutex = Mutex.new
+    end
+
+    def lock
+      @mutex.lock
+    end
+
+    def unlock
+      @mutex.unlock
+    end
+
+    conform_to Locking # actually Mutex itself would conform as well ;)
+  end
+
+  mutex = MemoryMutex.new
+  mutex.synchronize do
+    puts "Synchronized in memory."
+  end
+
+  MemoryMutex.conform_to? Locking     # => true
+  MemoryMutex.new.conform_to? Locking # => true
+
+  class MyClass
+    def initialize
+      @mutex = FileMutex.new
+    end
+
+    attr_reader :mutex
+
+    def mutex=(mutex)
+      Locking.check mutex
+      @mutex = mutex
+    end
+  end
+
+  obj = MyClass.new
+  obj.mutex # => #<FileMutex:0xb788f9ac @tempfile=#<File:/tmp/file-mutex.26553.2>>
+  begin
+    obj.mutex = Object.new
+  rescue Protocol::CheckFailed => e
+    e # => #<Protocol::CheckFailed: #<Protocol::NotImplementedErrorCheckError: Locking#lock(0): method 'lock' not responding in #<Object:0xb788f59c>>|#<Protocol::NotImplementedErrorCheckError: Locking#unlock(0): method 'unlock' not responding in #<Object:0xb788f59c>>
+  end
+  obj.mutex = MemoryMutex.new # => #<MemoryMutex:0xb788f038 @mutex=#<Mutex:0xb788eea8>>
+  # This works as well:
+  obj.mutex = Mutex.new       # => #<Mutex:0xb788ecc8>
+  Locking.check Mutex         # => true
+  Mutex.conform_to? Locking   # => true
+end
+# >> "Locking '/tmp/file-mutex.26553.1'.\nSynchronized with '/tmp/file-mutex.26553.1'.\nUnlocking '/tmp/file-mutex.26553.1'.\nSynchronized in memory.\n"