Output, Input, and Redirection

Executing commands can produce output (other than error messages) in two ways: they can yield a value, which is then printed preceded by “Value:”, and they can themselves invoke printing actions. Functions whose purpose is to print specific output (like tables) generally do not return a useful value (by convention the names to such functions start with “print”). Whatever is the manner in which output it produced, the user may decide to write the result to a file rather than to the terminal. To that end it suffices to prefix the command line (which must be an expression, not a ‘set’ definition) with “>” or with “>>” followed by a file name (which is taken to be delimited by white space; alternatively the file name may be enclosed in double quotes, in which case it can contain spaces); all terminal output will be redirected to that file for the duration of the command. In case of “>” a new file will be created, in case of “>>” the output is appended to an existing file. For instance:

atlas> > output_file block_sizes(ic)
atlas> >>output_file print_KGB(real_form(ic,2))
atlas> >>output_file print_KL_list(real_form(ic,2),dual_quasisplit_form(ic))

will produce in the current directory the file ‘output_file’ with the results of the indicated calls to block_sizes’, ‘print_KGB’, and ‘print_KL_list’.

One can also redirect command input from a file. Simply type:

atlas> <filename

on a line by itself to execute the contents of ‘filename’ as a series of commands. The output (responses to definitions, and values of expression commands, but not any prompts) still goes to the terminal (unless the file contains lines that themselves start with ‘>’); in addition messages are printed indicating the start and end of reading from that file, so that the user can track what source the commands producing the output (or an error) are coming from. Files being read like this can themselves open other input files. To keep track of this nesting, some indentation is added to normal command output for every level of input currently active. If the file name used for input is unknown (as searched from the current working directory), an alternative file name formed by adding the ‘.at’ suffix is tried (unless the given file name already contained that suffix), and if still nothing is found an error is reported. Any error will close all currently active input files.

Once a file is successfully input, axis remembers its file name and suppresses subsequent attempts to read that file as input. This is so that scripts can freely start by including other scripts whose definitions they depend on, without having multiple dependencies on the same script result in it being executed many times. The user can circumvent this check by writing:

atlas> <<filename

in which case the file will be read as input, even if it had been before. This can be useful if the file has been edited since it was last read in. Note however that in case input of a file is terminated by an error (either from one of its commands or from a file included by it) then the file is not yet recorded as having been read, so a single ‘<’ then suffices to reread it. Realex will refuse to open a file currently already being read from, to prevent infinite input loops in case of circular dependencies.

These input commands will search for their files in the directories specified by the special system variable ‘input_path’ which is of type ‘[string]’ (a row of strings). This variable can be assigned to from the atlas program, but is usually given its (initial) value through command line arguments to the atlas program of the form ‘–path=file_name’

In spite of similar syntax, output and input redirection have rather different characteristics. Output redirection only applies to a single expression evaluation. Input redirection should not be followed by anything on the same line, but it can invoke any number of commands from the given file. It can even be used recursively to include commands from other files that are needed to process the included file, it that file contains lines that start with ‘<’. One cannot globally redirect the output produced from the commands of an included file. If a command read from a file included at any level produces a syntax or runtime error, a message reporting the place of the error is printed, all included files are abandoned (since with some command failing, it is usually pointless to continue); then control is given back to the terminal.