asymptote: Files
6.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 comment="#", string mode="");
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 'comment' 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.
One can change the current working directory for read operations 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, string comment="#", string mode="");
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', any
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 '-globalwrite' (or '-nosafe')
command-line option is specified. The function 'string mktemp(string
s)' may be used to create and return the name of a unique temporary file
in the current directory based on the string 's'.
There are two special files: 'stdin', which reads from the keyboard,
and 'stdout', which writes to the terminal. The implicit initializer
for files is 'null'.
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), 'flush'
(output buffered data), 'endl' (terminate with a newline and flush),
'newl' (terminate with a newline), 'DOSendl' (terminate with a DOS
newline and flush), 'DOSnewl' (terminate with a DOS newline), 'tab'
(terminate with a tab), or 'comma' (terminate with a comma). 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 be opened with 'mode="xdr"', to read or write double
precision (64-bit) reals and single precision (32-bit) integers in Sun
Microsystem's XDR (External Data Representation) portable binary format
(available on all 'UNIX' platforms). Alternatively, a file may also be
opened with 'mode="binary"' to read or write double precision reals and
single precision integers in the native (nonportable) machine binary
format. The virtual member functions 'file singlereal(bool b=true)' and
'file singleint(bool b=true)' be used to change the precision of real
and integer I/O operations, respectively, for an XDR or binary file 'f'.
Similarly, the function 'file signedint(bool b=true)' can be used to
modify the signedness of integer reads and writes for an XDR or binary
file 'f'.
The virtual members 'name', 'mode', 'singlereal', 'singleint', and
'signedint' may be used to query the respective parameters for a given
file.
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)'. The function 'int precision(file file=stdout, int
digits=0)' sets the number of digits of output precision for 'file' to
'digits', provided 'digits' is nonzero, and returns the previous
precision setting. The function 'int tell(file)' returns the current
position in a file relative to the beginning. The routine '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 to the next 'n' output lines, 's' followed by
'Enter' to scroll without further interruption, or 'q' followed by
'Enter' to quit the current output operation. 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 store=true);
int getint(string name="", int default=0, string prompt="",
bool store=true);
real getreal(string name="", real default=0, string prompt="",
bool store=true);
pair getpair(string name="", pair default=0, string prompt="",
bool store=true);
triple gettriple(string name="", triple default=(0,0,0), string prompt="",
bool store=true);
defined in the module 'plain' may be used to prompt for a value from
'stdin' using the GNU 'readline' library. If 'store=true', the history
of values for 'name' is stored in the file '".asy_history_"+name' (
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 functions are
based on the internal routines
string readline(string prompt="", string name="", bool tabcompletion=false);
void saveline(string name, string value, bool store=true);
Here, 'readline' prompts the user with the default value formatted
according to 'prompt', while 'saveline' is used to save the string
'value' in a local history named 'name', optionally storing the local
history in a file '".asy_history_"+name'.
The routine 'history(string name, int n=1)' can be used to look up
the 'n' most recent values (or all values up to 'historylines' if 'n=0')
entered for string 'name'. The routine 'history(int n=0)' returns the
interactive history. For example,
write(output("transcript.asy"),history());
outputs the interactive history to the file 'transcript.asy'.
The function 'int delete(string s)' deletes the file named by the
string 's'. Unless the '-globalwrite' (or '-nosafe') option is enabled,
the file must reside in the current directory. The function 'int
rename(string from, string to)' may be used to rename file 'from' to
file 'to'. Unless the '-globalwrite' (or '-nosafe') option is enabled,
this operation is restricted to the current directory. The functions
int convert(string args="", string file="", string format="");
int animate(string args="", string file="", string format="");
call the 'ImageMagick' commands 'convert' and 'animate', respectively,
with the arguments 'args' and the file name constructed from the strings
'file' and 'format'.
Info Catalog
asymptote: Frames and pictures
asymptote: Programming
asymptote: Variable initializers