This filter is designed to solve advanced problems that involve shuffling multiple lists of waypoints, tracks, or routes.
The stack filter can be used to save the current state of the entire collection of data. That state is placed on top of a stack of collections, so you can simultaneously have as many stored collections of data as you can fit in your computer's memory.
The stack filter can be used in conjunction with other filters to implement a "union" or "logical or" functionality. The basic idea is to use the stack to store copies of the original list of waypoints, then use the 'swap' function to replace each copy with a filtered list. Finally, append all of the filtered lists to create one big list, which is then output. The following example finds a list of all points that are either inside county A or inside county B. Any points that are inside both counties are duplicated (but the duplicates can be removed with the DUPLICATE filter; see above.)
gpsbabel -i gpx -f in.gpx
-x stack,push,copy
-x polygon,file=county_a.txt
-x stack,swap
-x polygon,file=county_b.txt
-x stack,pop,append
-o gpx -F out.gpx
This example reads a large list of waypoints and extracts the points within 20 miles of each of two cities, writing the waypoint descriptions into two different PalmDoc files and exporting all of the points to the GPS receiver:
gpsbabel -i gpx -f indiana.gpx
-x stack,push,copy
-x radius,lat=41.0765,lon=-85.1365,distance=20m
-o palmdoc,dbname=Fort\ Wayne -F fortwayne.pdb
-x stack,swap
-x radius,lat=39.7733,lon=-86.1433,distance=20m
-o palmdoc,dbname=Indianapolis -F indianapolis.pdb
-x stack,pop,append
-o magellan -F fwaind.wpt
Push waypoint list onto stack.
This is one of three "primary" options to the stack filter.
When this option is specified, the current state is pushed onto the top of
the stack. By default, the current state is then cleared, but the
copy option can be used to cause it to be saved.
Pop waypoint list from stack.
This is one of three "primary" options to the stack filter.
This option "pops" the collection of data from the top of the stack.
By default, the saved state replaces the current state, but see the
discard and append options for
alternatives.
Swap waypoint list with <depth> item on stack.
This is one of three "primary" options to the stack filter.
When this option is specified, the current state is swapped with a saved
state from the stack. By default, it is swapped with the top of the stack,
but the depth can be used to specify a different saved
state.
(push) Copy waypoint list.
This option is only valid when used with the push option.
When this option is specified, a copy of the current state is pushed onto
the stack but the current state is left unchanged. Otherwise, the push
operation clears the current data collection.
(pop) Append list.
This option is only valid in conjunction with the pop.
When it is specified, the topmost collection of data from the stack is
appended to the current collection of data.
(pop) Discard top of stack.
This option is only valid when used with the pop option.
When this option is specified, the popped state is discarded and the current
state remains unchanged.
(pop) Replace list (default).
This option is only valid when used with the pop option.
This is the default behavior of the pop option, so you
should never need to specify it, but it is included for the sake of
readability. When this option is specified, the popped state replaces
the current state.