Next: , Previous: Frames and pictures, Up: Programming


5.6 Files

Asymptote can read and write text files (including comma-separated value) files and portable XDR (External Data Representation) binary files.

An input file must first be opened with input(string name, bool check=true, string commentchar="#"); reading is then done by assignment:

file fin=input("test.txt");
real a=fin;

If the optional boolean argument check is false, no check will be made that the file exists. If the file does not exist or is not readable, the function bool error(file) will return true. The first character of the string commentchar specifies a comment character. If this character is encountered in a data file, the remainder of the line is ignored. When reading strings, a comment character followed immediately by another comment character is treated as a single literal comment character.

If the -global (or -unsafe) option is enabled, one can change the current working directory to the contents of the string s with the function string cd(string s), which returns the new working directory. If string s is empty, the path is reset to the value it had at program startup.

When reading pairs, the enclosing parenthesis are optional. Strings are also read by assignment, by reading characters up to but not including a newline. In addition, Asymptote provides the function string getc(file) to read the next character (treating the comment character as an ordinary character) and return it as a string.

A file named name can be open for output with

file output(string name, bool update=false);
If update=false, any existing data in the file will be erased and only write operations can be used on the file. If update=true, existing data will be preserved, the position will be set to the end-of-file, and both reading and writing operations will be enabled. For security reasons, writing to files in directories other than the current directory is allowed only if the -global (or -unsafe) command-line option is specified.

There are two special files: stdin, which reads from the keyboard, and stdout, which writes to the terminal. The implicit initializer for files is stdout.

Data of a built-in type T can be written to an output file by calling one of the functions

write(string s="", T x, suffix suffix=endl ... T[]);
write(file file, string s="", T x, suffix suffix=none ... T[]);
write(file file=stdout, string s="", explicit T[] x ... T[][]);
write(file file=stdout, T[][]);
write(file file=stdout, T[][][]);
write(suffix suffix=endl);
write(file file, suffix suffix=none);
If file is not specified, stdout is used and terminated by default with a newline. If specified, the optional identifying string s is written before the data x. An arbitrary number of data values may be listed when writing scalars or one-dimensional arrays. The suffix may be one of the following: none (do nothing), endl (terminate with a newline), or tab (terminate with a tab). Here are some simple examples of data output:
file fout=output("test.txt");
write(fout,1);                  // Writes "1"
write(fout);                    // Writes a new line
write(fout,"List: ",1,2,3);     // Writes "List: 1     2     3"
A file may also be opened with xinput or xoutput, instead of input or output, to read or write double precision values in Sun Microsystem's XDR (External Data Representation) portable binary format (available on all UNIX platforms). A file may also be opened with binput or boutput to read or write double precision values in the native (nonportable) machine binary format. The function file single(file) may be used to set a file to read single precision XDR or binary values; calling file single(file,false) sets it back to read doubles again.

One can test a file for end-of-file with the boolean function eof(file), end-of-line with eol(file), and for I/O errors with error(file). One can flush the output buffers with flush(file), clear a previous I/O error with clear(file), and close the file with close(file). To set the number of digits of output precision, use precision(file,int). The function int tell(file) returns the current position in a file relative to the beginning. The function seek(file file, int pos) can be used to change this position, where a negative value for the position pos is interpreted as relative to the end-of-file. For example, one can rewind a file file with the command seek(file,0) and position to the final character in the file with seek(file,-1). The command seekeof(file) sets the position to the end of the file.

Assigning settings.scroll=n for a positive integer n requests a pause after every n output lines to stdout. One may then press Enter to continue or q followed by Enter to quit. If n is negative, the output scrolls a page at a time (i.e. by one less than the current number of display lines). The default value, settings.scroll=0, specifies continuous scrolling.

The routines

string getstring(string name="", string default="", string prompt="",
                 bool save=true);
int getint(string name="", int default=0, string prompt="",
           bool save=true);
real getreal(string name="", real default=0, string prompt="",
             bool save=true);
pair getpair(string name="", pair default=0, string prompt="",
             bool save=true)
defined in the module plain may be used to prompt for a value from stdin using the GNU readline library. If save=true, the history of values for name is saved to the file ".asy_"+name (see history). The most recent value in the history will be used to provide a default value for subsequent runs. The default value (initially default) is displayed after prompt. These routines are based on the following interface to readline, which prompts the user with the default value formatted according to prompt and saves the local history under the name ".asy_"+history, unless the string history begins with a linefeed ('\n'):
string readline(string prompt="", string history="", string initial="",
                bool tabcompletion=false);