The optional "work_dir" (or "wd" for short) specifies where to save any working files, such as with the save() method. It can be supplied as a relative path or as an absolute path. If "work_dir" is omitted, it is set based on the path of the $fname supplied or the current working directory if the constructor is called with an XML string or a filehandle (see set_wd() for more info).

  $clone = $self->clone;
    

With an argument, returns a reference to the waypoint whose "name" field is an exact match with $name. If an integer is specified instead of the "name" key/value pair, returns the waypoint at position $int in the array reference (1-indexed with negative integers also counting from the end of the array).

Returns "undef" if no corresponding waypoints are found such that this method can be used to check if a specific point exists (i.e. no exception is raised if $name or $int do not exist) .

  %point = ( lat => 54.786989, lon => -2.344214, ele => 512, name => 'My house' );
  $gpx->waypoints_add( \%point );
    or
  $pt = Geo::Gpx::Point->new( %point );
  $gpx->waypoints_add( $pt );
    

Alternatively, an array of "Geo::GXP::Points" can be provided. way_clip() is a short-hand for this method (convenient when used interactively in the debugger).

This method is only supported on unix-based systems that have the "xclip" utility installed (see DEPENDENCIES).

A $regex may be provided to limit the merge to a subset of waypoints from $gpx.

Returns the number of points successfully merged (i.e. the difference in "$gps->waypoints_count" before and after the merge).

"name" and all other meta fields supported by routes can be provided and will overwrite any existing fields in $route.

If $track has no "name" field and none is provided, the timestamp of the first point of the track will be used (this is experimental and may change in the future). All other fields supported by tracks can be provided and will overwrite any existing fields in $track.

A new track can also be created based an array reference(s) of Geo::Gpx::Point objects and added to the "Geo::Gpx" instance. If more than one array reference is supplied, the resulting track will contain as many segments as the number of aref's provided.

Alternatively, an integer may be specified as the first argument, referring to the track number from tracks aref (1-indexed). This is a convenience as it is quite common for tracks to be named with the timestamp fo the first point.

    my $iter = $gpx->iterate_points();
    while ( my $pt = $iter->() ) {
        print "Point: ", join( ', ', $pt->{lat}, $pt->{lon} ), "\n";
    }
    

  my $gpx = Geo::Gpx->new( xml => $some_xml );
  my $bounds = $gpx->bounds();
    

returns a structure like this:

  $bounds = {
    minlat => 57.120939,
    minlon => -2.9839832,
    maxlat => 57.781729,
    maxlon => -1.230902
  };
    

$iterator defaults to "$self->iterate_points" if not specified.

key/values are (all optional):

"version": specifies the GPX XML version scheme to use (defaults to 1.0).
"unsafe_chars": the set of characters to be considered unsafe for the XML mark-up and encoded as an entity.

If "version" is omitted, it defaults to the value of the "version" attribute. Parsing a GPX document sets the version. If the "version" attribute is unset defaults to 1.0.

"unsafe_chars" can be provided to specify which characters to consider unsafe in generating the XML mark-up. This field is then passed through to HTML::Entities function calls whose documentation describes that this field is "specified using the regular expression character class syntax (what you find within brackets in regular expressions)".

As of version 1.11 of "Geo::Gpx", the default set of characters are the '<', '&', '>', '"' characters. To revert to the pre-version 1.11 default, which is equivalent to that in <"HTML::Entities", explicitely specify "unsafe_chars => undef". This will encode as the latter module describes the "control chars, high-bit chars, and the '<', '&', '>', "'", '"' characters".

    my %json = map { $_ => $self->$_ }
        qw( name desc author keywords copyright
            time link waypoints tracks routes version );
    $json{bounds} = $self->bounds( $iter );
    

With one difference: the keys will only be set if they are defined.

The filename field is optional unless the instance was created without a filename (i.e with an XML string or a filehandle) and set_filename() has not been called yet. If the filename is a relative path, the file will be saved in the instance's working directory (not the caller's, "Cwd").

key/values are (all optional):

"force": overwrites existing files if true, otherwise it won't.
"extensions": save "<extensions>…</extension>" tags if true (defaults to false).
"meta_time": save the "<time>…</time>" tag in the file's meta information tags if true (defaults to false). Some applications like MapSource return an error if this tags is present. (All other time tags elsewhere are kept.)
"unsafe_chars": see the documentation for xml() above.

This working directory is always defined. The previous one is also stored in memory, such that set_wd('-') switches back and forth between two directories. The module never actually "chdir"'s, it just keeps track of where the user wishes to save files.