conditions 0.0.2.alpha

data/.gitignore

@@ -0,0 +1,4 @@
+pkg/*
+*.gem
+.bundle
+nbproject/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in conditions.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,24 @@
+Copyright (c) 2011, André Gawron
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+- Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+- Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+- The names of its contributors may be used to endorse or promote products
+  derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.rdoc

@@ -0,0 +1,37 @@
+= Conditions
+
+Conditions is some kind of low-level condition-based
+event-handler suitable for different kind of uses.
+Typical use is error handling. it's ported from LISP's Condition System:
+
+http://gigamonkeys.com/book/beyond-exception-handling-conditions-and-restarts.html
+
+THIS IS HIGHLY ALPHA! DO NOT USE IN PRODUCTION!
+(but syntax is most likely not going to change)
+
+For more information, read covering blog posts on:
+
+http://www.andre-gawron.de/123/the-diversity-of-error-handling
+
+http://www.andre-gawron.de/187/road-to-condition
+
+== Patching
+
+It's currently extending the Object class. Why? Kinda easy.
+I don't want to write Conditions::handle (etc).
+
+The Object class is patched as soon as Conditions are required. 
+I'm lookin into actually check before patching if there are other
+methods already in the Object class and probably not allow
+patching then. But that's for the future, it's alpha, right?
+
+== I'd like to patch and / or help maintain Conditions. How can I?
+
+Are you sure? Ok, feel free to ...
+
+* Fork the project: http://github.com/melkon/conditions
+* Make your feature addition or bug fix.
+
+== Copyright
+
+Copyright (c) 2011 André Gawron. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/conditions.gemspec

@@ -0,0 +1,19 @@
+$:.push File.expand_path("../lib", __FILE__)
+require "conditions/version"
+
+Gem::Specification.new do |s|
+  s.name        = "conditions"
+  s.version     = Conditions::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["André Gawron"]
+  s.email       = ["andre@ziemek.de"]
+  s.homepage    = "https://github.com/melkon/conditions"
+  s.summary     = %q{Implements the Lisp's condition system in Ruby}
+  s.description = %q{Implements the Lisp's condition system in Ruby}
+  s.license     = 'BSD'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/example/another-log

@@ -0,0 +1,6 @@
+yes
+no
+no
+no
+no
+yes

data/example/example.rb

@@ -0,0 +1,72 @@
+require "conditions"
+
+class MalformedLogEntryError < Condition ; end
+
+bind :NoticeSignaled => lambda { invoke :Suppress}
+
+p (bind :NoticeSignaled => lambda { invoke :Suppress } do
+  "block value is returning!"
+end)
+
+def parse_log_entry text
+
+  if !well_formed? text then
+
+    restart :UseValue     => proc { |value| text = value },
+            :ReparseEntry => proc { |fixed| text = parse_log_entry fixed } do
+
+      error MalformedLogEntryError
+
+    end
+    
+  end
+
+  text
+
+end
+
+def parse_log_file file
+
+  File.open(file).each do |line|
+
+    entry = (restart :SkipLogEntry => lambda { nil } do
+      parse_log_entry line
+    end)
+
+    yield entry if entry
+
+  end
+
+end
+
+def log_analyzer
+
+  bind :ConditionNotDefined    => lambda { invoke :Define },
+       :MalformedLogEntryError => lambda { invoke :UseValue, "failed\n" } do
+    find_logs do |log|
+      analyze_log log
+    end
+  end
+
+end
+
+def analyze_log log
+  parse_log_file log do |entry|
+    analyze_entry entry
+  end
+end
+
+def well_formed? text
+  "yes\n" == text ? true : false
+end
+
+def analyze_entry entry
+  p entry
+end
+
+def find_logs
+  yield "./log"
+  yield "./another-log"
+end
+
+log_analyzer

data/example/log

@@ -0,0 +1,5 @@
+yes
+yes
+no
+no
+yes

data/lib/conditions.rb

@@ -0,0 +1,16 @@
+# main api
+require "conditions/signals"
+require "conditions/handles"
+require "conditions/restarts"
+
+# base condition classes
+require "conditions/definitions/defaults"
+
+# helper functions and exception definitions
+require "conditions/lib/helpers"
+require "conditions/lib/exceptions"
+
+# remove this and the puppy will cry
+class Object
+  include Conditions
+end

data/lib/conditions/definitions/defaults.rb

@@ -0,0 +1,38 @@
+class Condition
+
+  attr_reader :dynamic, :trace, :message, :restarts
+
+  def initialize message = nil
+
+    @message = message
+    
+    @trace = Kernel.caller
+    @dynamic = false
+    @restarts = Utils::Handler::get_restarts
+
+  end
+
+end
+
+class ConditionDynamic < Condition
+  
+  def initialize *params
+
+    super params
+
+    @params = params
+    @dynamic = true
+    
+  end
+
+  def get key
+    @params[key]
+  end
+
+end
+
+class DynamicConditionCreation  < Condition ; end
+class ConditionNotDefined       < Condition ; end
+class NoDynamicConditionAllowed < Condition ; end
+
+class NoticeSignaled < Condition ; end

data/lib/conditions/handles.rb

@@ -0,0 +1,143 @@
+module Conditions
+
+  #
+  # handles a signaled condition
+  #
+  # handles a condition signaled by #signal or any other signaling method
+  # by registering handlers for given conditions.
+  #
+  # if a handler matches a condition, it will be executed and after that,
+  # the stack will be unwound to the point where the latest #handle registered
+  # a handler for given condition returning the value of the executed handler.
+  #
+  # @param *conditions conditions which shall be catched by #handle,
+  # @param &block block which will be executed normally if no condition will be signaled
+  #
+  # @return return value of &block
+  # @return if a condition is catched, the return value of the registered handler
+  #
+  # @raises ConditionHandled if the catched condition doesnt belong to current block
+  #
+  # @see #parse_handlers for syntax information on *conditions
+  #
+  def handle *conditions, &block
+
+    conditions = Utils::parse_handlers conditions
+
+    conditions.each do |condition|
+      Utils::Handler::set(:condition, condition.merge!(:raise => true))
+    end
+
+    value = begin
+      block.call
+    rescue Exception::ConditionHandled => ex
+
+      # if condition doesnt belong to this block,
+      # continue unwinding the stack
+      if !Utils::find_handler(ex.condition[:name], conditions) then
+        raise Exception::ConditionHandled, :value => ex.value, :condition => ex.condition
+      end
+
+      ex.value
+
+    end
+
+    conditions.each do |condition|
+      Utils::Handler::unset(:condition, condition)
+    end
+
+    value
+
+  end
+
+  #
+  # binds a handler to a condition
+  #
+  # #bind works similiar to #handle but instead of unwinding the stack,
+  # #bind returns the value of the last called handler.
+  #
+  # caveat:
+  #
+  # *if* there's a condition bound by #handle in the upper callstack
+  # *and* the same condition is bound by #bind inside of this #handle,
+  # the system will unwind the stack to #handle - but the condition's handler
+  # bound by #bind will be executed and properly unregistered.
+  #
+  # @param *conditions conditions which shall be bound by #bind,
+  # @param &block block which will be executed normally if no condition will be signaled
+  #
+  # @return return value of &block
+  # @return if a condition is signaled and bound by #bind, it returns value of the last registered handler
+  #
+  # @see #parse_handlers for syntax information on *conditions
+  #
+  def bind *conditions, &block
+
+    conditions = Utils::parse_handlers conditions
+
+    conditions.each do |condition|
+      Utils::Handler::set(:condition, condition.merge!(:raise => false))
+    end
+
+    value = true
+    if block_given? then
+
+      value = begin
+
+        # tmp save the value of the callback
+        # and return it after the conditions were unset
+        value = block.call
+
+        conditions.each do |condition|
+          Utils::Handler::unset(:condition, condition)
+        end
+
+        value
+
+      # it is possible that a Condition has a handler registered by #handle
+      # and therefore will unwind the stack. but if a handler bound by #bind
+      # and #bind is used with a block, the bound handler will not be unregistered.
+      # therefore, catch the exception intended for #handle
+      # unregister the handler registered by #bind
+      # and rethrow the exception again to reach the proper #handle
+      rescue Exception::ConditionHandled => ex
+
+        conditions.each do |condition|
+          Utils::Handler::unset(:condition, condition)
+        end
+
+        raise Exception::ConditionHandled, :value => ex.value, :condition => ex.condition
+
+      end
+
+    end
+
+    value
+
+  end
+
+  #
+  # unregisters a bound condition
+  #
+  # if bind is used without a block,
+  # #unbind is used to unregister the condition's handler
+  #
+  # @param *conditions conditions which shall be unregistered by #unbind,
+  #
+  # @return [Boolean] true
+  #
+  # @see #parse_handlers for syntax information on *conditions
+  #
+  def unbind *conditions
+
+    conditions = Utils::parse_handlers conditions
+
+    conditions.each do |condition|
+      Exception::Handler::unset(:condition, condition)
+    end
+
+    true
+
+  end
+
+end

data/lib/conditions/lib/exceptions.rb

@@ -0,0 +1,35 @@
+module Conditions::Exception
+
+  class ConditionNotHandledError < StandardError ; end
+  class ConditionHandled < StandardError
+
+    attr_reader :value, :condition
+
+    def initialize info
+
+      super info[:value]
+
+      @value = info[:value]
+      @condition = info[:condition]
+
+    end
+
+  end
+
+  class RestartNotFoundError < StandardError ; end
+  class RestartHandled < StandardError
+
+    attr_reader :value, :restart
+
+    def initialize info
+
+      super info[:value]
+
+      @value = info[:value]
+      @restart = info[:restart]
+
+    end
+
+  end
+
+end

data/lib/conditions/lib/helpers.rb

@@ -0,0 +1,226 @@
+module Conditions::Utils
+
+  class Handler
+
+    @@types = {:condition => {},
+                :restart   => {}}
+
+    #
+    # yields every registered condition for given type
+    #
+    # opts:
+    #   :reverse => true|false [default: true] LIFO or FIFO of yielded handlers
+    #
+    # @param [String, Symbol] supported types: :condition, :restart
+    # @param [String, Symbol] name of the condition
+    # @param [Hash] opts current available: :reverse => true
+    #
+    def self.get(type, condition_name, opts = {})
+
+      condition_name = Utils::normalize(condition_name)
+
+      if (!@@types[type].has_key?(condition_name)) or (@@types[type][condition_name].empty?)
+        return nil
+      end
+
+      opts[:reserve] = true unless opts[:reserve] === false
+
+      if opts[:reserve] === true
+        direction = :reverse_each
+      else
+        direction = :each
+      end
+
+      @@types[type][condition_name].send(direction) do |condition|
+
+        condition[:name] = condition_name
+
+        yield condition
+
+      end
+
+    end
+
+    def self.get_restarts()
+      return @@types[:restarts];
+    end
+
+    def self.get_handlers()
+      return @@types[:condition];
+    end
+
+    def self.set(type, condition)
+
+      condition[:name] = Utils::normalize(condition[:name])
+
+      @@types[type][condition[:name]] = [] unless @@types[type][condition[:name]]
+      @@types[type][condition[:name]].push({:block => condition[:block],
+                                            :raise => condition[:raise]})
+
+    end
+
+    def self.unset(type, condition)
+
+      condition[:name] = Utils::normalize(condition[:name])
+
+      @@types[type][condition[:name]].each_with_index do |saved_condition, index|
+
+        if saved_condition[:block] == condition[:block]
+
+          # completely delete the restart-entry if no block is given anymore
+          if 2 >@@types[type][condition[:name]].size then
+            @@types[type].delete(condition[:name])
+          else
+            @@types[type][condition[:name]].delete_at(index)
+          end
+
+          # unset only one condition
+          return true
+
+        end
+
+      end
+
+    end
+
+  end
+
+  #
+  # parses magically the correct handlers / restarts
+  #
+  # #parse_handlers takes a hash as an argument and tries to identify
+  # the handlers / restarts and their callbacks. the syntax is the same for both.
+  #
+  # the simpliest is:
+  #
+  # :HandlerName => callback[, ...]
+  #
+  # class names are also supported:
+  #
+  # HandlerNAme => callback[, ...]
+  #
+  # class names as well as symbol will be casted to strings internally.
+  #
+  # currently, the callback has to be a lambda or
+  # a proc function to work within the condition system.
+  #
+  # it's also possible to define multiple handlers / restarts with the same callback:
+  #
+  # :HandlerName1, :HandlerName2, {:HandlerName3 => callback}[, ...]
+  #
+  # now let's mix everything together:
+  #
+  # :HandlerName => callback, HandlerName1, {:HandlerName2 => callback}, :HandlerName3 => callback
+  #
+  # why does this work?
+  #
+  # it's a lot of magic with hashes, since the #handle and #restart functions are using the * operator.
+  # this way, the parameters are wrapped in a Hash and can be magically transformed.
+  #
+  # @param [Hash] handlers a multidimensional Hash
+  #
+  # @return [Hash] a structured hash {{:name => :HandlerName, :block => callback}[, ...}}
+  #
+  def self.parse_handlers(handlers)
+
+    without_proc = []
+    parsed = []
+
+    handlers.each do |handler|
+
+      if handler.is_a? Hash
+
+        handler.each do |handler_name, handler_proc|
+
+          without_proc.each do |handler_name|
+            parsed.push(:name => handler_name, :block => handler_proc)
+          end
+
+          parsed.push(:name => handler_name, :block => handler_proc)
+
+        end
+
+        without_proc.clear
+
+      else
+
+        without_proc.push(handler)
+
+      end
+
+    end
+
+    parsed
+
+  end
+
+  #
+  # creates a condition object
+  #
+  # creates a condition object of given conditon_name symbol or string-class
+  # if the requested condition_name is not a existing class,
+  # #generate_condition registers a restart offering to dynamically create class.
+  # currently, the new class will be created in the module Conditions.
+  #
+  # this condition class inherits the class ConditionDynamic.
+  #
+  # @param [String, Symbol] condition_name the condition class' name to instance. it must start with an upper case letter!
+  # @param *params parameters forwarded to the condition class' constructor
+  #
+  # @return [Condition] object of the demanded condition class
+  #
+  # @error :ConditionNotDefined if requested condition class does not exist
+  #
+  # @restart :Define creates a dynamic condition named like condition_name
+  #
+  def self.generate_condition(condition_name, *params)
+
+    if not condition_name.kind_of?(Class)
+
+      if !Conditions.const_defined? condition_name then
+        restart :WriteToFile => lambda { p "will be implemented anytime soon" },
+                 :Define      => lambda { Conditions::const_set(condition_name, Class.new(ConditionDynamic))
+                                           notice :DynamicConditionCreation, "#{condition_name} dynamically created" } do
+
+            error :ConditionNotDefined, condition_name
+        end
+      end
+
+      condition_name = Conditions::const_get(condition_name)
+
+    end
+    
+    condition_name.new(*params)
+
+  end
+
+  #
+  # finds a handler in the given hash
+  #
+  # @param [String, Symbol] the handler / restart to find
+  # @param [Hash] a hash of handlers / restarts: {{:name => :Handlername}[, ...]}
+  #
+  # @return [Boolean] true if found
+  # @return [Boolean] false if not
+  #
+  def self.find_handler(name, handlers)
+
+    name = Utils::normalize(name)
+
+    handlers.each do |handler|
+
+      if name == handler[:name]
+        return true
+      end
+
+    end
+
+    false
+
+  end
+
+  def self.normalize(name)
+    return name.to_s
+  end
+
+end

data/lib/conditions/restarts.rb

@@ -0,0 +1,76 @@
+module Conditions
+
+  #
+  # register a possible restart-option
+  #
+  # register a possible restart-option
+  # which can be invoked by an condition handler using #invoke
+  #
+  # since its possible to access the method's scope
+  # you can actually modify the method's behaviour from a handler
+  # which can be pretty dangerous but also very rewarding.
+  #
+  # if no restart was invoked, it returns the value of the block
+  # otherwise, it returns the value of invoked restart
+  #
+  # @param *restarts register restarts
+  # @param &block the code to execute normally
+  #
+  # @return value of the &block
+  # @return value of the invoked restart
+  #
+  # @raises RestartHandled if the catched restart doesnt belong to this block
+  #
+  # @see #parse_handlers for syntax information on *conditions
+  #
+  def restart *restarts, &block
+
+    restarts = Utils::parse_handlers restarts
+
+    restarts.each { |restart|  Utils::Handler::set(:restart, restart)}
+
+    value = begin
+      block.call
+    rescue Exception::RestartHandled => ex
+
+      # if restart doesnt belong to this block,
+      # continue unwinding the stack
+      if !Utils::find_handler(ex.restart, restarts) then
+        raise Exception::RestartHandled, :value => ex.value, :restart => ex.restart
+      end
+
+      ex.value
+
+    end
+
+    restarts.each { |restart| Utils::Handler::unset(:restart, restart)}
+
+    value
+
+  end
+
+  #
+  # invokes a registered restart
+  #
+  # #invoke checks if a restart with restart_name was registered
+  # and calls it if found.
+  #
+  # @param [String] restart_name the restart which shall be invoked
+  # @param *params parameters which are needed by the restart
+  #
+  # @raises RestartHandled if a invoked restart is called
+  # @raises RestartNotFoundError if a demanded restart was not found
+  #
+  # @see #parse_handlers for syntax information on *conditions
+  #
+  def invoke restart_name, *params
+
+    Utils::Handler::get(:restart, restart_name) do |restart|
+      raise Exception::RestartHandled, :value => restart[:block].call(*params), :restart => restart_name
+    end
+
+    raise Exception::RestartNotFoundError, restart_name
+
+  end
+
+end

data/lib/conditions/signals.rb

@@ -0,0 +1,95 @@
+module Conditions
+
+  #
+  # calls the registered handler for given condition
+  #
+  # if the registered handler is established using #handle,
+  # the call to #signal will not return and raise an exception instead.
+  #
+  # if it's established using bind, #signal will return normally with
+  # the handler's returned value.
+  #
+  # @param [Symbol] conditon_name the condition to signal
+  # @param *params additional information wich will be directly passed
+  #                to the condition's constructor
+  #
+  # @return value the return value of the called handler.
+  #
+  # @raises ConditionHandled if a handler is established with #handle
+  #
+  def signal condition_name, *params
+
+    value = nil
+
+    condition = Utils::generate_condition condition_name, *params
+
+    Utils::Handler::get :condition, condition_name do |handler|
+
+      value = case handler[:block].arity
+        when 0 then handler[:block].call
+        when 1 then handler[:block].call condition
+        when 2 then handler[:block].call condition, value
+      end
+
+      raise(Exception::ConditionHandled, :value => value, :condition => handler) if handler[:raise]
+
+    end
+
+    value
+
+  end
+
+  #
+  # errors a condition
+  #
+  # it's build on top of #signal but will raise an ConditionNotHandledError
+  # if #signal returns normally. This ensures that a condition errored using
+  # #error has to be handled by a condition handler with an non-local exit
+  # as it's done by using #handle.
+  #
+  # @param [Symbol] condition condition's name
+  # @param *params additional information wich will be directly passed
+  #                to the condition's constructor
+  #
+  # @raises ConditionNotHandledError if the condition was not handled
+  #
+  def error condition, *params
+
+    signal condition, *params
+
+    raise Exception::ConditionNotHandledError, "condition #{condition} was not handled"
+
+  end
+
+  #
+  # notices a condition
+  #
+  # it's build on top of #signal and will print the given message
+  # it can be suppressed by invoking the restart :Suppress.
+  #
+  # since notice is calling #signal,
+  # the given condition can also be handled
+  #
+  # if no handler is bound to given condition, #notice returns normally.
+  #
+  # @param [Symbol] condition condition's name
+  # @param [String] message
+  #
+  # @return nil or bound handler's returned value
+  #
+  # @signal :NoticeSignaled if #notice got called.
+  #
+  # @restart :Suppress message will not be printed
+  #
+  def notice condition, message
+
+    restart :Suppress => lambda { nil } do
+      signal :NoticeSignaled, condition
+      print "Notice: #{message}"
+    end
+
+    signal condition
+
+  end
+
+end

data/lib/conditions/version.rb

@@ -0,0 +1,3 @@
+module Conditions
+  VERSION = "0.0.2.alpha"
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification 
+name: conditions
+version: !ruby/object:Gem::Version 
+  prerelease: 6
+  version: 0.0.2.alpha
+platform: ruby
+authors: 
+- "Andr\xC3\xA9 Gawron"
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-08-31 00:00:00 Z
+dependencies: []
+
+description: Implements the Lisp's condition system in Ruby
+email: 
+- andre@ziemek.de
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- LICENSE
+- README.rdoc
+- Rakefile
+- conditions.gemspec
+- example/another-log
+- example/example.rb
+- example/log
+- example/newfile
+- lib/conditions.rb
+- lib/conditions/definitions/defaults.rb
+- lib/conditions/handles.rb
+- lib/conditions/lib/exceptions.rb
+- lib/conditions/lib/helpers.rb
+- lib/conditions/restarts.rb
+- lib/conditions/signals.rb
+- lib/conditions/version.rb
+homepage: https://github.com/melkon/conditions
+licenses: 
+- BSD
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 1.3.1
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.5
+signing_key: 
+specification_version: 3
+summary: Implements the Lisp's condition system in Ruby
+test_files: []
+