=head1 NAME

Geo::GML - Geography Markup Language processing

=head1 INHERITANCE

 Geo::GML is extended by
   Geo::GML::2_0_0
   Geo::GML::2_1_1
   Geo::GML::2_1_2
   Geo::GML::2_1_2_0
   Geo::GML::2_1_2_1
   Geo::GML::3_0_0
   Geo::GML::3_0_1
   Geo::GML::3_1_0
   Geo::GML::3_1_1
   Geo::GML::3_2_1

=head1 SYNOPSIS

 use Geo::GML   qw/gml321/;
 use Geo::GML::3_2_1;   # not needed unless daemon

 my $gml = Geo::GML::3_2_1->new('READER', ...);
 my $gml = Geo::GML->new('READER', version => '3.2.1');

 # see XML::Compile::Cache on how to use readers and writers
 my $data = $gml->reader("gml:GridCoverage")->($xmlmsg);
 my $xml  = $gml->writer($sometype)->($doc, $perldata);

 # or without help of the cache, XML::Compile::Schema
 my $r    = $gml->schemas->compile(READER => $sometype);
 my $data = $r->($xml);

 # overview (large) on all defined elements
 $gml->printIndex;

=head1 DESCRIPTION

Base class for all GML XML protocol implementations.  The details about
GML structures can differ, and therefore you should be explicit which
versions you understand and produce.

The first releases of this module are not powerful, but hopefully
people contribute.  For instance, an example conversion script between
various versions is very welcome!  It would be nice to 

=head1 METHODS

=head2 Constructors

Geo::GML-E<gt>B<new>('READER'|'WRITER'|'RW', OPTIONS)

=over 4

 Option          --Default
 allow_undeclared  <true>
 prefixes          undef
 schemas           <created internally>
 version           <required>

. allow_undeclared => BOOLEAN

=over 4

In the optimal case, all types used in your application are declared
during the initiation phase of your program.  This will make it easy
to write a fast daemon application, or transform your program into a
daemon later.  So: "false" would be a good setting.  However, on the moment,
the developer of this module has no idea which types people will use.
Please help me with the specs!

=back

. prefixes => ARRAY|HASH

=over 4

Prefix abbreviations, to be used by cache object.  Which prefixes are
defines slightly depends on the schema version.

=back

. schemas => XML::Compile::Cache object

. version => VERSION|NAMESPACE

=over 4

Only used when the object is created directly from this base-class.  It
determines which GML syntax is to be used.  Can be a VERSION like "3.1.1"
or a NAMESPACE URI like 'NS_GML_3_0'.

=back

=back

=head2 Accessors

$obj-E<gt>B<direction>

=over 4

Returns 'READER', 'WRITER', or 'RW'.

=back

$obj-E<gt>B<schemas>

=over 4

Returns the internal schema object, type XML::Compile::Cache.

=back

$obj-E<gt>B<version>

=over 4

GML version, for instance '3.2.1'.

=back

=head2 Helpers

$obj-E<gt>B<printIndex>([FILEHANDLE], OPTIONS)

=over 4

List all the elements which can be produced with the schema.  This will
call XML::Compile::Cache subroutine printIndex to show (by default) only
the elements and exclude the abstract elements from the list.

The selected FILEHANDLE is the default.  OPTIONS overrule the defaults
which are passed to that C<printIndex()>.

=back

$obj-E<gt>B<template>('PERL'|'XML', TYPE, OPTIONS)

=over 4

See XML::Compile::Schema subroutine template.  This will create an example
of the data-structure based on GML.  All OPTIONS are passed to the
template generator, the only reason to have this method, is to avoid
the need to collect all the GML XML files yourself.

example: 

  use Geo::GML;
  use Geo::GML::Util     qw/NS_GML_321/;
  use XML::Compile::Util qw/pack_type/;
  my $type = pack_type NS_GML_321, 'RectifiedGridCoverage';
  my $gml  = Geo::GML->new(version => NS_GML_321);
  print $gml->template(PERL => $type);

=back

