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.
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
$_[$[].
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.
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.
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
$_[$[].
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
$_[$[].
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).
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.
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.
Base64 encode output values that match pattern. Warning: As a rule, your pattern should match any value that contains '\n'. If any such value is not Base64
encoded, it will be output in a form that does not represent the '\n' bytes
in LDIF form. That is, if the output is parsed as LDIF, the resulting value
will be like the original value, except the '\n' 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).
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.
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.
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.
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:
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.
(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).
(F) The MIME::Base64 module isn't installed, and Mozilla::LDAP::Utils can't
be used (as an inferior substitute). To rectify this, get a copy of
MIME::Base64 from http://www.perl.com/CPAN-local/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.
(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.
use Mozilla::LDAP::LDIF qw(read_file_URL_or_name);
$in = new Mozilla::LDAP::LDIF (*STDIN, \&read_file_URL_or_name);
$out = new Mozilla::LDAP::LDIF (*STDOUT, 78);
@records = get $in (undef); # read to end of file (^D)
put $out (@records);
use Mozilla::LDAP::Conn();
$conn = new Mozilla::LDAP::Conn (...);
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;
}