gecoder 0.8.3 → 0.9.0

data/lib/gecoder/interface/constraints/bool_enum/relation.rb

@@ -1,87 +1,54 @@
-module Gecode
-  module BoolEnumMethods
-    # Produces an expression that can be handled as if it was a variable 
-    # representing the conjunction of all boolean variables in the enumeration.
+module Gecode::BoolEnum
+  module BoolEnumOperand
+    # Produces a BoolOperand that represents the conjunction (AND) of all
+    # boolean operands in this enumeration.
+    #
+    # ==== Examples 
+    #
+    #   # Conjunction of all elements in +bool_enum+.
+    #   bool_enum.conjunction
     def conjunction
-      return Gecode::Constraints::BoolEnum::Relation::ConjunctionStub.new(
-        @model, :lhs => self)
+      Relation::BoolEnumConjunctionOperand.new(@model, self)
     end
     
-    # Produces an expression that can be handled as if it was a variable 
-    # representing the disjunction of all boolean variables in the enumeration.
+    # Produces a BoolOperand that represents the disjunction (OR) of all
+    # boolean operands in this enumeration.
+    #
+    # ==== Examples 
+    #
+    #   # Disjunction of all elements in +bool_enum+.
+    #   bool_enum.disjunction
     def disjunction
-      return Gecode::Constraints::BoolEnum::Relation::DisjunctionStub.new(
-        @model, :lhs => self)
+      Relation::BoolEnumDisjunctionOperand.new(@model, self)
     end
   end
-end
 
-module Gecode::Constraints::BoolEnum
   # A module that gathers the classes and modules used by boolean enumeration 
   # relation constraints.
   module Relation #:nodoc:
-    # Describes a CompositeStub for the conjunction constraint, which constrain
-    # the conjunction of all boolean variables in an enumeration.
-    # 
-    # == Example
-    # 
-    #   # The conjunction of all variables in +bool_enum+ must be true. I.e. all
-    #   # boolean variables must take the value true.
-    #   bool_enum.conjunction.must_be.true
-    #   
-    #   # The conjunction of all variables in +bool_enum+ must equal b1.
-    #   bool_enum.conjunction.must ==  b1
-    #   
-    #   # The conjunction of all variables in +bool_enum+ must not equal b1 and 
-    #   # b2. It's reified it with +bool+ and selects the strength +domain+.
-    #   bool_enum.conjunction.must_not.equal(b1 & b2, :reify => bool, 
-    #     :strength => :domain)
-    class ConjunctionStub < Gecode::Constraints::Bool::CompositeStub
-      def constrain_equal(variable, params, constrain)
-        enum = @params[:lhs]
-        
-        @model.add_interaction do
-          if variable.respond_to? :bind
-            bound = variable.bind
-          else
-            bound = variable ? 1 : 0
-          end
-          Gecode::Raw::rel(@model.active_space, Gecode::Raw::BOT_AND,
-            enum.to_bool_var_array, bound, *propagation_options)
-        end
-        return variable
+    class BoolEnumConjunctionOperand < Gecode::Bool::ShortCircuitEqualityOperand #:nodoc:
+      def initialize(model, bool_enum)
+        super model
+        @enum = bool_enum
+      end
+
+      def constrain_equal(bool_operand, constrain_domain, propagation_options)
+        Gecode::Raw::rel(@model.active_space, Gecode::Raw::BOT_AND,
+          @enum.to_bool_enum.bind_array, bool_operand.to_bool_var.bind, 
+          *propagation_options)
       end
     end
     
-    # Describes a CompositeStub for the disjunction constraint, which constrain
-    # the disjunction of all boolean variables in an enumeration.
-    # 
-    # == Example
-    # 
-    #   # The disjunction of all variables in +bool_enum+ must be true. I.e. at
-    #   # least one of the boolean variables must take the value true.
-    #   bool_enum.disjunction.must_be.true
-    #   
-    #   # The disjunction of all variables in +bool_enum+ must equal b1.
-    #   bool_enum.conjunction.must ==  b1
-    #   
-    #   # The disjunction of all variables in +bool_enum+ must not equal b1 and 
-    #   # b2. It's reified it with +bool+ and selects the strength +domain+.
-    #   bool_enum.disjunction.must_not.equal(b1 & b2, :reify => bool, 
-    #     :strength => :domain)
-    class DisjunctionStub < Gecode::Constraints::Bool::CompositeStub
-      def constrain_equal(variable, params, constrain)
-        enum = @params[:lhs]
-        
-        @model.add_interaction do
-          if variable.respond_to? :bind
-            bound = variable.bind
-          else
-            bound = variable ? 1 : 0
-          end
-          Gecode::Raw::rel(@model.active_space, Gecode::Raw::BOT_OR,
-            enum.to_bool_var_array, bound, *propagation_options)
-        end
+    class BoolEnumDisjunctionOperand < Gecode::Bool::ShortCircuitEqualityOperand #:nodoc:
+      def initialize(model, bool_enum)
+        super model
+        @enum = bool_enum
+      end
+
+      def constrain_equal(bool_operand, constrain_domain, propagation_options)
+        Gecode::Raw::rel(@model.active_space, Gecode::Raw::BOT_OR,
+          @enum.to_bool_enum.bind_array, bool_operand.to_bool_var.bind, 
+          *propagation_options)
       end
     end
   end

data/lib/gecoder/interface/constraints/bool_enum_constraints.rb

@@ -1,28 +1,79 @@
-module Gecode
-  module BoolEnumMethods
-    include Gecode::Constraints::LeftHandSideMethods
-    
+# A module containing constraints that have enumerations of boolean 
+# operands as left hand side.
+module Gecode::BoolEnum #:nodoc:
+  # A BoolEnumOperand is a enumeration of BoolOperand on which the
+  # constraints defined in BoolEnumConstraintReceiver can be placed.
+  #
+  # Enumerations of boolean operands can be created either by using
+  # Gecode::Model#bool_var_array and Gecode::Model#bool_var_matrix, or
+  # by wrapping an existing enumeration containing BoolOperand using
+  # Gecode::Model#wrap_enum. The enumerations, no matter how they were
+  # created, all respond to the properties defined by BoolEnumOperand.
+  #
+  # ==== Examples 
+  #
+  # Produces an array of five boolean operands inside a problem formulation
+  # using Gecode::Model#bool_var_array:
+  #
+  #   bool_enum = bool_var_array(5)
+  #
+  # Uses Gecode::Model#wrap_enum inside a problem formulation to create
+  # a BoolEnumOperand from an existing enumeration containing the
+  # boolean operands +bool_operand1+ and +bool_operand2+:
+  #
+  #   bool_enum = wrap_enum([bool_operand1, bool_operand2])
+  #   
+  #--
+  # Classes that mix in BoolEnumOperand must define #model and
+  # #to_bool_enum .
+  module BoolEnumOperand
+    include Gecode::Operand 
+
+    def method_missing(method, *args) #:nodoc:
+      if Gecode::BoolEnum::Dummy.instance_methods.include? method.to_s
+        # Delegate to the bool enum.
+        to_bool_enum.method(method).call(*args)
+      else
+        super
+      end
+    end
+
     private
-    
-    # Produces an expression for the lhs module.
-    def expression(params)
-      params.update(:lhs => self)
-      Constraints::BoolEnum::Expression.new(@model, params)
+
+    def construct_receiver(params)
+      BoolEnumConstraintReceiver.new(@model, params)
     end
   end
-  
-  # A module containing constraints that have enumerations of boolean variables 
-  # as left hand side.
-  module Constraints::BoolEnum
-    # Expressions with bool enums as left hand sides.
-    class Expression < Gecode::Constraints::Expression #:nodoc:
-      # Raises TypeError unless the left hand side is a bool enum.
-      def initialize(model, params)
-        super
-        
-        unless params[:lhs].respond_to? :to_bool_var_array
-          raise TypeError, 'Must have bool enum as left hand side.'
-        end
+
+  # BoolEnumConstraintReceiver contains all constraints that can be
+  # placed on a BoolEnumOperand.
+  #
+  # Constraints are placed by calling BoolEnumOperand#must (or any other
+  # of the variations defined in Operand), which produces a
+  # BoolEnumConstraintReceiver from which the desired constraint can be
+  # used.
+  #
+  # ==== Examples 
+  #
+  # Constrains +bool_enum+, with three boolean operands, to take the 
+  # value of the tuples [false, true, false] or [true, false, true] 
+  # using BoolEnumConstraintReceiver#in:
+  #
+  #   bool_enum.must_be.in [[false, true, false], [true, false, true]]
+  #
+  # Constrains +bool_enum+ to channel +int_operand+ using 
+  # BoolEnumConstraintReceiver#channel:
+  #
+  #   bool_enum.must.channel int_operand
+  #
+  class BoolEnumConstraintReceiver < Gecode::ConstraintReceiver
+    # Raises TypeError unless the left hand side is an bool enum
+    # operand.
+    def initialize(model, params) #:nodoc:
+      super
+
+      unless params[:lhs].respond_to? :to_bool_enum
+        raise TypeError, 'Must have bool enum operand as left hand side.'
       end
     end
   end

data/lib/gecoder/interface/constraints/bool_var_constraints.rb

@@ -1,72 +1,151 @@
-module Gecode
-  class FreeBoolVar
-    include Gecode::Constraints::LeftHandSideMethods
-    
+# A module that deals with the operands, properties and constraints of
+# boolean operands.
+module Gecode::Bool #:nodoc:
+  # A BoolOperand is a combination of variables on which the
+  # constraints defined in BoolConstraintReceiver can be placed.
+  #
+  # Boolean operands can be created either by using
+  # Gecode::Model#bool_var et al, or by using properties that produce
+  # boolean operands. The operands, no matter how they were created, 
+  # all respond to the properties defined by BoolOperand.
+  #
+  # ==== Examples 
+  #
+  # Produces a single boolean operand (more specifically a BoolVar)
+  # inside a problem formulation, using Gecode::Model#bool_var:
+  #
+  #   bool_operand = bool_var
+  #
+  # Uses the BoolOperand#& property to produce a new boolean
+  # operand representing +bool_operand1+ AND +bool_operand2+:
+  #
+  #   new_bool_operand = bool_operand1 & bool_operand2
+  #
+  # Uses the BoolEnumOperand#conjunction property to produce a new
+  # boolean operand representing the conjunction of all boolean operands
+  # in the enumeration +bool_enum+:
+  #
+  #   new_bool_operand = bool_enum.conjunction
+  #
+  #--
+  # Classes that mix in BoolOperand must define #model and #to_bool_var .
+  module BoolOperand  
+    include Gecode::Operand 
+
+    def method_missing(method, *args) #:nodoc:
+      if Gecode::BoolVar.instance_methods.include? method.to_s
+        # Delegate to the bool var.
+        to_bool_var.method(method).call(*args)
+      else
+        super
+      end
+    end
+
     private
-    
-    # Produces an expression for the lhs module.
-    def expression(params)
-      params.update(:lhs => self)
-      Constraints::Bool::Expression.new(@model, params)
+
+    def construct_receiver(params)
+      BoolConstraintReceiver.new(@model, params)
     end
   end
-  
-  # A module containing constraints that have int variables as left hand side
-  # (but not enumerations).
-  module Constraints::Bool
-    # Describes a boolean expression.
-    class Expression < Gecode::Constraints::Expression #:nodoc:
-    end
-    
-    # A composite expression which is an bool expression with a left hand side 
-    # resulting from a previous constraint.
-    class CompositeExpression < Gecode::Constraints::CompositeExpression #:nodoc:
-      # The block given should take three parameters. The first is the variable 
-      # that should be the left hand side, if it's nil then a new one should be
-      # created. The second is the has of parameters. The block should return 
-      # the variable used as left hand side.
-      def initialize(model, params, &block)
-        super(Expression, Gecode::FreeBoolVar, lambda{ model.bool_var }, model,
-          params, &block)
-      end
-      
-      # Override to also deal with constant booleans.
-      def true(options = {})
-        # We don't need any additional constraints.
-        @params.update Gecode::Constraints::Util.decode_options(options)
-        @model.add_interaction do
-          @constrain_equal_proc.call(!@params[:negate], @params)
-        end
+
+  # BoolConstraintReceiver contains all constraints that can be
+  # placed on a BoolOperand.
+  #
+  # Constraints are placed by calling BoolOperand#must (or any other
+  # of the variations defined in Operand), which produces a 
+  # BoolConstraintReceiver from which the desired constraint can be used.
+  #
+  # Each constraint accepts a number of options. See ConstraintReceiver
+  # for more information.
+  #
+  # ==== Examples 
+  #
+  # Constrains +bool_operand+ to be true using
+  # BoolConstraintReceiver#true:
+  #
+  #   bool_operand.must_be.true
+  #
+  # Constrains +bool_operand1+ AND +bool_operand2+ to be true using 
+  # the BoolOperand#& property and BoolConstraintReceiver#true:
+  #
+  #   (bool_operand1 & bool_operand2).must_be.true
+  #
+  # Constrains the conjunction of all boolean operands in +bool_enum+ to
+  # _not_ imply +bool_operand+ using the 
+  # BoolEnumOperand#conjunction property and BoolConstraintReceiver#imply:
+  #
+  #   bool_enum.conjunction.must_not.imply bool_operand
+  #
+  # The same as above, but specifying that strength :domain should be 
+  # used and that the constraint should be reified with +bool_operand2+:
+  #
+  #   bool_enum.conjunction.must_not.imply(bool_operand, :strength => :domain, :reify => bool_operand2)
+  #
+  class BoolConstraintReceiver < Gecode::ConstraintReceiver
+    # Raises TypeError unless the left hand side is an bool operand.
+    def initialize(model, params) #:nodoc:
+      super
+
+      unless params[:lhs].respond_to? :to_bool_var
+        raise TypeError, 'Must have bool operand as left hand side.'
       end
-      
-      # Override to also deal with constant booleans.
-      def false(options = {})
-        # We don't need any additional constraints.
-        @params.update Gecode::Constraints::Util.decode_options(options)
-        @model.add_interaction do
-          @constrain_equal_proc.call(@params[:negate], @params)
+    end
+  end
+
+  # An operand that short circuits boolean equality.
+  class ShortCircuitEqualityOperand #:nodoc:
+    include Gecode::Bool::BoolOperand
+    attr :model
+
+    def initialize(model)
+      @model = model
+    end
+
+    def construct_receiver(params)
+      params.update(:lhs => self)
+      receiver = BoolConstraintReceiver.new(@model, params)
+      op = self
+      receiver.instance_eval{ @short_circuit = op }
+      class <<receiver
+        alias_method :equality_without_short_circuit, :==
+        def ==(operand, options = {})
+          if !@params[:negate] and options[:reify].nil? and 
+              operand.respond_to? :to_bool_var
+            # Short circuit the constraint.
+            @params.update Gecode::Util.decode_options(options)
+            @model.add_constraint(Gecode::BlockConstraint.new(
+                @model, @params) do
+              @short_circuit.constrain_equal(operand, false,
+                @params.values_at(:strength, :kind))
+            end)
+          else
+            equality_without_short_circuit(operand, options)
+          end
         end
+        alias_comparison_methods
       end
+
+      return receiver
     end
-    
-    # Describes a stub that produces an int variable, which can then be used 
-    # with the normal int variable constraints. An example would be the 
-    # conjunction constraint.
-    #
-    #   bools.conjunction.must == b1 | b2
-    #
-    # <tt>bools.conjunction</tt> produces a boolean variable which the 
-    # constraint <tt>.must == b1 | b2</tt> is then applied to. In the above 
-    # case two constraints (and one temporary variable) are required, but in 
-    # the case of equality only one constraint is required.
-    # 
-    # Whether a constraint involving a reification stub supports negation, 
-    # reification, strength options and so on depends on the constraint on the
-    # right hand side.
-    class CompositeStub < Gecode::Constraints::CompositeStub
-      def initialize(model, params)
-        super(CompositeExpression, model, params)
+
+    def to_bool_var
+      variable = model.bool_var
+      options = 
+        Gecode::Util.decode_options({}).values_at(:strength, :kind)
+      model.add_interaction do
+        constrain_equal(variable, true, options)
       end
+      return variable
+    end
+
+    private
+
+    # Constrains this operand to equal +bool_operand+ using the
+    # specified +propagation_options+. If +constrain_domain+ is true
+    # then the method should also attempt to constrain the bounds of the
+    # domain of +bool_operand+.
+    def constrain_equal(bool_operand, constrain_domain, propagation_options)
+      raise NotImplementedError, 'Abstract method has not been implemented.'
     end
   end
 end

data/lib/gecoder/interface/constraints/extensional_regexp.rb

@@ -5,7 +5,7 @@ module Gecode
     # omitted then no upper bound is placed. If both +at_least+ and
     # +at_most+ are omitted then no bounds are placed.
     #
-    # See Constraints::IntEnum::Extensional::RegexpConstraint for the
+    # See IntEnum::Extensional::RegexpConstraint for the
     # allowed syntax of +regexp+.
     def repeat(regexp, at_least = nil, at_most = nil)
       unless at_least.nil? or at_least.kind_of? Fixnum
@@ -17,7 +17,7 @@ module Gecode
           "Expected the at_most argument to be a Fixnum, got #{at_most.class}"
       end
 
-      reg = Constraints::Util::Extensional.parse_regexp regexp
+      reg = Util::Extensional.parse_regexp regexp
       if at_most.nil?
         if at_least.nil?
           reg.send '*'
@@ -48,12 +48,12 @@ module Gecode
     # Matches any of the specified +regexps+.
     def any(*regexps)
       regexps.inject(Gecode::Raw::REG.new) do |result, regexp|
-        result | Constraints::Util::Extensional.parse_regexp(regexp)
+        result | Util::Extensional.parse_regexp(regexp)
       end
     end
   end
 
-  module Constraints::Util::Extensional
+  module Util::Extensional
     module_function
 
     # Parses a regular expression over the integer domain, returning