gecoder-with-gecode 0.8.3 → 0.9.0

data/lib/gecoder/interface/constraints/int_enum/extensional.rb

@@ -1,7 +1,17 @@
-module Gecode::Constraints::IntEnum
-  class Expression
-    # Posts a tuple constraint on the variables in the enum, constraining them
-    # to equal one of the specified tuples.
+module Gecode::IntEnum
+  class IntEnumConstraintReceiver
+    # Constrains all the operands in this enumeration to be equal to
+    # one of the specified tuples. Neither negation nor reification is
+    # supported.
+    # 
+    # ==== Examples 
+    # 
+    #   # Constrains the two integer operands in +numbers+ to either have 
+    #   # values 1 and 7, or values 47 and 11.
+    #   numbers.must_be.in [[1,7], [47,11]]
+    #
+    #   # The same as above, but preferring speed over low memory usage.
+    #   numbers.must_be.in([[1,7], [47,11]], :kind => :speed)
     def in(tuples, options = {})
       if @params[:negate]
         raise Gecode::MissingConstraintError, 'A negated tuple constraint is ' +
@@ -12,7 +22,7 @@ module Gecode::Constraints::IntEnum
           'constraint.'
       end
       
-      util = Gecode::Constraints::Util
+      util = Gecode::Util
       
       # Check that the tuples are correct.
       expected_size = @params[:lhs].size
@@ -27,64 +37,9 @@ module Gecode::Constraints::IntEnum
         @params.update(util.decode_options(options)))
     end
 
-    # Adds a constraint that forces the enumeration to match the
-    # specified regular expression over the integer domain. The regular
-    # expression is expressed using arrays and integers. See
-    # IntEnum::Extensional::RegexpConstraint for more information and examples of
-    # such regexps.
-    def match(regexp, options = {})
-      if @params[:negate]
-        raise Gecode::MissingConstraintError, 'A negated regexp constraint ' +
-          'is not implemented.'
-      end
-      unless options[:reify].nil?
-        raise ArgumentError, 'Reification is not supported by the regexp ' + 
-          'constraint.'
-      end
-
-      @params[:regexp] = 
-        Gecode::Constraints::Util::Extensional.parse_regexp regexp
-      @params.update Gecode::Constraints::Util.decode_options(options)
-      @model.add_constraint Extensional::RegexpConstraint.new(@model, @params)
-    end
-  end
-  
-  # A module that gathers the classes and modules used in extensional 
-  # constraints.
-  module Extensional #:nodoc:
-    # Describes a tuple constraint, which constrains all the variables in an 
-    # enumeration of integer variables to be equal to one of the specified 
-    # tuples. Neither negation nor reification is supported.
-    # 
-    # == Example
-    # 
-    #   # Constrains the two integer variables in +numbers+ to either have 
-    #   # values 1 and 7, or values 47 and 11.
-    #   numbers.must_be.in [[1,7], [47,11]]
-    #
-    #   # The same as above, but preferring speed over low memory usage.
-    #   numbers.must_be.in([[1,7], [47,11]], :kind => :speed)
-    class TupleConstraint < Gecode::Constraints::Constraint
-      def post
-        # Bind lhs.
-        lhs = @params[:lhs].to_int_var_array
-
-        # Create the tuple set.
-        tuple_set = Gecode::Raw::TupleSet.new
-        @params[:tuples].each do |tuple|
-          tuple_set.add tuple
-        end
-        tuple_set.finalize
-
-        # Post the constraint.
-        Gecode::Raw::extensional(@model.active_space, lhs, tuple_set, 
-          *propagation_options)
-      end
-    end
-
-    # Describes a regexp constraint, which constrains the enumeration of
-    # integer variables to match a specified regexp in the integer
-    # domain. Neither negation nor reification is supported.
+    # Constrains the sequence of operands in this enumeration to match
+    # a specified regexp in the integer domain. Neither negation nor
+    # reification is supported.
     #
     # == Regexp syntax
     #
@@ -114,7 +69,7 @@ module Gecode::Constraints::IntEnum
     # Additionally Model#at_least_once and Model#at_most_once are
     # provided as convenience methods.
     #
-    # === Examples
+    # ==== Examples 
     #
     #   # Matches 1 followed by any number of 2s.
     #   [1, repeat(2)]
@@ -166,28 +121,66 @@ module Gecode::Constraints::IntEnum
     #   # Exactly the same as the above.
     #   [0, repeat(1, 0, 1)]
     #
-    # == Example
+    # ==== Examples 
     #
-    #   # Constrains the two integer variables in +numbers+ to have
+    #   # Constrains the two integer operands in +numbers+ to have
     #   # values 1 and 7.
     #   numbers.must.match [1, 7]
     #
-    #   # Constrains the integer variables in +numbers+ to contain the
+    #   # Constrains the integer operands in +numbers+ to contain the
     #   # value 47 followed by 11, with all other values set to -1.
     #   numbers.must.match [repeat(-1), 47, 11, repeat(-1)]
     #
-    #   # Constrains exactly three of the integer variables in +numbers+ to 
+    #   # Constrains exactly three of the integer operands in +numbers+ to 
     #   # contain 47 or 11, each followed by at least two
-    #   # variables set to -1. All other variables are constrained to
+    #   # operands set to -1. All other operands are constrained to
     #   # equal -1.
     #   numbers.must.match repeat([repeat(-1), any(11, 47), 
     #                              repeat(-1, 2)], 3, 3)
     #
-    class RegexpConstraint < Gecode::Constraints::Constraint
+    def match(regexp, options = {})
+      if @params[:negate]
+        raise Gecode::MissingConstraintError, 'A negated regexp constraint ' +
+          'is not implemented.'
+      end
+      unless options[:reify].nil?
+        raise ArgumentError, 'Reification is not supported by the regexp ' + 
+          'constraint.'
+      end
+
+      @params[:regexp] = 
+        Gecode::Util::Extensional.parse_regexp regexp
+      @params.update Gecode::Util.decode_options(options)
+      @model.add_constraint Extensional::RegexpConstraint.new(@model, @params)
+    end
+  end
+  
+  # A module that gathers the classes and modules used in extensional 
+  # constraints.
+  module Extensional #:nodoc:
+    class TupleConstraint < Gecode::Constraint #:nodoc:
+      def post
+        # Bind lhs.
+        lhs = @params[:lhs].to_int_enum.bind_array
+
+        # Create the tuple set.
+        tuple_set = Gecode::Raw::TupleSet.new
+        @params[:tuples].each do |tuple|
+          tuple_set.add tuple
+        end
+        tuple_set.finalize
+
+        # Post the constraint.
+        Gecode::Raw::extensional(@model.active_space, lhs, tuple_set, 
+          *propagation_options)
+      end
+    end
+
+    class RegexpConstraint < Gecode::Constraint #:nodoc:
       def post
         lhs, regexp = @params.values_at(:lhs, :regexp)
-        Gecode::Raw::extensional(@model.active_space, lhs.to_int_var_array, 
-          regexp, *propagation_options)
+        Gecode::Raw::extensional(@model.active_space, 
+          lhs.to_int_enum.bind_array, regexp, *propagation_options)
       end
     end
   end

data/lib/gecoder/interface/constraints/int_enum/sort.rb

@@ -1,36 +1,60 @@
-module Gecode::Constraints::IntEnum
-  class Expression
-    # Initiates a sort constraint. Beyond the common options the sort constraint
-    # can also take the following options:
+module Gecode::IntEnum
+  class IntEnumConstraintReceiver
+    # Constrains the elements in this enumeration to be sorted in ascending 
+    # order. The following options can be given in addition to the
+    # common constraint options:
     # 
-    # [:as]     Defines a target (must be an int variable enumerable) that will
+    # [:as]     Defines a target (must be an IntEnum) that will
     #           hold the sorted version of the original enumerable. The original
     #           enumerable will not be affected (i.e. will not necessarily be 
     #           sorted)
-    # [:order]  Sets an int variable enumerable that should be used to store the
-    #           order of the original enum's variables when sorted. The original
+    # [:order]  Sets an IntEnum that should be used to store the
+    #           order of the original enum's operands when sorted. The original
     #           enumerable will not be affected (i.e. will not necessarily be 
     #           sorted)
     # 
     # If neither of those options are specified then the original enumerable
     # will be constrained to be sorted (otherwise not). Sort constraints with
     # options do not allow negation.
+    #
+    # ==== Examples 
+    #
+    #   # Constrain +numbers+ to be sorted.
+    #   numbers.must_be.sorted
+    #
+    #   # Constrain +numbers+ to not be sorted.
+    #   numbers.must_not_be.sorted
+    # 
+    #   # Constrain +sorted_numbers+ to be a sorted version of +numbers+. 
+    #   numbers.must_be.sorted(:as => sorted_numbers)
+    #
+    #   # Constrain +order+ to be the order in which +numbers+ has to be
+    #   # ordered to be sorted.
+    #   numbers.must_be.sorted(:order => order)
+    #   
+    #   # Constrain +sorted_numbers+ to be +numbers+ sorted in the order 
+    #   # described by the IntEnum +order+. 
+    #   numbers.must_be.sorted(:as => sorted_numbers, :order => order)
+    #
+    #   # Constrains +numbers+ to be sorted, reifying with the boolean 
+    #   # operand +is_sorted+, while selecting +domain+ as strength.
+    #   numbers.must_be.sorted(:reify => :is_sorted, :strength => :domain)
     def sorted(options = {})
       # Extract and check options.
       target = options.delete(:as)
       order = options.delete(:order)
-      unless target.nil? or target.respond_to? :to_int_var_array
+      unless target.nil? or target.respond_to? :to_int_enum
         raise TypeError, 'Expected int var enum as :as, got ' + 
           "#{target.class}."
       end
-      unless order.nil? or order.respond_to? :to_int_var_array
+      unless order.nil? or order.respond_to? :to_int_enum
         raise TypeError, 'Expected int var enum as :order, got ' + 
           "#{order.class}."
       end
       
       # Extract standard options and convert to constraint.
       reified = !options[:reify].nil?
-      @params.update(Gecode::Constraints::Util.decode_options(options))
+      @params.update(Gecode::Util.decode_options(options))
       if target.nil? and order.nil?
         @model.add_constraint Sort::SortConstraint.new(@model, @params)
       else
@@ -53,33 +77,18 @@ module Gecode::Constraints::IntEnum
 
   # A module that gathers the classes and modules used in sort constraints.
   module Sort #:nodoc:
-    # Describes a sort constraint which constrains a target enumeration of 
-    # integer variables to be the sorted version of another set of integer 
-    # variables. Optionally a third enumeration may be used to define the order
-    # in which the the variables should be sorted.
-    # 
-    # Neither negation nor reification is supported.
-    # 
-    # == Example
-    # 
-    #   # Constrains +sorted_numbers+ to be a sorted version of +numbers+. 
-    #   numbers.must_be.sorted(:as => sorted_numbers)
-    #   
-    #   # Constrains +sorted_numbers+ to be +numbers+ sorted in the order 
-    #   # described by the integer variable enumeration +order+. 
-    #   numbers.must_be.sorted(:as => sorted_numbers, :order => order)
-    class SortConstraintWithOptions < Gecode::Constraints::Constraint
+    class SortConstraintWithOptions < Gecode::Constraint #:nodoc:
       def post
         if @params[:target].nil?
           # We must have a target.
-          lhs = @params[:lhs]
+          lhs = @params[:lhs].to_int_enum
           @params[:target] = @model.int_var_array(lhs.size, lhs.domain_range)
         end
         
         # Prepare the parameters.
         params = @params.values_at(:lhs, :target, :order).map do |param| 
-          if param.respond_to? :to_int_var_array
-            param.to_int_var_array
+          if param.respond_to? :to_int_enum
+            param.to_int_enum.bind_array
           else
             param
           end
@@ -91,19 +100,7 @@ module Gecode::Constraints::IntEnum
       end
     end
     
-    # Describes a sort constraint which constrains an enumeration of integer 
-    # variables to be sorted. Supports reification and negation.
-    # 
-    # == Example
-    # 
-    #   # Constrains the variables in +int_enum+ to be sorted ascendingly.
-    #   int_enum.must_be.sorted
-    #   
-    #   # Reifies the constraint that the variables in +int_enum+ to be sorted 
-    #   # ascendingly with the boolean variable +is_sorted+, while selecting 
-    #   # +domain+ as strength.
-    #   int_enum.must_be.sorted(:reify => :is_sorted, :strength => :domain)
-    class SortConstraint < Gecode::Constraints::ReifiableConstraint
+    class SortConstraint < Gecode::ReifiableConstraint #:nodoc:
       def post
         lhs, strength, kind, reif_var = 
           @params.values_at(:lhs, :strength, :kind, :reif)
@@ -112,9 +109,9 @@ module Gecode::Constraints::IntEnum
         # We translate the constraint into n-1 relation constraints.
         options = {
           :strength => 
-            Gecode::Constraints::Util::PROPAGATION_STRENGTHS.invert[strength],
+            Gecode::Util::PROPAGATION_STRENGTHS.invert[strength],
           :kind => 
-            Gecode::Constraints::Util::PROPAGATION_KINDS.invert[kind]
+            Gecode::Util::PROPAGATION_KINDS.invert[kind]
         }
         if using_reification
           reification_variables = @model.bool_var_array(lhs.size - 1)
@@ -135,4 +132,4 @@ module Gecode::Constraints::IntEnum
       negate_using_reification
     end
   end
-end
+end

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

@@ -1,28 +1,85 @@
-module Gecode
-  module IntEnumMethods
-    include Gecode::Constraints::LeftHandSideMethods
-    
+# A module containing constraints that have enumerations of integer 
+# operands as left hand side.
+module Gecode::IntEnum #:nodoc:
+  # A IntEnumOperand is a enumeration of IntOperand on which the
+  # constraints defined in IntEnumConstraintReceiver can be placed.
+  #
+  # Enumerations of integer operands can be created either by using
+  # Gecode::Model#int_var_array and Gecode::Model#int_var_matrix, or
+  # by wrapping an existing enumeration containing IntOperand using
+  # Gecode::Model#wrap_enum. The enumerations, no matter how they were
+  # created, all respond to the properties defined by IntEnumOperand.
+  #
+  # ==== Examples 
+  #
+  # Produces an array of five int operands with domain 0..9 inside a 
+  # problem formulation using Gecode::Model#int_var_array:
+  #
+  #   int_enum = int_var_array(5, 0..9)
+  #
+  # Uses Gecode::Model#wrap_enum inside a problem formulation to create
+  # a IntEnumOperand from an existing enumeration containing the
+  # integer operands +int_operand1+ and +int_operand2+:
+  #
+  #   int_enum = wrap_enum([int_operand1, int_operand2])
+  #   
+  #--
+  # Classes that mix in IntEnumOperand must define #model and
+  # #to_int_enum .
+  module IntEnumOperand
+    include Gecode::Operand 
+
+    def method_missing(method, *args) #:nodoc:
+      if Gecode::IntEnum::Dummy.instance_methods.include? method.to_s
+        # Delegate to the int enum.
+        to_int_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::IntEnum::Expression.new(@model, params)
+
+    def construct_receiver(params)
+      IntEnumConstraintReceiver.new(@model, params)
     end
   end
-  
-  # A module containing constraints that have enumerations of integer 
-  # variables as left hand side.
-  module Constraints::IntEnum
-    # Expressions with int enums as left hand sides.
-    class Expression < Gecode::Constraints::Expression #:nodoc:
-      # Raises TypeError unless the left hand side is an int enum.
-      def initialize(model, params)
-        super
-        
-        unless params[:lhs].respond_to? :to_int_var_array
-          raise TypeError, 'Must have int enum as left hand side.'
-        end
+
+  # IntEnumConstraintReceiver contains all constraints that can be
+  # placed on a IntEnumOperand.
+  #
+  # Constraints are placed by calling IntEnumOperand#must (or any other
+  # of the variations defined in Operand), which produces a 
+  # IntEnumConstraintReceiver from which the desired constraint can be used.
+  #
+  # Some constraint accepts a number of options. See ConstraintReceiver
+  # for more information.
+  #
+  # ==== Examples 
+  #
+  # Constrains the integer operands in +int_enum+ to take on different
+  # values by using IntEnumConstraintReceiver#distinct:
+  #
+  #   int_enum.must_be.distinct
+  #
+  # Constrains +int_enum2+ to have the same elements as +int_enum+, but
+  # sorted in ascending order. Uses IntEnumConstraintReceiver#sorted:
+  #
+  #   int_enum.must_be.sorted(:as => int_enum2)
+  #
+  # The same as above, but specifying that strength :domain should be 
+  # used and that the constraint should be reified with +bool_operand+:
+  #
+  #   int_enum.must_be.sorted(:as => int_enum2, :strength => :domain, :reify => bool_operand)
+  #
+  class IntEnumConstraintReceiver < Gecode::ConstraintReceiver
+    # Raises TypeError unless the left hand side is an int enum
+    # operand.
+    def initialize(model, params) #:nodoc:
+      super
+
+      unless params[:lhs].respond_to? :to_int_enum
+        raise TypeError, 'Must have int enum operand as left hand side.'
       end
     end
   end