gecoder 0.8.2 → 0.8.3

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

@@ -0,0 +1,101 @@
+module Gecode
+  class Model
+    # Specifies an integer regexp that matches +regexp+ repeated between
+    # +at_least+ and +at_most+ times (inclusive). If +at_most+ is
+    # 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
+    # allowed syntax of +regexp+.
+    def repeat(regexp, at_least = nil, at_most = nil)
+      unless at_least.nil? or at_least.kind_of? Fixnum
+        raise TypeError, 
+          "Expected the at_least argument to be a Fixnum, got #{at_least.class}"
+      end
+      unless at_most.nil? or at_most.kind_of?(Fixnum)
+        raise TypeError, 
+          "Expected the at_most argument to be a Fixnum, got #{at_most.class}"
+      end
+
+      reg = Constraints::Util::Extensional.parse_regexp regexp
+      if at_most.nil?
+        if at_least.nil?
+          reg.send '*'
+        else
+          reg.send('()', at_least)
+        end
+      else
+        reg.send('()', at_least, at_most)
+      end
+    end
+
+    # Matches +regexp+ repeated zero or one time (i.e. like '?' in normal 
+    # regexps). Produces the same result as calling 
+    #   
+    #   repeat(regexp, 0, 1)
+    def at_most_once(regexp)
+      repeat(regexp, 0, 1)
+    end
+    
+    # Matches +regexp+ repeated at least one time (i.e. like '+' in normal 
+    # regexps). Produces the same result as calling 
+    #   
+    #   repeat(regexp, 1)
+    def at_least_once(regexp)
+      repeat(regexp, 1)
+    end
+
+    # 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)
+      end
+    end
+  end
+
+  module Constraints::Util::Extensional
+    module_function
+
+    # Parses a regular expression over the integer domain, returning
+    # an instance of Gecode::REG .
+    #
+    # Pseudo-BNF of the integer regexp representation:
+    # regexp ::= <Fixnum> | <TrueClass> | <FalseClass> | <Gecode::Raw::REG> 
+    #          | [<regexp>, ...]
+    def parse_regexp(regexp)
+      # Check the involved types.
+      unless regexp.kind_of? Enumerable
+        regexp = [regexp]
+      end
+      regexp.to_a.flatten.each do |element|
+        unless element.kind_of?(Fixnum) or element.kind_of?(Gecode::Raw::REG) or
+            element.kind_of?(TrueClass) or element.kind_of?(FalseClass)
+          raise TypeError, 
+            "Can't translate #{element.class} into integer or boolean regexp."
+        end
+      end
+
+      # Convert it into a regexp.
+      internal_parse_regexp(regexp)
+    end
+
+    private
+
+    # Recursively converts arg into an instance of Gecode::REG. It is
+    # assumed that arg is of kind Gecode::Raw::REG, Fixnum, TrueClass,
+    # FalseClass or Enumerable.
+    def self.internal_parse_regexp(arg)
+      case arg 
+        when Gecode::Raw::REG: arg
+        when Fixnum: Gecode::Raw::REG.new(arg)
+        when TrueClass: Gecode::Raw::REG.new(1)
+        when FalseClass: Gecode::Raw::REG.new(0)
+        when Enumerable
+          # Recursively convert the elements of the arg.
+          arg.inject(Gecode::Raw::REG.new) do |regexp, element|
+            regexp += internal_parse_regexp(element)
+          end
+      end
+    end
+  end
+end

data/lib/gecoder/interface/constraints/int/channel.rb

@@ -35,19 +35,7 @@ module Gecode::Constraints::Int
     #            set to k then the integer variable takes value i+k exactly 
     #            when the variable at index i in the boolean enumration is true 
     #            and the rest are false.
-    def channel(bool_enum, options = {})
-      unless bool_enum.respond_to? :to_bool_var_array
-        raise TypeError, 'Expected an enumration of boolean variables, got ' + 
-          "#{bool_enum.class}."
-      end
-      
-      # Just provide commutivity with the boolean enum channel constraint.
-      if @params[:negate]
-        bool_enum.must_not.channel(@params[:lhs], options)
-      else
-        bool_enum.must.channel(@params[:lhs], options)
-      end
-    end
+    provide_commutivity(:channel){ |rhs, _| rhs.respond_to? :to_bool_var_array }
   end
   
   # A module that gathers the classes and modules used in channel constraints

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

@@ -7,23 +7,20 @@ module Gecode::Constraints::IntEnum
         raise Gecode::MissingConstraintError, 'A negated channel constraint ' + 
           'is not implemented.'
       end
-      unless enum.respond_to?(:to_int_var_array) or 
-          enum.respond_to?(:to_set_var_array)
-        raise TypeError, "Expected int or set enum, got #{enum.class}."
+      unless enum.respond_to?(:to_int_var_array)
+        raise TypeError, "Expected int enum, got #{enum.class}."
       end
-      if enum.respond_to? :to_set_var_array
-        if options.has_key? :reify
-          raise ArgumentError, 'The channel constraints does not support the ' +
-            'reification option.'
-        end
-        @params.update(Gecode::Constraints::Set::Util.decode_options(options))
-      else
-        @params.update(Gecode::Constraints::Util.decode_options(options))
+      if options.has_key? :reify
+        raise ArgumentError, 'The channel constraints does not support the ' +
+          'reification option.'
       end
       
+      @params.update(Gecode::Constraints::Util.decode_options(options))
       @params.update(:rhs => enum)
       @model.add_constraint Channel::ChannelConstraint.new(@model, @params)
     end
+    
+    provide_commutivity(:channel){ |rhs, _| rhs.respond_to? :to_set_var_array }
   end
   
   # A module that gathers the classes and modules used in channel constraints.
@@ -33,14 +30,12 @@ module Gecode::Constraints::IntEnum
     # enumeration of set variables. Channel constraints are used to give 
     # access to multiple viewpoints when modelling. 
     # 
-    # When used on two integer enumeration, the channel constraint can be 
-    # thought of as constraining the arrays to be each other's inverses. When 
-    # used with an enumeration of sets the i:th set includes the value of the
-    # j:th integer.  
+    # The channel constraint can be thought of as constraining the arrays to 
+    # be each other's inverses. I.e. if the i:th value in the first enumeration
+    # is j, then the j:th value in the second enumeration is constrained to be 
+    # i.
     # 
-    # Neither reification nor negation is supported. Selecting strength is only 
-    # supported when using the constraint between two integer enumerations, 
-    # it's not supported when a set enumeration is used.  
+    # Neither reification nor negation is supported.
     # 
     # == Example
     # 
@@ -82,26 +77,11 @@ module Gecode::Constraints::IntEnum
     # 
     #   elements.must.channel positions
     # 
-    # == Example (sets)
-    # 
-    #   # +set_enum+ is constrained to channel +int_enum+.
-    #   int_enum.must.channel set_enum
-    # 
-    #   # This is another way of saying the above.
-    #   set_enum.must.channel int_enum
     class ChannelConstraint < Gecode::Constraints::Constraint
       def post
         lhs, rhs = @params.values_at(:lhs, :rhs)
-      
-        lhs = lhs.to_int_var_array
-        if rhs.respond_to? :to_int_var_array
-          # Int var array.
-          Gecode::Raw::channel(@model.active_space, lhs, rhs.to_int_var_array,
-            *propagation_options)
-        else
-          # Set var array, no propagation options.
-          Gecode::Raw::channel(@model.active_space, lhs, rhs.to_set_var_array)
-        end
+        Gecode::Raw::channel(@model.active_space, lhs.to_int_var_array, 
+          rhs.to_int_var_array, *propagation_options)
       end
     end
   end

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

@@ -26,6 +26,27 @@ module Gecode::Constraints::IntEnum
       @model.add_constraint Extensional::TupleConstraint.new(@model, 
         @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 
@@ -60,5 +81,114 @@ module Gecode::Constraints::IntEnum
           *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.
+    #
+    # == Regexp syntax
+    #
+    # The regular expressions are specified using arrays, integers and a
+    # few methods provided by Model. Arrays are used to group the
+    # integers in sequences that must be matched. The following array
+    # describes a regular expression matching a 1 followed by a 7.
+    #
+    #   [1, 7]
+    #
+    # Arrays can be nested or left out when not needed. I.e. the above
+    # is semantically equal to
+    #
+    #   [[[1], 7]]
+    #
+    # A couple of methods provided by Model are used to express patterns 
+    # beyond mere sequences:
+    #
+    # [Model#repeat] Used for specifying patterns that include patterns
+    #                that may be repeated a given number of times. The 
+    #                number of times to repeat a pattern can be specified 
+    #                using a lower and upper bound, but the bounds can be 
+    #                omitted to for instance allow an expression to be 
+    #                repeated any number of times.
+    # [Model#any]    Used for specifying alternatives.
+    # 
+    # Additionally Model#at_least_once and Model#at_most_once are
+    # provided as convenience methods.
+    #
+    # === Examples
+    #
+    #   # Matches 1 followed by any number of 2s.
+    #   [1, repeat(2)]
+    #
+    #   # Semantically the same as above. It just has a bunch of
+    #   # needless brackets thrown in.
+    #   [[1], [repeat([2])]]
+    #
+    #   # Matches 1 followed by [a 2 followed by a 3] at least two times.
+    #   # Matches e.g. 1, 2, 3, 2, 3
+    #   [1, repeat([2, 3], 2)]
+    #
+    #   # Matches between one and two [2 followed by [at least three 1]] 
+    #   # followed by between three and four 3. Matches e.g. 
+    #   # 2, 1, 1, 1, 2, 1, 1, 1, 3, 3, 3
+    #   [repeat([2, repeat(1, 3], 1, 2), repeat(3, 3, 4)]
+    #
+    #   # Matches [1, 2 or 3] followed by 4. Matches e.g. 2, 4
+    #   [any(1, 2, 3), 4]
+    #
+    #   # Matches 0 followed by [[1 followed by 2] or [3 followed by 5]]. 
+    #   # Matches e.g. 0, 1, 2 as well as 0, 3, 5
+    #   [0, any([1, 2], [3, 5])]
+    #
+    #   # Matches 0 followed by [[[1 followed by 7] at least two times] 
+    #   # or [[8, 9], at most two times]. Matches e.g. 
+    #   # 0, 1, 7, 1, 7, 1, 7 as well as 0, 8, 9
+    #   [0, any(repeat([1, 7], 2), repeat([8, 9], 0, 2)]
+    #
+    #   # Matches 0 followed by at least one 1.
+    #   [0, at_least_once(1)]
+    #
+    #   # Exactly the same as the above.
+    #   [0, repeat(1, 1)]
+    #
+    #   # Matches 0 followed by at least one [[1 followed by 7] or [3
+    #   # followed by 2]]. Matches e.g. 0, 1, 7, 3, 2, 1, 7
+    #   [0, at_least_once(any([1, 7], [3, 2]]
+    #
+    #   # Matches 0 followed by at either [[1 followed by 7] at least once] 
+    #   # or [[3 followed by 2] at least once]. Matches e.g. 
+    #   # 0, 1, 7, 1, 7 but does _not_ match 0, 1, 7, 3, 2, 1, 7
+    #   [0, any(at_least_once([1, 7]), at_least_once([3, 2])]
+    #
+    #   # Matches 0, followed by at most one 1. Matches 0 as well as 
+    #   # 0, 1
+    #   [0, at_most_once(1)]
+    #
+    #   # Exactly the same as the above.
+    #   [0, repeat(1, 0, 1)]
+    #
+    # == Example
+    #
+    #   # Constrains the two integer variables in +numbers+ to have
+    #   # values 1 and 7.
+    #   numbers.must.match [1, 7]
+    #
+    #   # Constrains the integer variables 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 
+    #   # contain 47 or 11, each followed by at least two
+    #   # variables set to -1. All other variables 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 post
+        lhs, regexp = @params.values_at(:lhs, :regexp)
+        Gecode::Raw::extensional(@model.active_space, lhs.to_int_var_array, 
+          regexp, *propagation_options)
+      end
+    end
   end
 end

data/lib/gecoder/interface/constraints/set/channel.rb

@@ -0,0 +1,54 @@
+module Gecode::Constraints::Set
+  class Expression
+    # Adds a channel constraint on the set variable with the specified enum of 
+    # boolean variables.
+    def channel(bool_enum, options = {})
+      if @params[:negate]
+        raise Gecode::MissingConstraintError, 'A negated channel constraint ' + 
+          'is not implemented.'
+      end
+      if options.has_key? :reify
+        raise ArgumentError, 'The channel constraint does not support the ' + 
+          'reification option.'
+      end
+      unless bool_enum.respond_to? :to_bool_var_array
+        raise TypeError, 'Expected an enum of bool variables, ' + 
+          "got #{bool_enum.class}."
+      end
+      
+      @params.update(:rhs => bool_enum)
+      @params.update Gecode::Constraints::Set::Util.decode_options(options)
+      @model.add_constraint Channel::ChannelConstraint.new(@model, @params)
+    end
+  end
+  
+  # A module that gathers the classes and modules used in channel constraints
+  # involving one set variable and a boolean enum.
+  module Channel #:nodoc:
+    # Describes a channel constraint that "channels" a set variable and an
+    # enumerations of boolean variables. This constrains the set variable to
+    # include value i exactly when the variable at index i in the boolean
+    # enumeration is true.
+    # 
+    # Neither reification nor negation is supported. The boolean enum and set
+    # can be interchanged.
+    #
+    # == Examples
+    #
+    # # Constrains the enumeration of boolean variables called +bools+ to at
+    # # least have the first and third variables set to true 
+    # set.must_be.superset_of [0, 2]
+    # set.must.channel bools
+    #
+    # # An alternative way of writing the above.
+    # set.must_be.superset_of [0, 2]
+    # bools.must.channel set
+    class ChannelConstraint < Gecode::Constraints::Constraint
+      def post
+        lhs, rhs = @params.values_at(:lhs, :rhs)
+        Gecode::Raw::channel(@model.active_space, rhs.to_bool_var_array, 
+          lhs.bind)
+      end
+    end
+  end
+end

data/lib/gecoder/interface/constraints/set_enum/channel.rb

@@ -2,16 +2,47 @@ module Gecode::Constraints::SetEnum
   class Expression
     # Posts a channel constraint on the variables in the enum with the specified
     # int enum.
-    def channel(enum)
+    def channel(enum, options = {})
       unless enum.respond_to? :to_int_var_array
         raise TypeError, "Expected integer variable enum, for #{enum.class}."
       end
-      
-      # Just provide commutativity to the corresponding int enum constraint.
       if @params[:negate]
-        enum.must_not.channel(@params[:lhs])
-      else
-        enum.must.channel(@params[:lhs])
+        raise Gecode::MissingConstraintError, 'A negated channel constraint ' + 
+          'is not implemented.'
+      end
+      if options.has_key? :reify
+        raise ArgumentError, 'The channel constraints does not support the ' +
+          'reification option.'
+      end
+      
+      @params.update(Gecode::Constraints::Set::Util.decode_options(options))
+      @params.update(:rhs => enum)
+      @model.add_constraint Channel::IntChannelConstraint.new(@model, @params)
+    end
+  end
+  
+  # A module that gathers the classes and modules used in channel constraints.
+  module Channel #:nodoc:
+    # Describes a channel constraint which "channels" one enumeration of 
+    # integer variables with one enumeration of set variables. The i:th set 
+    # in the enumeration of set variables is constrainde to includes the value 
+    # of the j:th integer variable. 
+    # 
+    # Neither reification nor negation is supported.
+    # 
+    # == Examples
+    # 
+    #   # +set_enum+ is constrained to channel +int_enum+.
+    #   int_enum.must.channel set_enum
+    # 
+    #   # This is another way of saying the above.
+    #   set_enum.must.channel int_enum
+    #
+    class IntChannelConstraint < Gecode::Constraints::Constraint
+      def post
+        lhs, rhs = @params.values_at(:lhs, :rhs)
+        Gecode::Raw::channel(@model.active_space, rhs.to_int_var_array, 
+          lhs.to_set_var_array)
       end
     end
   end

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

@@ -75,3 +75,4 @@ require 'gecoder/interface/constraints/set/relation'
 require 'gecoder/interface/constraints/set/cardinality'
 require 'gecoder/interface/constraints/set/connection'
 require 'gecoder/interface/constraints/set/operation'
+require 'gecoder/interface/constraints/set/channel'

data/lib/gecoder/interface/constraints.rb

@@ -271,6 +271,43 @@ module Gecode
       
       private
       
+      # Provides commutivity for the constraint with the specified method name.
+      # If the method with the specified method name is called with something 
+      # that, when given to the block, evaluates to true, then the constraint
+      # will be called on the right hand side with the left hand side as 
+      # argument.
+      #
+      # The original constraint method is assumed to take two arguments: a 
+      # right hand side and a hash of options.
+      def self.provide_commutivity(constraint_name, &block)
+        unique_id = constraint_name.to_sym.to_i
+        pre_alias_method_name = 'pre_commutivity_' << unique_id.to_s
+        if method_defined? constraint_name
+          alias_method pre_alias_method_name, constraint_name
+        end
+        
+        module_eval <<-end_code
+          @@commutivity_check_#{unique_id} = block
+          def #{constraint_name}(rhs, options = {})
+            if @@commutivity_check_#{unique_id}.call(rhs, options)
+              if @params[:negate]
+                rhs.must_not.method(:#{constraint_name}).call(
+                  @params[:lhs], options)
+              else
+                rhs.must.method(:#{constraint_name}).call(
+                  @params[:lhs], options)
+              end
+            else
+              if self.class.method_defined? :#{pre_alias_method_name}
+                #{pre_alias_method_name}(rhs, options)
+              else
+                raise TypeError, \"Unexpected argument type \#{rhs.class}.\" 
+              end
+            end
+          end
+        end_code
+      end
+      
       # Creates aliases for any defined comparison methods.
       def self.alias_comparison_methods
         Gecode::Constraints::Util::COMPARISON_ALIASES.each_pair do |orig, aliases|
@@ -472,3 +509,4 @@ require 'gecoder/interface/constraints/bool_var_constraints'
 require 'gecoder/interface/constraints/bool_enum_constraints'
 require 'gecoder/interface/constraints/set_var_constraints'
 require 'gecoder/interface/constraints/set_enum_constraints'
+require 'gecoder/interface/constraints/extensional_regexp'