Asymptote
can read and write text files (including comma-separated
value) files and portable XDR (External Data Representation)
binary files.
An input file can 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. If Asymptote
is compiled with
support for libcurl
, name
can be a URL.
Unless the -noglobalread
command-line option is specified,
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.
Reading from files in other directories is allowed unless the
-noglobalread
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, endl); // 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,
or to read the entire file into a string.
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.
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
(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 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 magick
and animate
,
respectively, with the arguments args
and the file name constructed
from the strings file
and format
.