=encoding utf8

=head1 NAME

XML::Compile::Schema::NameSpaces - Connect name-spaces from schemas

=head1 SYNOPSIS

 # Used internally by XML::Compile::Schema
 my $nss = XML::Compile::Schema::NameSpaces->new;
 $nss->add($schema);

=head1 DESCRIPTION

This module keeps overview on a set of namespaces, collected from various
schema files.  Per XML namespace, it will collect a list of fragments
which contain definitions for the namespace, each fragment comes from a
different source.  These fragments are searched in reverse order when
an element or type is looked up (the last definitions overrule the
older definitions).

=head1 METHODS

=head2 Constructors

=over 4

=item $obj-E<gt>B<new>(%options)

=back

=head2 Accessors

=over 4

=item $obj-E<gt>B<add>( $schema, [$schemas] )

Add L<XML::Compile::Schema::Instance|XML::Compile::Schema::Instance> objects to the internal
knowledge of this object.

=item $obj-E<gt>B<allSchemas>()

Returns a list of all known schema instances.

=item $obj-E<gt>B<doesExtend>($exttype, $basetype)

Returns true when $exttype extends $basetype.

=item $obj-E<gt>B<find>($kind, $address|<$uri,$name>, %options)

Lookup the definition for the specified $kind of definition: the name
of a global element, global attribute, attributeGroup or model group.
The $address is constructed as C< {uri}name > or as separate $uri and $name.

 -Option      --Default
  include_used  <true>

=over 2

=item include_used => BOOLEAN

=back

=item $obj-E<gt>B<findID>( $address|<$uri,$id> )

Lookup the definition for the specified id, which is constructed as
C< uri#id > or as separate $uri and $id.

=item $obj-E<gt>B<findSgMembers>($class, $type)

Lookup the substitutionGroup alternatives for a specific element, which
is an $type (element full name) of form C< {uri}name > or as separate
URI and NAME.  Returned is an ARRAY of HASHes, each describing one type
(as returned by L<find()|XML::Compile::Schema::NameSpaces/"Accessors">)

=item $obj-E<gt>B<findTypeExtensions>($type)

This method can be quite expensive, with large and nested schemas.

=item $obj-E<gt>B<importIndex>(%options)

[1.41] Returns a HASH with namespaces which are declared in all currently
known schema's, pointing to ARRAYs of the locations where the import should
come from.

In reality, the locations mentioned are often wrong. But when you think
you want to load all schema's dynamically at start-up (no, you do not
want it but it is a SOAP paradigma) then you get that info easily with
this method.

=item $obj-E<gt>B<list>()

Returns the list of name-space URIs defined.

=item $obj-E<gt>B<namespace>($uri)

Returns a list of L<XML::Compile::Schema::Instance|XML::Compile::Schema::Instance> objects which have
the $uri as target namespace.

=item $obj-E<gt>B<printIndex>( [$fh], %options )

Show all definitions from all namespaces, for debugging purposes, by
default the selected.  Additional %options are passed to 
L<XML::Compile::Schema::Instance::printIndex()|XML::Compile::Schema::Instance/"Index">.

 -Option      --Default
  include_used  <true>
  namespace     <ALL>

=over 2

=item include_used => BOOLEAN

Show also the index from all the schema objects which are defined
to be usable as well; which were included via L<use()|XML::Compile::Schema::NameSpaces/"Accessors">.

=item namespace => URI|ARRAY-of-URI

Show only information about the indicate namespaces.

=back

example: 

 my $nss = $schema->namespaces;
 $nss->printIndex(\*MYFILE);
 $nss->printIndex(namespace => "my namespace");

 # types defined in the wsdl schema
 use XML::Compile::SOAP::Util qw/WSDL11/;
 $nss->printIndex(\*STDERR, namespace => WSDL11);

=item $obj-E<gt>B<schemas>($uri)

We need the name-space; when it is lacking then import must help, but that
must be called explicitly.

=item $obj-E<gt>B<use>($object)

Use any other L<XML::Compile::Schema|XML::Compile::Schema> extension as fallback, if the
L<find()|XML::Compile::Schema::NameSpaces/"Accessors"> does not succeed for the current object.  Searches for
definitions do not recurse into the used object.

Returns the list of all used OBJECTS.
This method implements L<XML::Compile::Schema::useSchema()|XML::Compile::Schema/"Accessors">.

=back

=head1 SEE ALSO

This module is part of XML-Compile distribution version 1.51,
built on November 05, 2015. Website: F<http://perl.overmeer.net/xml-compile/>

Other distributions in this suite:
L<XML::Compile>,
L<XML::Compile::SOAP>,
L<XML::Compile::WSDL11>,
L<XML::Compile::SOAP12>,
L<XML::Compile::SOAP::Daemon>,
L<XML::Compile::SOAP::WSA>,
L<XML::Compile::C14N>,
L<XML::Compile::WSS>,
L<XML::Compile::WSS::Signature>,
L<XML::Compile::Tester>,
L<XML::Compile::Cache>,
L<XML::Compile::Dumper>,
L<XML::Compile::RPC>,
L<XML::Rewrite>
and
L<XML::LibXML::Simple>.

Please post questions or ideas to the mailinglist at
F<http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/xml-compile> .
For live contact with other developers, visit the C<#xml-compile> channel
on C<irc.perl.org>.

=head1 LICENSE

Copyrights 2006-2015 by [Mark Overmeer]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>