action
put stream-name indexer? modifiers? (& stream-name indexer? modifiers?)* string-expression
An action that writes the specified string expression to one or more destinations.
If you use put
to write to a markup sink
, then the string expression may be either a
markup source
or a string source
. On the other hand, if you are using put
to write to a
string sink
, then the string expression must be a string source
.
The string expression is evaluated only as needed, depending on its content:
file
followed by a filename, the file will be read incrementally, allowing large
files to be processed.
string source function
, the function will be called when its text is
required. The #current-output
set inherited by the function is the set of destinations being
written to by the put
. After this, text from the function will be read incrementally, so the
information returned does not need to be stored in memory all at once.
string
returning function call, the call will be executed when its text is
required. The #current-output
set inherited by the function is the set of destinations being
written to by the put
.
Only the following modifiers are permitted with put
:
binary
open modifier.
The specified modifiers replace the one currently in force. If no modifiers are specified, the ones currently in force are used.
Before writing text to the specified destinations, the put
action saves the old
#current-output
set, and creates a new #current-output
set consisting of the specified
destinations. When the writing is complete, the previous #current-output
is restored. This causes
#current-output
sets to be nested within each other. This useful feature is important when the string
expression contains a %c
operator.
#current-output
may be given as one of the destinations. In this case, the text is written to the set
of destinations that are currently active, as well as the other ones specified.
You can only use put
on an open stream.