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


4.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, 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 string commentchar specifies a comment character (the default comment character # is actually determined by the variable commentchar in plain.asy). If this character is encountered in a data file, the remainder of the line is ignored. When reading strings, the comment character must be in the first column (otherwise it will treated as an ordinary character).

One can change the current working directory with the string cd(string) function, which returns the new working directory.

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 only, returning it as a string.

A file named name can be open for output with

file output(string name, bool append=false);
data will be appended to an existing file only if the file is opened with append=true. Data of type T can be written to an output file by calling one of the following functions
write(string s="", T x, suffix e=endl);
write(file fout, string s="", T x, suffix e=none);
write(string s="" ... T[] x);
write(file fout, string s="" ... T[] x);
write(file fout=stdout, suffix e=endl);
If the fout is not specified, stdout is used and terminated with a newline. If specified, the optional identifying string s is written before the data x. Except when writing objects that may generate multiple lines of output (like arrays or guides), an arbitrary number of data values may be given. The suffix e may be one of the following: none (do nothing), endl (terminate with a newline), or tab (terminate with a tab). Here is a simple example 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"
There are two special files: stdin, which reads from the keyboard, and stdout, which writes to the terminal.

A file may also be opened with xinput or xoutput instead of input or output, in which case it will read or write double precision values written in Sun Microsystem's XDR (External Data Representation) portable binary format (available on all UNIX platforms). The function file single(file) sets the file to read single precision XDR values; calling file single(file,false) sets it back to read doubles again. The default initializer for file is stdout.

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 routines

string getstring(string name, string default="", string prompt="",
                 string prefix=getstringprefix, bool save=true);
real getreal(string name, real default=0, string prompt="",
             string prefix=getstringprefix, bool save=true);
defined in plain.asy may be used to read a value from stdin. If save=true, the value is saved to the file named prefix+name, to provide the default value for subsequent runs. The default value (initially default) is displayed after prompt. The initial value of getstringprefix is ".asy_".