README
1Net::LDAP::Express version 0.12
2===============================
3
4 Net::LDAP::Express is an alternative interface to the fantastic
5 Graham Barr's Net::LDAP, that simplifies the tasks of adding and
6 deleting multiple entries, renaming them, or searching entries
7 residing in a common subtree.
8
9 Net::LDAP is a great module for working with directory servers, but
10 it's a bit overkill when you want to do simple short scripts or have
11 big programs that always do the same job again and again, say: open
12 an authenticated connection to a directory server, search entries
13 against the same attributes each time and in the same way (e.g.:
14 approx search against the three attributes cn, uid and loginname).
15 With Net::LDAP this would mean:
16
17 * connect to the directory server using new();
18
19 * authenticate with bind() ;
20
21 * compose a search filter, and pass it to search(), along with the
22 base subtree;
23
24 * perform the search getting a Net::LDAP::Search object;
25
26 * verify that the search was successful using the code() or
27 is_error() method on the search object;
28
29 * if the search was successful, extract the entries from the
30 Search object, for example with entries or shift_entry.
31
32 With Net::LDAP::Express this is done with:
33
34 * connect, authenticate, define default search subtree and
35 simple-search attributes with the new() method;
36
37 * pass the simplesearch method a search string to be matched
38 against the attributes defined with searchattrs in new() and
39 check the return value: if it was successful you have a
40 reference to an array of Net::LDAP::Entry objects, if it was
41 unsuccessful you get undef, and you can check what the error was
42 with the error() method (or the error code with errcode) ;
43
44
45NOTES ABOUT THIS RELEASE
46
47This is a fix for a bug filed against release 0.11 by Dag-Erling Smørgrav.
48The fix itself is a one line change, so don't expect anything new.
49
50The code is now more than 10 years old and it could use more love than
51I can provide. If you're able and willing to improve the code, please
52do. One thing that this code is waiting for is switching to a cleaner
53delegation approach than the current subclassing.
54
55This module is not part of the perl-ldap distribution.
56
57
58INSTALLATION
59
60To install this module type the following:
61
62 perl Makefile.PL
63 make
64 make test
65 make install
66
67Note that make test will do nothing unless you set some environment
68variables -see TESTING THE SOURCE
69
70
71TESTING THE SOURCE
72
73This module's tests require that you have access to a directory server
74to test the functionalities. If you don't set some environment
75variables before running "make test", the tests will just check for a
76correct installation of the module and for the presence of some other
77modules that Net::LDAP::Express depends upon.
78
79To effectively run the tests just prepend to "make test" a sensible
80assignment to the TEST_HOST environment variable assignment, like in
81
82TEST_HOST='ldap.server.com' make test
83
84This will run the tests contacting the directory server at
85ldap.server.com. If the server runs on a non-standard port just add a
86TEST_PORT variable:
87
88TEST_HOST='ldap.server.com' TEST_PORT=1389 make test
89
90The scripts will try to use ou=simple,o=test as their base subtree
91(the ou=simple is there because the module was supposed to be called
92Net::LDAP::Simple in the beginning). If you want to change it, just
93use a TEST_BASE environment variable with the base subtree of your
94choice. The tree you use as TEST_BASE will be added a ou=test subtree
95and the tests will take place there. Feel free to get rid of it when
96the tests are finished.
97
98Some tests will try to create and modify entries on the directory
99server, and this requires some privileges. The test script will use
100cn=admin,o=test as bind DN and "secret" as password; again, if this
101isn't the case you can simply prepend an assignment to TEST_BINDDN and
102TEST_BINDPW.
103
104
105DEPENDENCIES
106
107This module requires these other modules and libraries:
108
109 Net::LDAP and all the perl-ldap distribution by Graham Barr
110 Test::More for "make test"
111
112
113CREDITS
114
115I would like to thank all the people that helped me with their
116suggestions and opinions. Among them:
117
118* Dag-Erling Smørgrav for submitting bug #96007
119
120* submersible_toaster of perlmonks
121 (http://perlmonks.org/index.pl?node_id=195273), that first gave me
122 his encouragement to develop this module;
123
124* Jim Harle, Christopher A. Bongaarts from the perl-ldap mailing list;
125
126* Ken Williams from the module-authors mailing list;
127
128* Frederik Uyttersprot from the comp.lang.perl.modules newsgroup;
129
130* Chris Ridd, William R. Ward for their feedback about the name;
131
132* Italian Perl Mongers, in particular Stefano Rodighiero (larsen),
133 TheHobbit and bepi for their suggestions and contribution;
134
135* my friend and brother Stefano Sanna;
136
137* John Woodell, that suggested me to add the "sort_by" feature;
138
139* Gordon Lack, for the "exact" search feature;
140
141* and, obviously, Graham Barr!
142
143
144COPYRIGHT AND LICENCE
145
146Copyright (C) 2003-2014 Marco Marongiu
147
148This program is free software; you can redistribute it and/or modify
149it under the terms of the GNU General Public License as published by
150the Free Software Foundation; either version 2 of the License, or
151(at your option) any later version.
152
153This program is distributed in the hope that it will be useful,
154but WITHOUT ANY WARRANTY; without even the implied warranty of
155MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
156GNU General Public License for more details.
157
158You should have received a copy of the GNU General Public License
159along with this program; if not, write to the Free Software
160Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
161