NAME
    GPS::Babel - Perl interface to gpsbabel

VERSION
    This document describes GPS::Babel version 0.12

SYNOPSIS
        use GPS::Babel;

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

        # Read an OZIExplorer file into a data structure
        my $data  = $babel->read('route.ozi', 'ozi');

        # Convert a file automatically choosing input and output
        # format based on extension
        $babel->convert('points.wpt', 'points.gpx');

        # Call gpsbabel directly
        $babel->direct(qw(gpsbabel -i saroute,split
            -f in.anr -f in2.anr -o an1,type=road -F out.an1));

DESCRIPTION
    From <http://gpsbabel.org/>:

        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 )"
        Return true if the available version of gpsbabel is equal to or
        greater than the supplied version string. For example:

            die "I need gpsbabel 1.3.0 or later\n"
                unless $babel->got_ver('1.3.0');

    "guess_format( $filename )"
        Given a filename return the name of the gpsbabel format that handles
        files of that type. Croaks with a suitable message if the format
        can't be identified from the extension. If more than one format
        matches an error listing all of the matching formats will be thrown.

        Optionally a format name may be supplied as the second argument in
        which case an error will be thrown if the installed gpsbabel doesn't
        support that format.

        Format guessing only works with gpsbabel 1.2.8 or later. As
        mentioned above, the requirement that an extension maps
        unambiguously to a format means that installing a later version of
        gpsbabel which adds support for another format that uses the same
        extension can cause code that used to work to stop working. For this
        reason format guessing should only be used in interactive programs
        that give the user the opportunity to specify a format explicitly if
        such an ambiguity exists.

    "get_exename()"
        Get the name of the gpsbabel executable that will be used. This
        defaults to whatever File::Which::which('gpsbabel') returns. To use
        a particular gpsbabel binary either pass the path to the constructor
        using the 'exename' option or call "set_exename( $path )".

    "set_exename( $path )"
        Set the path and name of the gpsbabel executable to use. The
        executable doesn't have to be called 'gpsbabel' - although naming
        any other program is unlikely to have pleasing results...

            $babel->set_exename('/sw/bin/gpsbabel');

    "read( $filename [, { $options } ] )"
        Read a file in a format supported by gpsbabel into a "Geo::Gpx"
        object. The input format is guessed from the filename unless
        supplied explicitly in the options like this

            $data = $babel->read('hotels.wpt', { in_format => 'xmap' });

        See "Geo::Gpx" for documentation on the returned object.

    "write( $filename, $gpx_data [, { $options }] )"
        Write GPX data (typically in the form of an instance of "Geo::Gpx")
        to a file in one of the formats gpsbabel supports. $gpx_data must be
        a reference to an object that exposes a method called "xml" that
        returns a GPX document. "Geo::Gpx" satisfies this requirement.

        The format will be guessed from the filename (see caveats above) or
        may be explicitly specified by passing a hash containing
        "out_format" as the third argument:

            $babsel->write('points.kml', $my_points, { out_format => 'kml' });

        For consistency the data is filtered through gpsbabel even if the
        desired output format is 'gpx'. If you will only be dealing with GPX
        files use "Geo::Gpx" directly.

    "convert( $infile, $outfile, [, { $options } ] )"
        Convert a file from one format to another. Both formats must be
        supported by gpsbabel.

        With no options "convert" attempts to guess the input and output
        formats using "guess_format" - see the caveats about that above. To
        specify the formats explicitly supply as a third argument a hash
        containing the keys "in_format" and "out_format" like this:

            $babel->convert('infile.wpt', 'outfile.kml',
                { in_format => 'compegps', out_format => 'kml' });

        gpsbabel treats waypoints, tracks and routes as separate channels of
        information and not all formats support reading and writing all
        three. "convert" attempts to convert anything that can be both read
        by the input format and written by the output format. If the formats
        have nothing in common an error will be thrown.

    "direct( @options )"
        Invoke gpsbabel with the supplied options. The supplied options are
        passed unmodified to system(), for example:

            $babel->direct(qw(-i gpx -f somefile.gpx -o kml -F somefile.kml));

        Throws appropriate errors if gpsbabel fails.

DIAGNOSTICS
    "%s not found"
        Can't find the gpsbabel executable.

    "Missing filename"
        "guess_format" (or a method that calls it) needs a filename from
        which to guess the format.

    "Unknown format "%s""
        An explicit format was passed to "guess_format" that doesn't appear
        to be supported by the installed gpsbabel.

    "Filename "%s" has no extension"
        Can't guess the format of a filename with no extension.

    "No format handles extension .%s"
        The installed gpsbabel doesn't contain a format that explicitly
        supports the named extension. That doesn't necessarily mean that
        gpsbabel can't handle the file: many file formats use a number of
        different extensions and many gpsbabel input/output modules don't
        specify the extensions they support. If in doubt check the gpsbabel
        documentation and supply the format explicitly.

    "Multiple formats (%s) handle extension .%s"
        "guess_format" couldn't unambiguously guess the appropriate format
        from the extension. Check the gpsbabel documentation and supply an
        explicit format.

    "Must provide input and output filenames"
        "convert" needs input and output filenames.

    "Formats %s and %s have no read/write capabilities in common"
        Some gpsbabel formats are read only, some are write only, some
        support only waypoints or only tracks. "convert" couldn't find
        enough common ground between input and output formats to be able to
        convert any data.

    "%s failed with error %s"
        A call to gpsbabel failed.

    "Must provide an input filename"
        "read" needs to know the name of the file to read.

    "Must provide some data to output"
        "write" needs data to output. The supplied object must expose a
        method called "xml" that returns GPX data. Typically this is
        achieved by passing a "Geo::Gpx".

CONFIGURATION AND ENVIRONMENT
    GPS::Babel requires no configuration files or environment variables.
    With the exception of "direct()" all calls pass the argument -p '' to
    gpsbabel to inhibit reading of any inifile. See
    "/www.gpsbabel.org/htmldoc- 1.3.2/inifile.html" in http: for more
    details.

DEPENDENCIES
    GPS::Babel needs gpsbabel, ideally installed on your PATH and ideally
    version 1.2.8 or later.

    In addition GPS::Babel requires the following Perl modules:

        Geo::Gpx (for read, write)
        File::Which

INCOMPATIBILITIES
    GPS::Babel has only been tested with versions 1.3.0 and later of
    gpsbabel. It should work with earlier versions but it's advisable to
    upgrade to the latest version if possible. The gpsbabel developer
    community is extremely active so it's worth having the latest version
    installed.

BUGS AND LIMITATIONS
    No bugs have been reported.

    Please report any bugs or feature requests to
    "bug-gps-babel@rt.cpan.org", or through the web interface at
    <http://rt.cpan.org>.

AUTHOR
    Andy Armstrong "<andy@hexten.net>"

    Robert Lipe and numerous contributors did all the work by providing
    gpsbabel in the first place. This is just a wafer-thin layer on top of
    all their goodness.

LICENCE AND COPYRIGHT
    Copyright (c) 2006, Andy Armstrong "<andy@hexten.net>". All rights
    reserved.

    This module is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY
    BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
    FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
    OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
    PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
    EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
    ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
    YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
    NECESSARY SERVICING, REPAIR, OR CORRECTION.

    IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
    WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
    REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
    TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
    CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
    SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
    RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
    FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
    SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
    DAMAGES.