protocol 0.8.1 → 0.8.2

data/CHANGES

@@ -1,3 +1,6 @@
+0.8.2 - 2008-07-20
+  * Some cleanup.
+  * Bumped up dependency on ParseTree to 3.0.
 0.8.1 - 2008-12-17
   * Fixed ParseTree dependency
   * Added license file.

data/Rakefile

@@ -4,13 +4,14 @@ 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'
 
 desc "Installing library"
 task :install  do
@@ -32,19 +33,13 @@ 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
+  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
 This library offers an implementation of protocols against which you can check
@@ -55,21 +50,53 @@ for methods specified in a protocol.
 EOT
 
     s.require_path = 'lib'
-    s.add_dependency 'ParseTree', '~> 2.0'
+    s.add_dependency 'ParseTree', '~> 3.0'
 
     s.has_rdoc = true
-    s.rdoc_options << '--title' << s.summary <<
-      '-S'
+    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://protocol.rubyforge.org"
-    s.rubyforge_project = "protocol"
+    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
+    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
+  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.8.1
+0.8.2

data/doc-main.txt

@@ -0,0 +1,238 @@
+== Protocol - Method Protocol Specifications in Ruby 
+
+=== Author
+
+Florian Frank mailto:flori@ping.de
+
+=== License
+
+This is free software; you can redistribute it and/or modify it under the
+terms of the GNU General Public License Version 2 as published by the Free
+Software Foundation: www.gnu.org/copyleft/gpl.html
+
+=== Download
+
+The latest version of <b>protocol</b> can be found at
+
+* http://rubyforge.org/frs/?group_id=4778
+
+The homepage of this library is located at
+
+* http://protocol.rubyforge.org
+
+=== Description
+
+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. Additionally you can define preconditions/postconditions
+for methods specified in a protocol.
+
+=== Usage
+
+This defines a protocol named +Enumerating+:
+
+ Enumerating = Protocol do
+   # Iterate over each element of this Enumerating class and pass it to the
+   # +block+.
+   def each(&block) end
+
+   include Enumerable
+ end
+
+Every class, that conforms to this protocol, has to implement the understood
+messages (+each+ in this example - with no ordinary arguments and a block
+argument). The following would be an equivalent protocol definition:
+
+ Enumerating = Protocol do
+   # Iterate over each element of this Enumerating class and pass it to the
+   # +block+.
+   understand :each, 0, true
+
+   include Enumerable
+ end
+
+An example of a conforming class is the class +Ary+:
+ class Ary
+   def initialize
+     @ary = [1, 2, 3]
+   end
+ 
+   def each(&block)
+     @ary.each(&block)
+   end
+ 
+   conform_to Enumerating
+ end
+
+The last line (this command being the last line of the class definition is
+important!) of class +Ary+ <tt>conform_to Enumerating</tt> checks the
+conformance of +Ary+ to the +Enumerating+ protocol. If the +each+ method were
+not implemented in +Ary+ a CheckFailed exception would have been thrown,
+containing all the offending CheckError instances.
+
+It also mixes in all the methods that were included in protocol +Enumerating+
+(+Enumerable+'s instance methods). More examples of this can be seen in the
+examples sub directory of the source distribution of this library in file
+examples/enumerating.rb.
+
+==== Template Method Pattern
+
+It's also possible to mix protocol specification and behaviour implementation
+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
+        yield
+      ensure
+        unlock
+      end
+    end
+  end
+
+This specifies a Locking protocol against which several class implementations
+can be checked against for conformance. Here's a FileMutex implementation:
+
+ 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
+
+The Locking#synchronize method is a template method (see
+http://en.wikipedia.org/wiki/Template_method_pattern), that uses the
+implemtented methods, to make block based locking possbile:
+
+ mutex = FileMutex.new
+ mutex.synchronize do
+   puts "Synchronized with '#{file.path}'."
+ end
+ 
+Now it's easy to swap the implementation to a memory based mutex
+implementation instead:
+
+ 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
+
+To check an +object+ for conformity to the Locking protocol call
+Locking.check +object+ and rescue a CheckFailed. Here's an example class
+
+ class MyClass
+   def initialize
+     @mutex = FileMutex.new
+   end
+
+   attr_reader :mutex
+
+   def mutex=(mutex)
+     Locking.check mutex
+     @mutex = mutex
+   end
+ end
+
+This causes a CheckFailed exception to be thrown:
+ obj.mutex = Object.new
+
+This would not raise an exception:
+ obj.mutex = MemoryMutex.new
+
+And neither would this
+
+ obj.mutex = Mutex.new # => #<Mutex:0xb799a4f0 @locked=false, @waiting=[]>
+
+because coincidentally this is true
+
+ Mutex.conform_to? Locking # => true
+
+and thus Locking.check doesn't throw an exception. See the
+examples/locking.rb file for code.
+
+==== Preconditions and Postconditions
+
+You can add additional runtime checks for method arguments and results by
+specifying pre- and postconditions. Here is the classical stack example, that
+shows how:
+
+ StackProtocol = Protocol do
+   def push(x)
+     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? }
+     postcondition { size === s - 1 }
+   end
+ end
+
+Defining protocols and checking against conformance doesn't get in the way of
+Ruby's duck typing, but you can still use protocols to define, document, and
+check implementations that you expect from client code.
+
+==== Error modes in Protocols
+
+You can set different error modes for your protocols. By default the mode is
+set to :error, and a failed protocol conformance check raises a CheckError (a
+marker module) exception. Alternatively you can set the error mode to
+:warning with:
+
+ Foo = Protocol do
+   check_failure :warning
+ end
+
+during Protocol definition or later
+
+  Foo.check_failure :warning
+
+In :warning mode no execptions are raised, only a warning is printed to
+STDERR. If you set the error mode via Protocol::ProtocolModule#check_failure
+to :none, nothing will happen on conformance check failures.

data/lib/protocol.rb

@@ -1,248 +1,7 @@
-# :stopdoc:
-# vim: set et sw=2 ts=2:
-# :startdoc:
+require 'protocol/version'
 require 'parse_tree'
 require 'sexp_processor'
-#
-# = protocol.rb - Method Protocol Specifications in Ruby 
-#
-# == Author
-#
-# Florian Frank mailto:flori@ping.de
-#
-# == License
-#
-# This is free software; you can redistribute it and/or modify it under the
-# terms of the GNU General Public License Version 2 as published by the Free
-# Software Foundation: www.gnu.org/copyleft/gpl.html
-#
-# == Download
-#
-# The latest version of <b>protocol</b> can be found at
-#
-# * http://rubyforge.org/frs/?group_id=4778
-#
-# The homepage of this library is located at
-#
-# * http://protocol.rubyforge.org
-#
-# == Description
-#
-# 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. Additionally you can define preconditions/postconditions
-# for methods specified in a protocol.
-# 
-# == Usage
-#
-# This defines a protocol named +Enumerating+:
-#
-#  Enumerating = Protocol do
-#    # Iterate over each element of this Enumerating class and pass it to the
-#    # +block+.
-#    def each(&block) end
-#
-#    include Enumerable
-#  end
-#
-# Every class, that conforms to this protocol, has to implement the understood
-# messages (+each+ in this example - with no ordinary arguments and a block
-# argument). The following would be an equivalent protocol definition:
-#
-#  Enumerating = Protocol do
-#    # Iterate over each element of this Enumerating class and pass it to the
-#    # +block+.
-#    understand :each, 0, true
-#
-#    include Enumerable
-#  end
-# 
-# An example of a conforming class is the class +Ary+:
-#  class Ary
-#    def initialize
-#      @ary = [1, 2, 3]
-#    end
-#  
-#    def each(&block)
-#      @ary.each(&block)
-#    end
-#  
-#    conform_to Enumerating
-#  end
-#
-# The last line (this command being the last line of the class definition is
-# important!) of class +Ary+ <tt>conform_to Enumerating</tt> checks the
-# conformance of +Ary+ to the +Enumerating+ protocol. If the +each+ method were
-# not implemented in +Ary+ a CheckFailed exception would have been thrown,
-# containing all the offending CheckError instances.
-#
-# It also mixes in all the methods that were included in protocol +Enumerating+
-# (+Enumerable+'s instance methods). More examples of this can be seen in the
-# examples sub directory of the source distribution of this library in file
-# examples/enumerating.rb.
-#
-# === Template Method Pattern
-#
-# It's also possible to mix protocol specification and behaviour implementation
-# 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
-#         yield
-#       ensure
-#         unlock
-#       end
-#     end
-#   end
-#
-# This specifies a Locking protocol against which several class implementations
-# can be checked against for conformance. Here's a FileMutex implementation:
-#
-#  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
-#
-# The Locking#synchronize method is a template method (see
-# http://en.wikipedia.org/wiki/Template_method_pattern), that uses the
-# implemtented methods, to make block based locking possbile:
-#
-#  mutex = FileMutex.new
-#  mutex.synchronize do
-#    puts "Synchronized with '#{file.path}'."
-#  end
-#  
-# Now it's easy to swap the implementation to a memory based mutex
-# implementation instead:
-#
-#  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
-#
-# To check an +object+ for conformity to the Locking protocol call
-# Locking.check +object+ and rescue a CheckFailed. Here's an example class
-#
-#  class MyClass
-#    def initialize
-#      @mutex = FileMutex.new
-#    end
-#
-#    attr_reader :mutex
-#
-#    def mutex=(mutex)
-#      Locking.check mutex
-#      @mutex = mutex
-#    end
-#  end
-#
-# This causes a CheckFailed exception to be thrown:
-#  obj.mutex = Object.new
-#
-# This would not raise an exception:
-#  obj.mutex = MemoryMutex.new
-#
-# And neither would this
-#
-#  obj.mutex = Mutex.new # => #<Mutex:0xb799a4f0 @locked=false, @waiting=[]>
-#
-# because coincidentally this is true
-#
-#  Mutex.conform_to? Locking # => true
-#
-# and thus Locking.check doesn't throw an exception. See the
-# examples/locking.rb file for code.
-#
-# === Preconditions and Postconditions
-#
-# You can add additional runtime checks for method arguments and results by
-# specifying pre- and postconditions. Here is the classical stack example, that
-# shows how:
-#
-#  StackProtocol = Protocol do
-#    def push(x)
-#      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? }
-#      postcondition { size == s - 1 }
-#    end
-#  end
-#
-# Defining protocols and checking against conformance doesn't get in the way of
-# Ruby's duck typing, but you can still use protocols to define, document, and
-# check implementations that you expect from client code.
-#
-# === Error modes in Protocols
-#
-# You can set different error modes for your protocols. By default the mode is
-# set to :error, and a failed protocol conformance check raises a CheckError (a
-# marker module) exception. Alternatively you can set the error mode to
-# :warning with:
-#
-#  Foo = Protocol do
-#    check_failure :warning
-#  end
-#
-# during Protocol definition or later
-#
-#   Foo.check_failure :warning
-#
-# In :warning mode no execptions are raised, only a warning is printed to
-# STDERR. If you set the error mode via Protocol::ProtocolModule#check_failure
-# to :none, nothing will happen on conformance check failures.
-#
+
 module Protocol
   class ::Object
     # Returns true if this object conforms to +protocol+, otherwise false.

data/lib/protocol/version.rb

@@ -0,0 +1,8 @@
+module Protocol
+  # Protocol version
+  VERSION         = '0.8.2'
+  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

data/make_doc.rb

@@ -1,9 +1,6 @@
 #!/usr/bin/env ruby
 # vim: set et sw=2 ts=2:
 
-require 'rbconfig'
-
-bindir = Config::CONFIG['bindir']
 $outdir = 'doc/'
 puts "Creating documentation in '#$outdir'."
-system "#{bindir}/ruby #{bindir}/rdoc -S -d --main=Protocol -o #$outdir lib/protocol.rb"
+system "rdoc --main=doc-main.txt -o #$outdir doc-main.txt lib/protocol.rb"

data/protocol.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+Gem::Specification.new do |s|
+    s.name = 'protocol'
+    s.version = '0.8.2'
+    s.files = ["CHANGES", "COPYING", "Rakefile", "VERSION", "doc-main.txt", "examples", "examples/comparing.rb", "examples/enumerating.rb", "examples/game.rb", "examples/hello_world_patternitis.rb", "examples/indexing.rb", "examples/locking.rb", "examples/queue.rb", "examples/stack.rb", "install.rb", "lib", "lib/protocol", "lib/protocol.rb", "lib/protocol/core.rb", "lib/protocol/version.rb", "make_doc.rb", "protocol.gemspec", "tests", "tests/test_protocol.rb"]
+    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', '~> 3.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://protocol.rubyforge.org"
+    s.rubyforge_project = "protocol"
+  end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: protocol
 version: !ruby/object:Gem::Version 
-  version: 0.8.1
+  version: 0.8.2
 platform: ruby
 authors: 
 - Florian Frank
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-12-17 00:00:00 +01:00
+date: 2009-07-28 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -20,7 +20,7 @@ dependencies:
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        version: "2.0"
+        version: "3.0"
     version: 
 description: 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.
 email: flori@ping.de
@@ -28,37 +28,39 @@ executables: []
 
 extensions: []
 
-extra_rdoc_files: []
-
+extra_rdoc_files: 
+- doc-main.txt
 files: 
-- install.rb
+- CHANGES
+- COPYING
+- Rakefile
+- VERSION
+- doc-main.txt
 - examples
+- examples/comparing.rb
+- examples/enumerating.rb
+- examples/game.rb
+- examples/hello_world_patternitis.rb
 - examples/indexing.rb
 - examples/locking.rb
 - examples/queue.rb
 - examples/stack.rb
-- examples/enumerating.rb
-- examples/game.rb
-- examples/comparing.rb
-- examples/hello_world_patternitis.rb
-- Rakefile
+- install.rb
 - lib
 - lib/protocol
-- lib/protocol/core.rb
 - lib/protocol.rb
-- VERSION
+- lib/protocol/core.rb
+- lib/protocol/version.rb
 - make_doc.rb
+- protocol.gemspec
 - tests
 - tests/test_protocol.rb
-- CHANGES
-- COPYING
 has_rdoc: true
 homepage: http://protocol.rubyforge.org
 post_install_message: 
 rdoc_options: 
-- --title
-- Method Protocols for Ruby Classes
-- -S
+- --main
+- doc-main.txt
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement