Net::LDAP::Express version 0.01
============================

    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 first release of Net::LDAP::Express. The target for this
release is to check that it works, that it proves useful in its target
cases and that it hasn't critical bugs. It isn't optimized. 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 test some environment
variables before running "make test" they will simply 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" an
environment variable assignment, like

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. In
case this isn't the case, just use a TEST_BASE environment variable
with the base subtree.

Some tests will try to create and modify entries on the directory
server, that could require 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

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.