1NAME
2 GPS::Babel - Perl interface to gpsbabel
3
4VERSION
5 This document describes GPS::Babel version 0.11
6
7SYNOPSIS
8 use GPS::Babel;
9
10 my $babel = GPS::Babel->new();
11
12 # Read an OZIExplorer file into a data structure
13 my $data = $babel->read('route.ozi', 'ozi');
14
15 # Convert a file automatically choosing input and output
16 # format based on extension
17 $babel->convert('points.wpt', 'points.gpx');
18
19 # Call gpsbabel directly
20 $babel->direct(qw(gpsbabel -i saroute,split
21 -f in.anr -f in2.anr -o an1,type=road -F out.an1));
22
23DESCRIPTION
24 From <http://gpsbabel.org/>:
25
26 GPSBabel converts waypoints, tracks, and routes from one format to
27 another, whether that format is a common mapping format like
28 Delorme, Streets and Trips, or even a serial upload or download to a
29 GPS unit such as those from Garmin and Magellan. By flattening the
30 Tower of Babel that the authors of various programs for manipulating
31 GPS data have imposed upon us, it returns to us the ability to
32 freely move our own waypoint data between the programs and hardware
33 we choose to use.
34
35 As I write this "gpsbabel" supports 96 various GPS related data formats.
36 In addition to file conversion it supports upload and download to a
37 number of serial and USB devices. This module provides a (thin) wrapper
38 around the gpsbabel binary making it easier to use in a perlish way.
39
40 GPSBabel supports many options including arbitrary chains of filters,
41 merging data from multiple files and many format specific parameters.
42 This module doesn't attempt to provide an API wrapper around all these
43 options. It does however provide for simple access to the most common
44 operations. For more complex cases a passthrough method ("direct")
45 passes its arguments directly to gpsbabel with minimal preprocessing.
46
47 GPSBabel is able to describe its built in filters and formats and
48 enumerate the options they accept. This information is available as a
49 perl data structure which may be used to construct a dynamic user
50 interface that reflects the options available from the gpsbabel binary.
51
52 Format Guessing
53 "GPS::Babel" queries the capabilities of "gpsbabel" and can use this
54 information to automatically choose input and output formats based on
55 the extensions of filenames. This makes it possible to, for example,
56 create tools that bulk convert a batch of files choosing the correct
57 format for each one.
58
59 While this can be convenient there is an important caveat: if more than
60 one format is associated with a particular extension GPS::Babel will
61 fail rather than risking making the wrong guess. Because new formats are
62 being added to gpsbabel all the time it's possible that a format that
63 can be guessed today will become ambiguous tomorrow. That raises the
64 spectre of a program that works now breaking in the future.
65
66 Also some formats support a particular extension without explicitly
67 saying so - for example the compegps format supports .wpt files but
68 gpsbabel (currently) reports that the only format explicitly associated
69 with the .wpt extension is xmap. This means that "GPS::Babel" will
70 confidently guess that the format for a file called something.wpt is
71 xmap even if the file contains compegps data.
72
73 In general then you should only use format guessing in applications
74 where the user will have the opportunity to select a format explicitly
75 if an unambiguous guess can't be made. For applications that must run
76 unattended or where the user doesn't have this kind of control you
77 should make the choice of filter explicit by passing "in_format" and/or
78 "out_format" options to "read", "write" and "convert" as appropriate.
79
80INTERFACE
81 "new( { options } )"
82 Create a new "GPS::Babel" object. Optionally the exename option may
83 be used to specify the full name of the gpsbabel executable
84
85 my $babel = GPS::Babel->new({
86 exename => 'C:\GPSBabel\gpsbabel.exe'
87 });
88
89 "check_exe()"
90 Verify that the name of the gpsbabel executable is known throwing an
91 error if it isn't. This is generally called by other methods but you
92 may call it yourself to cause an error to be thrown early in your
93 program if gpsbabel is not available.
94
95 "get_info()"
96 Returns a reference to a hash that describes the capabilities of
97 your gpsbabel binary. The format of this hash is probably best
98 explored by running the following script and perusing its output:
99
100 #!/usr/bin/perl -w
101
102 use strict;
103 use GPS::Babel;
104 use Data::Dumper;
105
106 $| = 1;
107
108 my $babel = GPS::Babel->new();
109 print Dumper($babel->get_info());
110
111 This script is provided in the distribution as
112 "scripts/babel_info.pl".
113
114 In general the returned hash has the following structure:
115
116 $info = {
117 version => $gpsbabel_version,
118 banner => $gpsbabel_banner,
119 filters => {
120 # big hash of filters
121 },
122 formats => {
123 # big hash of formats
124 },
125 for_ext => {
126 # hash mapping lower case extension name to a list
127 # of formats that use that extension
128 }
129 };
130
131 The "filters", "formats" and "for_ext" hashes are only present if
132 you have gpsbabel 1.2.8 or later installed.
133
134 "banner()"
135 Get the GPSBabel banner string - the same string that is output by
136 the command
137
138 $ gpsbabel -V
139
140 "version()"
141 Get the GPSBabel version number. The version is extracted from the
142 banner string.
143
144 print $babel->version(), "\n";
145
146 "got_ver( $ver )"
147 Return true if the available version of gpsbabel is equal to or
148 greater than the supplied version string. For example:
149
150 die "I need gpsbabel 1.3.0 or later\n"
151 unless $babel->got_ver('1.3.0');
152
153 "guess_format( $filename )"
154 Given a filename return the name of the gpsbabel format that handles
155 files of that type. Croaks with a suitable message if the format
156 can't be identified from the extension. If more than one format
157 matches an error listing all of the matching formats will be thrown.
158
159 Optionally a format name may be supplied as the second argument in
160 which case an error will be thrown if the installed gpsbabel doesn't
161 support that format.
162
163 Format guessing only works with gpsbabel 1.2.8 or later. As
164 mentioned above, the requirement that an extension maps
165 unambiguously to a format means that installing a later version of
166 gpsbabel which adds support for another format that uses the same
167 extension can cause code that used to work to stop working. For this
168 reason format guessing should only be used in interactive programs
169 that give the user the opportunity to specify a format explicitly if
170 such an ambiguity exists.
171
172 "get_exename()"
173 Get the name of the gpsbabel executable that will be used. This
174 defaults to whatever File::Which::which('gpsbabel') returns. To use
175 a particular gpsbabel binary either pass the path to the constructor
176 using the 'exename' option or call "set_exename( $path )".
177
178 "set_exename( $path )"
179 Set the path and name of the gpsbabel executable to use. The
180 executable doesn't have to be called 'gpsbabel' - although naming
181 any other program is unlikely to have pleasing results...
182
183 $babel->set_exename('/sw/bin/gpsbabel');
184
185 "read( $filename [, { $options } ] )"
186 Read a file in a format supported by gpsbabel into a "Geo::Gpx"
187 object. The input format is guessed from the filename unless
188 supplied explicitly in the options like this
189
190 $data = $babel->read('hotels.wpt', { in_format => 'xmap' });
191
192 See "Geo::Gpx" for documentation on the returned object.
193
194 "write( $filename, $gpx_data [, { $options }] )"
195 Write GPX data (typically in the form of an instance of "Geo::Gpx")
196 to a file in one of the formats gpsbabel supports. $gpx_data must be
197 a reference to an object that exposes a method called "xml" that
198 returns a GPX document. "Geo::Gpx" satisfies this requirement.
199
200 The format will be guessed from the filename (see caveats above) or
201 may be explicitly specified by passing a hash containing
202 "out_format" as the third argument:
203
204 $babsel->write('points.kml', $my_points, { out_format => 'kml' });
205
206 For consistency the data is filtered through gpsbabel even if the
207 desired output format is 'gpx'. If you will only be dealing with GPX
208 files use "Geo::Gpx" directly.
209
210 "convert( $infile, $outfile, [, { $options } ] )"
211 Convert a file from one format to another. Both formats must be
212 supported by gpsbabel.
213
214 With no options "convert" attempts to guess the input and output
215 formats using "guess_format" - see the caveats about that above. To
216 specify the formats explicitly supply as a third argument a hash
217 containing the keys "in_format" and "out_format" like this:
218
219 $babel->convert('infile.wpt', 'outfile.kml',
220 { in_format => 'compegps', out_format => 'kml' });
221
222 gpsbabel treats waypoints, tracks and routes as separate channels of
223 information and not all formats support reading and writing all
224 three. "convert" attempts to convert anything that can be both read
225 by the input format and written by the output format. If the formats
226 have nothing in common an error will be thrown.
227
228 "direct( @options )"
229 Invoke gpsbabel with the supplied options. The supplied options are
230 passed unmodified to system(), for example:
231
232 $babel->direct(qw(-i gpx -f somefile.gpx -o kml -F somefile.kml));
233
234 Throws appropriate errors if gpsbabel fails.
235
236DIAGNOSTICS
237 "%s not found"
238 Can't find the gpsbabel executable.
239
240 "Missing filename"
241 "guess_format" (or a method that calls it) needs a filename from
242 which to guess the format.
243
244 "Unknown format "%s""
245 An explicit format was passed to "guess_format" that doesn't appear
246 to be supported by the installed gpsbabel.
247
248 "Filename "%s" has no extension"
249 Can't guess the format of a filename with no extension.
250
251 "No format handles extension .%s"
252 The installed gpsbabel doesn't contain a format that explicitly
253 supports the named extension. That doesn't necessarily mean that
254 gpsbabel can't handle the file: many file formats use a number of
255 different extensions and many gpsbabel input/output modules don't
256 specify the extensions they support. If in doubt check the gpsbabel
257 documentation and supply the format explicitly.
258
259 "Multiple formats (%s) handle extension .%s"
260 "guess_format" couldn't unambiguously guess the appropriate format
261 from the extension. Check the gpsbabel documentation and supply an
262 explicit format.
263
264 "Must provide input and output filenames"
265 "convert" needs input and output filenames.
266
267 "Formats %s and %s have no read/write capabilities in common"
268 Some gpsbabel formats are read only, some are write only, some
269 support only waypoints or only tracks. "convert" couldn't find
270 enough common ground between input and output formats to be able to
271 convert any data.
272
273 "%s failed with error %s"
274 A call to gpsbabel failed.
275
276 "Must provide an input filename"
277 "read" needs to know the name of the file to read.
278
279 "Must provide some data to output"
280 "write" needs data to output. The supplied object must expose a
281 method called "xml" that returns GPX data. Typically this is
282 achieved by passing a "Geo::Gpx".
283
284CONFIGURATION AND ENVIRONMENT
285 GPS::Babel requires no configuration files or environment variables.
286 With the exception of "direct()" all calls pass the argument -p '' to
287 gpsbabel to inhibit reading of any inifile. See
288 "/www.gpsbabel.org/htmldoc- 1.3.2/inifile.html" in http: for more
289 details.
290
291DEPENDENCIES
292 GPS::Babel needs gpsbabel, ideally installed on your PATH and ideally
293 version 1.2.8 or later.
294
295 In addition GPS::Babel requires the following Perl modules:
296
297 Geo::Gpx (for read, write)
298 File::Which
299
300INCOMPATIBILITIES
301 GPS::Babel has only been tested with versions 1.3.0 and later of
302 gpsbabel. It should work with earlier versions but it's advisable to
303 upgrade to the latest version if possible. The gpsbabel developer
304 community is extremely active so it's worth having the latest version
305 installed.
306
307BUGS AND LIMITATIONS
308 No bugs have been reported.
309
310 Please report any bugs or feature requests to
311 "bug-gps-babel@rt.cpan.org", or through the web interface at
312 <http://rt.cpan.org>.
313
314AUTHOR
315 Andy Armstrong "<andy@hexten.net>"
316
317 Robert Lipe and numerous contributors did all the work by providing
318 gpsbabel in the first place. This is just a wafer-thin layer on top of
319 all their goodness.
320
321LICENCE AND COPYRIGHT
322 Copyright (c) 2006, Andy Armstrong "<andy@hexten.net>". All rights
323 reserved.
324
325 This module is free software; you can redistribute it and/or modify it
326 under the same terms as Perl itself. See perlartistic.
327
328DISCLAIMER OF WARRANTY
329 BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
330 FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
331 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
332 PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
333 EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
334 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
335 ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
336 YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
337 NECESSARY SERVICING, REPAIR, OR CORRECTION.
338
339 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
340 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
341 REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
342 TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
343 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
344 SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
345 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
346 FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
347 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
348 DAMAGES.
349
350