=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
