source? #main-input

One of the built-in input sources.

In a translation program, #main-input identifies the text that will be automatically processed. Thus, when files are named on the command line, #main-input supplies the text of each of the files in the order in which their names appear on the command line. When no file is named on the command line, #main-input identifies the same source as #process-input (that is, "standard input").

In a process program, #main-input always identifies the same source as #process-input.

#main-input explicitly identifies a source of input, and can be used as the scanning source in:

• do scan
• repeat scan
• the input function of a do sgml-parse
• the scan source of a do sgml-parse
• submit

The use of #main-input has the following constraints:

• It can be used only once in each run of a program by do scan, repeat scan, or submit. If it is used more than once, an error will be generated.
• #main-input is usually read incrementally, meaning that the contents of the stream are not all buffered in memory before processing begins. In some situations, however, this is not the case. If you use #main-input as a string expression (for example: length of #main-input), as a passed "value" argument in a function, or as part of a concatenated string (for example: set this-string to str-var || #main-input), the entire contents of #main-input will be read into memory.
• In scan or submit actions, #main-input either must be the only input source or must be directly output to a stream and read as usual.

Further difficulty arises when #main-input does not have an "end". This can happen when it is piped from a keyboard or other such device, where the input can wait forever for another character. This will "hang" a program that attempts to read in all #main-input at once.

In light of these difficulties, take care to design your program to read #main-input incrementally.

The appropriate herald type for #main-input is "source".