constraint 0.1 → 0.2

data/README.TXT

@@ -1,37 +1,48 @@
-This library provides a way to ensure that object always satisfy a 
-specified set of constraints. An object that can be constrained must be 
-of kind <tt>Constraint::Shell</tt>. Constraints can be added to classes 
-and single objects. It is possible to define methods that handle 
-constraint violations and can make the object fit the demands.
+:title:  Constraint -- Ensure that objects always satisfy a set of constraints
+
+
+This library provides a way to ensure that certain objects always 
+satisfy a specified set of constraints. An object that can be 
+constrained must be a child of <tt>Constraint::Shell</tt>, which acts as 
+a wrapper for the actual value. Constraints can added to subclasses and 
+its instances (per-object constraints). It is possible to define methods 
+that handle constraint violations and retrofit the object according to 
+its definition.
+
+With some help from the developer, this library can also be used (to 
+some extent at least) to generate correct values and to find solutions 
+fitting the set of constraints.
 
 Project::  http://rubyforge.org/projects/constraint/
 Download:: http://rubyforge.org/frs/?group_id=748
 Support::  http://rubyforge.org/forum/?group_id=748
 
-In my experience, a certain type of errors in dynamically typed 
-languages are caused by pushing some wrong object to a collection type 
-of object. What makes this type of error so awkward is that they often 
-result in an exception in some totally different part of your program, 
-which is why it sometimes can be quite hard to track down what is 
-actually causing the problem. The goal of this library is to raise an 
-exception right where such a thing happens. While ruby is sometimes a 
-little bit hesitant in raising exceptions, this library tries to 
-counteract this tendency a little bit.
+In my experience, a certain type of error in dynamically typed languages 
+is caused by pushing a wrong object to a collection or similar. What 
+makes this type of error so awkward is that they often result in an 
+exception in a different part of your program, which is why it can 
+sometimes be unnecessarily difficult to track down what is actually 
+causing the problem. The goal of this library is to raise an exception 
+right where such a thing happens. While ruby is sometimes a little bit 
+hesitant in raising exceptions, this library tries to gently counteract 
+this attitude a little.
 
 Be aware that this library introduces yet another level of indirection 
-and yet additional runtime checks what slows things down a little. If 
+and yet additional runtime checks which slows things down a little. If 
 you define CONSTRAINT_DISABLE before requiring the library, constraint 
 checks will be deactivated.
 
 
-= Documentation
+= Examples
 
 Constrained classes should inherit from <tt>Constraint::Shell</tt>. The 
 subclass should provide a way for defining new instances (by defining 
 #new_constrained) and redefine #process_constrained_value. The 
 @constrained_value instance variable contains the shell's actual values.
 
-Examples:
+== Basic use
+
+    require 'constraint'
 
     class ConstrainedArray < Constraint::Shell
         def new_constrained
@@ -44,38 +55,110 @@ Examples:
     end
 
     class NumericArray < ConstrainedArray
-        or_constraint("Numeric") {|e| e.kind_of?(Numeric)}
+        or_constraint("Numeric") {|o, e| e.kind_of?(Numeric)}
     end
 
     class EvenNumericArray < NumericArray
-        and_constraint("Even") {|e| e.modulo(2) == 0}
+        and_constraint("Even") {|o, e| e.modulo(2) == 0}
     end
 
+    enarr = EvenNumericArray.new([2,4,6])
+    enarr
+    => [2, 4, 6]
+    enarr << 8
+    => [2, 4, 6, 8]
+    enarr << 9
+    (irb):23:in `irb_binding': Fixnum didn't meet constraint 'Even': 9 (ConstraintViolation)
+
+
     class EvenInteger < Constraint::Shell
-        and_constraint("Numeric") {|e| e.kind_of?(Integer)}
-        and_constraint("Even") {|e| e.modulo(2) == 0}
+        and_constraint("Numeric") {|o, e| e.kind_of?(Integer)}
+        and_constraint("Even") {|o, e| e.modulo(2) == 0}
     end
 
     enum = EvenInteger.new(2)
-    enum.and_constraint("LT10") {|e| e < 10}
+    enum.and_constraint("LT10") {|o, e| e < 10}
+
+    enum + 2
+    => 4
+
+    enum + 1
+    (irb):11:in `irb_binding': Fixnum didn't meet constraint 'Even': 3 (ConstraintViolation)
+
+    enum.on_constraint_violation('Even') {|o, e| (e / 2).round * 2}
+    enum + 1
+    => 2
+
 
-or:
+== Duckismo
 
     class DuckPalace < ConstrainedArray
-        and_constraint('Quack') {|e| e.do_you_quack?}
-        and_constraint('Ticket') {|e| e.your_ticket_please == :valid}
+        and_constraint('Quack') {|o, e| e.do_you_quack?}
+        and_constraint('Ticket') {|o, e| e.your_ticket_please == :valid}
     end
 
     whiteduckpalace = DuckPalace.new
-    whiteduckpalace.and_constraint('White') {|e| e.colour == 'white'}
-    class << whiteduckpalace
-        def handle_constraint_violation(contraint_name, object)
-            case contraint_name
-            when 'white'
-                return object.paint_me('white') if object.respond_to?(:paint_me)
+    whiteduckpalace.and_constraint('White') {|o, e| e.colour == 'white'}
+    whiteduckpalace.on_constraint_violation('White') do |o, e|
+        if e.respond_to?(:paint)
+            e.paint('white')
+        else
+            raise ConstraintViolation
+        end
+    end
+
+
+== Generators
+
+With some help from the programmer, +Constraint+ can generate valid 
+values and collect possible solutions fulfilling a set of constraints.  
+The only prerequisite is to define the method 
+#generate_constrained_value that gives the next value in line (starting 
+from a value given as argument, which can be nil) or raises a 
+Constraint::NoMoreValues exception if no more values are available. This 
+isn't the most sophisticated solution but it may be useful in some 
+situations.
+
+Here is a basic example that illustrates this use of the library:
+
+    class NumInRange < Constraint::Shell
+        constraint_attr :min, 0
+        constraint_attr :max, nil
+        
+        and_constraint('Numeric') {|o, e| e.kind_of?(Numeric)}
+        and_constraint('InRange') {|o, e| o.min <= e && (!o.max || o.max >= e)}
+        on_constraint_violation('InRange') {|o, e| (o.max && e > o.max) ? o.max : o.min}
+
+        def generate_constrained_value(value)
+            if value
+                if !max or @max > value
+                    value + 1
+                else
+                    raise Constraint::NoMoreValues
+                end
+            else
+                @min
             end
-            return super
         end
     end
 
+    class Num1To10 < NumInRange
+        @min = 1
+        @max = 10
+    end
+
+    p Num1To10.new
+    => 1
+    p Num1To10.new(-10)
+    => 1
+    p Num1To10.new(5.2) + 2.2
+    => 7.4
+    p Num1To10.new(5.2) + 20.2
+    => 10
+    p Num1To10.new.collect_constrained_values
+    => [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+    p Num1To10.new(5).collect_constrained_values
+    => [5, 6, 7, 8, 9, 10]
+    p Num1To10.new(5).collect_constrained_values_until {|e| e == 8}
+    => [5, 6, 7]
 

data/VERSION.TXT

@@ -1 +1 @@
-0.1
+0.2

data/examples/in_range.rb

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+# in_range.rb
+# @Author:      Thomas Link
+# @License:     GPL (see http://www.gnu.org/licenses/gpl.txt)
+# @Created:     14-Jun-2005.
+# @Last Change: 14-Jun-2005.
+# @Revision:    0.135
+#
+# = Description
+# = Usage
+# = TODO
+# = CHANGES
+
+require 'constraint'
+
+class NumInRange < Constraint::Shell
+    constraint_attr :min, 0
+    constraint_attr :max, nil
+    
+    and_constraint('Numeric') {|o, e| e.kind_of?(Numeric)}
+    and_constraint('InRange') {|o, e| o.min <= e && (!o.max || o.max >= e)}
+    on_constraint_violation('InRange') {|o, e| (o.max && e > o.max) ? o.max : o.min}
+
+    def generate_constrained_value(value)
+        if value
+            if !max or @max > value
+                value + 1
+            else
+                raise Constraint::NoMoreValues
+            end
+        else
+            @min
+        end
+    end
+end
+
+
+if __FILE__ == $0
+    p "--- NumInRange"
+    p n = NumInRange.new
+    p n.max = 10
+    p n.collect_constrained_values
+    
+    p n = NumInRange.new(5)
+    p n.max = 10
+    p n.collect_constrained_values
+    p n.max
+    p (n + 20).max
+
+    p "--- Num1To10"
+    class Num1To10 < NumInRange
+        @min = 1
+        @max = 10
+    end
+
+    p Num1To10.new
+    p Num1To10.new(1)
+    p Num1To10.new(5).collect_constrained_values
+    p Num1To10.new(5).collect_constrained_values_until {|e| e == 8}
+    p Num1To10.new(10)
+    p Num1To10.new(0)
+    p Num1To10.new(20)
+    
+    p Num1To10.new(1.3)
+    p Num1To10.new(5.3)
+    p Num1To10.new(0.3)
+    p Num1To10.new(10.3)
+    p Num1To10.new(-10)
+    p Num1To10.new(5.2) + 2.2
+    p Num1To10.new(5.2) + 20.2
+end
+

data/examples/primes.rb

@@ -0,0 +1,97 @@
+#!/usr/bin/env ruby
+# primes.rb
+# @Author:      Thomas Link (samul@web.de)
+# @License:     GPL (see http://www.gnu.org/licenses/gpl.txt)
+# @Created:     12-Jun-2005.
+# @Last Change: 12-Jun-2005.
+# @Revision:    0.178
+
+require 'constraint'
+
+# Primes: 
+class Prime < Constraint::Shell
+    @@primes   = [2, 3]
+    @@noprimes = [4, 6, 9]
+
+    class << self
+        def collect_primes(n)
+            pr = Prime.new(n)
+            pr.instance_eval do
+                @@primes[0..@@primes.index(pr.constrained_value)]
+            end
+        end
+    end
+    
+    def new_constrained
+        generate_constrained_value(nil)
+    end
+
+    def generate_constrained_value(value)
+        if !value
+            return 2
+        elsif value <= 2
+            super
+        elsif value == 3
+            return 2
+        else
+            if value.modulo(2) == 0
+                return value - 1
+            else
+                return value - 2
+            end
+        end
+    end
+
+    def add_noprime(n)
+        add_this_noprime(n)
+        for pr in @@primes[0..10]
+            nn = n * pr
+            add_this_noprime(nn)
+        end
+    end
+
+    def add_this_noprime(n)
+        unless @@noprimes.include?(n)
+            @@noprimes << n
+        end
+    end
+    
+    def check_prime(n)
+        next_constrained_value!(n)
+        for pr in @@primes
+            if pr > n
+                break
+            elsif n.modulo(pr) == 0
+                add_noprime(n)
+                return false
+            end
+        end
+        @@primes << n
+        true
+    end
+
+    and_constraint('KnownNoPrime') {|p, n| !@@noprimes.include?(n)}
+    and_constraint('KnownPrime') {|p, n| @@primes.include?(n)}
+    or_constraint('Prime') {|p, n| p.check_prime(n)}
+    on_constraint_violation('Prime', 'KnownNoPrime') do |o, n|
+        o.next_constrained_value!(n).constrained_value
+    end
+end
+
+
+if __FILE__ == $0
+    p (p = Prime.new(3))
+    p p.next_constrained_value!
+
+    p Prime.new(100)
+    p Prime.collect_primes(100)
+    
+    def test_prime(n)
+        puts "#{n} => #{Prime.new(n).inspect}"
+    end
+
+    for i in 3..20
+        test_prime(i)
+    end
+end
+

data/examples/queens.rb

@@ -0,0 +1,108 @@
+#!/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.190
+#
+# = Description
+# = Usage
+# = TODO
+# = CHANGES
+
+require 'constraint'
+
+QUEEN_MIN = 1
+QUEEN_MAX = 5
+
+class Queen < Constraint::Shell
+    # or_constraint('Numeric') {|q, e| e.kind_of?(Numeric)}
+    # or_constraint('Range') {|q, e| e >= QUEEN_MIN && e <= QUEEN_MAX}
+
+    def strike_any?(x, board)
+        board.each_with_index do |q, ox0|
+            ox = ox0 + 1
+            if x != ox
+                y = @constrained_value
+                oy = q.constrained_value
+                if y == oy or ((y - oy).abs == (x - ox).abs)
+                    # p "DBG #{x}x#{y} #{ox}x#{oy} #{y-oy} #{x-ox}"
+                    return true
+                end
+            end
+        end
+        return false
+    end
+end
+
+class QueensBoard < Constraint::Shell
+    def new_constrained
+        @boards = []
+        @masks  = []
+        nil
+    end
+
+    def process_constrained_value
+        if @constrained_value
+            super
+        end
+    end
+        
+    def new_board(pos)
+        unless (b = @boards[pos])
+            b = []
+            QUEEN_MAX.downto(1) do |x|
+                xx, pos = pos.divmod(QUEEN_MAX ** (x - 1))
+                b << Queen.new(xx + 1)
+            end
+            @boards[pos] = b
+        end
+        b
+    end
+   
+    def board
+        new_board(@constrained_value)
+    end
+    
+    or_constraint('Good') do |qb, board|
+        begin
+            b = qb.new_board(board)
+        rescue Exception => e
+            p e
+        end
+        # p b.collect {|e| e.constrained_value}
+        rv = true
+        b.each_with_index do |e, i|
+            if e.strike_any?(i + 1, b)
+                rv = false
+                break
+            end
+        end
+        rv
+    end
+
+    def generate_constrained_value(value)
+        if !value
+            0
+        elsif value < (QUEEN_MAX ** QUEEN_MAX)
+            value + 1
+        else
+            super
+        end
+    end
+end
+
+
+if __FILE__ == $0
+    b = QueensBoard.new
+    
+    puts "First solution:"
+    p b.next_constrained_value!.board.collect {|e| e.constrained_value}
+
+    puts "All Solutions:"
+    for board in b.collect_constrained_values_until {|e| e >= (QUEEN_MAX ** QUEEN_MAX) - 2}
+        p board.board.collect {|e| e.constrained_value}
+    end
+end
+