/*! \mainpage Geo::GDAL

\section index_version Version

These pages document the development version of the GDAL Perl API,
which is extended from the released versions APIs.

<a href="http://map.hut.fi/doc/Geo-GDAL-1.4/html/index.html">The
documentation for the version 1.4 API.</a>

<a href="http://map.hut.fi/doc/Geo-GDAL-1.5/html/index.html">The
documentation for the version 1.5 API.</a>

<a href="http://map.hut.fi/doc/Geo-GDAL-1.6/html/index.html">The
documentation for the version 1.6 API.</a>

\section index_intro Introduction

The Geo::GDAL modules are the Perl bindings to the GDAL/OGR
library. The modules allow you to access and manipulate from Perl all
geospatial data that the installed GDAL library is configured to
read/write.

This documentation covers mainly the syntax of the bindings. For more
in-depth documentation see the main documentation of <a
href="http://www.gdal.org/">GDAL</a> and <a
href="http://www.gdal.org/ogr/">OGR</a>.

Some arguments are optional and have a default value. This is
illustrated like this:

SomeMethod(arg1, arg2 = 4);

arg1 is a required argument.

arg2 may be left out and if left out, will get the value 4 (in this
case).

Only the last argument or arguments can be optional.

In some cases a method can be called in a traditional way and with
named arguments (i.e. with a hash):

\code
$object->method(1, 2, 3);
$object->method(number=>1, param=>2, other=>3);
$object->method({number=>1, param=>2, other=>3});
\endcode

Note especially the difference between the second and the third
versions. In some cases the named arguments must be given in an
anonymous hash.

In some cases a method may behave differently depending on the
parameters that it gets:

\code
$object->method($hashref); # a method called with a reference to a hash
$object->method($arrayref); # a method called with a reference to an array
\endcode

In some cases a method may examine the context in which it is called,
and behave differently:

\code
$object->method();
$return = $object->method(); # method called in scalar context
@return = $object->method(); # method called in list context
\endcode

Many of the methods may throw an error, which can be caught by putting
the call into eval{}; and then examining the contents of $@.

\section index_exceptions Exceptions

Geo::GDAL uses the Perl exception mechanism in such a way that
exceptions that are classified in GDAL as failures or fatal errors
trigger a Perl exception, and an exception that is classified as a
warning triggers a Perl warning.

Perl exceptions can be caught by \a eval() and Perl warnings can be
caught by signal '__WARN__'. Examples:

\code
use Geo::GDAL;
eval {
    $point = Geo::OGR::Geometry->create(WKT=>"POINTXX(1 1)");
};
print STDERR "Error: $@";
\endcode

Prints:
\code
Error: RuntimeError OGR Error: Unsupported geometry type
\endcode

\code
use Geo::GDAL;
BEGIN { $SIG{'__WARN__'} = sub {  print STDERR "Warning: @_"; } }
Geo::GDAL::Driver('GTiff')->Create('x',10,10,1,'Byte',{a=>'b'});
\endcode

Prints: 
\code
Warning: Driver GTiff does not support a creation option at site/lib/Geo/GDAL.pm line 771.
\endcode

\section index_footer Note

This documentation is generated from files within the GDAL
distribution (directory swig/perl) with a tweaked version of <a
href="http://www.bigsister.ch/doxygenfilter/">Perl Doxygen Filter</a>
with Doxygen.

*/
