[Summary view] [Print] [Text view]

   1  =head1 NAME
   2  
   3  Net::LDAP::LDIF - LDIF reading and writing
   4  
   5  =head1 SYNOPSIS
   6  
   7   use Net::LDAP::LDIF;
   8  
   9   $ldif = Net::LDAP::LDIF->new( "file.ldif", "r", onerror => 'undef' );
  10   while( not $ldif->eof ( ) ) {
  11     $entry = $ldif->read_entry ( );
  12     if ( $ldif->error ( ) ) {
  13       print "Error msg: ", $ldif->error ( ), "\n";
  14       print "Error lines:\n", $ldif->error_lines ( ), "\n";
  15     } else {
  16       # do stuff
  17     }
  18   }
  19   $ldif->done ( );
  20  
  21  =head1 DESCRIPTION
  22  
  23  B<Net::LDAP::LDIF> provides a means to convert between
  24  L<Net::LDAP::Entry> objects and LDAP entries represented in LDIF
  25  format files. Reading and writing are supported and may manipulate
  26  single entries or lists of entries.
  27  
  28  As when reading an entire file into memory with perl normally, take
  29  into account the possibility of memory use when loading an LDIF file
  30  in one go.
  31  
  32  =head1 CONSTRUCTOR
  33  
  34  =over 4
  35  
  36  =item new ( FILE )
  37  
  38  Open the file read-only. C<FILE> may be the name of a file or an
  39  already open filehandle. If C<FILE> begins or ends with a C<|> then
  40  C<FILE> will be passed directly to C<open>.
  41  
  42  =item new ( FILE, MODE, OPTIONS )
  43  
  44  Open the file with the given C<MODE>, eg "w" or "a". C<FILE> may be
  45  the name of a file or an already open filehandle. If C<FILE> begins or
  46  ends with a C<|> then C<FILE> will be passed directly to C<open>.
  47  
  48  =over 4
  49  
  50  =item encode =E<gt> 'none' | 'canonical' | 'base64'
  51  
  52  Some DN values in LDIF cannot be written verbatim and have to be encoded
  53  in some way:
  54  
  55  =over 4
  56  
  57  =item 'none'
  58  
  59  The default.
  60  
  61  =item 'canonical'
  62  
  63  See L<Net::LDAP::Util/canonical_dn>.
  64  
  65  =item 'base64'
  66  
  67  Use base64.
  68  
  69  =back
  70  
  71  =item onerror =E<gt> 'die' | 'warn' | undef
  72  
  73  Specify what happens when an error is detected.
  74  
  75  =over 4
  76  
  77  =item 'die'
  78  
  79  C<Net::LDAP::LDIF> will croak with an appropriate message.
  80  
  81  =item 'warn'
  82  
  83  C<Net::LDAP::LDIF> will warn with an appropriate message.
  84  
  85  =item undef
  86  
  87  C<Net::LDAP::LDIF> will warn with an appropriate message if C<-w> is
  88  in effect.  The method that was called will return C<undef>.
  89  
  90  =back
  91  
  92  =item change =E<gt> 1
  93  
  94  Write entry changes to the LDIF file instead of the entries itself.
  95  I.e. write LDAP operations acting on the entries to the file instead of the entries contents.
  96  
  97  =item lowercase =E<gt> 1
  98  
  99  Convert attribute names to lowercase when writing.
 100  
 101  =item sort =E<gt> 1
 102  
 103  Sort attribute names when writing entries according to the rule:
 104  objectclass first then all other attributes alphabetically sorted
 105  
 106  =item version =E<gt> '1'
 107  
 108  Set the LDIF version to write to the resulting LDIF file.
 109  
 110  According to RFC 2849 currently the only legal value for this option is I<1>.
 111  
 112  When this option is set Net::LDAP::LDIF tries to adhere more strictly to the
 113  LDIF specification in RFC2489 in a few places.
 114  
 115  The default is I<undef> meaning no version information is written to the LDIF file.
 116  
 117  =item wrap =E<gt> 78
 118  
 119  Number of columns where output line wrapping shall occur.
 120  
 121  Default is 78. Setting it to 40 or lower inhibits wrapping.
 122  
 123  =item raw =E<gt> REGEX
 124  
 125  Use REGEX to denote the names of attributes that are to be considered
 126  binary in search results.
 127  
 128  When running on Perl 5.8 and this option is given Net::LDAP converts all
 129  values of attributes not matching this REGEX into Perl UTF-8 strings
 130  so that the regular Perl operators (pattern matching, ...) can operate
 131  as one expects even on strings with international characters.
 132  
 133  If this option is not given or the version of Perl Net::LDAP is running on
 134  is too old strings are encodeed the same as in earlier versions of perl-ldap.
 135  
 136  Example: raw =E<gt> qr/(?i:^jpegPhoto|;binary)/
 137  
 138  =back
 139  
 140  =back
 141  
 142  =head1 METHODS
 143  
 144  =over 4
 145  
 146  =item read_entry ( )
 147  
 148  Read one entry from the file and return it as a C<Net::LDAP::Entry>
 149  object.
 150  
 151  =item eof ( )
 152  
 153  Returns I<true> when the end of the file is reached.
 154  
 155  =item write_entry ( ENTRIES )
 156  
 157  Write the entries to the LDIF file.
 158  
 159  =item write_version ( )
 160  
 161  If the object's version is defined, this method allows to explicitely
 162  write the version before an entry is written.
 163  
 164  If  not called explicitely, it gets called automatically when writing
 165  the first entry.
 166  
 167  =item version ( [ VERSION ] )
 168  
 169  If called without arguments it returns the version of the LDIF file
 170  or undef if no version has been set.
 171  If called with an argument it sets the LDIF version to VERSION.
 172  
 173  According to RFC 2849 currently the only legal value for VERSION is I<1>.
 174  
 175  =item handle ( )
 176  
 177  Returns the file handle the C<Net::LDAP::LDIF> object reads from
 178  or writes to.
 179  
 180  =item done ( )
 181  
 182  This method signals that the LDIF object is no longer needed. If a
 183  file was opened automatically when the object was created it will be
 184  closed. This method is called automatically via DESTROY when the
 185  object goes out of scope.
 186  
 187  =item error ( )
 188  
 189  Returns error message if error was found.
 190  
 191  =item error_lines ( )
 192  
 193  Returns lines that resulted in error.
 194  
 195  =item current_entry ( )
 196  
 197  Returns the current C<Net::LDAP::Entry> object.
 198  
 199  =item current_lines ( )
 200  
 201  Returns the lines that generated the current C<Net::LDAP::Entry>
 202  object.
 203  
 204  =item next_lines ( )
 205  
 206  Returns the lines that will generate the next C<Net::LDAP::Entry>
 207  object.
 208  
 209  =back
 210  
 211  =head1 AUTHOR
 212  
 213  Graham Barr E<lt>gbarr@pobox.comE<gt>.
 214  
 215  Please report any bugs, or post any suggestions, to the perl-ldap
 216  mailing list E<lt>perl-ldap@perl.orgE<gt>.
 217  
 218  =head1 COPYRIGHT
 219  
 220  Copyright (c) 1997-2004 Graham Barr. All rights reserved. This program
 221  is free software; you can redistribute it and/or modify it under the
 222  same terms as Perl itself.
 223  
 224  =cut