Net::LDAP::Express version 0.10 =============================== Net::LDAP::Express is an alternative interface to the fantastic Graham Barr's Net::LDAP, that simplifies the tasks of adding and deleting multiple entries, renaming them, or searching entries residing in a common subtree. 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::Express 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) ; NOTES ABOUT THIS RELEASE This is the second release of Net::LDAP::Express. The first release seemed to work well, so the target for this second release is to see if it proves useful to be useful in its target cases and that it hasn't critical bugs. It isn't optimized, but I am beginning to working on it. Maybe the code isn't that clean. Maybe it even isn't elegant. I consider these things minor bugs that I'll correct along the way. For the moment, please check that this code works and only after that give me all the hints you find useful to make the code in this module better. This module is not (yet?) part of the perl-ldap distribution and is being developed indipendendently, at the moment. INSTALLATION To install this module type the following: perl Makefile.PL make make test make install Note that make test will do nothing unless you set some environment variables -see TESTING THE SOURCE TESTING THE SOURCE This module's tests require that you have access to a directory server to test the functionalities. If you don't set some environment variables before running "make test", the tests will just check for a correct installation of the module and for the presence of some other modules that Net::LDAP::Express depends upon. To effectively run the tests just prepend to "make test" a sensible assignment to the TEST_HOST environment variable assignment, like in TEST_HOST='ldap.server.com' make test This will run the tests contacting the directory server at ldap.server.com. If the server runs on a non-standard port just add a TEST_PORT variable: TEST_HOST='ldap.server.com' TEST_PORT=1389 make test The scripts will try to use ou=simple,o=test as their base subtree (the ou=simple is there because the module was supposed to be called Net::LDAP::Simple in the beginning). If you want to change it, just use a TEST_BASE environment variable with the base subtree of your choice. The tree you use as TEST_BASE will be added a ou=test subtree and the tests will take place there. Feel free to get rid of it when the tests are finished. Some tests will try to create and modify entries on the directory server, and this requires some privileges. The test script will use cn=admin,o=test as bind DN and "secret" as password; again, if this isn't the case you can simply prepend an assignment to TEST_BINDDN and TEST_BINDPW. DEPENDENCIES This module requires these other modules and libraries: Net::LDAP and all the perl-ldap distribution by Graham Barr Test::More for "make test" CREDITS I would like to thank all the people that helped me with their suggestions and opinions. Among them: * submersible_toaster of perlmonks (http://perlmonks.org/index.pl?node_id=195273), that first gave me his encouragement to develop this module; * Jim Harle, Christopher A. Bongaarts from the perl-ldap mailing list; * Ken Williams from the module-authors mailing list; * Frederik Uyttersprot from the comp.lang.perl.modules newsgroup; * Chris Ridd, William R. Ward for their feedback about the name; * Italian Perl Mongers, in particular Stefano Rodighiero (larsen), TheHobbit and bepi for their suggestions and contribution; * my friend and brother Stefano Sanna; * John Woodell, that suggested me to add the "sort_by" feature; * and, obviously, Graham Barr! COPYRIGHT AND LICENCE Copyright (C) 2003 Marco Marongiu 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. 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., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. VERSION INFORMATION $Id: README,v 1.2 2004/12/04 18:10:20 bronto Exp $