put...referent

action

Syntax
put stream-name indexer? open-modifier* (&stream-name indexer? open-modifer*)* 
   referent string-expression


Purpose

Writes a referent into a stream.

Indexer is an optional [...] (item), {...} (key), or lastmost phrase; open-modifiers is an optional list of stream modifiers; and string-expression contains the referent name.

Referents cannot be written to every stream. They can only be written to streams which were opened with either a referents-allowed or referents-displayed modifier. By default, the #main-output stream in any program that uses referents is treated as if it were opened with referents-allowed, and the #error and #console streams are treated as if they were opened with referents-displayed.

Programmers are required to explicitly control where referents are written because when writing to a stream opened with referents-allowed:

  • referent resolution requires post-processing the stream where the referents were written
  • those streams are not written to their final destination until the post-processing is complete.

When writing to a stream opened with referents-displayed, the referents are immediately converted to a string expression identifying the name of the referent and its current value. This string expression is an ordinary value. No replacement is done when referents are resolved.

Using the keyword referent when writing to a stream opened with referents-allowed never produces the "current" value of a referent, only a reference to some value which may be determined in the future. For this reason, a referent cannot be used in all the same ways that a string expression is used. (For instance, it cannot be used as a key value, or passed as an argument to a function.) It can only be written to streams.