1LDIF(3)               User Contributed Perl Documentation              LDIF(3)
2
3
4

NAME

6       Mozilla::LDAP::LDIF - read or write LDIF (LDAP Data Interchange Format)
7

SYNOPSIS

9        use Mozilla::LDAP::LDIF
10           qw(set_Entry get_LDIF put_LDIF unpack_LDIF pack_LDIF
11              sort_attributes references enlist_values delist_values
12              read_v1 read_v0 read_file_URL_or_name);
13
14        $ldif = Mozilla::LDAP::LDIF->new(*FILEHANDLE, \&read_reference, $comments);
15        @record = get $ldif;
16        @records = get $ldif ($maximum_number);
17        $entry = set_Entry (\entry, \@record);
18        $entry = readOneEntry $ldif;
19        @entries = readEntries $ldif ($maximum_number);
20
21        $ldif = Mozilla::LDAP::LDIF->new(*FILEHANDLE, $options);
22        $success = put $ldif (@record);
23        $success = put $ldif (\@record, \object ...);
24        $success = writeOneEntry $ldif (\entry);
25        $success = writeEntries  $ldif (\entry, \entry ...);
26
27        @record = get_LDIF (*FILEHANDLE, $eof, \&read_reference, $comments);
28        @record = get_LDIF; # *STDIN
29
30        $success = put_LDIF (*FILEHANDLE, $options, @record);
31        $success = put_LDIF (*FILEHANDLE, $options, \@record, \object ...);
32
33        @record = unpack_LDIF ($string, \&read_reference, $comments);
34
35        $string = pack_LDIF ($options, @record);
36        $string = pack_LDIF ($options, \@record, \object ...);
37
38        @record = enlist_values (@record);
39        @record = delist_values (@record);
40
41        @record = sort_attributes (@record);
42
43        $DN  = LDIF_get_DN (@record); # alias get_DN
44        @DNS = LDIF_get_DN (\@record, \object ...); # alias get_DN
45
46        $offset = next_attribute (\@record, $offset, @options);
47
48        @references = references (@record);
49        @references = references (\@record, \object ...);
50
51        $success = read_v1 (\$url);  # alias read_file_URL
52        $success = read_v0 (\$name); # alias read_file_name
53        $success = read_file_URL_or_name (\$url_or_name);
54

REQUIRES

56       MIME::Base64, Exporter, Carp
57

INSTALLATION

59       Put the LDIF.pm file into a subdirectory named Mozilla/LDAP, in one of
60       the directories named in @INC.  site_perl is a good choice.
61

EXPORTS

63       Nothing (unless you request it).
64

DESCRIPTION

66       LDIF version 1 is defined by <draft-good-ldap-ldif-03>.  An LDIF record
67       like this:
68
69           DN: cn=Foo Bar, o=ITU
70           cn: Foo Bar
71           Sn: Bar
72           objectClass: person
73           objectClass: organizatio
74            nalPerson
75           jpegPhoto:< file:foobar.jpg
76           # comment
77
78       corresponds (in this module) to a Perl array like this:
79
80           (DN => "cn=Foo Bar, o=ITU",
81            cn => "Foo Bar",
82            Sn => "Bar",
83            objectClass => [ "person", "organizationalPerson" ],
84            jpegPhoto => \"file:foobar.jpg",
85            '# comment', undef
86           )
87
88       URLs or file names are read by a separate function.  This module
89       provides functions to read a file name (LDIF version 0) or a file URL
90       that names a local file (minimal LDIF version 1), or either.  You can
91       supply a similar function to read other forms of URL.
92
93       Most output and utility methods in this module accept a parameter list
94       that is either an LDIF array (the first item is a string, usually
95       "dn"), or a list of references, with each reference pointing to either
96       an LDIF array or an object from which this module can get LDIF arrays
97       by calling the object's getLDIFrecords method.  This module calls
98       $object->getLDIFrecords(), expecting it to return a list of references
99       to LDIF arrays.  getLDIFrecords may return references to the object's
100       own data, although it should not return references to anything that
101       will be modified as a side-effect of another call to getLDIFrecords(),
102       on any object.
103

METHODS

105   Input
106       new Mozilla::LDAP::LDIF (*FILEHANDLE, \&read_reference, $comments)
107           Create and return an object to read LDIF from the given file.  If
108           *FILEHANDLE is not defined, return an object to read from *STDIN.
109
110           If \&read_reference is defined, call it when reading each reference
111           to another data source, with ${$_[$[]} equal to the reference.  The
112           function should copy the referent (for example, the contents of the
113           named file) into $_[$[].
114
115           Ignore LDIF comment lines, unless $comments eq "comments".
116
117       get $ldif
118           Read an LDIF record from the given file.  Combine continuation
119           lines and base64-decode attribute values.  Return an array of
120           strings, representing the record.  Return a false value if end of
121           file is encountered before an LDIF record.
122
123       get $ldif ($maximum_number)
124           Read LDIF records from the given file, until end of file is
125           encountered or the given $maximum_number of records are read.  If
126           $maximum_number is undef (or negative), read until end of file.
127           Return an array of references to arrays, each representing one
128           record.  Return a false value if end of file is encountered before
129           an LDIF record, or $maximum_number is zero.
130
131       readOneEntry $ldif
132       readEntries $ldif ($maximum_number)
133           Read Mozilla::LDAP::Entry objects from the given file, and return
134           references to them.  Call Mozilla::LDAP::Conn->newEntry() to create
135           each returned object.  Return a false value if end of file is
136           encountered before an LDIF record, or $maximum_number is zero.
137           readOneEntry returns a reference to a single object.  readEntries
138           returns an array of references to as many as $maximum_number
139           objects.  See get (above) for more information.
140
141       set_Entry (\entry, \@record)
142           Set the DN and attributes of the given Mozilla::LDAP::Entry object
143           from the given LDIF record.  Return a reference to the entry.
144
145       get_LDIF (*FILEHANDLE, $eof, \&read_reference, $comments)
146           Read an LDIF record from the given file.  Return an array of
147           strings, representing the record.  Return a false value if end of
148           file is encountered before an LDIF record.
149
150           If *FILEHANDLE is not defined, read from *STDIN.
151
152           If $eof is passed, set it true if the end of the given file was
153           encountered; otherwise set it false.  This function may set $eof
154           false and also return a record (if the record was terminated by the
155           end of file).
156
157           If \&read_reference is defined, call it when reading each reference
158           to another data source, with ${$_[$[]} equal to the reference.  The
159           function should copy the referent (for example, the contents of the
160           named file) into $_[$[].
161
162           Ignore LDIF comment lines, unless $comments eq "comments".
163
164       unpack_LDIF ($string, \&read_reference, $comments)
165           Read one LDIF record from the given string.  Return an array of
166           strings, representing the record.  Return a false value if the
167           given string doesn't contain an LDIF record.
168
169           If \&read_reference is defined, call it when reading each reference
170           to another data source, with ${$_[$[]} equal to the reference.  The
171           function should copy the referent (for example, the contents of the
172           named file) into $_[$[].
173
174           Ignore LDIF comment lines, unless $comments eq "comments".
175
176       read_v1 (\$url)
177       read_file_URL (\$url)
178           Change the parameter, from a reference to a URL (string) to a
179           string containing a copy of the contents of the file named by that
180           URL, and return true.  Return false if the URL doesn't name a local
181           file, or the file can't be read.
182
183           This implements LDIF version 1, although it doesn't support URLs
184           that refer to anything but a local file (e.g. HTTP or FTP URLs).
185
186       read_v0 (\$name)
187       read_file_name (\$name)
188           Change the parameter, from a reference to a file name to a string
189           containing a copy of the contents of that file, and return true.
190           Return false if the file can't be read.
191
192           This implements LDIF version 0.
193
194       read_file_URL_or_name (\$url_or_name)
195           Change the parameter, from a reference to a URL or file name, to a
196           string containing a copy of the contents of the file it names, and
197           return true.  Return false if the file can't be read.
198
199   Output
200       Mozilla::LDAP::LDIF->new(*FILEHANDLE, $options)
201           Create and return an object used to write LDIF to the given file.
202           $options are described below.
203
204       put $ldif (@record)
205       put $ldif (\@record, \object ...)
206       put_LDIF (*FILEHANDLE, $options, @record)
207       put_LDIF (*FILEHANDLE, $options, \@record, \object ...)
208           Write LDIF records to the given file.  $options are described
209           below.
210
211       writeOneEntry $ldif (\entry)
212       writeEntries  $ldif (\entry, \entry ...)
213           Write Mozilla::LDAP::Entry objects to the given file.
214
215       pack_LDIF ($options, @record)
216       pack_LDIF ($options, \@record, \object ...)
217           Return an LDIF string, representing the given records.
218
219       $options
220           The options parameter (above) may be either "undef", indicating all
221           default options, or a number, which is equivalent to "[max_line =>"
222           number"]", or a reference to an array that contains a list of
223           options, composed from:
224
225           "max_line =>" number
226               If number > 1, break output into continuation lines, so no line
227               is longer than number bytes (not counting the end-of-line
228               marker).
229
230               Default: 0 (output is not broken into continuation lines).
231
232           "encode =>" pattern
233               Base64 encode output values that match pattern.  Warning: As a
234               rule, your pattern should match any value that contains an
235               output line separator (see the SEP option, below).  If any such
236               value is not Base64 encoded, it will be output in a form that
237               does not represent the separator bytes in LDIF form.  That is,
238               if the output is parsed as LDIF, the resulting value will be
239               like the original value, except the separator bytes will be
240               removed.
241
242               Default: "^[:< ]|[^ -\x7E]"
243
244               For example:
245
246                   pack_LDIF ([encode=>"^ |[^ -\xFD]"], @record)
247
248               returns a string in which UTF-8 strings are not encoded (unless
249               they begin with a space or contain control characters) and
250               lines are not continued.  Such a string may be easier to view
251               or edit than standard LDIF, although it's more prone to be
252               garbled when sent in email or processed by software designed
253               for ASCII.  It can be parsed without loss of information (by
254               unpack_LDIF).
255
256           "sep =>" string
257               Output string at the end of each line.
258
259               Default: "\n" (the usual line separator, for output text).
260
261       output_separator ()
262           Return the standard LDIF line separator most similar to "\n".  The
263           output option "[sep => output_separator()]" is recommended, if you
264           want to produce standard LDIF output.
265
266   Utilities
267       sort_attributes (@record)
268       sort_attributes (\@record, \object ...)
269           Return a record equivalent to each parameter, except with the
270           attributes sorted, primarily by attribute name (ignoring case) and
271           secondarily by attribute value (using &cmp).  If the parameter list
272           is a single record, return a single record; otherwise return a list
273           of references to records.
274
275       enlist_values (@record)
276       enlist_values (\@record, \object ...)
277           Return a record equivalent to the parameter, except with values of
278           the same attribute type combined into a nested array.  For example,
279
280               enlist_values (givenName => "Joe", givenname => "Joey", GivenName => "Joseph")
281
282           returns
283
284               (givenName => ["Joe", "Joey", "Joseph"])
285
286           If the parameter list is a single record, return a single record;
287           otherwise return a list of references to records.
288
289       delist_values (@record)
290       delist_values (\@record, \object ...)
291           Return a record equivalent to the parameter, except with all values
292           contained directly (not in a nested array).  For example,
293
294               delist_values (givenName => ["Joe", "Joey", "Joseph"])
295
296           returns
297
298               (givenName => "Joe", givenName => "Joey", givenName => "Joseph")
299
300           If the parameter list is a single record, return a single record;
301           otherwise return a list of references to records.
302
303       references (@record)
304       references (\@record, \object ...)
305           In list context, return a list of references to each of the
306           references to external data sources, in the given records.  In
307           scalar context, return the length of that list; that is, the total
308           number of references to external data sources.
309
310       LDIF_get_DN (@record)
311       get_DN (@record)
312           Return the DN of the given record.  Return undef if the first
313           attribute of the record isn't a DN.
314
315       LDIF_get_DN (\@record, \object ...)
316       get_DN (\@record, \object ...)
317           Return the DN of each of the given records, as an array with one
318           element for each parameter.  If a given record's first attribute
319           isn't a DN, the corresponding element of the returned array is
320           undef.
321
322       next_attribute (\@record, $offset, @options)
323           Return the offset of an attribute type in the given record.  Search
324           forward, starting at $offset + 1, or 0 if $offset is not defined.
325           Return undef if no attribute is found.  The @options list is
326           composed of zero or more of the following:
327
328           "name => "expression
329           "type => "expression
330               Don't return an offset unless the given expression evaluates to
331               TRUE, with $_ aliased to the attribute type name.
332
333           "value => "expression
334               Don't return an offset unless the given expression evaluates to
335               TRUE, with $_ aliased to one of the attribute values.
336
337           In either case, the expression may be a string, which is simply
338           evaluated (using eval), or a reference to a subroutine, which is
339           called with $_ as its only parameter.  The value returned by eval
340           or the subroutine is taken as the result of evaluation.
341
342           If no options are given, the offset of the next attribute is
343           returned.
344
345           Option expressions can modify the record, since they are passed an
346           alias to an element of the record.  An option can selectively
347           prevent the evaluation of subsequent options: options are evaluated
348           in the order they appear in the @options list, and if an option
349           evaluates to FALSE, subsequent options are not evaluated.
350

DIAGNOSTICS

352       $0 can't open %s: $!
353           (W) Mozilla::LDAP::LDIF::read_file_* failed to open a file,
354           probably named in an LDIF attrval-spec.
355
356       $0 non-LDIF line: %s
357           (D) The input contains a line that can't be parsed as LDIF.  It is
358           carried along in place of an attribute name, with an undefined
359           value.  For example, unpack_LDIF("abc") outputs this warning, and
360           returns ("abc", undef).
361
362       Can't use MIME::Base64
363           (F) The MIME::Base64 module isn't installed.  To rectify this, get
364           a copy of MIME::Base64 from
365           http://www.perl.com/CPAN/modules/by-module/MIME/ and install it.
366           If you have trouble, try simply putting Base64.pm in a subdirectory
367           named MIME, in one of the directories named in @INC (site_perl is a
368           good choice).  You'll get a correct, but relatively slow
369           implementation.
370
371       Useless use of %s in scalar or void context
372           (W) The function returns multiple records, of which all but the
373           last will be ignored by the caller.  Time and space were wasted to
374           create them.  It would probably be better to call the function in
375           list context, or to pass it only a single record.
376

EXAMPLES

378           use Mozilla::LDAP::LDIF qw(read_file_URL_or_name);
379
380           $in  = Mozilla::LDAP::LDIF->new(*STDIN, \&read_file_URL_or_name);
381           $out = Mozilla::LDAP::LDIF->new(*STDOUT, 78);
382           @records = get $in (undef); # read to end of file (^D)
383           put $out (@records);
384
385           use Mozilla::LDAP::Conn();
386
387           $conn = Mozilla::LDAP::Conn->new(...);
388           while ($entry = readOneEntry $in) {
389               add $conn ($entry);
390           }
391
392           use Mozilla::LDAP::LDIF qw(get_LDIF put_LDIF
393               references read_v1 next_attribute sort_attributes);
394
395           while (@record = get_LDIF (*STDIN, $eof)) {
396               # Resolve all the file URLs:
397               foreach my $r (references (@record)) {
398                   read_v1 ($$r);
399               }
400               # Capitalize all the attribute names:
401               for ($r = undef; defined ($r = next_attribute (\@record, $r)); ) {
402                   $record[$r] = ucfirst $record[$r];
403               }
404               # Capitalize all the title values:
405               next_attribute (\@record, undef,
406                               type => '"title" eq lc $_',
407                               value => '$_ = ucfirst; 0');
408               # Sort the attributes and output the record, 78 characters per line:
409               put_LDIF (*STDOUT, 78, sort_attributes (@record));
410               last if $eof;
411           }
412

BUGS

414       Output Line Separator
415           Output lines are separated by "\n", by default.  Although this
416           works well in many cases, it is not standard LDIF unless "\n" is
417           "\012" or "\015\012".  It is not, on some platforms (Macintosh, for
418           example).  To get standard output, use the output option "[sep =>
419           Mozilla::LDAP::LDIF::output_separator()]".
420
421       Input Line Separator
422           This package may fail to read standard LDIF correctly, if the input
423           record separator is not LF.  To avoid this bug, set $/ = "\012".
424           Other values of $/ work less well: CR ($/ eq "\015") handles input
425           separated by CR or CR LF, but not LF alone; and CR LF ($/ eq
426           "\015\012") handles input separated by CR LF, but not LF alone.
427
428           This bug arises when handling standard LDIF received 'raw' via the
429           Internet (via HTTP, for example).  There's no problem with an input
430           file that has been converted (as generic text) from standard
431           Internet line separators to $/ (that is, the usual line separator
432           for the local platform).
433

AUTHOR

435       John Kristian <kristian@netscape.com>
436
437       Thanks to Leif Hedstrom, from whose code I took ideas; and to the users
438       who took the trouble to correct my mistakes.  But I accept all blame.
439

SEE ALSO

441       Mozilla::LDAP::Entry, Mozilla::LDAP::Conn, and of course Perl.
442
443
444
445perl v5.16.3                      2007-06-14                           LDIF(3)
Impressum