view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        GPSBabel converts waypoints, tracks, and routes from one format to
        another, whether that format is a common mapping format like
        Delorme, Streets and Trips, or even a serial upload or download to a
        GPS unit such as those from Garmin and Magellan. By flattening the
        Tower of Babel that the authors of various programs for manipulating
        GPS data have imposed upon us, it returns to us the ability to
        freely move our own waypoint data between the programs and hardware
        we choose to use.

    As I write this "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 ("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.

  Format Guessing
    "GPS::Babel" queries the capabilities of "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 "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 "in_format" and/or
    "out_format" options to "read", "write" and "convert" as appropriate.

INTERFACE
    "new( { options } )"
        Create a new "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'
            });

    "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.

    "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
        "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 "filters", "formats" and "for_ext" hashes are only present if
        you have gpsbabel 1.2.8 or later installed.

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

            $ gpsbabel -V

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

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

    "got_ver( $ver )"