view release on metacpan or  search on metacpan

index.dox  view on Meta::CPAN

the debug messages. This means that the messages will end up in
\@Geo::GDAL::error and can be accessed with Geo::GDAL::errstr. That
can be changed by calling Geo::GDAL::DontUseExceptions, after which
all error and debug messages are sent to standard error (STDERR). For
example

\code
$ENV{CPL_DEBUG} = 'ON';
Geo::GDAL::DontUseExceptions;
my $mp = Geo::OGR::Geometry->new(GeometryType => 'MultiPoint', Points => [[1,1]]);
$mp->AddGeometry(Geo::OGR::Geometry->new(GeometryType => 'Point'));
say $mp->As(Format => 'ISO WKT');
\endcode

Prints

OGR: OGRMultiPoint::exportToWkt() - skipping POINT EMPTY.

to STDERR, and

MULTIPOINT ((1 1))

to STDOUT.

\section index_named_params Named parameters

Quite many methods and subroutines in Geo::GDAL accept named
parameters. In all cases the named parameters are handled with the
same filter, which accepts either a list of parameters (the order is
the order in which the named parameters are described in this
documentation), single hash reference, or a list of key value pairs.
The keys are given in the documentation but the filter ignores case
and underscores. Thus, although the name of the parameter is
ProgressData, the method will happily recognize also progress_data.

\section index_progress Progress callback

Some methods accept a callback function for reporting the
progress. The progress subroutine is called with three arguments: a
number, a string, and user defined data. The user defined data
is an argument to the method.

\code
sub progress {
    my($progress, $message, $data) = @_;
    my $terminate = 0;
    ...
    return $terminate ? 0 : 1;
}
\endcode

\section index_stdout_redirection Redirecting stdout to a writer object

The Perl bindings takes advantage of the virtual file system of GDAL
and offers a way to redirect the output from a format driver to a Perl
object. The object needs to implement \c write and \c close
methods. \c write is called for each output from the driver with the
output byte string as an argument. \c close is called when the dataset
being used in the creation is destroyed. Note that the destruction of
the dataset may depend on destruction of all objects that depend on
it. For a simple example see page \ref streaming.

Due to the limitation of the redirection mechanism only one redirection
may be active at any time.

Note that the return value of the \c write method does not have any
effect. Internally the return value is set to the length of the byte
string.

\section index_refcount Reference counting

In GDAL many objects may depend on other objects to exist, for example
a geometry, which is an attribute of a feature depends on the feature
to exist when the geometry is accessed. If a feature is destroyed,
then using a geometry object, which points for its data into the
feature, will lead to memory error.

GDAL maintains its own reference counting but this is largely lost in
the bindings.

The Perl bindings attempt to maintain these dependencies by keeping
the parent objects alive under the hood, independent of their existence
in the user space. Thus it is perfectly legal to do something like

\code
my $layer = Geo::OGR::Driver('Memory')->
    Create()->
        CreateLayer(Name => 'layer',
                    Fields => [{Name => 'test', Type => 'Integer'},
                               {Name => 'geom', Type => 'Point'}]);
\endcode

or

\code
my $geometry;
{
    my $feature = $layer->InsertFeature({test => 13, geom => {WKT => 'POINT (10 20)'}});
    $geometry = $feature->Geometry('geom');
}
say $geometry->AsText;
\endcode

There is at least one caveat. Swig sets the bindings up in such a way
that the objects are tied hashes. For example a feature can used as a
hash.

\code
my $feature = $lauer->InsertFeature({test => 13, geom => {WKT => 'POINT (10 20)'}});
my $test = $feature->{test};
\endcode

Due to the mechanism of tied hashes in Perl it is not possible to
maintain the parent referencing when using this syntax. Thus do not
use this for subobjects. (In fact it will create an error.)

\code
my $feature = $lauer->InsertFeature({test => 13, geom => {WKT => 'POINT (10 20)'}});
my $geom = $feature->{geom}; # will lead to memory error!
\endcode