net-ldap 0.1.1 → 0.2

data/lib/net/ldap/entry.rb

@@ -1,266 +1,185 @@
-# LDAP Entry (search-result) support classes
+# -*- ruby encoding: utf-8 -*-
+##
+# Objects of this class represent individual entries in an LDAP directory.
+# User code generally does not instantiate this class. Net::LDAP#search
+# provides objects of this class to user code, either as block parameters or
+# as return values.
 #
-#----------------------------------------------------------------------------
+# In LDAP-land, an "entry" is a collection of attributes that are uniquely
+# and globally identified by a DN ("Distinguished Name"). Attributes are
+# identified by short, descriptive words or phrases. Although a directory is
+# free to implement any attribute name, most of them follow rigorous
+# standards so that the range of commonly-encountered attribute names is not
+# large.
 #
-# Copyright (C) 2006 by Francis Cianfrocca. All Rights Reserved.
+# An attribute name is case-insensitive. Most directories also restrict the
+# range of characters allowed in attribute names. To simplify handling
+# attribute names, Net::LDAP::Entry internally converts them to a standard
+# format. Therefore, the methods which take attribute names can take Strings
+# or Symbols, and work correctly regardless of case or capitalization.
 #
-# Gmail: garbagecat10
+# An attribute consists of zero or more data items called <i>values.</i> An
+# entry is the combination of a unique DN, a set of attribute names, and a
+# (possibly-empty) array of values for each attribute.
 #
-# This program is free software; you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation; either version 2 of the License, or
-# (at your option) any later version.
+# Class Net::LDAP::Entry provides convenience methods for dealing with LDAP
+# entries. In addition to the methods documented below, you may access
+# individual attributes of an entry simply by giving the attribute name as
+# the name of a method call. For example:
 #
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
+#   ldap.search( ... ) do |entry|
+#     puts "Common name: #{entry.cn}"
+#     puts "Email addresses:"
+#     entry.mail.each {|ma| puts ma}
+#   end
 #
-# You should have received a copy of the GNU General Public License
-# along with this program; if not, write to the Free Software
-# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+# If you use this technique to access an attribute that is not present in a
+# particular Entry object, a NoMethodError exception will be raised.
 #
-#---------------------------------------------------------------------------
-#
-
-module Net
-class LDAP
-
-
-  # Objects of this class represent individual entries in an LDAP directory.
-  # User code generally does not instantiate this class. Net::LDAP#search
-  # provides objects of this class to user code, either as block parameters or
-  # as return values.
-  #
-  # In LDAP-land, an "entry" is a collection of attributes that are uniquely
-  # and globally identified by a DN ("Distinguished Name"). Attributes are
-  # identified by short, descriptive words or phrases. Although a directory is
-  # free to implement any attribute name, most of them follow rigorous
-  # standards so that the range of commonly-encountered attribute names is not
-  # large.
-  #
-  # An attribute name is case-insensitive. Most directories also restrict the
-  # range of characters allowed in attribute names. To simplify handling
-  # attribute names, Net::LDAP::Entry internally converts them to a standard
-  # format. Therefore, the methods which take attribute names can take Strings
-  # or Symbols, and work correctly regardless of case or capitalization.
+#--
+# Ugly problem to fix someday: We key off the internal hash with a canonical
+# form of the attribute name: convert to a string, downcase, then take the
+# symbol. Unfortunately we do this in at least three places. Should do it in
+# ONE place.
+class Net::LDAP::Entry
+  ##
+  # This constructor is not generally called by user code.
+  def initialize(dn = nil) #:nodoc:
+    @myhash = {}
+    @myhash[:dn] = [dn]
+  end
+
+  ##
+  # Use the LDIF format for Marshal serialization.
+  def _dump(depth) #:nodoc:
+    to_ldif
+  end
+
+  ##
+  # Use the LDIF format for Marshal serialization.
+  def self._load(entry) #:nodoc:
+    from_single_ldif_string(entry)
+  end
+
+  class << self
+    ##
+    # Converts a single LDIF entry string into an Entry object. Useful for
+    # Marshal serialization. If a string with multiple LDIF entries is
+    # provided, an exception will be raised.
+    def from_single_ldif_string(ldif)
+      ds = Net::LDAP::Dataset.read_ldif(::StringIO.new(ldif))
+
+      return nil if ds.empty?
+
+      raise Net::LDAP::LdapError, "Too many LDIF entries" unless ds.size == 1
+
+      entry = ds.to_entries.first
+
+      return nil if entry.dn.nil?
+      entry
+    end
+
+    ##
+    # Canonicalizes an LDAP attribute name as a \Symbol. The name is
+    # lowercased and, if present, a trailing equals sign is removed.
+    def attribute_name(name)
+      name = name.to_s.downcase
+      name = name[0..-2] if name[-1] == ?=
+      name.to_sym
+    end
+  end
+
+  ##
+  # Sets or replaces the array of values for the provided attribute. The
+  # attribute name is canonicalized prior to assignment.
   #
-  # An attribute consists of zero or more data items called <i>values.</i> An
-  # entry is the combination of a unique DN, a set of attribute names, and a
-  # (possibly-empty) array of values for each attribute.
+  # When an attribute is set using this, that attribute is now made
+  # accessible through methods as well.
   #
-  # Class Net::LDAP::Entry provides convenience methods for dealing with LDAP
-  # entries. In addition to the methods documented below, you may access
-  # individual attributes of an entry simply by giving the attribute name as
-  # the name of a method call. For example:
+  #   entry = Net::LDAP::Entry.new("dc=com")
+  #   entry.foo             # => NoMethodError
+  #   entry["foo"] = 12345  # => [12345]
+  #   entry.foo             # => [12345]
+  def []=(name, value)
+    @myhash[self.class.attribute_name(name)] = Kernel::Array(value)
+  end
+
+  ##
+  # Reads the array of values for the provided attribute. The attribute name
+  # is canonicalized prior to reading. Returns an empty array if the
+  # attribute does not exist.
+  def [](name)
+    name = self.class.attribute_name(name)
+    @myhash[name] || []
+  end
+
+  ##
+  # Returns the first distinguished name (dn) of the Entry as a \String.
+  def dn
+    self[:dn].first.to_s
+  end
+
+  ##
+  # Returns an array of the attribute names present in the Entry.
+  def attribute_names
+    @myhash.keys
+  end
+
+  ##
+  # Accesses each of the attributes present in the Entry.
   #
-  #   ldap.search( ... ) do |entry|
-  #     puts "Common name: #{entry.cn}"
-  #     puts "Email addresses:"
-  #     entry.mail.each {|ma| puts ma}
-  #   end
-  #
-  # If you use this technique to access an attribute that is not present in a
-  # particular Entry object, a NoMethodError exception will be raised.
-  #
-  #--
-  # Ugly problem to fix someday: We key off the internal hash with a canonical
-  # form of the attribute name: convert to a string, downcase, then take the
-  # symbol. Unfortunately we do this in at least three places. Should do it in
-  # ONE place.
-  #
-  class Entry
-    # This constructor is not generally called by user code.
-    #
-    def initialize dn = nil # :nodoc:
-      @myhash = {}
-      @myhash[:dn] = [dn]
-    end
-
-    def _dump depth
-      to_ldif
-    end
-
-    class << self
-      def _load entry
-        from_single_ldif_string entry
-      end
-    end
-
-    #--
-    # Discovered bug, 26Aug06: I noticed that we're not converting the
-    # incoming value to an array if it isn't already one.
-    def []=(name, value) # :nodoc:
-      sym = attribute_name(name)
-      value = [value] unless value.is_a?(Array)
-      @myhash[sym] = value
-    end
-
-    #--
-    # We have to deal with this one as we do with []= because this one and not
-    # the other one gets called in formulations like entry["CN"] << cn.
-    #
-    def [](name) # :nodoc:
-      name = attribute_name(name) unless name.is_a?(Symbol)
-      @myhash[name] || []
-    end
-
-    # Returns the dn of the Entry as a String.
-    def dn
-      self[:dn][0].to_s
-    end
-
-    # Returns an array of the attribute names present in the Entry.
-    def attribute_names
-      @myhash.keys
-    end
-
-    # Accesses each of the attributes present in the Entry.
-    # Calls a user-supplied block with each attribute in turn,
-    # passing two arguments to the block: a Symbol giving
-    # the name of the attribute, and a (possibly empty)
-    # Array of data values.
-    #
-    def each
-      if block_given?
-        attribute_names.each {|a|
-          attr_name,values = a,self[a]
-          yield attr_name, values
-        }
-      end
-    end
-
-    alias_method :each_attribute, :each
-
-    # Converts the Entry to a String, representing the
-    # Entry's attributes in LDIF format.
-    #--
-    def to_ldif
-      ary = []
-      ary << "dn: #{dn}\n"
-      v2 = "" # temp value, save on GC
-      each_attribute do |k,v|
-        unless k == :dn
-          v.each {|v1|
-            v2 = if (k == :userpassword) || is_attribute_value_binary?(v1)
-              ": #{Base64.encode64(v1).chomp.gsub(/\n/m,"\n ")}"
-            else
-              " #{v1}"
-            end
-            ary << "#{k}:#{v2}\n"
-          }
-        end
-      end
-      ary << "\n"
-      ary.join
-    end
-
-    #--
-    # TODO, doesn't support broken lines.
-    # It generates a SINGLE Entry object from an incoming LDIF stream which is
-    # of course useless for big LDIF streams that encode many objects.
-    #
-    # DO NOT DOCUMENT THIS METHOD UNTIL THESE RESTRICTIONS ARE LIFTED.
-    #
-    # As it is, it's useful for unmarshalling objects that we create, but not
-    # for reading arbitrary LDIF files. Eventually, we should have a class
-    # method that parses large LDIF streams into individual LDIF blocks
-    # (delimited by blank lines) and passes them here.
-    #
-    class << self
-      def from_single_ldif_string ldif
-        entry = Entry.new
-        entry[:dn] = []
-        ldif.split(/\r?\n/m).each {|line|
-          break if line.length == 0
-          if line =~ /\A([\w]+):(:?)[\s]*/
-            entry[$1] <<= if $2 == ':'
-              Base64.decode64($')
-            else
-              $'
-            end
-          end
-        }
-        entry.dn ? entry : nil
-      end
-    end
-    
-    #--
-    # Part of the support for getter and setter style access to attributes. 
-    #
-    def respond_to?(sym)
-      name = attribute_name(sym)
-      return true if valid_attribute?(name)
-      return super
+  # Calls a user-supplied block with each attribute in turn, passing two
+  # arguments to the block: a Symbol giving the name of the attribute, and a
+  # (possibly empty) \Array of data values.
+  def each # :yields: attribute-name, data-values-array
+    if block_given?
+      attribute_names.each {|a|
+        attr_name,values = a,self[a]
+        yield attr_name, values
+      }
     end
-
-    #--
-    # Supports getter and setter style access for all the attributes that this
-    # entry holds.
-    #
-    def method_missing sym, *args, &block # :nodoc:
-      name = attribute_name(sym)
-      
-      if valid_attribute? name 
-        if setter?(sym) && args.size == 1
-          value = args.first
-          value = [value] unless value.instance_of?(Array)
-          self[name]= value
-
-          return value
-        elsif args.empty?
-          return self[name]
-        end
+  end
+  alias_method :each_attribute, :each
+
+  ##
+  # Converts the Entry to an LDIF-formatted String
+  def to_ldif
+    Net::LDAP::Dataset.from_entry(self).to_ldif_string
+  end
+
+  def respond_to?(sym) #:nodoc:
+    return true if valid_attribute?(self.class.attribute_name(sym))
+    return super
+  end
+
+  def method_missing(sym, *args, &block) #:nodoc:
+    name = self.class.attribute_name(sym)
+
+    if valid_attribute?(name )
+      if setter?(sym) && args.size == 1
+        value = args.first
+        value = Array(value)
+        self[name]= value
+        return value
+      elsif args.empty?
+        return self[name]
       end
-      
-      super
     end
 
-    def write
-    end
-
-  private
+    super
+  end
 
-    #--
-    # Internal convenience method. It seems like the standard
-    # approach in most LDAP tools to base64 encode an attribute
-    # value if its first or last byte is nonprintable, or if
-    # it's a password. But that turns out to be not nearly good
-    # enough. There are plenty of A/D attributes that are binary
-    # in the middle. This is probably a nasty performance killer.
-    def is_attribute_value_binary? value
-      v = value.to_s
-      v.each_byte {|byt|
-        return true if (byt < 32) || (byt > 126)
-      }
-      if v[0..0] == ':' or v[0..0] == '<'
-        return true
-      end
-      false
-    end
-  
-    # Returns the symbol that can be used to access the attribute that
-    # sym_or_str designates.
-    #
-    def attribute_name(sym_or_str)
-      str = sym_or_str.to_s.downcase
-      
-      # Does str match 'something='? Still only returns :something
-      return str[0...-1].to_sym if str.size>1 && str[-1] == ?=
-      return str.to_sym
-    end
-    
-    # Given a valid attribute symbol, returns true. 
-    #
-    def valid_attribute?(attr_name)
-      attribute_names.include?(attr_name)
-    end
-    
-    def setter?(sym)
-      sym.to_s[-1] == ?=
-    end
-  end # class Entry
+  # Given a valid attribute symbol, returns true.
+  def valid_attribute?(attr_name)
+    attribute_names.include?(attr_name)
+  end
+  private :valid_attribute?
 
+  # Returns true if the symbol ends with an equal sign.
+  def setter?(sym)
+    sym.to_s[-1] == ?=
+  end
+  private :setter?
+end # class Entry
 
-end # class LDAP
-end # module Net
+require 'net/ldap/dataset' unless defined? Net::LDAP::Dataset

data/lib/net/ldap/filter.rb

@@ -1,164 +1,447 @@
-# Copyright (C) 2006 by Francis Cianfrocca. All Rights Reserved.
-#
-# Gmail: garbagecat10
-#
-# This program is free software; you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation; either version 2 of the License, or
-# (at your option) any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
+# -*- ruby encoding: utf-8 -*-
+
+##
+# Class Net::LDAP::Filter is used to constrain LDAP searches. An object of
+# this class is passed to Net::LDAP#search in the parameter :filter.
 #
-# You should have received a copy of the GNU General Public License
-# along with this program; if not, write to the Free Software
-# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+# Net::LDAP::Filter supports the complete set of search filters available in
+# LDAP, including conjunction, disjunction and negation (AND, OR, and NOT).
+# This class supplants the (infamous) RFC 2254 standard notation for
+# specifying LDAP search filters.
+#--
+# NOTE: This wording needs to change as we will be supporting LDAPv3 search
+# filter strings (RFC 4515).
+#++
 #
-#---------------------------------------------------------------------------
+# Here's how to code the familiar "objectclass is present" filter:
+#  f = Net::LDAP::Filter.present("objectclass")
 #
+# The object returned by this code can be passed directly to the
+# <tt>:filter</tt> parameter of Net::LDAP#search.
 #
+# See the individual class and instance methods below for more examples.
+class Net::LDAP::Filter
+  ##
+  # Known filter types.
+  FilterTypes = [ :ne, :eq, :ge, :le, :and, :or, :not, :ex ]
+
+  def initialize(op, left, right) #:nodoc:
+    unless FilterTypes.include?(op)
+      raise Net::LDAP::LdapError, "Invalid or unsupported operator #{op.inspect} in LDAP Filter."
+    end
+    @op = op
+    @left = left
+    @right = right
+  end
 
-require 'strscan'
+  class << self
+    # We don't want filters created except using our custom constructors.
+    private :new
+
+    ##
+    # Creates a Filter object indicating that the value of a particular
+    # attribute must either be present or match a particular string.
+    #
+    # Specifying that an attribute is 'present' means only directory entries
+    # which contain a value for the particular attribute will be selected by
+    # the filter. This is useful in case of optional attributes such as
+    # <tt>mail.</tt> Presence is indicated by giving the value "*" in the
+    # second parameter to #eq. This example selects only entries that have
+    # one or more values for <tt>sAMAccountName:</tt>
+    #
+    #   f = Net::LDAP::Filter.eq("sAMAccountName", "*")
+    #
+    # To match a particular range of values, pass a string as the second
+    # parameter to #eq. The string may contain one or more "*" characters as
+    # wildcards: these match zero or more occurrences of any character. Full
+    # regular-expressions are <i>not</i> supported due to limitations in the
+    # underlying LDAP protocol. This example selects any entry with a
+    # <tt>mail</tt> value containing the substring "anderson":
+    #
+    #   f = Net::LDAP::Filter.eq("mail", "*anderson*")
+    #
+    # This filter does not perform any escaping
+    def eq(attribute, value)
+      new(:eq, attribute, value)
+    end
 
-module Net
-class LDAP
+    ##
+    # Creates a Filter object indicating extensible comparison. This Filter
+    # object is currently considered EXPERIMENTAL.
+    #
+    #   sample_attributes = ['cn:fr', 'cn:fr.eq',
+    #     'cn:1.3.6.1.4.1.42.2.27.9.4.49.1.3', 'cn:dn:fr', 'cn:dn:fr.eq']
+    #   attr = sample_attributes.first # Pick an extensible attribute
+    #   value = 'roberts'
+    #
+    #   filter = "#{attr}:=#{value}" # Basic String Filter
+    #   filter = Net::LDAP::Filter.ex(attr, value) # Net::LDAP::Filter
+    #
+    #   # Perform a search with the Extensible Match Filter
+    #   Net::LDAP.search(:filter => filter)
+    #--
+    # The LDIF required to support the above examples on the OpenDS LDAP
+    # server:
+    #
+    #   version: 1
+    #
+    #   dn: dc=example,dc=com
+    #   objectClass: domain
+    #   objectClass: top
+    #   dc: example
+    #
+    #   dn: ou=People,dc=example,dc=com
+    #   objectClass: organizationalUnit
+    #   objectClass: top
+    #   ou: People
+    #
+    #   dn: uid=1,ou=People,dc=example,dc=com
+    #   objectClass: person
+    #   objectClass: organizationalPerson
+    #   objectClass: inetOrgPerson
+    #   objectClass: top
+    #   cn:: csO0YsOpcnRz
+    #   sn:: YsO0YiByw7Riw6lydHM=
+    #   givenName:: YsO0Yg==
+    #   uid: 1
+    #
+    # =Refs:
+    # * http://www.ietf.org/rfc/rfc2251.txt
+    # * http://www.novell.com/documentation/edir88/edir88/?page=/documentation/edir88/edir88/data/agazepd.html
+    # * https://docs.opends.org/2.0/page/SearchingUsingInternationalCollationRules
+    #++
+    def ex(attribute, value)
+      new(:ex, attribute, value)
+    end
 
+    ##
+    # Creates a Filter object indicating that a particular attribute value
+    # is either not present or does not match a particular string; see
+    # Filter::eq for more information.
+    #
+    # This filter does not perform any escaping
+    def ne(attribute, value)
+      new(:ne, attribute, value)
+    end
 
-# Class Net::LDAP::Filter is used to constrain
-# LDAP searches. An object of this class is
-# passed to Net::LDAP#search in the parameter :filter.
-#
-# Net::LDAP::Filter supports the complete set of search filters
-# available in LDAP, including conjunction, disjunction and negation
-# (AND, OR, and NOT). This class supplants the (infamous) RFC-2254
-# standard notation for specifying LDAP search filters.
-#
-# Here's how to code the familiar "objectclass is present" filter:
-#  f = Net::LDAP::Filter.pres( "objectclass" )
-# The object returned by this code can be passed directly to
-# the <tt>:filter</tt> parameter of Net::LDAP#search.
-#
-# See the individual class and instance methods below for more examples.
-#
-class Filter
+    ##
+    # Creates a Filter object indicating that the value of a particular
+    # attribute must match a particular string. The attribute value is
+    # escaped, so the "*" character is interpreted literally.
+    def equals(attribute, value)
+      new(:eq, attribute, escape(value))
+    end
 
-  def initialize op, a, b
-    @op = op
-    @left = a
-    @right = b
-  end
+    ##
+    # Creates a Filter object indicating that the value of a particular
+    # attribute must begin with a particular string. The attribute value is
+    # escaped, so the "*" character is interpreted literally.
+    def begins(attribute, value)
+      new(:eq, attribute, escape(value) + "*")
+    end
 
-  # #eq creates a filter object indicating that the value of
-  # a paticular attribute must be either <i>present</i> or must
-  # match a particular string.
-  #
-  # To specify that an attribute is "present" means that only
-  # directory entries which contain a value for the particular
-  # attribute will be selected by the filter. This is useful
-  # in case of optional attributes such as <tt>mail.</tt>
-  # Presence is indicated by giving the value "*" in the second
-  # parameter to #eq. This example selects only entries that have
-  # one or more values for <tt>sAMAccountName:</tt>
-  #  f = Net::LDAP::Filter.eq( "sAMAccountName", "*" )
-  #
-  # To match a particular range of values, pass a string as the
-  # second parameter to #eq. The string may contain one or more
-  # "*" characters as wildcards: these match zero or more occurrences
-  # of any character. Full regular-expressions are <i>not</i> supported
-  # due to limitations in the underlying LDAP protocol.
-  # This example selects any entry with a <tt>mail</tt> value containing
-  # the substring "anderson":
-  #  f = Net::LDAP::Filter.eq( "mail", "*anderson*" )
-  #--
-  # Removed gt and lt. They ain't in the standard!
-  #
-  def Filter::eq attribute, value; Filter.new :eq, attribute, value; end
-  def Filter::ne attribute, value; Filter.new :ne, attribute, value; end
-  #def Filter::gt attribute, value; Filter.new :gt, attribute, value; end
-  #def Filter::lt attribute, value; Filter.new :lt, attribute, value; end
-  def Filter::ge attribute, value; Filter.new :ge, attribute, value; end
-  def Filter::le attribute, value; Filter.new :le, attribute, value; end
-
-  # #pres( attribute ) is a synonym for #eq( attribute, "*" )
-  #
-  def Filter::pres attribute; Filter.eq attribute, "*"; end
+    ##
+    # Creates a Filter object indicating that the value of a particular
+    # attribute must end with a particular string. The attribute value is
+    # escaped, so the "*" character is interpreted literally.
+    def ends(attribute, value)
+      new(:eq, attribute, "*" + escape(value))
+    end
 
-  # operator & ("AND") is used to conjoin two or more filters.
-  # This expression will select only entries that have an <tt>objectclass</tt>
-  # attribute AND have a <tt>mail</tt> attribute that begins with "George":
-  #  f = Net::LDAP::Filter.pres( "objectclass" ) & Net::LDAP::Filter.eq( "mail", "George*" )
-  #
-  def & filter; Filter.new :and, self, filter; end
+    ##
+    # Creates a Filter object indicating that the value of a particular
+    # attribute must contain a particular string. The attribute value is
+    # escaped, so the "*" character is interpreted literally.
+    def contains(attribute, value)
+      new(:eq, attribute, "*" + escape(value) + "*")
+    end
 
-  # operator | ("OR") is used to disjoin two or more filters.
-  # This expression will select entries that have either an <tt>objectclass</tt>
-  # attribute OR a <tt>mail</tt> attribute that begins with "George":
-  #  f = Net::LDAP::Filter.pres( "objectclass" ) | Net::LDAP::Filter.eq( "mail", "George*" )
-  #
-  def | filter; Filter.new :or, self, filter; end
+    ##
+    # Creates a Filter object indicating that a particular attribute value
+    # is greater than or equal to the specified value.
+    def ge(attribute, value)
+      new(:ge, attribute, value)
+    end
 
+    ##
+    # Creates a Filter object indicating that a particular attribute value
+    # is less than or equal to the specified value.
+    def le(attribute, value)
+      new(:le, attribute, value)
+    end
+
+    ##
+    # Joins two or more filters so that all conditions must be true. Calling
+    # <tt>Filter.join(left, right)</tt> is the same as <tt>left &
+    # right</tt>.
+    #
+    #   # Selects only entries that have an <tt>objectclass</tt> attribute.
+    #   x = Net::LDAP::Filter.present("objectclass")
+    #   # Selects only entries that have a <tt>mail</tt> attribute that begins
+    #   # with "George".
+    #   y = Net::LDAP::Filter.eq("mail", "George*")
+    #   # Selects only entries that meet both conditions above.
+    #   z = Net::LDAP::Filter.join(x, y)
+    def join(left, right)
+      new(:and, left, right)
+    end
+
+    ##
+    # Creates a disjoint comparison between two or more filters. Selects
+    # entries where either the left or right side are true. Calling
+    # <tt>Filter.intersect(left, right)</tt> is the same as <tt>left |
+    # right</tt>.
+    #
+    #   # Selects only entries that have an <tt>objectclass</tt> attribute.
+    #   x = Net::LDAP::Filter.present("objectclass")
+    #   # Selects only entries that have a <tt>mail</tt> attribute that begins
+    #   # with "George".
+    #   y = Net::LDAP::Filter.eq("mail", "George*")
+    #   # Selects only entries that meet either condition above.
+    #   z = x | y
+    def intersect(left, right)
+      new(:or, left, right)
+    end
 
+    ##
+    # Negates a filter. Calling <tt>Fitler.negate(filter)</tt> i s the same
+    # as <tt>~filter</tt>.
+    #
+    #   # Selects only entries that do not have an <tt>objectclass</tt>
+    #   # attribute.
+    #   x = ~Net::LDAP::Filter.present("objectclass")
+    def negate(filter)
+      new(:not, filter, nil)
+    end
+
+    ##
+    # This is a synonym for #eq(attribute, "*"). Also known as #present and
+    # #pres.
+    def present?(attribute)
+      eq(attribute, "*")
+    end
+    alias_method :present, :present?
+    alias_method :pres, :present?
+
+    # http://tools.ietf.org/html/rfc4515 lists these exceptions from UTF1
+    # charset for filters. All of the following must be escaped in any normal
+    # string using a single backslash ('\') as escape. 
+    #
+    ESCAPES = {
+      "\0" => '00', # NUL            = %x00 ; null character
+      '*'  => '2A', # ASTERISK       = %x2A ; asterisk ("*")
+      '('  => '28', # LPARENS        = %x28 ; left parenthesis ("(")
+      ')'  => '29', # RPARENS        = %x29 ; right parenthesis (")")
+      '\\' => '5C', # ESC            = %x5C ; esc (or backslash) ("\")
+    }
+    # Compiled character class regexp using the keys from the above hash. 
+    ESCAPE_RE = Regexp.new(
+      "[" + 
+      ESCAPES.keys.map { |e| Regexp.escape(e) }.join + 
+      "]")
+
+    ##
+    # Escape a string for use in an LDAP filter
+    def escape(string)
+      string.gsub(ESCAPE_RE) { |char| "\\" + ESCAPES[char] }
+    end
+
+    ##
+    # Converts an LDAP search filter in BER format to an Net::LDAP::Filter
+    # object. The incoming BER object most likely came to us by parsing an
+    # LDAP searchRequest PDU. See also the comments under #to_ber, including
+    # the grammar snippet from the RFC.
+    #--
+    # We're hardcoding the BER constants from the RFC. These should be
+    # broken out insto constants.
+    def parse_ber(ber)
+      case ber.ber_identifier
+      when 0xa0 # context-specific constructed 0, "and"
+        ber.map { |b| parse_ber(b) }.inject { |memo, obj| memo & obj }
+      when 0xa1 # context-specific constructed 1, "or"
+        ber.map { |b| parse_ber(b) }.inject { |memo, obj| memo | obj }
+      when 0xa2 # context-specific constructed 2, "not"
+        ~parse_ber(ber.first)
+      when 0xa3 # context-specific constructed 3, "equalityMatch"
+        if ber.last == "*"
+        else
+          eq(ber.first, ber.last)
+        end
+      when 0xa4 # context-specific constructed 4, "substring"
+        str = ""
+        final = false
+        ber.last.each { |b|
+          case b.ber_identifier
+          when 0x80 # context-specific primitive 0, SubstringFilter "initial"
+            raise Net::LDAP::LdapError, "Unrecognized substring filter; bad initial value." if str.length > 0
+            str += b
+          when 0x81 # context-specific primitive 0, SubstringFilter "any"
+            str += "*#{b}"
+          when 0x82 # context-specific primitive 0, SubstringFilter "final"
+            str += "*#{b}"
+            final = true
+          end
+        }
+        str += "*" unless final
+        eq(ber.first.to_s, str)
+      when 0xa5 # context-specific constructed 5, "greaterOrEqual"
+        ge(ber.first.to_s, ber.last.to_s)
+      when 0xa6 # context-specific constructed 6, "lessOrEqual"
+        le(ber.first.to_s, ber.last.to_s)
+      when 0x87 # context-specific primitive 7, "present"
+        # call to_s to get rid of the BER-identifiedness of the incoming string.
+        present?(ber.to_s)
+      when 0xa9 # context-specific constructed 9, "extensible comparison"
+        raise Net::LDAP::LdapError, "Invalid extensible search filter, should be at least two elements" if ber.size<2
+        
+        # Reassembles the extensible filter parts 
+        # (["sn", "2.4.6.8.10", "Barbara Jones", '1'])
+        type = value = dn = rule = nil
+        ber.each do |element|
+          case element.ber_identifier
+            when 0x81 then rule=element
+            when 0x82 then type=element
+            when 0x83 then value=element
+            when 0x84 then dn='dn'
+          end
+        end
+
+        attribute = ''
+        attribute << type if type
+        attribute << ":#{dn}" if dn
+        attribute << ":#{rule}" if rule
+        
+        ex(attribute, value)
+      else
+        raise Net::LDAP::LdapError, "Invalid BER tag-value (#{ber.ber_identifier}) in search filter."
+      end
+    end
+
+    ##
+    # Converts an LDAP filter-string (in the prefix syntax specified in RFC-2254)
+    # to a Net::LDAP::Filter.
+    def construct(ldap_filter_string)
+      FilterParser.parse(ldap_filter_string)
+    end
+    alias_method :from_rfc2254, :construct
+    alias_method :from_rfc4515, :construct
+
+    ##
+    # Convert an RFC-1777 LDAP/BER "Filter" object to a Net::LDAP::Filter
+    # object.
+    #--
+    # TODO, we're hardcoding the RFC-1777 BER-encodings of the various
+    # filter types. Could pull them out into a constant.
+    #++
+    def parse_ldap_filter(obj)
+      case obj.ber_identifier
+      when 0x87 # present. context-specific primitive 7.
+        eq(obj.to_s, "*")
+      when 0xa3 # equalityMatch. context-specific constructed 3.
+        eq(obj[0], obj[1])
+      else
+        raise Net::LDAP::LdapError, "Unknown LDAP search-filter type: #{obj.ber_identifier}"
+      end
+    end
+  end
+
+  ##
+  # Joins two or more filters so that all conditions must be true.
   #
-  # operator ~ ("NOT") is used to negate a filter.
-  # This expression will select only entries that <i>do not</i> have an <tt>objectclass</tt>
-  # attribute:
-  #  f = ~ Net::LDAP::Filter.pres( "objectclass" )
+  #   # Selects only entries that have an <tt>objectclass</tt> attribute.
+  #   x = Net::LDAP::Filter.present("objectclass")
+  #   # Selects only entries that have a <tt>mail</tt> attribute that begins
+  #   # with "George".
+  #   y = Net::LDAP::Filter.eq("mail", "George*")
+  #   # Selects only entries that meet both conditions above.
+  #   z = x & y
+  def &(filter)
+    self.class.join(self, filter)
+  end
+
+  ##
+  # Creates a disjoint comparison between two or more filters. Selects
+  # entries where either the left or right side are true.
   #
-  #--
-  # This operator can't be !, evidently. Try it.
-  # Removed GT and LT. They're not in the RFC.
-  def ~@; Filter.new :not, self, nil; end
+  #   # Selects only entries that have an <tt>objectclass</tt> attribute.
+  #   x = Net::LDAP::Filter.present("objectclass")
+  #   # Selects only entries that have a <tt>mail</tt> attribute that begins
+  #   # with "George".
+  #   y = Net::LDAP::Filter.eq("mail", "George*")
+  #   # Selects only entries that meet either condition above.
+  #   z = x | y
+  def |(filter)
+    self.class.intersect(self, filter)
+  end
+
+  ##
+  # Negates a filter.
+  #
+  #   # Selects only entries that do not have an <tt>objectclass</tt>
+  #   # attribute.
+  #   x = ~Net::LDAP::Filter.present("objectclass")
+  def ~@
+    self.class.negate(self)
+  end
 
-  	# Equality operator for filters, useful primarily for constructing unit tests.
-	def == filter
-		str = "[@op,@left,@right]"
-		self.instance_eval(str) == filter.instance_eval(str)
-	end
+  ##
+  # Equality operator for filters, useful primarily for constructing unit tests.
+  def ==(filter)
+    # 20100320 AZ: We need to come up with a better way of doing this. This
+    # is just nasty.
+    str = "[@op,@left,@right]"
+    self.instance_eval(str) == filter.instance_eval(str)
+  end
 
-  def to_s
+  def to_raw_rfc2254
     case @op
     when :ne
-      "(!(#{@left}=#{@right}))"
+      "!(#{@left}=#{@right})"
     when :eq
-      "(#{@left}=#{@right})"
-    #when :gt
-     # "#{@left}>#{@right}"
-    #when :lt
-     # "#{@left}<#{@right}"
+      "#{@left}=#{@right}"
+    when :ex
+      "#{@left}:=#{@right}"
     when :ge
       "#{@left}>=#{@right}"
     when :le
       "#{@left}<=#{@right}"
     when :and
-      "(&(#{@left})(#{@right}))"
+      "&(#{@left.to_raw_rfc2254})(#{@right.to_raw_rfc2254})"
     when :or
-      "(|(#{@left})(#{@right}))"
+      "|(#{@left.to_raw_rfc2254})(#{@right.to_raw_rfc2254})"
     when :not
-      "(!(#{@left}))"
-    else
-      raise "invalid or unsupported operator in LDAP Filter"
+      "!(#{@left.to_raw_rfc2254})"
     end
   end
 
+  ##
+  # Converts the Filter object to an RFC 2254-compatible text format.
+  def to_rfc2254
+    "(#{to_raw_rfc2254})"
+  end
 
+  def to_s
+    to_rfc2254
+  end
+
+  ##
+  # Converts the filter to BER format.
   #--
-  # to_ber
   # Filter ::=
   #     CHOICE {
-  #         and            [0] SET OF Filter,
-  #         or             [1] SET OF Filter,
-  #         not            [2] Filter,
-  #         equalityMatch  [3] AttributeValueAssertion,
-  #         substrings     [4] SubstringFilter,
-  #         greaterOrEqual [5] AttributeValueAssertion,
-  #         lessOrEqual    [6] AttributeValueAssertion,
-  #         present        [7] AttributeType,
-  #         approxMatch    [8] AttributeValueAssertion
+  #         and             [0] SET OF Filter,
+  #         or              [1] SET OF Filter,
+  #         not             [2] Filter,
+  #         equalityMatch   [3] AttributeValueAssertion,
+  #         substrings      [4] SubstringFilter,
+  #         greaterOrEqual  [5] AttributeValueAssertion,
+  #         lessOrEqual     [6] AttributeValueAssertion,
+  #         present         [7] AttributeType,
+  #         approxMatch     [8] AttributeValueAssertion,
+  #         extensibleMatch [9] MatchingRuleAssertion
   #     }
   #
-  # SubstringFilter
+  # SubstringFilter ::=
   #     SEQUENCE {
   #         type               AttributeType,
   #         SEQUENCE OF CHOICE {
@@ -168,325 +451,309 @@ class Filter
   #         }
   #     }
   #
-  # Parsing substrings is a little tricky.
-  # We use the split method to break a string into substrings
-  # delimited by the * (star) character. But we also need
-  # to know whether there is a star at the head and tail
-  # of the string. A Ruby particularity comes into play here:
-  # if you split on * and the first character of the string is
-  # a star, then split will return an array whose first element
-  # is an _empty_ string. But if the _last_ character of the
-  # string is star, then split will return an array that does
-  # _not_ add an empty string at the end. So we have to deal
-  # with all that specifically.
+  # MatchingRuleAssertion ::=
+  #     SEQUENCE {
+  #       matchingRule    [1] MatchingRuleId OPTIONAL,
+  #       type            [2] AttributeDescription OPTIONAL,
+  #       matchValue      [3] AssertionValue,
+  #       dnAttributes    [4] BOOLEAN DEFAULT FALSE
+  #     }
+  #
+  # Matching Rule Suffixes
+  #     Less than   [.1] or .[lt]
+  #     Less than or equal to  [.2] or [.lte]
+  #     Equality  [.3] or  [.eq] (default)
+  #     Greater than or equal to  [.4] or [.gte]
+  #     Greater than  [.5] or [.gt]
+  #     Substring  [.6] or  [.sub]
   #
+  #++
   def to_ber
     case @op
     when :eq
-      if @right == "*"          # present
-        @left.to_s.to_ber_contextspecific 7
-      elsif @right =~ /[\*]/    #substring
-        ary = @right.split( /[\*]+/ )
-        final_star = @right =~ /[\*]$/
-        initial_star = ary.first == "" and ary.shift
-
-        seq = []
-        unless initial_star
-          seq << ary.shift.to_ber_contextspecific(0)
+      if @right == "*" # presence test
+        @left.to_s.to_ber_contextspecific(7)
+      elsif @right =~ /[*]/ # substring
+        # Parsing substrings is a little tricky. We use String#split to
+        # break a string into substrings delimited by the * (star)
+        # character. But we also need to know whether there is a star at the
+        # head and tail of the string, so we use a limit parameter value of
+        # -1: "If negative, there is no limit to the number of fields
+        # returned, and trailing null fields are not suppressed."
+        #
+        # 20100320 AZ: This is much simpler than the previous verison. Also,
+        # unnecessary regex escaping has been removed.
+
+        ary = @right.split(/[*]+/, -1)
+
+        if ary.first.empty?
+          first = nil
+          ary.shift
+        else
+          first = ary.shift.to_ber_contextspecific(0)
         end
-        n_any_strings = ary.length - (final_star ? 0 : 1)
-        #p n_any_strings
-        n_any_strings.times {
-          seq << ary.shift.to_ber_contextspecific(1)
-        }
-        unless final_star
-          seq << ary.shift.to_ber_contextspecific(2)
+
+        if ary.last.empty?
+          last = nil
+          ary.pop
+        else
+          last = ary.pop.to_ber_contextspecific(2)
         end
-        [@left.to_s.to_ber, seq.to_ber].to_ber_contextspecific 4
-      else                      #equality
-        [@left.to_s.to_ber, unescape(@right).to_ber].to_ber_contextspecific 3
+
+        seq = ary.map { |e| e.to_ber_contextspecific(1) }
+        seq.unshift first if first
+        seq.push last if last
+
+        [@left.to_s.to_ber, seq.to_ber].to_ber_contextspecific(4)
+      else # equality
+        [@left.to_s.to_ber, unescape(@right).to_ber].to_ber_contextspecific(3)
+      end
+    when :ex
+      seq = []
+
+      unless @left =~ /^([-;\w]*)(:dn)?(:(\w+|[.\w]+))?$/
+        raise Net::LDAP::LdapError, "Bad attribute #{@left}"
       end
+      type, dn, rule = $1, $2, $4
+
+      seq << rule.to_ber_contextspecific(1) unless rule.to_s.empty? # matchingRule
+      seq << type.to_ber_contextspecific(2) unless type.to_s.empty? # type
+      seq << unescape(@right).to_ber_contextspecific(3) # matchingValue
+      seq << "1".to_ber_contextspecific(4) unless dn.to_s.empty? # dnAttributes
+
+      seq.to_ber_contextspecific(9)
     when :ge
-      [@left.to_s.to_ber, unescape(@right).to_ber].to_ber_contextspecific 5
+      [@left.to_s.to_ber, unescape(@right).to_ber].to_ber_contextspecific(5)
     when :le
-      [@left.to_s.to_ber, unescape(@right).to_ber].to_ber_contextspecific 6
+      [@left.to_s.to_ber, unescape(@right).to_ber].to_ber_contextspecific(6)
+    when :ne
+      [self.class.eq(@left, @right).to_ber].to_ber_contextspecific(2)
     when :and
       ary = [@left.coalesce(:and), @right.coalesce(:and)].flatten
-      ary.map {|a| a.to_ber}.to_ber_contextspecific( 0 )
+      ary.map {|a| a.to_ber}.to_ber_contextspecific(0)
     when :or
       ary = [@left.coalesce(:or), @right.coalesce(:or)].flatten
-      ary.map {|a| a.to_ber}.to_ber_contextspecific( 1 )
+      ary.map {|a| a.to_ber}.to_ber_contextspecific(1)
     when :not
-        [@left.to_ber].to_ber_contextspecific 2
-    else
-      # ERROR, we'll return objectclass=* to keep things from blowing up,
-      # but that ain't a good answer and we need to kick out an error of some kind.
-      raise "unimplemented search filter"
+      [@left.to_ber].to_ber_contextspecific(2)
     end
   end
 
-  def unescape(right)
-    right.gsub(/\\([a-fA-F\d]{2,2})/) do
-      [$1.hex].pack("U")
-    end
+  ##
+  # Perform filter operations against a user-supplied block. This is useful
+  # when implementing an LDAP directory server. The caller's block will be
+  # called with two arguments: first, a symbol denoting the "operation" of
+  # the filter; and second, an array consisting of arguments to the
+  # operation. The user-supplied block (which is MANDATORY) should perform
+  # some desired application-defined processing, and may return a
+  # locally-meaningful object that will appear as a parameter in the :and,
+  # :or and :not operations detailed below.
+  #
+  # A typical object to return from the user-supplied block is an array of
+  # Net::LDAP::Filter objects.
+  #
+  # These are the possible values that may be passed to the user-supplied
+  # block:
+  #   * :equalityMatch (the arguments will be an attribute name and a value
+  #     to be matched);
+  #   * :substrings (two arguments: an attribute name and a value containing
+  #     one or more "*" characters);
+  #   * :present (one argument: an attribute name);
+  #   * :greaterOrEqual (two arguments: an attribute name and a value to be
+  #     compared against);
+  #   * :lessOrEqual (two arguments: an attribute name and a value to be
+  #     compared against);
+  #   * :and (two or more arguments, each of which is an object returned
+  #     from a recursive call to #execute, with the same block;
+  #   * :or (two or more arguments, each of which is an object returned from
+  #     a recursive call to #execute, with the same block; and
+  #   * :not (one argument, which is an object returned from a recursive
+  #     call to #execute with the the same block.
+  def execute(&block)
+    case @op
+    when :eq
+      if @right == "*"
+        yield :present, @left
+      elsif @right.index '*'
+        yield :substrings, @left, @right
+      else
+        yield :equalityMatch, @left, @right
+      end
+    when :ge
+      yield :greaterOrEqual, @left, @right
+    when :le
+      yield :lessOrEqual, @left, @right
+    when :or, :and
+      yield @op, (@left.execute(&block)), (@right.execute(&block))
+    when :not
+      yield @op, (@left.execute(&block))
+    end || []
   end
 
-
-	# Converts an LDAP search filter in BER format to an Net::LDAP::Filter
-	# object. The incoming BER object most likely came to us by parsing an
-	# LDAP searchRequest PDU.
-	# Cf the comments under #to_ber, including the grammar snippet from the RFC.
-	#--
-	# We're hardcoding the BER constants from the RFC. Ought to break them out
-	# into constants.
-	#
-	def Filter::parse_ber ber
-		case ber.ber_identifier
-		when 0xa0 # context-specific constructed 0, "and"
-			ber.map {|b| Filter::parse_ber(b)}.inject {|memo,obj| memo & obj}
-		when 0xa1 # context-specific constructed 1, "or"
-			ber.map {|b| Filter::parse_ber(b)}.inject {|memo,obj| memo | obj}
-		when 0xa2 # context-specific constructed 2, "not"
-			~ Filter::parse_ber( ber.first )
-		when 0xa3 # context-specific constructed 3, "equalityMatch"
-			if ber.last == "*"
-			else
-				Filter.eq( ber.first, ber.last )
-			end
-		when 0xa4 # context-specific constructed 4, "substring"
-			str = ""
-			final = false
-			ber.last.each {|b|
-				case b.ber_identifier
-				when 0x80 # context-specific primitive 0, SubstringFilter "initial"
-					raise "unrecognized substring filter, bad initial" if str.length > 0
-					str += b
-				when 0x81 # context-specific primitive 0, SubstringFilter "any"
-					str += "*#{b}"
-				when 0x82 # context-specific primitive 0, SubstringFilter "final"
-					str += "*#{b}"
-					final = true
-				end
-			}
-			str += "*" unless final
-			Filter.eq( ber.first.to_s, str )
-		when 0xa5 # context-specific constructed 5, "greaterOrEqual"
-			Filter.ge( ber.first.to_s, ber.last.to_s )
-		when 0xa6 # context-specific constructed 5, "lessOrEqual"
-			Filter.le( ber.first.to_s, ber.last.to_s )
-		when 0x87 # context-specific primitive 7, "present"
-			# call to_s to get rid of the BER-identifiedness of the incoming string.
-			Filter.pres( ber.to_s )
-		else
-			raise "invalid BER tag-value (#{ber.ber_identifier}) in search filter"
-		end
-	end
-
-
-	# Perform filter operations against a user-supplied block. This is useful when implementing
-	# an LDAP directory server. The caller's block will be called with two arguments: first, a
-	# symbol denoting the "operation" of the filter; and second, an array consisting of arguments
-	# to the operation. The user-supplied block (which is MANDATORY) should perform some desired
-	# application-defined processing, and may return a locally-meaningful object that will appear
-	# as a parameter in the :and, :or and :not operations detailed below.
-	#
-	# A typical object to return from the user-supplied block is an array of
-	# Net::LDAP::Filter objects.
-	#
-	# These are the possible values that may be passed to the user-supplied block:
-	#  :equalityMatch (the arguments will be an attribute name and a value to be matched);
-	#  :substrings (two arguments: an attribute name and a value containing one or more * characters);
-	#  :present (one argument: an attribute name);
-	#  :greaterOrEqual (two arguments: an attribute name and a value to be compared against);
-	#  :lessOrEqual (two arguments: an attribute name and a value to be compared against);
-	#  :and (two or more arguments, each of which is an object returned from a recursive call
-	#     to #execute, with the same block;
-	#  :or (two or more arguments, each of which is an object returned from a recursive call
-	#     to #execute, with the same block;
-	#  :not (one argument, which is an object returned from a recursive call to #execute with the
-	#     the same block.
-	#
-	def execute &block
-		case @op
-		when :eq
-			if @right == "*"
-				yield :present, @left
-			elsif @right.index '*'
-				yield :substrings, @left, @right
-			else
-				yield :equalityMatch, @left, @right
-			end
-		when :ge
-			yield :greaterOrEqual, @left, @right
-		when :le
-			yield :lessOrEqual, @left, @right
-		when :or, :and
-			yield @op, (@left.execute(&block)), (@right.execute(&block))
-		when :not
-			yield @op, (@left.execute(&block))
-		end || []
-	end
-
-
-  #--
-  # coalesce
+  ##
   # This is a private helper method for dealing with chains of ANDs and ORs
   # that are longer than two. If BOTH of our branches are of the specified
   # type of joining operator, then return both of them as an array (calling
   # coalesce recursively). If they're not, then return an array consisting
   # only of self.
-  #
-  def coalesce operator
+  def coalesce(operator) #:nodoc:
     if @op == operator
-      [@left.coalesce( operator ), @right.coalesce( operator )]
+      [@left.coalesce(operator), @right.coalesce(operator)]
     else
       [self]
     end
   end
 
-
-
-  #--
-  # We get a Ruby object which comes from parsing an RFC-1777 "Filter"
-  # object. Convert it to a Net::LDAP::Filter.
-  # TODO, we're hardcoding the RFC-1777 BER-encodings of the various
-  # filter types. Could pull them out into a constant.
-  #
-  def Filter::parse_ldap_filter obj
-    case obj.ber_identifier
-    when 0x87         # present. context-specific primitive 7.
-      Filter.eq( obj.to_s, "*" )
-    when 0xa3         # equalityMatch. context-specific constructed 3.
-      Filter.eq( obj[0], obj[1] )
-    else
-      raise LdapError.new( "unknown ldap search-filter type: #{obj.ber_identifier}" )
-    end
-  end
-
-
-
-
+  ##
   #--
   # We got a hash of attribute values.
   # Do we match the attributes?
   # Return T/F, and call match recursively as necessary.
-  def match entry
+  #++
+  def match(entry)
     case @op
     when :eq
       if @right == "*"
         l = entry[@left] and l.length > 0
       else
-        l = entry[@left] and l = l.to_a and l.index(@right)
+        l = entry[@left] and l = Array(l) and l.index(@right)
       end
     else
-      raise LdapError.new( "unknown filter type in match: #{@op}" )
+      raise Net::LDAP::LdapError, "Unknown filter type in match: #{@op}"
     end
   end
 
-  # Converts an LDAP filter-string (in the prefix syntax specified in RFC-2254)
-  # to a Net::LDAP::Filter.
-  def self.construct ldap_filter_string
-    FilterParser.new(ldap_filter_string).filter
-  end
-
-  # Synonym for #construct.
-  # to a Net::LDAP::Filter.
-  def self.from_rfc2254 ldap_filter_string
-    construct ldap_filter_string
-  end
-
-end # class Net::LDAP::Filter
-
-
-
-class FilterParser #:nodoc:
-
-  attr_reader :filter
-
-  def initialize str
-    @filter = parse( StringScanner.new( str )) or raise Net::LDAP::LdapError.new( "invalid filter syntax" )
+  ##
+  # Converts escaped characters (e.g., "\\28") to unescaped characters
+  # ("(").
+  def unescape(right)
+    right.gsub(/\\([a-fA-F\d]{2})/) { [$1.hex].pack("U") }
   end
+  private :unescape
+
+  ##
+  # Parses RFC 2254-style string representations of LDAP filters into Filter
+  # object hierarchies.
+  class FilterParser #:nodoc:
+    ##
+    # The constructed filter.
+    attr_reader :filter
+
+    class << self
+      private :new
+
+      ##
+      # Construct a filter tree from the provided string and return it.
+      def parse(ldap_filter_string)
+        new(ldap_filter_string).filter
+      end
+    end
 
-  def parse scanner
-    parse_filter_branch(scanner) or parse_paren_expression(scanner)
-  end
+    def initialize(str)
+      require 'strscan' # Don't load strscan until we need it.
+      @filter = parse(StringScanner.new(str))
+      raise Net::LDAP::LdapError, "Invalid filter syntax." unless @filter
+    end
 
-  def parse_paren_expression scanner
-    if scanner.scan(/\s*\(\s*/)
-      b = if scanner.scan(/\s*\&\s*/)
-        a = nil
-        branches = []
-        while br = parse_paren_expression(scanner)
-          branches << br
-        end
-        if branches.length >= 2
-          a = branches.shift
-          while branches.length > 0
-            a = a & branches.shift
-          end
-          a
-        end
-      elsif scanner.scan(/\s*\|\s*/)
-        # TODO: DRY!
-        a = nil
-        branches = []
-        while br = parse_paren_expression(scanner)
-          branches << br
-        end
-        if branches.length >= 2
-          a = branches.shift
-          while branches.length > 0
-            a = a | branches.shift
-          end
-          a
-        end
-      elsif scanner.scan(/\s*\!\s*/)
-        br = parse_paren_expression(scanner)
-        if br
-          ~ br
+    ##
+    # Parse the string contained in the StringScanner provided. Parsing
+    # tries to parse a standalone expression first. If that fails, it tries
+    # to parse a parenthesized expression.
+    def parse(scanner)
+      parse_filter_branch(scanner) or parse_paren_expression(scanner)
+    end
+    private :parse
+
+    ##
+    # Join ("&") and intersect ("|") operations are presented in branches.
+    # That is, the expression <tt>(&(test1)(test2)</tt> has two branches:
+    # test1 and test2. Each of these is parsed separately and then pushed
+    # into a branch array for filter merging using the parent operation.
+    #
+    # This method parses the branch text out into an array of filter
+    # objects.
+    def parse_branches(scanner)
+      branches = []
+      while branch = parse_paren_expression(scanner)
+        branches << branch
+      end
+      branches
+    end
+    private :parse_branches
+
+    ##
+    # Join ("&") and intersect ("|") operations are presented in branches.
+    # That is, the expression <tt>(&(test1)(test2)</tt> has two branches:
+    # test1 and test2. Each of these is parsed separately and then pushed
+    # into a branch array for filter merging using the parent operation.
+    #
+    # This method calls #parse_branches to generate the branch list and then
+    # merges them into a single Filter tree by calling the provided
+    # operation.
+    def merge_branches(op, scanner)
+      filter = nil
+      branches = parse_branches(scanner)
+
+      if branches.size >= 1
+        filter = branches.shift
+        while not branches.empty?
+          filter = filter.__send__(op, branches.shift)
         end
-      else
-        parse_filter_branch( scanner )
       end
 
-      if b and scanner.scan( /\s*\)\s*/ )
-        b
+      filter
+    end
+    private :merge_branches
+
+    def parse_paren_expression(scanner)
+      if scanner.scan(/\s*\(\s*/)
+        expr = if scanner.scan(/\s*\&\s*/)
+                 merge_branches(:&, scanner)
+               elsif scanner.scan(/\s*\|\s*/)
+                 merge_branches(:|, scanner)
+               elsif scanner.scan(/\s*\!\s*/)
+                 br = parse_paren_expression(scanner)
+                 ~br if br
+               else
+                 parse_filter_branch(scanner)
+               end
+
+        if expr and scanner.scan(/\s*\)\s*/)
+          expr
+        end
       end
     end
-  end
+    private :parse_paren_expression
 
-  # Added a greatly-augmented filter contributed by Andre Nathan
-  # for detecting special characters in values. (15Aug06)
-  # Added blanks to the attribute filter (26Oct06)
-  def parse_filter_branch scanner
-    scanner.scan(/\s*/)
-    if token = scanner.scan( /[\w\-_]+/ )
+    ##
+    # This parses a given expression inside of parentheses.
+    def parse_filter_branch(scanner)
       scanner.scan(/\s*/)
-      if op = scanner.scan( /\=|\<\=|\<|\>\=|\>|\!\=/ )
+      if token = scanner.scan(/[-\w:.]*[\w]/)
         scanner.scan(/\s*/)
-        #if value = scanner.scan( /[\w\*\.]+/ ) (ORG)
-        #if value = scanner.scan( /[\w\*\.\+\-@=#\$%&! ]+/ ) (ff suggested by Kouhei Sutou
-	if value = scanner.scan( /(?:[\w\*\.\+\-@=,#\$%&! ]|\\[a-fA-F\d]{2,2})+/ )
-          case op
-          when "="
-            Filter.eq( token, value )
-          when "!="
-            Filter.ne( token, value )
-          when "<"
-            Filter.lt( token, value )
-          when "<="
-            Filter.le( token, value )
-          when ">"
-            Filter.gt( token, value )
-          when ">="
-            Filter.ge( token, value )
+        if op = scanner.scan(/<=|>=|!=|:=|=/)
+          scanner.scan(/\s*/)
+          if value = scanner.scan(/(?:[-\w*.+@=,#\$%&!'\s]|\\[a-fA-F\d]{2})+/)
+            # 20100313 AZ: Assumes that "(uid=george*)" is the same as
+            # "(uid=george* )". The standard doesn't specify, but I can find
+            # no examples that suggest otherwise.
+            value.strip!
+            case op
+            when "="
+              Net::LDAP::Filter.eq(token, value)
+            when "!="
+              Net::LDAP::Filter.ne(token, value)
+            when "<="
+              Net::LDAP::Filter.le(token, value)
+            when ">="
+              Net::LDAP::Filter.ge(token, value)
+            when ":="
+              Net::LDAP::Filter.ex(token, value)
+            end
           end
         end
       end
     end
-  end
-
-end # class Net::LDAP::FilterParser
-
-end # class Net::LDAP
-end # module Net
+    private :parse_filter_branch
+  end # class Net::LDAP::FilterParser
+end # class Net::LDAP::Filter