1LDIF(3) User Contributed Perl Documentation LDIF(3)
2
6 Mozilla::LDAP::LDIF - read or write LDIF (LDAP Data Interchange Format)
7
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 $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 $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 @record = get_LDIF (*FILEHANDLE, $eof, \&read_reference, $comments);
28 @record = get_LDIF; # *STDIN
29 $success = put_LDIF (*FILEHANDLE, $options, @record);
31 $success = put_LDIF (*FILEHANDLE, $options, \@record, \object ...);
32 @record = unpack_LDIF ($string, \&read_reference, $comments);
34 $string = pack_LDIF ($options, @record);
36 $string = pack_LDIF ($options, \@record, \object ...);
37 @record = enlist_values (@record);
39 @record = delist_values (@record);
40 @record = sort_attributes (@record);
42 $DN = LDIF_get_DN (@record); # alias get_DN
44 @DNS = LDIF_get_DN (\@record, \object ...); # alias get_DN
45 $offset = next_attribute (\@record, $offset, @options);
47 @references = references (@record);
49 @references = references (\@record, \object ...);
50 $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
56 MIME::Base64, Exporter, Carp
57
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
63 Nothing (unless you request it).
64
66 LDIF version 1 is defined by <draft-good-ldap-ldif-03>. An LDIF record
67 like this:
68 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 corresponds (in this module) to a Perl array like this:
79 (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 URLs or file names are read by a separate function. This module pro‐
89 vides functions to read a file name (LDIF version 0) or a file URL that
90 names a local file (minimal LDIF version 1), or either. You can supply
91 a similar function to read other forms of URL.
92 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
105 Input
106 new Mozilla::LDAP::LDIF (*FILEHANDLE, \&read_reference, $comments)
108 Create and return an object to read LDIF from the given file. If
109 *FILEHANDLE is not defined, return an object to read from *STDIN.
110 If \&read_reference is defined, call it when reading each reference
112 to another data source, with ${$_[$[]} equal to the reference. The
113 function should copy the referent (for example, the contents of the
114 named file) into $_[$[].
115 Ignore LDIF comment lines, unless $comments eq "comments".
117 get $ldif
119 Read an LDIF record from the given file. Combine continuation
120 lines and base64-decode attribute values. Return an array of
121 strings, representing the record. Return a false value if end of
122 file is encountered before an LDIF record.
123 get $ldif ($maximum_number)
125 Read LDIF records from the given file, until end of file is encoun‐
126 tered or the given $maximum_number of records are read. If $maxi‐
127 mum_number is undef (or negative), read until end of file. Return
128 an array of references to arrays, each representing one record.
129 Return a false value if end of file is encountered before an LDIF
130 record, or $maximum_number is zero.
131 readOneEntry $ldif
133 readEntries $ldif ($maximum_number)
134 Read Mozilla::LDAP::Entry objects from the given file, and return
135 references to them. Call Mozilla::LDAP::Conn->newEntry() to create
136 each returned object. Return a false value if end of file is
137 encountered before an LDIF record, or $maximum_number is zero.
138 readOneEntry returns a reference to a single object. readEntries
139 returns an array of references to as many as $maximum_number
140 objects. See get (above) for more information.
141 set_Entry (\entry, \@record)
143 Set the DN and attributes of the given Mozilla::LDAP::Entry object
144 from the given LDIF record. Return a reference to the entry.
145 get_LDIF (*FILEHANDLE, $eof, \&read_reference, $comments)
147 Read an LDIF record from the given file. Return an array of
148 strings, representing the record. Return a false value if end of
149 file is encountered before an LDIF record.
150 If *FILEHANDLE is not defined, read from *STDIN.
152 If $eof is passed, set it true if the end of the given file was
154 encountered; otherwise set it false. This function may set $eof
155 false and also return a record (if the record was terminated by the
156 end of file).
157 If \&read_reference is defined, call it when reading each reference
159 to another data source, with ${$_[$[]} equal to the reference. The
160 function should copy the referent (for example, the contents of the
161 named file) into $_[$[].
162 Ignore LDIF comment lines, unless $comments eq "comments".
164 unpack_LDIF ($string, \&read_reference, $comments)
166 Read one LDIF record from the given string. Return an array of
167 strings, representing the record. Return a false value if the
168 given string doesn't contain an LDIF record.
169 If \&read_reference is defined, call it when reading each reference
171 to another data source, with ${$_[$[]} equal to the reference. The
172 function should copy the referent (for example, the contents of the
173 named file) into $_[$[].
174 Ignore LDIF comment lines, unless $comments eq "comments".
176 read_v1 (\$url)
178 read_file_URL (\$url)
179 Change the parameter, from a reference to a URL (string) to a
180 string containing a copy of the contents of the file named by that
181 URL, and return true. Return false if the URL doesn't name a local
182 file, or the file can't be read.
183 This implements LDIF version 1, although it doesn't support URLs
185 that refer to anything but a local file (e.g. HTTP or FTP URLs).
186 read_v0 (\$name)
188 read_file_name (\$name)
189 Change the parameter, from a reference to a file name to a string
190 containing a copy of the contents of that file, and return true.
191 Return false if the file can't be read.
192 This implements LDIF version 0.
194 read_file_URL_or_name (\$url_or_name)
196 Change the parameter, from a reference to a URL or file name, to a
197 string containing a copy of the contents of the file it names, and
198 return true. Return false if the file can't be read.
199 Output
201 Mozilla::LDAP::LDIF->new(*FILEHANDLE, $options)
203 Create and return an object used to write LDIF to the given file.
204 $options are described below.
205 put $ldif (@record)
207 put $ldif (\@record, \object ...)
208 put_LDIF (*FILEHANDLE, $options, @record)
209 put_LDIF (*FILEHANDLE, $options, \@record, \object ...)
210 Write LDIF records to the given file. $options are described
211 below.
212 writeOneEntry $ldif (\entry)
214 writeEntries $ldif (\entry, \entry ...)
215 Write Mozilla::LDAP::Entry objects to the given file.
216 pack_LDIF ($options, @record)
218 pack_LDIF ($options, \@record, \object ...)
219 Return an LDIF string, representing the given records.
220 $options
222 The options parameter (above) may be either "undef", indicating all
223 default options, or a number, which is equivalent to "[max_line =>"
224 number"]", or a reference to an array that contains a list of
225 options, composed from:
226 "max_line =>" number
228 If number > 1, break output into continuation lines, so no line
229 is longer than number bytes (not counting the end-of-line
230 marker).
231 Default: 0 (output is not broken into continuation lines).
233 "encode =>" pattern
235 Base64 encode output values that match pattern. Warning: As a
236 rule, your pattern should match any value that contains an out‐
237 put line separator (see the SEP option, below). If any such
238 value is not Base64 encoded, it will be output in a form that
239 does not represent the separator bytes in LDIF form. That is,
240 if the output is parsed as LDIF, the resulting value will be
241 like the original value, except the separator bytes will be
242 removed.
243 Default: "^[:< ]⎪[^ -\x7E]"
245 For example:
247 pack_LDIF ([encode=>"^ ⎪[^ -\xFD]"], @record)
249 returns a string in which UTF-8 strings are not encoded (unless
251 they begin with a space or contain control characters) and
252 lines are not continued. Such a string may be easier to view
253 or edit than standard LDIF, although it's more prone to be gar‐
254 bled when sent in email or processed by software designed for
255 ASCII. It can be parsed without loss of information (by
256 unpack_LDIF).
257 "sep =>" string
259 Output string at the end of each line.
260 Default: "\n" (the usual line separator, for output text).
262 output_separator ()
264 Return the standard LDIF line separator most similar to "\n". The
265 output option "[sep => output_separator()]" is recommended, if you
266 want to produce standard LDIF output.
267 Utilities
269 sort_attributes (@record)
271 sort_attributes (\@record, \object ...)
272 Return a record equivalent to each parameter, except with the
273 attributes sorted, primarily by attribute name (ignoring case) and
274 secondarily by attribute value (using &cmp). If the parameter list
275 is a single record, return a single record; otherwise return a list
276 of references to records.
277 enlist_values (@record)
279 enlist_values (\@record, \object ...)
280 Return a record equivalent to the parameter, except with values of
281 the same attribute type combined into a nested array. For example,
282 enlist_values (givenName => "Joe", givenname => "Joey", GivenName => "Joseph")
284 returns
286 (givenName => ["Joe", "Joey", "Joseph"])
288 If the parameter list is a single record, return a single record;
290 otherwise return a list of references to records.
291 delist_values (@record)
293 delist_values (\@record, \object ...)
294 Return a record equivalent to the parameter, except with all values
295 contained directly (not in a nested array). For example,
296 delist_values (givenName => ["Joe", "Joey", "Joseph"])
298 returns
300 (givenName => "Joe", givenName => "Joey", givenName => "Joseph")
302 If the parameter list is a single record, return a single record;
304 otherwise return a list of references to records.
305 references (@record)
307 references (\@record, \object ...)
308 In list context, return a list of references to each of the refer‐
309 ences to external data sources, in the given records. In scalar
310 context, return the length of that list; that is, the total number
311 of references to external data sources.
312 LDIF_get_DN (@record)
314 get_DN (@record)
315 Return the DN of the given record. Return undef if the first
316 attribute of the record isn't a DN.
317 LDIF_get_DN (\@record, \object ...)
319 get_DN (\@record, \object ...)
320 Return the DN of each of the given records, as an array with one
321 element for each parameter. If a given record's first attribute
322 isn't a DN, the corresponding element of the returned array is
323 undef.
324 next_attribute (\@record, $offset, @options)
326 Return the offset of an attribute type in the given record. Search
327 forward, starting at $offset + 1, or 0 if $offset is not defined.
328 Return undef if no attribute is found. The @options list is com‐
329 posed of zero or more of the following:
330 "name => "expression
332 "type => "expression
333 Don't return an offset unless the given expression evaluates to
334 TRUE, with $_ aliased to the attribute type name.
335 "value => "expression
337 Don't return an offset unless the given expression evaluates to
338 TRUE, with $_ aliased to one of the attribute values.
339 In either case, the expression may be a string, which is simply
341 evaluated (using eval), or a reference to a subroutine, which is
342 called with $_ as its only parameter. The value returned by eval
343 or the subroutine is taken as the result of evaluation.
344 If no options are given, the offset of the next attribute is
346 returned.
347 Option expressions can modify the record, since they are passed an
349 alias to an element of the record. An option can selectively pre‐
350 vent the evaluation of subsequent options: options are evaluated in
351 the order they appear in the @options list, and if an option evalu‐
352 ates to FALSE, subsequent options are not evaluated.
353
355 $0 can't open %s: $!
356 (W) Mozilla::LDAP::LDIF::read_file_* failed to open a file, proba‐
357 bly named in an LDIF attrval-spec.
358 $0 non-LDIF line: %s
360 (D) The input contains a line that can't be parsed as LDIF. It is
361 carried along in place of an attribute name, with an undefined
362 value. For example, unpack_LDIF("abc") outputs this warning, and
363 returns ("abc", undef).
364 Can't use MIME::Base64
366 (F) The MIME::Base64 module isn't installed. To rectify this, get
367 a copy of MIME::Base64 from http://www.perl.com/CPAN/mod‐
368 ules/by-module/MIME/ and install it. If you have trouble, try sim‐
369 ply putting Base64.pm in a subdirectory named MIME, in one of the
370 directories named in @INC (site_perl is a good choice). You'll get
371 a correct, but relatively slow implementation.
372 Useless use of %s in scalar or void context
374 (W) The function returns multiple records, of which all but the
375 last will be ignored by the caller. Time and space were wasted to
376 create them. It would probably be better to call the function in
377 list context, or to pass it only a single record.
378
380 use Mozilla::LDAP::LDIF qw(read_file_URL_or_name);
381 $in = Mozilla::LDAP::LDIF->new(*STDIN, \&read_file_URL_or_name);
383 $out = Mozilla::LDAP::LDIF->new(*STDOUT, 78);
384 @records = get $in (undef); # read to end of file (^D)
385 put $out (@records);
386 use Mozilla::LDAP::Conn();
388 $conn = Mozilla::LDAP::Conn->new(...);
390 while ($entry = readOneEntry $in) {
391 add $conn ($entry);
392 }
393 use Mozilla::LDAP::LDIF qw(get_LDIF put_LDIF
395 references read_v1 next_attribute sort_attributes);
396 while (@record = get_LDIF (*STDIN, $eof)) {
398 # Resolve all the file URLs:
399 foreach my $r (references (@record)) {
400 read_v1 ($$r);
401 }
402 # Capitalize all the attribute names:
403 for ($r = undef; defined ($r = next_attribute (\@record, $r)); ) {
404 $record[$r] = ucfirst $record[$r];
405 }
406 # Capitalize all the title values:
407 next_attribute (\@record, undef,
408 type => '"title" eq lc $_',
409 value => '$_ = ucfirst; 0');
410 # Sort the attributes and output the record, 78 characters per line:
411 put_LDIF (*STDOUT, 78, sort_attributes (@record));
412 last if $eof;
413 }
414
416 Output Line Separator
417 Output lines are separated by "\n", by default. Although this
418 works well in many cases, it is not standard LDIF unless "\n" is
419 "\012" or "\015\012". It is not, on some platforms (Macintosh, for
420 example). To get standard output, use the output option "[sep =>
421 Mozilla::LDAP::LDIF::output_separator()]".
422 Input Line Separator
424 This package may fail to read standard LDIF correctly, if the input
425 record separator is not LF. To avoid this bug, set $/ = "\012".
426 Other values of $/ work less well: CR ($/ eq "\015") handles input
427 separated by CR or CR LF, but not LF alone; and CR LF ($/ eq
428 "\015\012") handles input separated by CR LF, but not LF alone.
429 This bug arises when handling standard LDIF received 'raw' via the
431 Internet (via HTTP, for example). There's no problem with an input
432 file that has been converted (as generic text) from standard Inter‐
433 net line separators to $/ (that is, the usual line separator for
434 the local platform).
435
437 John Kristian <kristian@netscape.com>
438 Thanks to Leif Hedstrom, from whose code I took ideas; and to the users
440 who took the trouble to correct my mistakes. But I accept all blame.
441
443 Mozilla::LDAP::Entry, Mozilla::LDAP::Conn, and of course Perl.
444perl v5.8.8 2007-06-14 LDIF(3)