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
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 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)
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 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 Ignore LDIF comment lines, unless $comments eq "comments".
116 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 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 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 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 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 If *FILEHANDLE is not defined, read from *STDIN.
151 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 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 Ignore LDIF comment lines, unless $comments eq "comments".
163 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 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 Ignore LDIF comment lines, unless $comments eq "comments".
175 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 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 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 This implements LDIF version 0.
193 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 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 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 writeOneEntry $ldif (\entry)
212 writeEntries $ldif (\entry, \entry ...)
213 Write Mozilla::LDAP::Entry objects to the given file.
214 pack_LDIF ($options, @record)
216 pack_LDIF ($options, \@record, \object ...)
217 Return an LDIF string, representing the given records.
218 $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 "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 Default: 0 (output is not broken into continuation lines).
231 "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 Default: "^[:< ]|[^ -\x7E]"
243 For example:
245 pack_LDIF ([encode=>"^ |[^ -\xFD]"], @record)
247 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 "sep =>" string
257 Output string at the end of each line.
258 Default: "\n" (the usual line separator, for output text).
260 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 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 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 enlist_values (givenName => "Joe", givenname => "Joey", GivenName => "Joseph")
281 returns
283 (givenName => ["Joe", "Joey", "Joseph"])
285 If the parameter list is a single record, return a single record;
287 otherwise return a list of references to records.
288 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 delist_values (givenName => ["Joe", "Joey", "Joseph"])
295 returns
297 (givenName => "Joe", givenName => "Joey", givenName => "Joseph")
299 If the parameter list is a single record, return a single record;
301 otherwise return a list of references to records.
302 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 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 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 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 "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 "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 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 If no options are given, the offset of the next attribute is
343 returned.
344 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
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 $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 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 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
378 use Mozilla::LDAP::LDIF qw(read_file_URL_or_name);
379 $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 use Mozilla::LDAP::Conn();
386 $conn = Mozilla::LDAP::Conn->new(...);
388 while ($entry = readOneEntry $in) {
389 add $conn ($entry);
390 }
391 use Mozilla::LDAP::LDIF qw(get_LDIF put_LDIF
393 references read_v1 next_attribute sort_attributes);
394 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
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 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 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
435 John Kristian <kristian@netscape.com>
436 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
441 Mozilla::LDAP::Entry, Mozilla::LDAP::Conn, and of course Perl.
442perl v5.16.3 2007-06-14 LDIF(3)