LDIF(3) User Contributed Perl Documentation LDIF(3)NAMEMozilla::LDAP::LDIF - read or write LDIF (LDAP Data Interchange Format)
SYNOPSIS
use Mozilla::LDAP::LDIF
qw(set_Entry get_LDIF put_LDIF unpack_LDIF pack_LDIF
sort_attributes references enlist_values delist_values
read_v1 read_v0 read_file_URL_or_name);
$ldif = Mozilla::LDAP::LDIF->new(*FILEHANDLE, \&read_reference, $comments);
@record = get $ldif;
@records = get $ldif ($maximum_number);
$entry = set_Entry (\entry, \@record);
$entry = readOneEntry $ldif;
@entries = readEntries $ldif ($maximum_number);
$ldif = Mozilla::LDAP::LDIF->new(*FILEHANDLE, $options);
$success = put $ldif (@record);
$success = put $ldif (\@record, \object ...);
$success = writeOneEntry $ldif (\entry);
$success = writeEntries $ldif (\entry, \entry ...);
@record = get_LDIF (*FILEHANDLE, $eof, \&read_reference, $comments);
@record = get_LDIF; # *STDIN
$success = put_LDIF (*FILEHANDLE, $options, @record);
$success = put_LDIF (*FILEHANDLE, $options, \@record, \object ...);
@record = unpack_LDIF ($string, \&read_reference, $comments);
$string = pack_LDIF ($options, @record);
$string = pack_LDIF ($options, \@record, \object ...);
@record = enlist_values (@record);
@record = delist_values (@record);
@record = sort_attributes (@record);
$DN = LDIF_get_DN (@record); # alias get_DN
@DNS = LDIF_get_DN (\@record, \object ...); # alias get_DN
$offset = next_attribute (\@record, $offset, @options);
@references = references (@record);
@references = references (\@record, \object ...);
$success = read_v1 (\$url); # alias read_file_URL
$success = read_v0 (\$name); # alias read_file_name
$success = read_file_URL_or_name (\$url_or_name);
REQUIRES
MIME::Base64, Exporter, Carp
INSTALLATION
Put the LDIF.pm file into a subdirectory named Mozilla/LDAP, in one of
the directories named in @INC. site_perl is a good choice.
EXPORTS
Nothing (unless you request it).
DESCRIPTION
LDIF version 1 is defined by <draft-good-ldap-ldif-03>. An LDIF record
like this:
DN: cn=Foo Bar, o=ITU
cn: Foo Bar
Sn: Bar
objectClass: person
objectClass: organizatio
nalPerson
jpegPhoto:< file:foobar.jpg
# comment
corresponds (in this module) to a Perl array like this:
(DN => "cn=Foo Bar, o=ITU",
cn => "Foo Bar",
Sn => "Bar",
objectClass => [ "person", "organizationalPerson" ],
jpegPhoto => \"file:foobar.jpg",
'# comment', undef
)
URLs or file names are read by a separate function. This module
provides functions to read a file name (LDIF version 0) or a file URL
that names a local file (minimal LDIF version 1), or either. You can
supply a similar function to read other forms of URL.
Most output and utility methods in this module accept a parameter list
that is either an LDIF array (the first item is a string, usually
"dn"), or a list of references, with each reference pointing to either
an LDIF array or an object from which this module can get LDIF arrays
by calling the object's getLDIFrecords method. This module calls
$object->getLDIFrecords(), expecting it to return a list of references
to LDIF arrays. getLDIFrecords may return references to the object's
own data, although it should not return references to anything that
will be modified as a side-effect of another call to getLDIFrecords(),
on any object.
METHODS
Input
new Mozilla::LDAP::LDIF (*FILEHANDLE, \&read_reference, $comments)
Create and return an object to read LDIF from the given file. If
*FILEHANDLE is not defined, return an object to read from *STDIN.
If \&read_reference is defined, call it when reading each reference
to another data source, with ${$_[$[]} equal to the reference. The
function should copy the referent (for example, the contents of the
named file) into $_[$[].
Ignore LDIF comment lines, unless $comments eq "comments".
get $ldif
Read an LDIF record from the given file. Combine continuation
lines and base64-decode attribute values. Return an array of
strings, representing the record. Return a false value if end of
file is encountered before an LDIF record.
get $ldif ($maximum_number)
Read LDIF records from the given file, until end of file is
encountered or the given $maximum_number of records are read. If
$maximum_number is undef (or negative), read until end of file.
Return an array of references to arrays, each representing one
record. Return a false value if end of file is encountered before
an LDIF record, or $maximum_number is zero.
readOneEntry $ldif
readEntries $ldif ($maximum_number)
Read Mozilla::LDAP::Entry objects from the given file, and return
references to them. Call Mozilla::LDAP::Conn->newEntry() to create
each returned object. Return a false value if end of file is
encountered before an LDIF record, or $maximum_number is zero.
readOneEntry returns a reference to a single object. readEntries
returns an array of references to as many as $maximum_number
objects. See get (above) for more information.
set_Entry (\entry, \@record)
Set the DN and attributes of the given Mozilla::LDAP::Entry object
from the given LDIF record. Return a reference to the entry.
get_LDIF (*FILEHANDLE, $eof, \&read_reference, $comments)
Read an LDIF record from the given file. Return an array of
strings, representing the record. Return a false value if end of
file is encountered before an LDIF record.
If *FILEHANDLE is not defined, read from *STDIN.
If $eof is passed, set it true if the end of the given file was
encountered; otherwise set it false. This function may set $eof
false and also return a record (if the record was terminated by the
end of file).
If \&read_reference is defined, call it when reading each reference
to another data source, with ${$_[$[]} equal to the reference. The
function should copy the referent (for example, the contents of the
named file) into $_[$[].
Ignore LDIF comment lines, unless $comments eq "comments".
unpack_LDIF ($string, \&read_reference, $comments)
Read one LDIF record from the given string. Return an array of
strings, representing the record. Return a false value if the
given string doesn't contain an LDIF record.
If \&read_reference is defined, call it when reading each reference
to another data source, with ${$_[$[]} equal to the reference. The
function should copy the referent (for example, the contents of the
named file) into $_[$[].
Ignore LDIF comment lines, unless $comments eq "comments".
read_v1 (\$url)
read_file_URL (\$url)
Change the parameter, from a reference to a URL (string) to a
string containing a copy of the contents of the file named by that
URL, and return true. Return false if the URL doesn't name a local
file, or the file can't be read.
This implements LDIF version 1, although it doesn't support URLs
that refer to anything but a local file (e.g. HTTP or FTP URLs).
read_v0 (\$name)
read_file_name (\$name)
Change the parameter, from a reference to a file name to a string
containing a copy of the contents of that file, and return true.
Return false if the file can't be read.
This implements LDIF version 0.
read_file_URL_or_name (\$url_or_name)
Change the parameter, from a reference to a URL or file name, to a
string containing a copy of the contents of the file it names, and
return true. Return false if the file can't be read.
Output
Mozilla::LDAP::LDIF->new(*FILEHANDLE, $options)
Create and return an object used to write LDIF to the given file.
$options are described below.
put $ldif (@record)
put $ldif (\@record, \object ...)
put_LDIF (*FILEHANDLE, $options, @record)
put_LDIF (*FILEHANDLE, $options, \@record, \object ...)
Write LDIF records to the given file. $options are described
below.
writeOneEntry $ldif (\entry)
writeEntries $ldif (\entry, \entry ...)
Write Mozilla::LDAP::Entry objects to the given file.
pack_LDIF ($options, @record)
pack_LDIF ($options, \@record, \object ...)
Return an LDIF string, representing the given records.
$options
The options parameter (above) may be either "undef", indicating all
default options, or a number, which is equivalent to "[max_line =>"
number"]", or a reference to an array that contains a list of
options, composed from:
"max_line =>" number
If number > 1, break output into continuation lines, so no line
is longer than number bytes (not counting the end-of-line
marker).
Default: 0 (output is not broken into continuation lines).
"encode =>" pattern
Base64 encode output values that match pattern. Warning: As a
rule, your pattern should match any value that contains an
output line separator (see the SEP option, below). If any such
value is not Base64 encoded, it will be output in a form that
does not represent the separator bytes in LDIF form. That is,
if the output is parsed as LDIF, the resulting value will be
like the original value, except the separator bytes will be
removed.
Default: "^[:< ]|[^ -\x7E]"
For example:
pack_LDIF ([encode=>"^ |[^ -\xFD]"], @record)
returns a string in which UTF-8 strings are not encoded (unless
they begin with a space or contain control characters) and
lines are not continued. Such a string may be easier to view
or edit than standard LDIF, although it's more prone to be
garbled when sent in email or processed by software designed
for ASCII. It can be parsed without loss of information (by
unpack_LDIF).
"sep =>" string
Output string at the end of each line.
Default: "\n" (the usual line separator, for output text).
output_separator ()
Return the standard LDIF line separator most similar to "\n". The
output option "[sep => output_separator()]" is recommended, if you
want to produce standard LDIF output.
Utilities
sort_attributes (@record)
sort_attributes (\@record, \object ...)
Return a record equivalent to each parameter, except with the
attributes sorted, primarily by attribute name (ignoring case) and
secondarily by attribute value (using &cmp). If the parameter list
is a single record, return a single record; otherwise return a list
of references to records.
enlist_values (@record)
enlist_values (\@record, \object ...)
Return a record equivalent to the parameter, except with values of
the same attribute type combined into a nested array. For example,
enlist_values (givenName => "Joe", givenname => "Joey", GivenName => "Joseph")
returns
(givenName => ["Joe", "Joey", "Joseph"])
If the parameter list is a single record, return a single record;
otherwise return a list of references to records.
delist_values (@record)
delist_values (\@record, \object ...)
Return a record equivalent to the parameter, except with all values
contained directly (not in a nested array). For example,
delist_values (givenName => ["Joe", "Joey", "Joseph"])
returns
(givenName => "Joe", givenName => "Joey", givenName => "Joseph")
If the parameter list is a single record, return a single record;
otherwise return a list of references to records.
references (@record)
references (\@record, \object ...)
In list context, return a list of references to each of the
references to external data sources, in the given records. In
scalar context, return the length of that list; that is, the total
number of references to external data sources.
LDIF_get_DN (@record)
get_DN (@record)
Return the DN of the given record. Return undef if the first
attribute of the record isn't a DN.
LDIF_get_DN (\@record, \object ...)
get_DN (\@record, \object ...)
Return the DN of each of the given records, as an array with one
element for each parameter. If a given record's first attribute
isn't a DN, the corresponding element of the returned array is
undef.
next_attribute (\@record, $offset, @options)
Return the offset of an attribute type in the given record. Search
forward, starting at $offset + 1, or 0 if $offset is not defined.
Return undef if no attribute is found. The @options list is
composed of zero or more of the following:
"name => "expression
"type => "expression
Don't return an offset unless the given expression evaluates to
TRUE, with $_ aliased to the attribute type name.
"value => "expression
Don't return an offset unless the given expression evaluates to
TRUE, with $_ aliased to one of the attribute values.
In either case, the expression may be a string, which is simply
evaluated (using eval), or a reference to a subroutine, which is
called with $_ as its only parameter. The value returned by eval
or the subroutine is taken as the result of evaluation.
If no options are given, the offset of the next attribute is
returned.
Option expressions can modify the record, since they are passed an
alias to an element of the record. An option can selectively
prevent the evaluation of subsequent options: options are evaluated
in the order they appear in the @options list, and if an option
evaluates to FALSE, subsequent options are not evaluated.
DIAGNOSTICS
$0 can't open %s: $!
(W) Mozilla::LDAP::LDIF::read_file_* failed to open a file,
probably named in an LDIF attrval-spec.
$0 non-LDIF line: %s
(D) The input contains a line that can't be parsed as LDIF. It is
carried along in place of an attribute name, with an undefined
value. For example, unpack_LDIF("abc") outputs this warning, and
returns ("abc", undef).
Can't use MIME::Base64
(F) The MIME::Base64 module isn't installed. To rectify this, get
a copy of MIME::Base64 from
http://www.perl.com/CPAN/modules/by-module/MIME/ and install it.
If you have trouble, try simply putting Base64.pm in a subdirectory
named MIME, in one of the directories named in @INC (site_perl is a
good choice). You'll get a correct, but relatively slow
implementation.
Useless use of %s in scalar or void context
(W) The function returns multiple records, of which all but the
last will be ignored by the caller. Time and space were wasted to
create them. It would probably be better to call the function in
list context, or to pass it only a single record.
EXAMPLES
use Mozilla::LDAP::LDIFqw(read_file_URL_or_name);
$in = Mozilla::LDAP::LDIF->new(*STDIN, \&read_file_URL_or_name);
$out = Mozilla::LDAP::LDIF->new(*STDOUT, 78);
@records = get $in (undef); # read to end of file (^D)
put $out (@records);
use Mozilla::LDAP::Conn();
$conn = Mozilla::LDAP::Conn->new(...);
while ($entry = readOneEntry $in) {
add $conn ($entry);
}
use Mozilla::LDAP::LDIF qw(get_LDIF put_LDIF
references read_v1 next_attribute sort_attributes);
while (@record = get_LDIF (*STDIN, $eof)) {
# Resolve all the file URLs:
foreach my $r (references (@record)) {
read_v1 ($$r);
}
# Capitalize all the attribute names:
for ($r = undef; defined ($r = next_attribute (\@record, $r)); ) {
$record[$r] = ucfirst $record[$r];
}
# Capitalize all the title values:
next_attribute (\@record, undef,
type => '"title" eq lc $_',
value => '$_ = ucfirst; 0');
# Sort the attributes and output the record, 78 characters per line:
put_LDIF (*STDOUT, 78, sort_attributes (@record));
last if $eof;
}
BUGS
Output Line Separator
Output lines are separated by "\n", by default. Although this
works well in many cases, it is not standard LDIF unless "\n" is
"\012" or "\015\012". It is not, on some platforms (Macintosh, for
example). To get standard output, use the output option "[sep =>
Mozilla::LDAP::LDIF::output_separator()]".
Input Line Separator
This package may fail to read standard LDIF correctly, if the input
record separator is not LF. To avoid this bug, set $/ = "\012".
Other values of $/ work less well: CR ($/ eq "\015") handles input
separated by CR or CR LF, but not LF alone; and CR LF ($/ eq
"\015\012") handles input separated by CR LF, but not LF alone.
This bug arises when handling standard LDIF received 'raw' via the
Internet (via HTTP, for example). There's no problem with an input
file that has been converted (as generic text) from standard
Internet line separators to $/ (that is, the usual line separator
for the local platform).
AUTHOR
John Kristian <kristian@netscape.com>
Thanks to Leif Hedstrom, from whose code I took ideas; and to the users
who took the trouble to correct my mistakes. But I accept all blame.
SEE ALSO
Mozilla::LDAP::Entry, Mozilla::LDAP::Conn, and of course Perl.
perl v5.18.1 2007-06-14 LDIF(3)
