manpagez: man pages & more
info asymptote
Home | html | info | man
 [ << ] [ < ] [ Up ] [ > ] [ >> ] [Top] [Contents] [Index] [ ? ]

## 6.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 an existing 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`.

 [ << ] [ < ] [ Up ] [ > ] [ >> ] [Top] [Contents] [Index] [ ? ]

This document was generated on May 24, 2014 using texi2html 5.0.

```© manpagez.com 2000-2018
Individual documents may contain additional copyright information.
```