save shelf-type? shelf-name

A declaration that can be intermixed with local variable declarations of a local scope. The save declaration can only be applied to global shelves. It causes a copy to be made of the specified shelf. For the duration of the local scope, every time the global shelf is referenced by name, it is the copy that is used. (This includes references from inside nested rules, from function calls, and from other rules.) When the local scope completes, the copy is destroyed and the saved shelf becomes the accessible one.

Essentially, save guarantees that a global shelf will have the same contents at the end of a local scope as it did at the beginning.

It is an error to save the same shelf in both domains (the output processor and the input processor) at the same time. This feature prevents getting saves that are not properly nested with respect to each other. It also ensures that shelves will always be "unsaved" in the opposite order from which they were saved.

Because save is a declaration, it may not have conditions.

When save is applied to a stream shelf, every item on that shelf must be either unattached or closed and attached to a buffer.

The shelf-type is an optional herald indicating the shelf type.

The following is an example of the effect of save on current item selection. This code outputs "20" and then "30":

  local counter my-shelf size 3

     set my-shelf @ 1 to 10
     set my-shelf @ 2 to 20
     set my-shelf @ 3 to 30
     using my-shelf @ 2
     do
        output "%d(my-shelf)%n"
        do
           save my-shelf
           output "%d(my-shelf)%n"
        done
     done