I wrote to Graham Barr to ask him if it was ok for me to use the Net::LDAP namespace, and he asked me to discuss the thing on the perl-ldap list before releasing anything on that namespace; that's what I am doing at the moment and I already have some feedback
What I am looking for now is some suggestion about the module name in the unlucky case that I won't be allowed to use the Net::LDAP namespace. An existing namespace would be preferred.
Below is the manpage of the first implementation of Net::LDAP::Simple -or whatever the name will be in the future.
NAME
Net::LDAP::Simple - Simplified interface for Net::LDAP
SYNOPSIS
use Net::LDAP::Simple;
# connect and bind to a directory server
# bindDN and bindpw are optional, if you don't specify them an
# anonymous bind is performed
# base is the base subtree for searches, it is an optional param
+eter
# searchattrs are the attributes that are used by the simplesear
+ch()
# method.
eval {
my $ldap =
Net::LDAP::Simple->new(host => 'localhost',
bindDN => 'cn=admin,ou=People,dc=me',
bindpw => 'secret',
base => 'ou=People,dc=me',
searchattrs => [qw(cn uid loginname)]
+,
%parms) ; # params for Net::LDAP::new
} ;
if ($@) {
die "Can't connect to ldap server: $@" ;
}
my $filter = '(|(loginname=~bronto)(|(cn=~bronto)(uid=~bronto)))
+' ;
my $entries ;
# These all return the same array of Net::LDAP::Entry objects
$entries = $ldap->search(filter => $filter) ; # uses new()'s bas
+e
$entries = $ldap->search(base => 'ou=People,dc=me',
filter => $filter) ;
$entries = $ldap->simplesearch('bronto') ; # uses new()'s search
+attrs
# Now elaborate results:
foreach my $entry (@$entries) {
modify_something_in_this($entry) ;
}
# You often want to update a set of entries
foreach my $entry (@$entries) {
die "Error updating entry" unless defined $ldap->update($entry
+) ;
}
# but you can also do this:
my $result = $ldap->update(@$entries) ;
unless (@$result == @$entries) {
print "Error updating entries: ",$ldap->error,
"; code ",$ldap->errcode,".\n\n" ;
}
# Add an entry, or an array of them, works as above:
die $ldap->error unless $ldap->add($entry) ;
# rename an entry: sometimes you simply want to change a name
# and nothing else...
$ldap->rename($entry,$newrdn) ;
DESCRIPTION
Net::LDAP::Simple is a simplified interface to the fantastic
Graham Barr's Net::LDAP. Net::LDAP is a great module for working
with directory servers, but it's a bit overkill when you want to
do simple short scripts or have big programs that always do the
same job again and again, say: open an authenticated connection to
a directory server, search entries against the same attributes
each time and in the same way (e.g.: approx search against the
three attributes cn, uid and loginname). With Net::LDAP this would
mean:
* connect to the directory server using new();
* authenticate with bind() ;
* compose a search filter, and pass it to search(), along with
the base subtree;
* perform the search getting a Net::LDAP::Search object;
* verify that the search was successful using the code() or
is_error() method on the search object;
* if the search was successful, extract the entries from the
Search object, for example with entries or shift_entry.
With Net::LDAP::Simple this is done with:
* connect, authenticate, define default search subtree and
simple-search attributes with the new() method;
* pass the simplesearch method a search string to be matched
against the attributes defined with searchattrs in new() and
check the return value: if it was successful you have a
reference to an array of Net::LDAP::Entry objects, if it was
unsuccessful you get undef, and you can check what the error
was with the error() method (or the error code with errcode) ;
CONSTRUCTOR
new(%parms)
Creates a Net::LDAP::Simple object. Accepts all the parameters
that are legal to Net::LDAP::new but the directory server
name/address is specified via the "host" parameter. Specific
Net::LDAP::Simple parameters are therefore:
host
the name or IP address of the directory server we are
connecting to. Mandatory.
bindDN
bind DN in case of authenticated bind
bindpw
bind password in case of authenticated bind
base
base subtree for searches. ***(Mandatory or optional?)
searchattrs
attributes to use for simple searches (see the
simplesearch method);
searchbool
boolean operator in case that more than one attribute is
specified with searchattrs; default is '|' (boolean or);
allowed boolean operators are | and &.
searchmatch
By default, an 'approx' search is performed by
simplesearch(); for those directory servers that doesn't
support the ~= operator it is possible to request a
substring search specifying the value 'substr' for the
searchmatch parameter.
searchextras
A list of attributes that should be returned in addition
of the default ones.
REDEFINED METHODS
All Net::LDAP methods are supported via inheritance. Method
specific in Net::LDAP::Simple or that override inherited methods
are documented below.
add If you pass it a scalar DN as first parameter, it will proxy
the method call to Net::LDAP::add and it will behave the sane
way returning a Net::LDAP::Message object. Or you can pass it
one or more Net::LDAP::Entry objects, and it will return a
reference to an array of Net::LDAP::Entry objects that
successfully made it on the directory server. You can check if
every entry has been added by comparing the length of the
input list against the length of the output list. Use the
error and/or errorcode methods to see what went wrong.
delete
Works the same way as "add", but it deletes entries instead
:-)
search
search works exactly as Net::LDAP::search() does, however it
takes advantage of the defaults set with new(): uses new()'s
base parameter if you don't specify another base, and adds
searchextras to default attributes unless you specify an
"attrs" parameter.
Another change in the search() interface is the return value:
now search() returns a reference to an array of entries for
success, or undef on error.
Passing a plain string to "search" just proxyies the call to
the method "simplesearch".
NOTE: Actually, I am undecided if this is a good thing. I am
pondering if search should simply be inherited by the
superclass... I'd like to have some feedback about that.
NEW METHODS
rename($entry,$newrdn)
Renames an entry; $entry can be a Net::LDAP::Entry or a DN,
$newrdn is a new value for the RDN. Returns $entry for
success, undef on failure.
update(@entries)
update takes a list of Net::LDAP::Entry objects as arguments
and commits changes on the directory server. Returns a
reference to an array of updated entries.
simplesearch($searchstring)
Searches entries using the new()'s search* and base
parameters. Takes a search string as argument. Returns a list
of entries on success, undef on error.
error
Returns last error's name
errcode
Returns last error's code
AUTHOR
Marco Marongiu, <bronto@CENSORED>
SEE ALSO
the Net::LDAP manpage.