view release on metacpan or  search on metacpan

lib/GPS/Babel.pm  view on Meta::CPAN

    we choose to use.

As I write this C<gpsbabel> supports 96 various GPS related data
formats. In addition to file conversion it supports upload and
download to a number of serial and USB devices. This module provides a
(thin) wrapper around the gpsbabel binary making it easier to use in a
perlish way.

GPSBabel supports many options including arbitrary chains of filters,
merging data from multiple files and many format specific parameters.
This module doesn't attempt to provide an API wrapper around all these
options. It does however provide for simple access to the most common
operations. For more complex cases a passthrough method (C<direct>)
passes its arguments directly to gpsbabel with minimal preprocessing.

GPSBabel is able to describe its built in filters and formats and
enumerate the options they accept. This information is available as a
perl data structure which may be used to construct a dynamic user
interface that reflects the options available from the gpsbabel binary.

=head2 Format Guessing

C<GPS::Babel> queries the capabilities of C<gpsbabel> and can use this
information to automatically choose input and output formats based on
the extensions of filenames. This makes it possible to, for example,
create tools that bulk convert a batch of files choosing the correct
format for each one.

While this can be convenient there is an important caveat: if more than
one format is associated with a particular extension GPS::Babel will
fail rather than risking making the wrong guess. Because new formats are
being added to gpsbabel all the time it's possible that a format that
can be guessed today will become ambiguous tomorrow. That raises the
spectre of a program that works now breaking in the future.

Also some formats support a particular extension without explicitly
saying so - for example the compegps format supports .wpt files but
gpsbabel (currently) reports that the only format explicitly associated
with the .wpt extension is xmap. This means that C<GPS::Babel> will
confidently guess that the format for a file called something.wpt is
xmap even if the file contains compegps data.

In general then you should only use format guessing in applications
where the user will have the opportunity to select a format explicitly
if an unambiguous guess can't be made. For applications that must run
unattended or where the user doesn't have this kind of control you
should make the choice of filter explicit by passing C<in_format> and/or
C<out_format> options to C<read>, C<write> and C<convert> as
appropriate.

=head1 INTERFACE

=over

=item C<new( { options } )>

Create a new C<GPS::Babel> object. Optionally the exename option may
be used to specify the full name of the gpsbabel executable

    my $babel = GPS::Babel->new({
        exename => 'C:\GPSBabel\gpsbabel.exe'
    });

=item C<check_exe()>

Verify that the name of the gpsbabel executable is known throwing an
error if it isn't. This is generally called by other methods but you may
call it yourself to cause an error to be thrown early in your program if
gpsbabel is not available.

=item C<get_info()>

Returns a reference to a hash that describes the capabilities of your
gpsbabel binary. The format of this hash is probably best explored by
running the following script and perusing its output:

    #!/usr/bin/perl -w

    use strict;
    use GPS::Babel;
    use Data::Dumper;

    $| = 1;

    my $babel = GPS::Babel->new();
    print Dumper($babel->get_info());

This script is provided in the distribution as C<scripts/babel_info.pl>.

In general the returned hash has the following structure:

    $info = {
        version     => $gpsbabel_version,
        banner      => $gpsbabel_banner,
        filters     => {
            # big hash of filters
        },
        formats     => {
            # big hash of formats
        },
        for_ext     => {
            # hash mapping lower case extension name to a list
            # of formats that use that extension
        }
    };

The C<filters>, C<formats> and C<for_ext> hashes are only present if you have
gpsbabel 1.2.8 or later installed.

=item C<banner()>

Get the GPSBabel banner string - the same string that is output by the command

    $ gpsbabel -V

=item C<version()>

Get the GPSBabel version number. The version is extracted from the banner string.

    print $babel->version(), "\n";