Net::LDAP::LDIF(3)

💖 NAME 💖

Net::LDAP::LDIF — LDIF reading and writing. Yup bestie, this is the Net::LDAP::LDIF(3) page in User Contributed Perl Documentation, and we're about to make LDIF make sense. 💅

✨ SYNOPSIS ✨

Okay so here's the example, and yes the code stays exactly as it is because code is sacred:

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 gives you a way to convert between Net::LDAP::Entry objects and LDAP entries represented in LDIF format files. Reading and writing are both supported, and it can manipulate single entries or lists of entries. Obsessed.

Also, heads up: just like when you read an entire file into memory with perl normally, take into account the possibility of memory use when loading an LDIF file in one go. No cap, that's the memory vibe check. 😭

🦋 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. Literally detected at runtime, iykyk. ✨

🎀 CONSTRUCTOR 🎀

new ( FILE [[, MODE ], OPTIONS ] )

Open the file with the given mode. Cute. Here's the breakdown:

• 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. Yes, that's a pipe vibe.
• 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. Bestie, read that twice.
• 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 👑

The icon behind this is 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.

---

Bestie, that's the whole Net::LDAP::LDIF(3) manual page. Source/version: perl v5.42.0; date: 2024-01-02. Mwah 💋✨