Save and restore waypoint lists (stack)

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

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:

push option

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 option

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 option

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.

copy option

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

append option

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

discard option

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

replace option

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

depth option

(swap) Item to use (default=1).

This option is only valid when used along with the swap
option. If specified, it indicates which item on the stack should be
swapped with the current state. The default value is 1, which corresponds
to the top of the stack.