5.14 Import

While Asymptote provides many features by default, some applications require specialized features contained in external Asymptote modules. For instance, the lines

access graph;
graph.axes();

draw x and y axes on a two-dimensional graph. Here, the command looks up the module under the name graph in a global dictionary of modules and puts it in a new variable named graph. The module is a structure, and we can refer to its fields as we usually would with a structure.

Often, one wants to use module functions without having to specify the module name. The code

from graph access axes;

adds the axes field of graph into the local name space, so that subsequently, one can just write axes(). If the given name is overloaded, all types and variables of that name are added. To add more than one name, just use a comma-separated list:

from graph access axes, xaxis, yaxis;

Wild card notation can be used to add all non-private fields and types of a module to the local name space:

from graph access *;

Similarly, one can add the non-private fields and types of a structure to the local environment with the unravel keyword:

struct matrix { 
  real a,b,c,d; 
} 
 
real det(matrix m) { 
  unravel m; 
  return a*d-b*c; 
} 

Alternatively, one can unravel selective fields:

real det(matrix m) { 
  from m unravel a,b,c as C,d;
  return a*d-b*C; 
} 

The command

import graph;

is a convenient abbreviation for the commands

access graph;
unravel graph;

That is, import graph first loads a module into a structure called graph and then adds its non-private fields and types to the local environment. This way, if a member variable (or function) is overwritten with a local variable (or function of the same signature), the original one can still be accessed by qualifying it with the module name.

Wild card importing will work fine in most cases, but one does not usually know all of the internal types and variables of a module, which can also change as the module writer adds or changes features of the module. As such, it is prudent to add import commands at the start of an Asymptote file, so that imported names won't shadow locally defined functions. Still, imported names may shadow other imported names, depending on the order in which they were imported, and imported functions may cause overloading resolution problems if they have the same name as local functions defined later.

To rename modules or fields when adding them to the local environment, use as:

access graph as graph2d;
from graph access xaxis as xline, yaxis as yline;

The command

import graph as graph2d;

is a convenient abbreviation for the commands

access graph as graph2d;
unravel graph2d;

Except for a few built-in modules, such as settings, all modules are implemented as Asymptote files. When looking up a module that has not yet been loaded, Asymptote searches the standard search paths (see section Search paths) for the matching file. The file corresponding to that name is read and the code within it is interpreted as the body of a structure defining the module.

If the file name contains nonalphanumeric characters, enclose it with quotation marks:

access "/usr/local/share/asymptote/graph.asy" as graph;

from "/usr/local/share/asymptote/graph.asy" access axes;

import "/usr/local/share/asymptote/graph.asy" as graph;

It is an error if modules import themselves (or each other in a cycle). The module name to be imported must be known at compile time.

However, you can import an Asymptote module determined by the string s at runtime like this:

eval("import "+s,true);

To conditionally execute an array of asy files, use

void asy(string format, bool overwrite ... string[] s);

The file will only be processed, using output format format, if overwrite is true or the output file is missing.

One can evaluate an Asymptote expression (without any return value, however) contained in the string s with:

void eval(string s, bool embedded=false);

It is not necessary to terminate the string s with a semicolon. If embedded is true, the string will be evaluated at the top level of the current environment. If embedded is false (the default), the string will be evaluated in an independent environment, sharing the same settings module (see settings).

One can evaluate arbitrary Asymptote code (which may contain unescaped quotation marks) with the command

void eval(code s, bool embedded=false);

Here code is a special type used with quote {} to enclose Asymptote code like this:

real a=1;
code s=quote {
  write(a);
};
eval(s,true);        // Outputs 1

To include the contents of a file graph verbatim (as if the contents of the file were inserted at that point), use one of the forms:

include graph;

include "/usr/local/share/asymptote/graph.asy";

To list all global functions and variables defined in a module named by the contents of the string s, use the function

void list(string s, bool imports=false);

Imported global functions and variables are also listed if imports is true.