Net::LDAP::LDIF (3)

Leading comments

Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)

Standard preamble:
========================================================================

(The comments found at the beginning of the groff file "man3/Net::LDAP::LDIF.3pm".)

NAME

Net::LDAP::LDIF - LDIF reading and writing

SYNOPSIS

 use Net::LDAP::LDIF;

 $ldif = Net::LDAP::LDIF->new( "file.ldif", "r", onerror => 'undef' );
 while ( not $ldif->eof ( ) ) {
   $entry = $ldif->read_entry ( );
   if ( $ldif->error ( ) ) {
     print "Error msg: ", $ldif->error ( ), "\n";
     print "Error lines:\n", $ldif->error_lines ( ), "\n";
   } else {
     # do stuff
   }
 }
 $ldif->done ( );

DESCRIPTION

Net::LDAP::LDIF provides a means to convert between Net::LDAP::Entry objects and entries represented in format files. Reading and writing are supported and may manipulate single entries or lists of entries.

As when reading an entire file into memory with perl normally, take into account the possibility of memory use when loading an

file in one go.

SPECIAL FEATURES

By default, Net::LDAP::LDIF supports reading attribute values from URLs of type "file://".

When Gisle Aas'

module package is installed, Net::LDAP::LDIF uses it to also support reading data from the types supported by these modules; most prominently "http://", "https://", and "ftp://" resources. This extended feature is dynamically detected at runtime.

CONSTRUCTOR

new (

FILE

[[,

MODE

],

OPTIONS

] )

Open the file with the given mode.

"FILE" may be the name of a file or an already open filehandle. If "FILE" begins or ends with a "|" then "FILE" will be passed directly to "open".

"MODE" can be any of the modes allowed for Perl's open() function, potentially extended by PerlIO layers as described in perlopentut. Alternatively, it can be one of the mode indicators "r", "r+", "w", "w+", "a", "a+" known from C's fopen() function, which get mapped to their Perl counterparts. If "MODE" is omitted, it defaults to "r" for reading.

"OPTIONS" is a list of name/value pairs, recognizing:

encode => 'none' | 'canonical' | 'base64'

Some

DN

values in

LDIF

cannot be written verbatim and have to be encoded in some way:

'none'

The default.

'canonical'

See ``canonical_dn'' in Net::LDAP::Util.

'base64'

Use base64.

onerror => 'die' | 'warn' | undef

Specify what happens when an error is detected.

'die'

"Net::LDAP::LDIF" will croak with an appropriate message.

'warn'

"Net::LDAP::LDIF" will warn with an appropriate message.

undef

"Net::LDAP::LDIF" will warn with an appropriate message if "-w" is in effect. The method that was called will return "undef".

change => 1

Write entry changes to the

LDIF

file instead of the entries itself. I.e. write

LDAP

operations acting on the entries to the file instead of the entries contents.

lowercase => 1

Convert attribute names to lowercase when writing.

sort => 1

Sort attribute names when writing entries according to the rule: objectclass first then all other attributes alphabetically sorted

version => '1'

Set the

LDIF

version to write to the resulting

LDIF

file.

According to

RFC 2849

currently the only legal value for this option is 1.

When this option is set Net::LDAP::LDIF tries to adhere more strictly to the

LDIF

specification in

RFC2489

in a few places.

The default is undef meaning no version information is written to the

LDIF

file.

wrap => 78

Number of columns where output line wrapping shall occur.

Default is 78. Setting it to 40 or lower inhibits wrapping.

raw =>

REGEX

Use

REGEX

to denote the names of attributes that are to be considered binary when reading.

When this option is given, Net::LDAP converts all values of attributes not matching this

REGEX

into Perl

UTF-8

strings so that the regular Perl operators (pattern matching, ...) can operate as one expects even on strings with international characters.

If this option is not given, attribute values are treated as byte strings.

Example: raw => qr/(?i:^jpegPhoto|;binary)/

METHODS

read_entry ( )

Read one entry from the file and return it as a "Net::LDAP::Entry" object.

eof ( )

Returns true when the end of the file is reached.

write_entry (

ENTRY

[,

OPTIONS

], ... )

Write entries to the

LDIF

file.

The arguments accepted are a list of entries, optionally interspersed with options belonging to the preceding entry.

For each entry, "OPTIONS" is a list of key-value pairs, recognizing:

control =>

CONTROL

control => [

CONTROL, ...

]

See ``

CONTROLS''

in Net::LDAP.

write_version ( )

If the object's version is defined, this method allows one to explicitly write the version before an entry is written.

If not called explicitly, it gets called automatically when writing the first entry.

version ( [

VERSION

] )

If called without arguments it returns the version of the

LDIF

file or undef if no version has been set. If called with an argument it sets the

LDIF

version to

VERSION.

According to

RFC 2849

currently the only legal value for

VERSION

is 1.

handle ( )

Returns the file handle the "Net::LDAP::LDIF" object reads from or writes to.

done ( )

This method signals that the

LDIF

object is no longer needed. If a file was opened automatically when the object was created it will be closed. This method is called automatically via

DESTROY

when the object goes out of scope.

error ( )

Returns error message if error was found.

error_lines ( )

Returns lines that resulted in error.

current_entry ( )

Returns the current "Net::LDAP::Entry" object.

current_lines ( )

Returns the lines that generated the current "Net::LDAP::Entry" object.

next_lines ( )

Returns the lines that will generate the next "Net::LDAP::Entry" object.

AUTHOR

Graham Barr <gbarr@pobox.com>.

Please report any bugs, or post any suggestions, to the perl-ldap mailing list <perl-ldap@perl.org>.

COPYRIGHT

Copyright (c) 1997-2004 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.