Class Net::LDAP::Filter
In: lib/net/ldap/filter.rb
Parent: Object

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 :filter parameter of Net::LDAP#search.

See the individual class and instance methods below for more examples.

Methods

&   ==   coalesce   construct   eq   execute   from_rfc2254   ge   le   match   ne   new   parse_ber   parse_ldap_filter   pres   to_ber   to_s   unescape   |   ~  

Public Class methods

Converts an LDAP filter-string (in the prefix syntax specified in RFC-2254) to a Net::LDAP::Filter.

eq creates a filter object indicating that the value of a paticular attribute must be either present 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 mail. 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 sAMAccountName:

 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 not supported due to limitations in the underlying LDAP protocol. This example selects any entry with a mail value containing the substring "anderson":

 f = Net::LDAP::Filter.eq( "mail", "*anderson*" )

def Filter::gt attribute, value; Filter.new :gt, attribute, value; end def Filter::lt attribute, value; Filter.new :lt, attribute, value; 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.

pres( attribute ) is a synonym for eq( attribute, "*" )

Public Instance methods

operator & ("AND") is used to conjoin two or more filters. This expression will select only entries that have an objectclass attribute AND have a mail attribute that begins with "George":

 f = Net::LDAP::Filter.pres( "objectclass" ) & Net::LDAP::Filter.eq( "mail", "George*" )

Equality operator for filters, useful primarily for constructing unit tests.

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.

operator | ("OR") is used to disjoin two or more filters. This expression will select entries that have either an objectclass attribute OR a mail attribute that begins with "George":

 f = Net::LDAP::Filter.pres( "objectclass" ) | Net::LDAP::Filter.eq( "mail", "George*" )

operator ~ ("NOT") is used to negate a filter. This expression will select only entries that do not have an objectclass attribute:

 f = ~ Net::LDAP::Filter.pres( "objectclass" )

[Validate]