=head1 NAME

Geo::GML - Geography Markup Language processing

=head1 INHERITANCE

=head1 SYNOPSIS

 use Geo::GML   qw/gml321/;

 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

Provides access to the GML definitions specified in XML.  The details
about GML structures can differ, and therefore you should be explicit
which versions you understand and produce.

If you need the <b>most recent</b> version of GML, then you get involved
with the ISO19139 standard.  See CPAN module Geo::ISO19139.

The first releases of this module will not powerful, but hopefully
people contribute.  For instance, an example conversion script between
various versions is very welcome!  It would be nice to help each other.
I will clean-up the implementation, to make it publishable, but do not
have the knowledge about what is needed.

=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
defined 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_300'.

=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

=head1 SEE ALSO

This module is part of Geo-GML distribution version 0.11,
built on June 12, 2008. Website: F<http://perl.overmeer.net/geo/>
All modules in this suite:
L</Geo::GML>,
L</Geo::ISO19139>,
L</Geo::Point>,
L</Geo::Proj4>,
L</Geo::WKT>,
L</Math::Polygon>

Please post questions or ideas to
F<http://geo-perl@list.hut.fi|the Geo-Perl mailinglist>

Related: F<http://www.isotc211.org|ISO TC211> and
ISO standard 19136.

=head1 COPYRIGHTS

=head2 License of the CODE

Copyrights of the perl code and the related documentation by
2008 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>

=head2 License of the SCHEMAS

The included schemas are copyrighted by the Open Geospatial Consortium, Inc.
They are unmodified copied from the files at F<http://schemas.opengis.net>.
Read OGCs disclaimer and copyright statements on documentation and software
at F<http://www.opengeospatial.org/ogc/legal>.  The license text is also
included in this CPAN distribution.