Skip to main content

Importing external code and data

It is possible to import external arr.ai scripts. Every imported arr.ai script must be a valid arr.ai expression. There are multiple ways to import arr.ai scripts.

Package Imports​

Package imports allow for importing files relative to a "root". The root for a script is the location of the nearest go.mod file, in either the same directory as the importing script or an ancestor directory.

You may define multiple go.mod files in the same repository to create multiple import roots for different parts of the codebase.

Example:

//{/path/to/script}

With the following directories structure:

project
├── go.mod
├── nested
│   ├── child1.arrai
│   ├── go.mod
│   └── path
│       └── to
│           └── grandchildren.arrai
├── parent.arrai
└── path
    └── to
        └── child2.arrai

In that scenario, the root path of parent.arrai and path/to/child2.arrai is project/ and the root path for nested/child1.arraiand nested/path/to/grandchildren.arrai is project/nested/. This means that any Package imports in parent.arrai and child2.arrai will be relative to project/ and Package imports in child1.arrai and grandchildren.arrai will be relative to project/nested.

Relative Imports​

It is possible to import a script relative to the importer's directory.

A relative import path begins with a .. For example:

//{./path/to/script}

It is not possible to import anything from the parent directories.

# this is not allowed
//{../script}
//{./../../script}

However, sometimes importing above the parent directory might be necessary for testing locally. It is possible to work around this by using the Package import and go.mod. Since go.mod also handles dependencies of arr.ai scripts, it is possible to use replace to a dependency so that it points to a custom URL or a filepath.

Example:

go.mod

go 1.15

require some/dependency/path v1.2.3

replace some/dependency/path v1.2.3 => ../some/custom/dependency

Note: There are plans to deprecate the use of Go dependencies and go.mod for managing arr.ai imports. Whatever the new solution is will have an equivalent mechanism for replace.

Remote Imports​

Remote imports allow importing of an arr.ai script that is hosted in a GitHub repository. This can be done by the following:

//{github.com/username/repo_name/path/to/script}

Versioning​

By default, arrai fetches the latest available version of the repository.

If the importing script's project has a go.mod (found the same way as for Package Imports above) that already requires the module being imported, that pinned version is used instead — including following a replace directive that points it at a fork or a local filepath. This lets you pin or override remote imports the same way you would a regular Go dependency:

require github.com/username/repo_name v1.2.3

replace github.com/username/repo_name => ../local/fork

It is not possible to pin a version inline in the import path itself (e.g. //{github.com/username/repo_name@v1.2.3/path/to/script}); add or update the require line in go.mod instead.

HTTP Imports​

HTTP imports allow importing of a remotely-hosted arr.ai script given its URL. The server must return an arr.ai script as a text. This can be done by the following:

//{http://www.somewebsite.com/path/to/arrai}

or

//{https://www.somewebsite.com/path/to/arrai}

Non-arr.ai import​

arr.ai supports importing of non-arr.ai files. The currently supported files are the following file formats:

  • JSON
  • YAML

This can be done by adding the file extension to explicitly state file format like the following:

//{./path/to/file.json}

For importing arr.ai scripts, it is not necessary to add the .arrai extension as it is always assumed that the files are arr.ai scripts, unless explicitly stated.