.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Net::LDAP::FilterBuilder 3pm"
.TH Net::LDAP::FilterBuilder 3pm "2016-10-30" "perl v5.24.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::LDAP::FilterBuilder \- Build LDAP filter statements
.SH "VERSION"
.IX Header "VERSION"
version 1.200000
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Net::LDAP::FilterBuilder;
\&
\& my $filter1 = Net::LDAP::FilterBuilder\->new( sn => \*(AqJones\*(Aq );
\& # now $filter1 eq \*(Aq(sn=Jones)\*(Aq
.Ve
.PP
Basic logic operations such as \f(CW\*(C`and\*(C'\fR, \f(CW\*(C`or\*(C'\fR and \f(CW\*(C`not\*(C'\fR:
.PP
.Vb 2
\& $filter1\->and( givenName => \*(AqDavid\*(Aq );
\& # (&(sn=Jones)(givenName=David))
\& 
\& my $filter2 = Net::LDAP::FilterBuilder\->new( sn => [ \*(AqJones\*(Aq, \*(AqEdwards\*(Aq, \*(AqLewis\*(Aq ] );
\& # (|(sn=Jones)(sn=Edwards)(sn=Lewis))
\& 
\& my $filter3 = Net::LDAP::FilterBuilder\->new( givenName => \*(AqDavid\*(Aq )\->not;
\& # (!(givenName=David))
.Ve
.PP
Build up filters incrementally from other FilterBuidler objects:
.PP
.Vb 2
\& my $filter4 = Net::LDAP::FilterBuilder\->new( sn => [\*(AqJones\*(Aq, \*(AqEdwards\*(Aq] )\->and( $filter3 );
\& # (&(|(sn=Jones)(sn=Edwards))(!(givenName=David)))
.Ve
.PP
Special characters to \s-1LDAP\s0 will be escaped:
.PP
.Vb 2
\& my $filter5 = Net::LDAP::FilterBuilder\->new( sn => \*(Aqfoo*bar\*(Aq );
\& # (sn=foo\e*bar)
.Ve
.PP
To disable escaping, pass a Scalar reference:
.PP
.Vb 2
\& my $filter6 = Net::LDAP::FilterBuilder\->new( sn => \e\*(Aqfoo*bar\*(Aq );
\& # (sn=foo*bar)
.Ve
.PP
Alternate operators are available through the three-argument constructor form:
.PP
.Vb 2
\& my $filter7 = Net::LDAP::FilterBuilder\->new( \*(Aq>=\*(Aq, dateOfBirth => \*(Aq19700101000000Z\*(Aq );
\& # (dateOfBirth>=19700101000000Z)
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a convenience module which greatly simplifies the construction of \s-1LDAP\s0
query filter statements, which are described in \s-1RFC 4515\s0 and also the
Net::LDAP::Filter manual page.
.SH "PURPOSE"
.IX Header "PURPOSE"
Use this module to construct \s-1LDAP\s0 filter statements which are compliant with
the \s-1RFC 4515\s0 syntax and also safely escape special characters. Filter
statements can be built incrementally using simple logic operations.
.SH "USAGE"
.IX Header "USAGE"
To make any filter, call the constructor \f(CW\*(C`new\*(C'\fR with the attribute and value
to match:
.PP
.Vb 1
\& my $filter = Net::LDAP::FilterBuilder\->new( sn => \*(AqJones\*(Aq );
.Ve
.PP
The value returned is an object, but stringifies to the current query:
.PP
.Vb 2
\& print "success" if $filter eq \*(Aq(sn=Jones)\*(Aq;
\& # prints "success"
.Ve
.PP
However you can refine the filter statement using three additional methods for
the logical operations \f(CW\*(C`and\*(C'\fR, \f(CW\*(C`or\*(C'\fR and \f(CW\*(C`not\*(C'\fR, as shown in the \*(L"\s-1SYOPSIS\*(R"\s0
section, above, and the \*(L"\s-1METHODS\*(R"\s0 section below.
.PP
There are two ways to refine a filter. Either call the logic method with a new
attribute and value, or call a logic method and pass another
Net::LDAP::FilterBuilder object. These two practices are also shown in the
\&\*(L"\s-1SYNOPSIS\*(R"\s0 section, above.
.SS "Comparison Operators"
.IX Subsection "Comparison Operators"
By default the module uses an equal operator between the attribute and value.
To select an alternate operator, use the three agurment form of the
constructor:
.PP
.Vb 2
\& my $filter = Net::LDAP::FilterBuilder\->new( \*(Aq>=\*(Aq, dateOfBirth => \*(Aq19700101000000Z\*(Aq );
\& # (dateOfBirth>=19700101000000Z)
.Ve
.PP
Note that this module is not aware of the list of valid operators, it simply
takes the first argument to be the operator, whatever it might be.
.SS "Special Character Escaping"
.IX Subsection "Special Character Escaping"
If you happen to include one of the small set of characters which are of
special significance to \s-1LDAP\s0 filter statements in your value argument, then
those characters will be escaped. The list of characters is:
.PP
.Vb 1
\& ( ) * \e NUL
.Ve
.PP
To avoid this pass in a scalar reference as the value argument. For example to
enable a wildcard (substring) match on a value:
.PP
.Vb 2
\& my $filter = Net::LDAP::FilterBuilder\->new( sn => \e\*(Aqfoo*bar\*(Aq );
\& # (sn=foo*bar)
.Ve
.SH "METHODS"
.IX Header "METHODS"
.IP "\fBas_str\fR" 4
.IX Item "as_str"
Returns the string representation of the \s-1LDAP\s0 filter.  Note that the
object will stringify to this value in string context, too.
.IP "\fBand\fR(\s-1FILTERSPEC\s0)" 4
.IX Item "and(FILTERSPEC)"
Logically conjoins this filter with the one specified by \s-1FILTERSPEC.
FILTERSPEC\s0 may be a Net::LDAP::FilterBuilder object, or a
hash representation of the filter as taken by \fBnew\fR.
.Sp
Returns the newly-conjoined Net::LDAP::FilterBuilder.
.IP "\fBor\fR(\s-1FILTERSPEC\s0)" 4
.IX Item "or(FILTERSPEC)"
Logically disjoins this filter with the one specified by \s-1FILTERSPEC.
FILTERSPEC\s0 may be a Net::LDAP::FilterBuilder object, or a
hash representation of the filter as taken by \fBnew\fR.
.Sp
Returns the newly-disjoined Net::LDAP::FilterBuilder.
.IP "\fBnot\fR" 4
.IX Item "not"
Logically complements this filter.
.Sp
Returns the newly-negated Net::LDAP::FilterBuilder.
.SH "MAINTAINER"
.IX Header "MAINTAINER"
Oliver Gorwits \f(CW\*(C`<oliver.gorwits@oucs.ox.ac.uk>\*(C'\fR
.SH "AUTHOR"
.IX Header "AUTHOR"
Originally written by Ray Miller.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2010 by University of Oxford.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.