Info Catalog asymptote: Casts asymptote: Programming asymptote: Static

asymptote: Import

 
 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
 (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 (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'.
 

Info Catalog asymptote: Casts asymptote: Programming asymptote: Static