Net::LDAP::LDIF - phpMan

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 LDAP entries represented in LDIF 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 LDIF file in one
    go.

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

    When Gisle Aas' LWP module package is installed, Net::LDAP::LDIF uses it
    to also support reading data from the URL 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".

                Note this value is the string 'undef', not the "undef"
                value.

        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.

        In scalar mode, the "Net::LDAP::Entry" object is returned alone,
        while in list mode a list is returned consisting of the
        "Net::LDAP::Entry" object as first element followed by all
        "Net::LDAP::Control" objects that were part of the LDIF entry. See
        RFC 2849 for details.

    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 AT pobox.com>.

    Please report any bugs, or post any suggestions, to the perl-ldap
    mailing list <perl-ldap AT 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.