set file string-expression open-modifiers to string-expression

A convenient way to create a file when the entire contents can be described with a single string-expression. It can be used anywhere that the sequence open...as file, put, close would be used. As an example:

  down-translate
  ...
  element  copyright
     set file "copy.txt" to "%c%n"

The same open modifiers that can be used for open can be used for set file.

set file is a convenient way to copy files, but is most useful when the right-hand side refers to an external source function.

The string-expression is only evaluated as needed. This means that if the string expression consists of any of the following, alone or in a join operation, they are processed "as needed". If the string-expression contains:

file followed by a filename, then the file can be read incrementally, allowing large files to be pocessed.

a call to an external source function, then:

• The function will be called when its text is required. The #current-output set inherited by the function is an anonymous buffer used to buffer the output until it can all be copied to the destination stream at the end of the action.
• Text from the function will be read incrementally, so that all of the information returned does not need to be stored in memory all at once.

any stream-returning function call, then that function call will be executed at the point where its text is required. The #current-output set inherited by the function is an anonymous buffer used to buffer the output until it can all be copied to the destination stream at the end of the action.