using

control structure

Syntax
using shelf-name[n]
   action

using  shelf-name item n
   action


Purpose

Each shelf has a "current item", the item that will be used if you refer to the shelf by its name alone, without using an indexer. By default, the current item on every shelf is the last item. The current item can be changed in any of the following ways:

  • By repeating over the shelf, in which case the current item advances on each iteration of the loop.
  • By passing a specific item of a shelf to a function as a modifiable or read-only argument.
  • By specifying a new current item with using

In the following example, the default current item is output, then the current output is changed by a using statements and the current item is output again: 

  global stream animals initial
   { "cow" with key "Bessie",
     "pig" with key "Wilbur",
     "hen" with key "Little Red",
     "horse" with key "Dobbin"
   }
  
  process
     output animals || "%n"
     using animals[2]
      output animals || "%n"
     using animals {"Little Red"}
      output animals || "%n"
     output animals || "%n"

The output of this program is: 

  horse
  pig
  hen
  horse

The using statement is in effect only for the statement that follows, which is why the final output statement outputs the default current item. To make a using statement affect more than one statement, include the statements in a do...done block. 

  process
   using animals[2]
    do
      output animals || "%n"
      set animals to "rabbit"
      output animals || "%n"
    done

You can also use using to establish an alias for a shelf. This is useful if you want to simplify a reference to a shelf that is part of a record: 

  declare record metadata-label
     field stream author
     field stream title
     field stream publisher
     field stream year
     field switch in-print initial {true}
  
  process
    local metadata-label doc-info
  
    using doc-info:author as author
     do
       set author to "J. R. R. Tolkien"
       ; other stuff
     done

If the shelf associated with an alias has multiple items, then you can index into the alias just as you would index into the shelf. The alias of a shelf has its own current item, so that if you specify an item when creating the alias, or if you subsequently change the current item with any of the methods above, that current item belongs to the alias name. The true name of the shelf has its own current item that will be used whenever the shelf is referred to by its real name.