From: Chris R. <chr...@us...> - 2003-08-01 19:00:42
|
Update of /cvsroot/perl-ldap/ldap/lib/Net/LDAP In directory sc8-pr-cvs1:/tmp/cvs-serv17959 Modified Files: Entry.pod Log Message: Updated documentation style. Index: Entry.pod =================================================================== RCS file: /cvsroot/perl-ldap/ldap/lib/Net/LDAP/Entry.pod,v retrieving revision 1.11 retrieving revision 1.12 diff -u -d -r1.11 -r1.12 --- Entry.pod 7 May 2003 10:57:16 -0000 1.11 +++ Entry.pod 1 Aug 2003 19:00:39 -0000 1.12 @@ -4,64 +4,64 @@ =head1 SYNOPSIS - use Net::LDAP; + use Net::LDAP; - $ldap = Net::LDAP->new($host); - $mesg = $ldap->search(@search_args); + $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"; - } - } + 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 + # or - use Net::LDAP::Entry; + use Net::LDAP::Entry; - $entry = Net::LDAP::Entry->new; + $entry = Net::LDAP::Entry->new; - $entry->add( - attr1 => 'value1', - attr2 => [qw(value1 value2)] - ); + $entry->add ( + attr1 => 'value1', + attr2 => [ qw(value1 value2) ] + ); - $entry->delete( 'unwanted' ); + $entry->delete ( 'unwanted' ); - $entry->replace( - attr1 => 'newvalue' - attr2 => [qw(new values)] - ); + $entry->replace ( + attr1 => 'newvalue' + attr2 => [ qw(new values) ] + ); - $entry->update( $ldap ); # update directory server + $entry->update ( $ldap ); # update directory server - $entry2 = $entry->clone; # copies entry + $entry2 = $entry->clone; # copies entry =head1 DESCRIPTION -The B<Net::LDAP::Entry> object represents a single entry in the directory. -It is a container for attribute-value pairs. +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. +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. +entry. Entries for this purpose can also be created by reading an LDIF +file with the L<Net::LDAP::LDIF> module. =head1 CONSTRUCTORS =over 4 -=item new +=item new ( ) Create a new entry object with the changetype set to C<'add'> -=item clone +=item clone ( ) Returns a copy of the B<Net::LDAP::Entry> object. @@ -71,36 +71,31 @@ =over 4 +=item add ( ATTR =E<gt> VALUE, ... ) +Add more attributes or values to the entry. Each C<VALUE> should be a +string if only a single value is wanted in the attribute, or a +reference to an array of strings if multiple values are wanted. The +values given will be added to the values which already exist for the +given attributes. -=item add ( ATTR =E<gt> VALUE [, ATTR2 =E<gt> 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. - + $entry->add ( 'sn' => 'Barr' ); + $entry->add ( 'street' => [ '1 some road','nowhere' ] ); -=item attributes ( [ OPTIONS ] ) +B<NOTE>: these changes are local to the client and will not appear on +the directory server until the C<update> method is called. -Return a list of attributes that this entry has. +=item attributes ( OPTIONS ) -OPTIONS is a list of name/value pairs, valid options are :- +Return a list of attributes in this entry =over 4 -=item nooptions +=item nooptions =E<gt> 1 -If TRUE, return a list of the attribute names excluding any options. For example for the entry +Return a list of the attribute names excluding any options. For +example for the entry name: Graham Barr name;en-us: Bob @@ -108,10 +103,10 @@ then - @values = $entry->attributes() + @values = $entry->attributes; print "default: @values\n"; - @values = $entry->attributes( nooptions => 1); + @values = $entry->attributes ( nooptions => 1 ); print "nooptions: @values\n"; will output @@ -121,15 +116,17 @@ =back +=item changetype ( ) +Returns the type of operation that would be performed when the update +method is called. -=item changetype ( [ TYPE ] ) +=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. +Set the type of operation that will be performed when the update +method is called to C<TYPE>. -Possible values for TYPE are +Possible values for C<TYPE> are =over 4 @@ -140,144 +137,134 @@ =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. +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. +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. +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 ( ) +Delete the entry from the server on the next call to C<update>. -=item delete ( ATTR [ =E<gt> VALUE [, ATTR2 =E<gt> VALUE2... ]] ) +=item delete ( ATTR =E<gt> [ VALUE, ... ], ... ) Delete the values of given attributes from the entry. Values are references to arrays; passing a reference to an empty array is the -same as passing undef, and will result in the entire attribute being -deleted. If no attributes are passed then the next call to update will -cause the entry to be deleted from the server. For example: - - $entry->delete( 'mail' => [ 'fo...@ex...' ] ); - $entry->delete( 'description' => [ ], 'streetAddress' => [ ] ); - -B<NOTE>: these changes are local to the client and will not -appear on the directory server until the C<update> method -is called. +same as passing C<undef>, and will result in the entire attribute +being deleted. For example: + $entry->delete ( 'mail' => [ 'fo...@ex...' ] ); + $entry->delete ( 'description' => [ ], 'streetAddress' => [ ] ); +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 ] ) +=item 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. +Get the DN of the entry. -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 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 ] ) +Returns C<TRUE> if the entry has an attribute called C<ATTR>. -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. +=item get_value ( ATTR, OPTIONS ) -The return value may be changed by OPTIONS, which is a list of name -=E<gt> value pairs, valid options are :- +Get the values for the attribute C<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. =over 4 -=item alloptions +=item alloptions =E<gt> 1 -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 +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 + 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); + $ref = $entry->get_value ( 'name', alloptions => 1 ); will return a hash reference that would be like - { - '' => [ 'Graham Barr' ], - ';en-us' => [ 'Bob' ] - } + { + '' => [ 'Graham Barr' ], + ';en-us' => [ 'Bob' ] + } -=item asref +=item asref =E<gt> 1 -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. +The result will be a reference to an array containing all the values +for the attribute, or C<undef> if the attribute does not exist. - $scalar = $entry->get_value('name'); + $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. +$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 = $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> +$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 =E<gt> VALUE [, ATTR2 =E<gt> VALUE2 ... ] ) - -Similar to add, except that the values given will replace -any values that already exist for the given attributes. +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. -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 replace ( ATTR =E<gt> VALUE, ... ) +Similar to C<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. +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. +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. +C<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. +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 @@ -290,14 +277,14 @@ Graham Barr E<lt>gb...@po...E<gt>. -Please report any bugs, or post any suggestions, to the perl-ldap mailing list -E<lt>per...@pe...E<gt>. +Please report any bugs, or post any suggestions, to the perl-ldap +mailing list E<lt>per...@pe...E<gt>. =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. +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> |