Added Net::LDAP to the distribution for easier installs.

lib/Net/LDAP/Entry.pod

@@ -0,0 +1,295 @@
+=head1 NAME
+
+Net::LDAP::Entry - An LDAP entry object
+
+=head1 SYNOPSIS
+
+  use Net::LDAP;
+
+  $ldap = Net::LDAP->new($host);
+  $mesg = $ldap->search(@search_args);
+
+  my $max = $mesg->count;
+  for($i = 0 ; $i < $max ; $i++) {
+    my $entry = $mesg->entry($i);
+    foreach my $attr ($entry->attributes) {
+      print join("\n ",$attr, $entry->get_value($attr)),"\n";
+    }
+  }
+
+  # or
+
+  use Net::LDAP::Entry;
+  
+  $entry = Net::LDAP::Entry->new;
+  
+  $entry->add(
+    attr1 => 'value1',
+    attr2 => [qw(value1 value2)]
+  );
+  
+  $entry->delete( 'unwanted' );
+  
+  $entry->replace(
+    attr1 => 'newvalue'
+    attr2 => [qw(new values)]
+  );
+  
+  $entry->update( $ldap ); # update directory server
+
+=head1 DESCRIPTION
+
+The B<Net::LDAP::Entry> object represents a single entry in the directory.
+It is a container for attribute-value pairs.
+
+A B<Net::LDAP::Entry> object can be used in two situations. The first and
+probably most common use is in the result of a search to the directory
+server.
+
+The other is where a new object is created locally and then a single
+command is sent to the directory server to add, modify or replace an
+entry. Entries for this purpose can also be created by reading an
+LDIF file with the L<Net::LDAP::LDIF> module.
+
+=head1 CONSTRUCTOR
+
+=over 4
+
+=item new
+
+Create a new entry object with the changetype set to C<'add'>
+
+=back
+
+=head1 METHODS
+
+=over 4
+
+
+
+=item add ( ATTR => VALUE [, ATTR2 => VALUE2 ... ] )
+
+Add one or more new attributes to the entry. Each value
+must be a scalar variable or a reference to an array. The
+values given will be added to the values which already exist
+for the given attributes.
+
+  $entry->add( 'sn' => 'Barr');
+
+  $entry->add( 'street' => [ '1 some road','nowhere']);
+
+B<NOTE>: these changes are local to the client and will not
+appear on the directory server until the C<update> method
+is called.
+
+
+
+=item attributes ( [ OPTIONS ] )
+
+Return a list of attributes that this entry has.
+
+OPTIONS is a list of name/value pairs, valid options are :-
+
+=over 4
+
+=item nooptions
+
+If TRUE, return a list of the attribute names excluding any options. For example for the entry
+
+  name: Graham Barr
+  name;en-us: Bob
+  jpeg;binary: **binary data**
+
+then
+
+  @values = $entry->attributes()
+  print "default: @values\n";
+
+  @values = $entry->attributes( nooptions => 1);
+  print "nooptions: @values\n";
+
+will output
+
+  default: name name;en-us jpeg;binary
+  nooptions: name jpeg
+
+=back
+
+
+
+=item changetype ( [ TYPE ] )
+
+If called without arguments it returns the type of operation that would
+be performed when the update method is called. If called with an argument
+it will set the changetype to TYPE.
+
+Possible values for TYPE are
+
+=over 4
+
+=item add
+
+The update method will call the add method on the client object, which
+will result in the entry being added to the directory server.
+
+=item delete
+
+The update method will call the delete method on the client object, which
+will result in the entry being removed from the directory server.
+
+=item modify
+
+The update method will call the modify method on the client object, which
+will result in any changes that have been made locally being made to the
+entry on the directory server.
+
+=item moddn/modrdn
+
+The update method will call the moddn method on the client object, which
+will result in any DN changes that have been made locally being made
+to the entry on the directory server. These DN changes are specified by
+setting the entry attributes newrdn, deleteoldrdn, and (optionally) newsuperior.
+
+=back
+
+
+
+=item delete ( [ ATTR [, ATTR2 ... ]] )
+
+Delete the given attributes from the entry. If no attributes
+are passed then the next call to update will cause the entry
+to be deleted from the server.
+
+B<NOTE>: these changes are local to the client and will not
+appear on the directory server until the C<update> method
+is called.
+
+
+
+=item dn ( [ DN ] )
+
+Set or get the DN for the entry. With no arguments C<dn> will return
+the current DN. If an argument is given then it will change the DN
+for the entry and return the previous value.
+
+B<NOTE>: these changes are local to the client and will not
+appear on the directory server until the C<update> method
+is called.
+
+
+
+=item exists ( ATTR )
+
+Returns TRUE if the entry has an attribute called ATTR.
+
+
+
+=item get_value ( ATTR [, OPTIONS ] )
+
+Get the values for the attribute ATTR. In a list context returns all
+values for the given attribute, or the empty list if the attribute does
+not exist. In a scalar context returns the first value for the attribute
+or undef if the attribute does not exist.
+
+The return value may be changed by OPTIONS, which is a list of name => value
+pairs, valid options are :-
+
+=over 4
+
+=item alloptions
+
+If TRUE then the result will be a hash reference. The keys of the hash
+will be the options and the hash value will be the values for those attributes.
+For example if an entry had
+
+  name: Graham Barr
+  name;en-us: Bob
+
+Then a get for attribute "name" with alloptions set to a true value
+
+  $ref = $entry->get_value( 'name', alloptions => 1);
+
+will return a hash reference that would be like
+
+  {
+    ''       => [ 'Graham Barr' ],
+    ';en-us' => [ 'Bob' ]
+  }
+
+=item asref
+
+If TRUE then the result will be a reference to an array containing all the
+values for the attribute, or undef if the attribute does not exist.
+
+  $scalar = $entry->get_value('name');
+  
+$scalar will be the first value for the C<name> attribute, or C<undef> if the
+entry does not contain a C<name> attribute.
+
+  $ref    = $entry->get_value('name', asref => 1);
+
+$ref will be a reference to an array, which will have all the values for
+the C<name> attribute. If the entry does not have an attribute called C<name>
+then $ref will be C<undef>
+
+=back
+
+B<NOTE>: In the interest of performance the array references returned by C<get_value>
+are references to structures held inside the entry object. These values and
+thier contents should B<NOT> be modified directly.
+
+
+
+=item replace ( ATTR => VALUE [, ATTR2 => VALUE2 ... ] )
+
+Similar to add, except that the values given will replace
+any values that already exist for the given attributes.
+
+B<NOTE>: these changes are local to the client and will not
+appear on the directory server until the C<update> method
+is called.
+
+
+
+=item update ( CLIENT )
+
+Update the directory server with any changes that have been made locally
+to the attributes of this entry. This means any calls that have been
+made to add, replace or delete since the last call to changetype or
+update was made.
+
+This method can also be used to modify the DN of the entry on the server,
+by specifying moddn or modrdn as the changetype, and setting the entry 
+attributes newrdn, deleteoldrdn, and (optionally) newsuperior.
+
+CLIENT is a C<Net::LDAP> object where the update will be sent to.
+
+The result will be an object of type
+L<Net::LDAP::Message> as returned by the add, modify
+or delete method called on CLIENT.
+
+=back
+
+=head1 SEE ALSO
+
+L<Net::LDAP>,
+L<Net::LDAP::LDIF>
+
+=head1 AUTHOR
+
+Graham Barr <gbarr@pobox.com>.
+
+Please report any bugs, or post any suggestions, to the perl-ldap mailing list
+<perl-ldap-dev@lists.sourceforge.net>.
+
+=head1 COPYRIGHT
+
+Copyright (c) 1997-2000 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.
+
+=for html <hr>
+
+I<$Id$>
+
+=cut