.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "LDIF 3pm"
.TH LDIF 3pm "2007-06-14" "perl v5.20.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mozilla::LDAP::LDIF \- read or write LDIF (LDAP Data Interchange Format)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\& 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, \e&read_reference, $comments);
\& @record = get $ldif;
\& @records = get $ldif ($maximum_number);
\& $entry = set_Entry (\eentry, \e@record);
\& $entry = readOneEntry $ldif;
\& @entries = readEntries $ldif ($maximum_number);
\&
\& $ldif = Mozilla::LDAP::LDIF\->new(*FILEHANDLE, $options);
\& $success = put $ldif (@record);
\& $success = put $ldif (\e@record, \eobject ...);
\& $success = writeOneEntry $ldif (\eentry);
\& $success = writeEntries  $ldif (\eentry, \eentry ...);
\&
\& @record = get_LDIF (*FILEHANDLE, $eof, \e&read_reference, $comments);
\& @record = get_LDIF; # *STDIN
\&
\& $success = put_LDIF (*FILEHANDLE, $options, @record);
\& $success = put_LDIF (*FILEHANDLE, $options, \e@record, \eobject ...);
\&
\& @record = unpack_LDIF ($string, \e&read_reference, $comments);
\&
\& $string = pack_LDIF ($options, @record);
\& $string = pack_LDIF ($options, \e@record, \eobject ...);
\&
\& @record = enlist_values (@record);
\& @record = delist_values (@record);
\&
\& @record = sort_attributes (@record);
\&
\& $DN  = LDIF_get_DN (@record); # alias get_DN
\& @DNS = LDIF_get_DN (\e@record, \eobject ...); # alias get_DN
\&
\& $offset = next_attribute (\e@record, $offset, @options);
\&
\& @references = references (@record);
\& @references = references (\e@record, \eobject ...);
\&
\& $success = read_v1 (\e$url);  # alias read_file_URL
\& $success = read_v0 (\e$name); # alias read_file_name
\& $success = read_file_URL_or_name (\e$url_or_name);
.Ve
.SH "REQUIRES"
.IX Header "REQUIRES"
MIME::Base64, Exporter, Carp
.SH "INSTALLATION"
.IX Header "INSTALLATION"
Put the \s-1LDIF\s0.pm file into a subdirectory named Mozilla/LDAP,
in one of the directories named in \f(CW@INC\fR.
site_perl is a good choice.
.SH "EXPORTS"
.IX Header "EXPORTS"
Nothing (unless you request it).
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\s-1LDIF\s0 version 1 is defined by \fI<draft\-good\-ldap\-ldif\-03>\fR.
An \s-1LDIF\s0 record like this:
.PP
.Vb 8
\&    DN: cn=Foo Bar, o=ITU
\&    cn: Foo Bar
\&    Sn: Bar
\&    objectClass: person
\&    objectClass: organizatio
\&     nalPerson
\&    jpegPhoto:< file:foobar.jpg
\&    # comment
.Ve
.PP
corresponds (in this module) to a Perl array like this:
.PP
.Vb 7
\&    (DN => "cn=Foo Bar, o=ITU",
\&     cn => "Foo Bar",
\&     Sn => "Bar",
\&     objectClass => [ "person", "organizationalPerson" ],
\&     jpegPhoto => \e"file:foobar.jpg",
\&     \*(Aq# comment\*(Aq, undef
\&    )
.Ve
.PP
URLs or file names are read by a separate function.
This module provides functions to read a file name (\s-1LDIF\s0 version 0)
or a file \s-1URL\s0 that names a local file (minimal \s-1LDIF\s0 version 1), or either.
You can supply a similar function to read other forms of \s-1URL.\s0
.PP
Most output and utility methods in this module accept a parameter list
that is either an \s-1LDIF\s0 array (the first item is a string, usually \*(L"dn\*(R"),
or a list of references, with each reference pointing to either
an \s-1LDIF\s0 array or an object from which this module can get \s-1LDIF\s0 arrays
by calling the object's \fBgetLDIFrecords\fR method.
This module calls \f(CW$object\fR\->\fIgetLDIFrecords()\fR, expecting it to
return a list of references to \s-1LDIF\s0 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 \fIgetLDIFrecords()\fR,
on any object.
.SH "METHODS"
.IX Header "METHODS"
.SS "Input"
.IX Subsection "Input"
.ie n .IP "\fBnew\fR Mozilla::LDAP::LDIF (*FILEHANDLE, \e&read_reference, $comments)" 4
.el .IP "\fBnew\fR Mozilla::LDAP::LDIF (*FILEHANDLE, \e&read_reference, \f(CW$comments\fR)" 4
.IX Item "new Mozilla::LDAP::LDIF (*FILEHANDLE, &read_reference, $comments)"
Create and return an object to read \s-1LDIF\s0 from the given file.
If *FILEHANDLE is not defined, return an object to read from *STDIN.
.Sp
If \e&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 \f(CW$_\fR[$[].
.Sp
Ignore \s-1LDIF\s0 comment lines, unless \f(CW$comments\fR eq \*(L"comments\*(R".
.ie n .IP "\fBget\fR $ldif" 4
.el .IP "\fBget\fR \f(CW$ldif\fR" 4
.IX Item "get $ldif"
Read an \s-1LDIF\s0 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 \s-1LDIF\s0 record.
.ie n .IP "\fBget\fR $ldif ($maximum_number)" 4
.el .IP "\fBget\fR \f(CW$ldif\fR ($maximum_number)" 4
.IX Item "get $ldif ($maximum_number)"
Read \s-1LDIF\s0 records from the given file, until end of file is encountered
or the given \f(CW$maximum_number\fR of records are read.
If \f(CW$maximum_number\fR 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 \s-1LDIF\s0 record,
or \f(CW$maximum_number\fR is zero.
.ie n .IP "\fBreadOneEntry\fR $ldif" 4
.el .IP "\fBreadOneEntry\fR \f(CW$ldif\fR" 4
.IX Item "readOneEntry $ldif"
.PD 0
.ie n .IP "\fBreadEntries\fR $ldif ($maximum_number)" 4
.el .IP "\fBreadEntries\fR \f(CW$ldif\fR ($maximum_number)" 4
.IX Item "readEntries $ldif ($maximum_number)"
.PD
Read Mozilla::LDAP::Entry objects from the given file, and
return references to them.
Call Mozilla::LDAP::Conn\->\fInewEntry()\fR to create each returned object.
Return a false value if end of file is encountered before an \s-1LDIF\s0 record,
or \f(CW$maximum_number\fR is zero.
\&\fBreadOneEntry\fR returns a reference to a single object.
\&\fBreadEntries\fR returns an array of references to as many as \f(CW$maximum_number\fR
objects.
See \fBget\fR (above) for more information.
.IP "\fBset_Entry\fR (\eentry, \e@record)" 4
.IX Item "set_Entry (entry, @record)"
Set the \s-1DN\s0 and attributes of the given Mozilla::LDAP::Entry object
from the given \s-1LDIF\s0 record.  Return a reference to the entry.
.ie n .IP "\fBget_LDIF\fR (*FILEHANDLE, $eof, \e&read_reference, $comments)" 4
.el .IP "\fBget_LDIF\fR (*FILEHANDLE, \f(CW$eof\fR, \e&read_reference, \f(CW$comments\fR)" 4
.IX Item "get_LDIF (*FILEHANDLE, $eof, &read_reference, $comments)"
Read an \s-1LDIF\s0 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 \s-1LDIF\s0 record.
.Sp
If *FILEHANDLE is not defined, read from *STDIN.
.Sp
If \f(CW$eof\fR is passed, set it true if the end of the given file was
encountered; otherwise set it false.
This function may set \f(CW$eof\fR false and also return a record
(if the record was terminated by the end of file).
.Sp
If \e&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 \f(CW$_\fR[$[].
.Sp
Ignore \s-1LDIF\s0 comment lines, unless \f(CW$comments\fR eq \*(L"comments\*(R".
.ie n .IP "\fBunpack_LDIF\fR ($string, \e&read_reference, $comments)" 4
.el .IP "\fBunpack_LDIF\fR ($string, \e&read_reference, \f(CW$comments\fR)" 4
.IX Item "unpack_LDIF ($string, &read_reference, $comments)"
Read one \s-1LDIF\s0 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 \s-1LDIF\s0 record.
.Sp
If \e&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 \f(CW$_\fR[$[].
.Sp
Ignore \s-1LDIF\s0 comment lines, unless \f(CW$comments\fR eq \*(L"comments\*(R".
.IP "\fBread_v1\fR (\e$url)" 4
.IX Item "read_v1 ($url)"
.PD 0
.IP "\fBread_file_URL\fR (\e$url)" 4
.IX Item "read_file_URL ($url)"
.PD
Change the parameter, from a reference to a \s-1URL \s0(string) to a string containing
a copy of the contents of the file named by that \s-1URL,\s0 and return true.
Return false if the \s-1URL\s0 doesn't name a local file, or the file can't be read.
.Sp
This implements \s-1LDIF\s0 version 1, although it doesn't support URLs that refer
to anything but a local file (e.g. \s-1HTTP\s0 or \s-1FTP\s0 URLs).
.IP "\fBread_v0\fR (\e$name)" 4
.IX Item "read_v0 ($name)"
.PD 0
.IP "\fBread_file_name\fR (\e$name)" 4
.IX Item "read_file_name ($name)"
.PD
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.
.Sp
This implements \s-1LDIF\s0 version 0.
.IP "\fBread_file_URL_or_name\fR (\e$url_or_name)" 4
.IX Item "read_file_URL_or_name ($url_or_name)"
Change the parameter, from a reference to a \s-1URL\s0 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.
.SS "Output"
.IX Subsection "Output"
.ie n .IP "Mozilla::LDAP::LDIF\->\fBnew\fR(*FILEHANDLE, $options)" 4
.el .IP "Mozilla::LDAP::LDIF\->\fBnew\fR(*FILEHANDLE, \f(CW$options\fR)" 4
.IX Item "Mozilla::LDAP::LDIF->new(*FILEHANDLE, $options)"
Create and return an object used to write \s-1LDIF\s0 to the given file.
\&\f(CW$options\fR are described below.
.ie n .IP "\fBput\fR $ldif (@record)" 4
.el .IP "\fBput\fR \f(CW$ldif\fR (@record)" 4
.IX Item "put $ldif (@record)"
.PD 0
.ie n .IP "\fBput\fR $ldif (\e@record, \eobject ...)" 4
.el .IP "\fBput\fR \f(CW$ldif\fR (\e@record, \eobject ...)" 4
.IX Item "put $ldif (@record, object ...)"
.ie n .IP "\fBput_LDIF\fR (*FILEHANDLE, $options, @record)" 4
.el .IP "\fBput_LDIF\fR (*FILEHANDLE, \f(CW$options\fR, \f(CW@record\fR)" 4
.IX Item "put_LDIF (*FILEHANDLE, $options, @record)"
.ie n .IP "\fBput_LDIF\fR (*FILEHANDLE, $options, \e@record, \eobject ...)" 4
.el .IP "\fBput_LDIF\fR (*FILEHANDLE, \f(CW$options\fR, \e@record, \eobject ...)" 4
.IX Item "put_LDIF (*FILEHANDLE, $options, @record, object ...)"
.PD
Write \s-1LDIF\s0 records to the given file.
\&\f(CW$options\fR are described below.
.ie n .IP "\fBwriteOneEntry\fR $ldif (\eentry)" 4
.el .IP "\fBwriteOneEntry\fR \f(CW$ldif\fR (\eentry)" 4
.IX Item "writeOneEntry $ldif (entry)"
.PD 0
.ie n .IP "\fBwriteEntries\fR  $ldif (\eentry, \eentry ...)" 4
.el .IP "\fBwriteEntries\fR  \f(CW$ldif\fR (\eentry, \eentry ...)" 4
.IX Item "writeEntries $ldif (entry, entry ...)"
.PD
Write Mozilla::LDAP::Entry objects to the given file.
.ie n .IP "\fBpack_LDIF\fR ($options, @record)" 4
.el .IP "\fBpack_LDIF\fR ($options, \f(CW@record\fR)" 4
.IX Item "pack_LDIF ($options, @record)"
.PD 0
.IP "\fBpack_LDIF\fR ($options, \e@record, \eobject ...)" 4
.IX Item "pack_LDIF ($options, @record, object ...)"
.PD
Return an \s-1LDIF\s0 string, representing the given records.
.ie n .IP "\fB\fB$options\fB\fR" 4
.el .IP "\fB\f(CB$options\fB\fR" 4
.IX Item "$options"
The options parameter (above) may be either
\&\f(CW\*(C`undef\*(C'\fR, indicating all default options, or
a number, which is equivalent to \f(CW\*(C`[max_line =>\*(C'\fR\fI number\fR\f(CW\*(C`]\*(C'\fR, or
a reference to an array that contains a list of options, composed from:
.RS 4
.ie n .IP """max_line =>""\fI number\fR" 4
.el .IP "\f(CWmax_line =>\fR\fI number\fR" 4
.IX Item "max_line => number"
If \fInumber\fR > 1, break output into continuation lines, so no line
is longer than \fInumber\fR bytes (not counting the end-of-line marker).
.Sp
Default: 0 (output is not broken into continuation lines).
.ie n .IP """encode =>""\fI pattern\fR" 4
.el .IP "\f(CWencode =>\fR\fI pattern\fR" 4
.IX Item "encode => pattern"
Base64 encode output values that match \fIpattern\fR.
Warning: As a rule, your \fIpattern\fR should match any value that contains
an output line separator (see the \s-1SEP\s0 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 \s-1LDIF\s0 form.
That is, if the output is parsed as \s-1LDIF,\s0 the resulting value will be
like the original value, except the separator bytes will be removed.
.Sp
Default: \f(CW"^[:< ]|[^ \-\ex7E]"\fR
.Sp
For example:
.Sp
.Vb 1
\&    pack_LDIF ([encode=>"^ |[^ \-\exFD]"], @record)
.Ve
.Sp
returns a string in which \s-1UTF\-8\s0 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 \s-1LDIF,\s0
although it's more prone to be garbled when sent in email
or processed by software designed for \s-1ASCII.\s0
It can be parsed without loss of information (by unpack_LDIF).
.ie n .IP """sep =>""\fI string\fR" 4
.el .IP "\f(CWsep =>\fR\fI string\fR" 4
.IX Item "sep => string"
Output \fIstring\fR at the end of each line.
.Sp
Default: \f(CW"\en"\fR (the usual line separator, for output text).
.RE
.RS 4
.RE
.IP "\fBoutput_separator\fR ()" 4
.IX Item "output_separator ()"
Return the standard \s-1LDIF\s0 line separator most similar to \*(L"\en\*(R".
The output option \f(CW\*(C`[sep => output_separator()]\*(C'\fR is recommended,
\&\fBif\fR you want to produce standard \s-1LDIF\s0 output.
.SS "Utilities"
.IX Subsection "Utilities"
.IP "\fBsort_attributes\fR (@record)" 4
.IX Item "sort_attributes (@record)"
.PD 0
.IP "\fBsort_attributes\fR (\e@record, \eobject ...)" 4
.IX Item "sort_attributes (@record, object ...)"
.PD
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.
.IP "\fBenlist_values\fR (@record)" 4
.IX Item "enlist_values (@record)"
.PD 0
.IP "\fBenlist_values\fR (\e@record, \eobject ...)" 4
.IX Item "enlist_values (@record, object ...)"
.PD
Return a record equivalent to the parameter, except with values of
the same attribute type combined into a nested array.  For example,
.Sp
.Vb 1
\&    enlist_values (givenName => "Joe", givenname => "Joey", GivenName => "Joseph")
.Ve
.Sp
returns
.Sp
.Vb 1
\&    (givenName => ["Joe", "Joey", "Joseph"])
.Ve
.Sp
If the parameter list is a single record, return a single record;
otherwise return a list of references to records.
.IP "\fBdelist_values\fR (@record)" 4
.IX Item "delist_values (@record)"
.PD 0
.IP "\fBdelist_values\fR (\e@record, \eobject ...)" 4
.IX Item "delist_values (@record, object ...)"
.PD
Return a record equivalent to the parameter, except with all values
contained directly (not in a nested array).  For example,
.Sp
.Vb 1
\&    delist_values (givenName => ["Joe", "Joey", "Joseph"])
.Ve
.Sp
returns
.Sp
.Vb 1
\&    (givenName => "Joe", givenName => "Joey", givenName => "Joseph")
.Ve
.Sp
If the parameter list is a single record, return a single record;
otherwise return a list of references to records.
.IP "\fBreferences\fR (@record)" 4
.IX Item "references (@record)"
.PD 0
.IP "\fBreferences\fR (\e@record, \eobject ...)" 4
.IX Item "references (@record, object ...)"
.PD
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.
.IP "LDIF_get_DN (@record)" 4
.IX Item "LDIF_get_DN (@record)"
.PD 0
.IP "get_DN (@record)" 4
.IX Item "get_DN (@record)"
.PD
Return the \s-1DN\s0 of the given record.
Return undef if the first attribute of the record isn't a \s-1DN.\s0
.IP "LDIF_get_DN (\e@record, \eobject ...)" 4
.IX Item "LDIF_get_DN (@record, object ...)"
.PD 0
.IP "get_DN (\e@record, \eobject ...)" 4
.IX Item "get_DN (@record, object ...)"
.PD
Return the \s-1DN\s0 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 \s-1DN,\s0
the corresponding element of the returned array is undef.
.ie n .IP "next_attribute (\e@record, $offset, @options)" 4
.el .IP "next_attribute (\e@record, \f(CW$offset\fR, \f(CW@options\fR)" 4
.IX Item "next_attribute (@record, $offset, @options)"
Return the offset of an attribute type in the given record.
Search forward, starting at \f(CW$offset\fR + 1, or 0 if \f(CW$offset\fR is not defined.
Return undef if no attribute is found.
The \f(CW@options\fR list is composed of zero or more of the following:
.RS 4
.ie n .IP """name => ""\fIexpression\fR" 4
.el .IP "\f(CWname => \fR\fIexpression\fR" 4
.IX Item "name => expression"
.PD 0
.ie n .IP """type => ""\fIexpression\fR" 4
.el .IP "\f(CWtype => \fR\fIexpression\fR" 4
.IX Item "type => expression"
.PD
Don't return an offset unless the given \fIexpression\fR evaluates to \s-1TRUE,\s0
with \f(CW$_\fR aliased to the attribute type name.
.ie n .IP """value => ""\fIexpression\fR" 4
.el .IP "\f(CWvalue => \fR\fIexpression\fR" 4
.IX Item "value => expression"
Don't return an offset unless the given \fIexpression\fR evaluates to \s-1TRUE,\s0
with \f(CW$_\fR aliased to one of the attribute values.
.RE
.RS 4
.Sp
In either case, the \fIexpression\fR may be a string, which is simply
evaluated (using \fBeval\fR), or
a reference to a subroutine, which is called with \f(CW$_\fR as its only parameter.
The value returned by \fBeval\fR or the subroutine is taken as the
result of evaluation.
.Sp
If no options are given, the offset of the next attribute is returned.
.Sp
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 \f(CW@options\fR list, and
if an option evaluates to \s-1FALSE,\s0 subsequent options are not evaluated.
.RE
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.ie n .IP "$0 can't open %s: $!" 4
.el .IP "\f(CW$0\fR can't open \f(CW%s:\fR $!" 4
.IX Item "$0 can't open %s: $!"
(W) Mozilla::LDAP::LDIF::read_file_* failed to open a file,
probably named in an \s-1LDIF\s0 attrval-spec.
.ie n .IP "$0 non-LDIF line: %s" 4
.el .IP "\f(CW$0\fR non-LDIF line: \f(CW%s\fR" 4
.IX Item "$0 non-LDIF line: %s"
(D) The input contains a line that can't be parsed as \s-1LDIF.\s0
It is carried along in place of an attribute name, with an undefined value.
For example, \fBunpack_LDIF\fR(\*(L"abc\*(R") outputs this warning, and returns (\*(L"abc\*(R", undef).
.IP "Can't use MIME::Base64" 4
.IX Item "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 \s-1MIME,\s0
in one of the directories named in \f(CW@INC\fR (site_perl is a good choice).
You'll get a correct, but relatively slow implementation.
.ie n .IP "Useless use of %s in scalar or void context" 4
.el .IP "Useless use of \f(CW%s\fR in scalar or void context" 4
.IX Item "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.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.Vb 1
\&    use Mozilla::LDAP::LDIF qw(read_file_URL_or_name);
\&
\&    $in  = Mozilla::LDAP::LDIF\->new(*STDIN, \e&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 (\e@record, $r)); ) {
\&            $record[$r] = ucfirst $record[$r];
\&        }
\&        # Capitalize all the title values:
\&        next_attribute (\e@record, undef,
\&                        type => \*(Aq"title" eq lc $_\*(Aq,
\&                        value => \*(Aq$_ = ucfirst; 0\*(Aq);
\&        # Sort the attributes and output the record, 78 characters per line:
\&        put_LDIF (*STDOUT, 78, sort_attributes (@record));
\&        last if $eof;
\&    }
.Ve
.SH "BUGS"
.IX Header "BUGS"
.IP "Output Line Separator" 4
.IX Item "Output Line Separator"
Output lines are separated by \*(L"\en\*(R", by default.
Although this works well in many cases, it is not standard \s-1LDIF\s0
unless \*(L"\en\*(R" is \*(L"\e012\*(R" or \*(L"\e015\e012\*(R".
It is not, on some platforms (Macintosh, for example).
To get standard output, use the output option
\&\f(CW\*(C`[sep => Mozilla::LDAP::LDIF::output_separator()]\*(C'\fR.
.IP "Input Line Separator" 4
.IX Item "Input Line Separator"
This package may fail to read standard \s-1LDIF\s0 correctly,
if the input record separator is not \s-1LF.\s0
To avoid this bug, set $/ = \*(L"\e012\*(R".
Other values of $/ work less well:
\&\s-1CR \s0($/ eq \*(L"\e015\*(R") handles input separated by \s-1CR\s0 or \s-1CR LF,\s0 but not \s-1LF\s0 alone;
and
\&\s-1CR LF \s0($/ eq \*(L"\e015\e012\*(R") handles input separated by \s-1CR LF,\s0 but not \s-1LF\s0 alone.
.Sp
This bug arises when handling standard \s-1LDIF\s0 received 'raw' via the Internet
(via \s-1HTTP,\s0 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).
.SH "AUTHOR"
.IX Header "AUTHOR"
John Kristian <kristian@netscape.com>
.PP
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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mozilla::LDAP::Entry, Mozilla::LDAP::Conn, and of course Perl.