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

lib/Net/LDAP/Schema.pod

@@ -0,0 +1,265 @@
+=head1 NAME
+
+Net::LDAP::Schema - Load and manipulate an LDAP v3 Schema
+
+=head1 SYNOPSIS
+
+ use Net::LDAP;
+ use Net::LDAP::Schema;
+
+ #
+ # Read schema from server
+ #
+ $ldap = Net::LDAP->new( $server );
+ $ldap->bind();
+ $schema = $ldap->schema();
+
+ #
+ # Load from LDIF
+ #
+ $schema = Net::LDAP::Schema->new;
+ $schema->parse( "schema.ldif" ) or die $schema->error;
+
+=head1 DESCRIPTION
+
+B<Net::LDAP::Schema> provides a means to load an LDAP schema and query it
+for information regarding supported objectclasses, attributes and syntaxes.
+
+=head1 METHODS
+
+Where a method is stated as taking the 'name or oid' of a schema item (which
+may be an object class, attribute or syntax) then a case-insensitive name
+or raw oid (object identifier, in dotted numeric string form, e.g. 2.5.4.0)
+may be supplied.
+
+=over 4
+
+=item attributes
+
+With no arguments, returns a list of the names all attributes in the schema.
+
+  @atts = $schema->attributes();
+
+If called with an argument which is the name or oid of a known object class,
+returns a list of the attributes which may (or must) be present in the OC.
+
+  @person_atts = $schema->attributes( "person" );
+
+Return value is an array or array reference depending on calling context, or
+empty list on error.
+
+=item ditstructurerules
+
+Returns a list of the names of all ditstructurerules in the schema.
+
+  @dts = $schema->ditstructurerules();
+
+Return value is an array or array reference depending on calling context.
+
+=item ditcontentrules
+
+Returns a list of the names of all ditcontentrules in the schema.
+
+  @dtc = $schema->ditcontentrules();
+
+Return value is an array or array reference depending on calling context.
+
+=item dump
+
+Given an argument which is the name of a file, and the file or
+directory has write permission, will dump the raw schema 
+information to a file.  If no argument is given the raw schema 
+information is dumped to standard out.
+
+  $result = $schema->dump( "./schema.dump" );
+
+  or
+
+  $result = $schema->dump();
+
+If no schema data is returned from directory server, the method
+will return undefined.  Otherwise a value of 1 is always returned.
+
+=item error
+
+Returns the last error encountered.
+
+=item is_objectclass, is_attribute, is_syntax, is_matchingrule
+
+Given the name or oid of a schema item (object class, attribute, 
+syntax or matchingrule respectively) returns the assoicated OID 
+or undef if the name or oid is not of the appropriate type.
+
+  # Is foo a known OC?
+  $oid = $schema->is_objectclass( "foo" );
+  # No? Bale out.
+  die( "Not an objectclass" ) unless $oid;
+  # Yes...so we can do this
+  @must = $schema->must( $oid );
+
+
+=item is_matchingruleuse, is_ditstructurerule, is_ditcontentrule, is_nameform
+
+Given the name or oid of a schema item (matchingruleuse, ditstructurerule, 
+ditcontentrule or nameform respectively) returns the assoicated OID 
+or undef if the name or oid is not of the appropriate type.
+
+  # Is foo a known OC?
+  $oid = $schema->is_nameform( "foo" );
+  # No? Bale out.
+  die( "Not a nameform" ) unless $oid;
+
+=item item
+
+Given two arguments, first of which is the name or oid of a known
+object class or attribute and second of which is the name of the
+item, returns the item's data value.  The item's value may be 
+undefined.
+
+  @item = $schema->item( $oid, "desc" );
+
+Return value is an array or a value depending on calling context.
+
+If the first argument is a name and there is more than one item in the
+schema with that name then undef, or the empty list, will be returned.
+
+=item items
+
+Given an argument which is the name or oid of a known object class or 
+attribute, returns the items available for this attribute or object class.
+The returned item name may have an undefined value.
+
+  @items = $schema->items( $oid );
+
+Return value is a list or array reference depending on calling context.
+
+If the argument given is a name and there is more than one item in the
+schema with that name then undef, or the empty list, will be returned.
+
+=item matchingrules
+
+Returns a list of the names of all matchingrules in the schema.
+
+  @mrs = $schema->matchingrules();
+
+Return value is an array or array reference depending on calling context.
+
+=item matchingruleuse
+
+Returns a list of the names of all matchingruleuse in the schema.
+
+  @mru = $schema->matchingruleuse();
+
+Return value is an array or array reference depending on calling context.
+
+=item may
+
+Given an argument which is the name or oid of a known object class, returns
+the name of the attributes which are optional in the class.
+
+  @may = $schema->may( $oc );
+
+Return value is an array or array reference depending on calling context.
+
+=item must
+
+Given an argument which is the name or oid of a known object class, returns
+the name of the attributes which are mandatory in the class
+
+  @must = $schema->must( $oc );
+
+Return value is an array or array reference depending on calling context.
+
+=item name
+
+Given an argument which is the name or oid of an item,
+returns the items canonical name or undef if the name or oid is not known.
+
+If the argument given is a name and there is more than one item in the
+schema with that name then undef will be returned.
+
+=item name2oid
+
+Given the name of a schema item (object class, attribute or syntax) returns
+the assoicated OID or undef if it is not recognised.
+
+It is possible that two objects, of different types, have the same name.
+In this case C<name2oid> will return a list of OIDs in an array context.
+In a scalar context it will return undef if there is more than one object
+with the given name.
+
+=item nameforms
+
+Returns a list of the names of all nameforms in the schema.
+
+  @nfm = $schema->nameforms();
+
+Return value is an array or array reference depending on calling context.
+
+=item objectclasses
+
+Returns a list of the names of all objectclasses in the schema.
+
+  @ocs = $schema->objectclasses();
+
+Return value is an array or array reference depending on calling context.
+
+=item parse
+
+Takes a single argument which can be any of, A message objected returned from
+an LDAP search, a Net::LDAP::Entry object or the name of a file containing
+an LDIF form of the schema.
+
+If the argument is a message result from a search, Net::LDAP::Schema will parse
+the schema from the first entry returned.
+
+Returns true on success and C<undef> on error.
+
+=item superclass
+
+Given an argument which is the name or oid of a known objectclass, returns
+the list of names of the immediate superclasses.
+
+=item syntax
+
+Given an argument which is the name or oid of a known attribute, returns the
+name of the attribute's syntax (or the syntax of the attributes superior
+if the syntax is inherited).
+
+  $name_syntax = $schema->syntax( "commonName" );
+
+=item syntaxes
+
+Returns a list of the names of all ldapSyntaxes in the schema. (The name of
+a syntax is not well defined. It may be an OID or abbreviated description).
+
+  @syns = $schema->syntaxes();
+
+Return value is an array or array reference depending on calling context.
+
+=back
+
+=head1 SEE ALSO
+
+L<Net::LDAP>,
+L<Net::LDAP::RFC>
+
+=head1 AUTHORS
+
+Graham Barr <gbarr@pobox.com>
+John Berthels <jjb@nexor.co.uk>
+
+Please report any bugs, or post any suggestions, to the perl-ldap mailing list
+<perl-ldap-dev@lists.sourceforge.net>.
+
+=head1 COPYRIGHT
+
+Copyright (c) 1998-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