The Import Command

Note: This page refers to version 1 of the environment. Version 2 still has an import command but it only takes a selector as an argument instead of an agent path. Documentation for version 2 can be found within the environment.

To include other resources (scripts describing agents and components of your model) into your environment you need to use the import command. The basic behaviour of this command is to find a version of the requested agent, load it, execute, activate it and finally give you access to any actions it has defined. Your script will wait until this process is finished before continuing (by default). However, there are a number of ways it can search for a version of the agent and also many ways it can be loaded.

Import Paths

Each resource (script) has a path to identify it, much like a URL. It is a "/" separated list of names, or just a single name in some cases, where each name cannot contain spaces or special characters and the first letter must not be a number. The agent browser can be used to navigate this hierarchy of resources.

Default Search Location

By default, if the resource is already loaded it does nothing. Otherwise, it loads a version found on the remote repository and uses that. If you have local changes they are not discarded but nor are they applied unless you manually redo your history. If there is no remote version then any local version is used.

Forcing Remote Version

The default behaviour can be overridden using the remote tag. This forces it to discard any local copy and any local changes (!!), replacing it with the version on the server.

import my/agent/path remote;

Forcing Local Version

Conversely you can make sure it always uses any local version so that it does not get the newest one from the server.

import my/agent/path local;

Doing a Rebase

Finally, you might have a local version with changes but want to update that with the latest remote version. It is possible but potentially risky to update your local copy with the remote one and then to automatically re-apply all of your changes to it. This is called rebasing and uses the rebase tag. However, it is likely to introduce mistakes that need manual correct afterwards.

import my/agent/path rebase;

Post-loading

Once loaded the resource is executed, activated and imported to the calling script. However each of these activities can be changed using tags.

Forcing execution

A script is only executed the first time it is loaded. To force execution when importing regardless of whether it is already loaded, use the force tag.

import path force;

Preventing execution

To prevent execution of an agent when it is first loaded, use the noexec option.

import path noexec;