constraint 0.1 → 0.2

data/examples/queens_ca.rb

@@ -0,0 +1,83 @@
+#!/usr/bin/env ruby
+# queens.rb
+# @Author:      Thomas Link (samul@web.de)
+# @License:     GPL (see http://www.gnu.org/licenses/gpl.txt)
+# @Created:     11-Jun-2005.
+# @Last Change: 12-Jun-2005.
+# @Revision:    0.290
+
+require 'constraint'
+
+QUEEN_MIN   = 1
+QUEEN_MAX   = 5
+MAX_BOARD_N = (QUEEN_MAX ** QUEEN_MAX) - 1
+
+class QueensBoard < Constraint::CArray
+    attr_reader :curr_board_n
+
+    def new_constrained
+        @boards = []
+        @masks  = []
+        @curr_board_n = 0
+        super
+    end
+    
+    def generate_constrained_value(value)
+        if (@curr_board_n += 1) <= MAX_BOARD_N
+            return board(@curr_board_n)
+        else
+            super
+        end
+    end
+
+    def board(pos=nil)
+        if pos
+            unless (b = @boards[pos])
+                b = @boards[pos] = []
+                (QUEEN_MAX - 1).downto(0) do |x|
+                    y, pos = pos.divmod(QUEEN_MAX ** x)
+                    b << y
+                end
+            end
+            return b
+        else
+            return @constrained_value
+        end
+    end
+   
+    def good?(x, y)
+        @constrained_value.each_with_index do |ox, oy|
+            if y == oy
+                next
+            elsif x == ox or ((y - oy).abs == (x - ox).abs)
+                return false
+            end
+        end
+        return true
+    end
+
+    or_constraint('Good') do |qb, queen|
+        rv = true
+        qb.constrained_value.each_with_index do |x, y|
+            if !qb.good?(x, y)
+                rv = false
+                break
+            end
+        end
+        rv
+    end
+end
+
+
+if __FILE__ == $0
+    b = QueensBoard.new
+    
+    puts "First solution:"
+    p b.next_constrained_value!.board.collect {|e| e}
+
+    puts "All Solutions:"
+    for board in b.collect_constrained_values_until {|e| b.curr_board_n >= MAX_BOARD_N}
+        p board.board.collect {|e| e}
+    end
+end
+

data/examples/queens_cb.rb

@@ -0,0 +1,82 @@
+#!/usr/bin/env ruby
+# queens.rb
+# @Author:      Thomas Link (samul@web.de)
+# @License:     GPL (see http://www.gnu.org/licenses/gpl.txt)
+# @Created:     11-Jun-2005.
+# @Last Change: 12-Jun-2005.
+# @Revision:    0.388
+
+require 'constraint'
+
+QUEEN_MIN   = 1
+QUEEN_MAX   = 5
+MAX_BOARD_N = (QUEEN_MAX ** QUEEN_MAX) - 1
+
+class QueensBoard < Constraint::CArray
+    attr_reader :curr_board_n
+
+    def new_constrained
+        @boards = []
+        @masks  = []
+        @curr_board_n = 0
+        super
+    end
+    
+    def generate_constrained_value(value)
+        if (@curr_board_n += 1) <= MAX_BOARD_N
+            return board(@curr_board_n)
+        else
+            super(@curr_board_n)
+        end
+    end
+
+    def board(pos=nil)
+        if pos
+            unless (@constrained_value = @boards[pos])
+                @constrained_value = []
+                (QUEEN_MAX - 1).downto(0) do |x|
+                    y, pos = pos.divmod(QUEEN_MAX ** x)
+                    self << [x, y]
+                end
+                @boards[pos] = @constrained_value
+            end
+        end
+        return @constrained_value
+    end
+   
+    or_constraint('Good') do |qb, queen|
+        x, y = queen
+        rv = true
+        qb.constrained_value.each do |other_queen|
+            if queen.equal?(other_queen)
+                next
+            end
+            ox, oy = other_queen
+            if y == oy or x == ox or ((y - oy).abs == (x - ox).abs)
+                rv = false
+                break
+            end
+        end
+        rv
+    end
+end
+
+
+if __FILE__ == $0
+    b = QueensBoard.new
+    
+    puts "First solution:"
+    p b.next_constrained_value!.board.collect {|x, y| y}
+
+    puts "All Solutions:"
+    for board in b.collect_constrained_values_until {|e| b.curr_board_n >= MAX_BOARD_N - 1}
+        b = board.board
+        # b.sort do |q1, q2|
+        #     x1, y1 = q1
+        #     x2, y2 = q2
+        #     x1 <=> x2
+        # end
+        p b.collect {|x, y| y}
+    end
+end
+

data/examples/queens_s.rb

@@ -0,0 +1,85 @@
+#!/usr/bin/env ruby
+# queens.rb
+# @Author:      Thomas Link (samul@web.de)
+# @License:     GPL (see http://www.gnu.org/licenses/gpl.txt)
+# @Created:     11-Jun-2005.
+# @Last Change: 12-Jun-2005.
+# @Revision:    0.223
+
+require 'constraint'
+
+QUEEN_MIN = 1
+QUEEN_MAX = 5
+
+class QueensBoard < Constraint::Shell
+    def new_constrained
+        @boards = []
+        @masks  = []
+        @max_board = (QUEEN_MAX ** QUEEN_MAX) - 1
+        nil
+    end
+
+    def process_constrained_value
+        if @constrained_value
+            super
+        end
+    end
+        
+    def generate_constrained_value(value)
+        if !value
+            return 0
+        elsif value < @max_board
+            return value + 1
+        else
+            super
+        end
+    end
+
+    def board(pos=@constrained_value)
+        unless (b = @boards[pos])
+            b = @boards[pos] = []
+            QUEEN_MAX.downto(1) do |x|
+                xx, pos = pos.divmod(QUEEN_MAX ** (x - 1))
+                b << xx
+            end
+        end
+        return b
+    end
+   
+    def strike_any?(x, y, board)
+        board.each_with_index do |oy, ox|
+            if x == ox
+                next
+            elsif y == oy or ((y - oy).abs == (x - ox).abs)
+                return true
+            end
+        end
+        return false
+    end
+
+    or_constraint('Good') do |qb, board|
+        b  = qb.board(board)
+        rv = true
+        b.each_with_index do |y, i|
+            if qb.strike_any?(i, y, b)
+                rv = false
+                break
+            end
+        end
+        rv
+    end
+end
+
+
+if __FILE__ == $0
+    b = QueensBoard.new
+    
+    puts "First solution:"
+    p b.next_constrained_value!.board.collect {|e| e}
+
+    puts "All Solutions:"
+    for board in b.collect_constrained_values_until {|e| e >= (QUEEN_MAX ** QUEEN_MAX) - 2}
+        p board.board.collect {|e| e}
+    end
+end
+

data/examples/run_queens.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+for i in queens*; do
+    echo ------$i
+    time ruby $i
+done

data/lib/constraint.rb

@@ -2,110 +2,114 @@
 # @Author:      Thomas Link (samul AT web.de)
 # @License:     GPL (see http://www.gnu.org/licenses/gpl.txt)
 # @Created:     23-Mai-2005.
-# @Last Change: 09-Jun-2005.
-# @Revision:    607
+# @Last Change: 14-Jun-2005.
+# @Revision:    986
 
-
-class ConstraintViolation < Exception
-end
+require 'forwardable'
 
 
-# If CONSTRAINT_DISABLE is set to true *before* loading this library, 
+# If CONSTRAINT_DISABLE is set to true _before_ loading this library, 
 # constraint checking is turned off.
 CONSTRAINT_DISABLE = false unless defined?(CONSTRAINT_DISABLE)
 
 
 module Constraint
-    VERSION = '0.1'
+    VERSION = '0.2'
+    
+
+    class Violation < Exception
+    end
     
-    # The base constraint class. Always evaluates to true.
-    class NilConstraint
+    class NoMoreValues < Violation
+    end
+
+    # The base constraint class.
+    class SingleConstraint
         # shell:: The Shell class containing this constraint
         # name::  This constraint's name
         # description:: Optional constraint description
         # block:: The constraint that must evaluate to true in order for this constraint to succeed
         def initialize(shell, name, description=nil, &block)
-            @shell       = shell
-            @other       = shell.constraints
+            # @other       = shell.constraints
             @name        = name
-            @description = description
             @this        = block
         end
 
-        # Return true if +args+ complies with @this constraint.
-        def evaluate(object)
-            begin
-                rv = @this.call(object)
-            rescue Exception => e
-                @shell.log_constraint_exception(e)
-            end
-            begin
-                if @other
-                    return evaluate_control(rv, object)
-                elsif rv
-                    return object
-                else
-                    return evaluate(handle_violation(object))
-                end
-            rescue ConstraintViolation => e
-                raise e
+        def evaluate(invoker, object)
+            if @this.call(invoker, object)
+                object
+            else
+                invoker.handle_constraint_violation(@name, object)
             end
         end
-
-        # Delegate to Shell#handle_constraint_violation.
-        def handle_violation(object)
-            return @shell.handle_constraint_violation(@name, object)
-        end
-
-        private
-        # Combine constraints. In the base class, always evaluate to 
-        # true.
-        def evaluate_control(value, object)
-            raise "Subclass responsibility"
-            # value ? object : handle_violation(object)
-        end
     end
-   
-    class OrConstraint < NilConstraint
-        private
-        # Return true if +value+ or the @other constraint are true.
-        def evaluate_control(value, object)
-            value ? object : @other.evaluate(object)
+
+    # All constraints must succeed.
+    class AndConstraint < Array
+        def evaluate(invoker, object)
+            for a in self
+                object = a.evaluate(invoker, object)
+            end
+            object
         end
     end
-
-    class AndConstraint < NilConstraint
-        private
-        # Return true if +value+ and the @other constraint are true.
-        def evaluate_control(value, object)
-            return value ? @other.evaluate(object) : handle_violation(object)
+    
+    # At least one constraint must succeed.
+    class OrConstraint < Array
+        def evaluate(invoker, object)
+            c = nil
+            for o in self
+                begin
+                    return o.evaluate(invoker, object)
+                rescue Constraint::Violation => e
+                    c = e
+                end
+            end
+            raise c
         end
     end
-
+    
     module Helper
         # The current class's/object's head constraint.
         attr_reader :constraints
-        # A hash of constraint descriptions.
-        attr_reader :descriptions
+        # A hash of constraint constaint_descriptions.
+        attr_reader :constaint_descriptions
+        # An array of constraint handlers
+        attr_reader :constaint_handlers
+        # An array of additional attributes that should be copied when 
+        # replicating a shell
+        attr_reader :constraint_attributes
        
-        # Define an OrConstraint. If the new constraint succeedes, all 
-        # previous constraints become obsolete.
+        # Define an OrConstraint. Either this or the previous constraint have to succeed.
         # name::  This constraint's name
         # description:: Optional constraint description
         # block:: The constraint that must evaluate to true in order for this constraint to succeed
         def or_constraint(name, desc=nil, &block)
             describe_constraint(name, desc)
-            @constraints = OrConstraint.new(self, name, desc, &block)
+            @constraints = @constraints.dup
+            constraint   = SingleConstraint.new(self, name, desc, &block)
+            if @constraints.empty?
+                @constraints << constraint
+            else
+                last = @constraints.last
+                case last
+                when OrConstraint
+                    last << constraint
+                else
+                    @constraints[-1] = OrConstraint.new([last, constraint])
+                end
+            end
         end
 
-        # Define an AndConstraint. This and all previous constraints 
+        # Define an SingleConstraint. This and all previous constraints 
         # have to succeed.
         # name::  This constraint's name
         # description:: Optional constraint description
         # block:: The constraint that must evaluate to true in order for this constraint to succeed
         def and_constraint(name, desc=nil, &block)
             describe_constraint(name, desc)
-            @constraints = AndConstraint.new(self, name, desc, &block)
+            @constraints = @constraints.dup
+            @constraints << SingleConstraint.new(self, name, desc, &block)
         end
 
         # If $VERBOSE is set, print the exception to $stderr.
@@ -115,50 +119,94 @@ module Constraint
             end
         end
 
-        # Handle constraint violations. Can be overwritten by subclasses 
-        # in order to rescue the constraint. The return value will 
-        # replace the original object.
-        # name:: The constraint's name that didn't succeed
-        # object:: The object that caused the violation
-        def handle_constraint_violation(name, object)
-            c = @descriptions.collect {|name, desc| desc}.join(', ')
-            raise ConstraintViolation,
-                "#{self.class}: #{object.class} didn't meet constraints (#{c}): #{object.inspect}", 
-                caller[5..-1]
+        # Define a new constraint handler. The block takes a 
+        # continuation as its first argument. If the amendment of the 
+        # object isn't successful, the handler must throw an 
+        # Constraint::Violation exception.
+        #
+        # Example:
+        #
+        #   enum = EvenInteger.new(2)
+        #   enum.and_constraint('LT10') {|enum, n| n < 10}
+        #   enum.on_constraint_violation('LT10') do |o, n|
+        #       n > 10 ? 10 : 0
+        #   end
+        #
+        # *names:: The constraints names
+        # block:: The handler (argument: object)
+        def on_constraint_violation(*names, &block)
+            @constaint_handlers = @constaint_handlers.dup
+            names.each do |name|
+                @constaint_handlers[name] ||= []
+                @constaint_handlers[name] << block
+            end
         end
 
+        def constraint_attr(name, val)
+            (@constraint_attributes = @constraint_attributes.dup) << name
+            instance_eval %{
+                class << self
+                    attr_accessor :#{name}
+                end
+                attr_accessor :#{name}
+            }
+            instance_variable_set("@#{name}", val)
+        end
+
+        # Copy needed class/object variables.
+        def replicate_constraints(predecessor)
+            @constaint_descriptions = predecessor.constaint_descriptions
+            @constaint_handlers     = predecessor.constaint_handlers
+            @constraints            = predecessor.constraints
+            for name in (@constraint_attributes = predecessor.constraint_attributes)
+                nname = "@#{name}"
+                instance_variable_set(nname, predecessor.instance_variable_get(nname))
+            end
+        end
+        
         private
         # Copy constraint-related class-local variables from +klass+ to self. 
-        def inherit_constraint(klass)
-            @descriptions = klass.descriptions.dup
-            @constraints  = klass.constraints
-        end
+        # def inherit_constraint(klass)
+        #     @constaint_descriptions = klass.constaint_descriptions
+        #     @constaint_handlers     = klass.constaint_handlers
+        #     @constraints            = klass.constraints
+        # end
 
         # Register a constraint description. If no description is 
         # provided, the +name+ is used.
         # name:: This constraint's name
         # desc:: Optional constraint description
         def describe_constraint(name, desc=nil)
-            @descriptions[name] = (desc || name)
+            @constaint_descriptions[name] = (desc || name)
         end
     end
 
     # If CONSTRAINT_DISABLE is set to true *before* loading this library, 
     # constraint checking is turned off.
     class Shell
+        extend Forwardable
+
         # The actual value that is covered by the Shell.
         attr_reader :constrained_value
 
-        @descriptions = {}
-        @constraints  = nil
+        @constaint_descriptions = {}
+        @constaint_handlers     = {}
+        # @constraints            = nil
+        @constraints            = AndConstraint.new
+        @constraint_attributes    = []
 
         class << self
             include Helper
-
+ 
+            def delegate_to_constrained_value(meth, alias_name)
+                class_eval %{alias #{alias_name} #{meth}}
+                def_delegator(:@constrained_value, meth)
+            end
+                
             def inherited(subclass)
                 parent = self
                 subclass.class_eval do
-                    inherit_constraint(parent)
+                    replicate_constraints(parent)
                 end
             end
 
@@ -174,12 +222,12 @@ module Constraint
             # Wrap +methods+ so that some arguments are filtered through 
             # #check_constraints. This is useful in two situations:
             # 
-            #   * if filtering the return value would be inefficient -- 
+            # * if filtering the return value would be inefficient -- 
             #   e.g. with methods performing trivial Array operations 
             #   where the return value will comply with the constraints 
             #   if its argument do.
             #
-            #   * if the return value of the method call is not an 
+            # * if the return value of the method call is not an 
             #   instance of the actual value's class (only then will the 
             #   value's integrity be checked)
             # 
@@ -187,7 +235,6 @@ module Constraint
             # 
             # methods:: Method names as symbols
             # block::   Select the arguments that should be filtered
-
             def with_arguments_constrained(*methods, &block)
                 unless CONSTRAINT_DISABLE
                     methods.each do |method|
@@ -215,24 +262,29 @@ module Constraint
 
         include Helper
         
-        def initialize(core=nil, predecessor=nil)
-            if predecessor
-                @descriptions = predecessor.descriptions
-                @constraints  = predecessor.constraints
-            else
-                @descriptions = self.class.descriptions.dup
-                @constraints  = self.class.constraints
-                @constraints  = @constraints.dup if @constraints
-            end
-            
-            if core
-                @constrained_value = core
-            else
-                @constrained_value = new_constrained
-            end
+        delegate_to_constrained_value(:inspect,       :inspect_constraint_shell)
+        delegate_to_constrained_value(:=~,            :match_constraint_shell)
+        delegate_to_constrained_value(:instance_eval, :constraint_shell_eval)
 
+        # delegate_to_constrained_value(:tainted?,      :tainted_constraint_shell?)
+        # delegate_to_constrained_value(:taint,         :taint_constraint_shell)
+        # delegate_to_constrained_value(:untaint,       :untaint_constraint_shell)
+       
+        delegate_to_constrained_value(:===,           :case_equal_constraint_shell)
+        # def ===(other)
+        #     if other.kind_of?(Shell)
+        #         super
+        #     else
+        #         @constrained_value === other
+        #     end
+        # end
+        
+        def initialize(core=nil, predecessor=nil, &block)
+            predecessor ||= self.class
+            replicate_constraints(predecessor)
+            @constrained_value = core || new_constrained
             unless CONSTRAINT_DISABLE
-                process_constrained_value {|e| check_constraints(e)}
+                check_constrained_value
             end
         end
 
@@ -244,12 +296,86 @@ module Constraint
             replicate_constraint_shell(super)
         end
         
-        # Construct a new instance.
+        # Construct a new instance. By default, this method calls 
+        # generate_constrained_value(nil).
         def new_constrained
-            # nil
-            raise 'Subclass responsibility'
+            generate_constrained_value(nil)
+            # raise 'Subclass responsibility'
+        end
+
+        # Generate the next value for #next_constrained_value.
+        def generate_constrained_value(value)
+            raise Constraint::NoMoreValues, "No more values: #{value}"
+        end
+
+        # "Increase" the current value to the next valid one (see 
+        # #generate_constrained_value). Modify the object in-place.
+        def next_constrained_value!(value=nil)
+            begin
+                cv = @constrained_value
+                if value
+                    @constrained_value = value
+                end
+                begin
+                    while (@constrained_value = generate_constrained_value(@constrained_value))
+                        check_constrained_value
+                        return self
+                    end
+                rescue Constraint::NoMoreValues => e
+                    raise e
+                rescue Constraint::Violation => e
+                    retry
+                end
+                raise_constraint_violation(nil, value, "No more values: #{value}")
+            rescue Exception => e
+                @constrained_value = cv
+                raise e
+            end
+        end
+        
+        # Return an object with an increased value (see 
+        # #generate_constrained_value).
+        def next_constrained_value(value=nil)
+            self.clone.next_constrained_value!(value)
+        end
+
+        # Return an array of constrained values starting from the 
+        # current value until a value for which block is true. Requires 
+        # #generate_constrained_value to be defined.
+        def collect_constrained_values_while(&block)
+            collect_constrained_values_control do |val, acc|
+                if (rv = block.call(val))
+                    acc << self.dup
+                    next_constrained_value!
+                end
+                rv
+            end
+        end
+        
+        # Return an array of constrained values starting from the 
+        # current value until a value for which block is true. Requires 
+        # #generate_constrained_value to be defined.
+        def collect_constrained_values_until(&block)
+            collect_constrained_values_control do |val, acc|
+                if (rv = !block.call(val))
+                    acc << self.dup
+                    next_constrained_value!
+                end
+                rv
+            end
         end
        
+        # Collect all values. Shell#generate_constrained_value must 
+        # provide a means to decide when no more values should be 
+        # generated.
+        def collect_constrained_values
+            collect_constrained_values_control do |val, acc|
+                acc << self.dup
+                next_constrained_value!
+                true
+            end
+        end
+        
         # Filters @constrained_value through the supplied block (usually a 
         # call to #check_constraints) and collects the output in 
         # @constrained_value).
@@ -258,6 +384,10 @@ module Constraint
             @constrained_value = yield @constrained_value
         end
       
+        def check_constrained_value
+            process_constrained_value {|e| check_constraints(e)}
+        end
+        
         if CONSTRAINT_DISABLE
             def check_constraints(object)
                 object
@@ -266,7 +396,7 @@ module Constraint
             # Check if +object+ complies with @constraints.
             def check_constraints(object)
                 if @constraints
-                    return @constraints.evaluate(object)
+                    return @constraints.evaluate(self, object)
                 else
                     return object
                 end
@@ -288,7 +418,7 @@ module Constraint
         # Shell.with_arguments_constrained and friends.
         #
         # new_value:: The result from the method call
-        # [block]:: Optional, called @constrained_value is +new_value+
+        # block:: Optional, called @constrained_value is +new_value+
         def with_constraints(new_value)
             if new_value.equal?(@constrained_value)
                 yield if block_given?
@@ -300,6 +430,25 @@ module Constraint
             end
         end
 
+        # Handle constraint violations. Can be overwritten by subclasses 
+        # in order to rescue the constraint. The return value will 
+        # replace the original object.
+        # name:: The constraint's name that didn't succeed
+        # object:: The object that caused the violation
+        def handle_constraint_violation(name, object)
+            handlers = @constaint_handlers[name]
+            if handlers
+                for h in handlers
+                    begin
+                        return h.call(self, object)
+                    rescue Constraint::Violation
+                        next
+                    end
+                end
+            end
+            raise_constraint_violation(name, object)
+        end
+
         if CONSTRAINT_DISABLE
             def method_missing(method, *args, &block)
                 with_constraints(@constrained_value.send(method, *args, &block))
@@ -313,7 +462,7 @@ module Constraint
             def method_missing(method, *args, &block)
                 # $stderr.puts "Constraint::Shell: Delegate method: #{method}" if $DEBUG
                 with_constraints(@constrained_value.send(method, *args, &block)) do
-                    process_constrained_value {|e| check_constraints(e)}
+                    check_constrained_value
                 end
             end
         end
@@ -324,12 +473,47 @@ module Constraint
         end
 
         private
-        # Some kind of semi-deep copy.
-        def replicate_constraint_shell(new_instance)
-            cv = @constrained_value.clone
-            new_instance.instance_eval do
+        # Eval block while it's yielding true. Maintain 
+        # @constrained_value in case of an exception.
+        def collect_constrained_values_control(&block)
+            begin
+                acc = []
+                cv  = @constrained_value
+                begin
+                    while block.call(@constrained_value, acc)
+                    end
+                rescue Constraint::Violation
+                end
+                return acc
+            ensure
                 @constrained_value = cv
             end
+        end
+        
+        # Raise a Constraint::Violation.
+        def raise_constraint_violation(name, object, msg=nil)
+            i = 0
+            caller.each_with_index do |e,l|
+                if e =~ /^(\w+:)?([^:].*?[\\\/])+?constraint.rb:\d+:/
+                    i = l
+                end
+            end
+            msg ||= "#{object.class} didn't meet constraint '#{name}': #{object.inspect}"
+            raise Constraint::Violation, msg, caller[i+1..-1]
+        end
+
+        # Some kind of semi-deep copy. If @constrained_value can't be 
+        # cloned (e.g., a Fixnum), the new_instance will be returned as 
+        # such.
+        # new_instance:: A duplicate of Shell
+        def replicate_constraint_shell(new_instance)
+            begin
+                cv = @constrained_value.clone
+                new_instance.constraint_shell_eval do
+                    @constrained_value = cv
+                end
+            rescue TypeError
+            end
             new_instance
         end
     end