Unix/Linux Go Back    


CentOS 7.0 - man page for mozilla::ldap::ldif (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


LDIF(3) 		       User Contributed Perl Documentation			  LDIF(3)

NAME
       Mozilla::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::LDIF qw(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.16.3				    2007-06-14					  LDIF(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 11:58 AM.