Importing External Scripts

A guide to accessing resources from other script files.

Introduction

The import statement allows you to access resources from a different script in your current script file.

Example

import [math]
assert {run math[floor] 5.5} == 5

Resources are imported by name, without the .script extension.

When a script resource is imported the script is run and the result is automatically packed into the variable named after the script.

This means that import [my_script, other] is functionally equivalent to the following:

my_script = run my_script.script
other = run other.script

The import statement benefits from improved performance, error handling and may have access to some non-script resources known by the environment.

Native Library Scripts

The script environment contains 'native' scripts. Unlike user-loaded scripts, these can be written in other programming languages (or dynamically-created).

They are (typically) loaded before any user scripts are parsed.

Domains can add their own native scripts.

Native scripts are able to run significantly faster than interpreted scripts and can provide safe access to resources or functionality not available directly in the language.

The following native scripts are available in the default CraftScript environment:

Name	Description
math	A set of simple mathematical functions, e.g. sin, round, sqrt.
parser	A function that can parse source code text into an executable script object.
global	A key<->value map of global variables available anywhere in this environment.

You can replace a native script with your own copy by loading a script with the same name (e.g. math.script).

While this is not recommended (as native scripts have significant performance benefit) it can be used to replace or override behaviour.

Import Results

The result of the imported resource (e.g. import [math]) is stored in the variable of the same name (e.g. math).

When a user-created script is imported it is run.

The imported value is the result of the script, not the executable script object.

The result of a script is typically whatever is left on its final executed line.

Example

The result of the following script is 15.

sum.script

var = 10
var + 5

The numerical value 15 is returned at the end of the final statement 10 + 5.

When importing this script, the imported value would be the result of this code (15).

import [sum]
assert sum == 15

Scripts that are designed to be imported will typically take one of three forms.

Function Import

Some scripts may define a single function, with the goal of this being imported by another script.

message.script

function {
    require [name, message]
    /msg {name} {message}
}

The result of this import will be an executable function.

import [message]
run message ["Notch", "hello how are you"]

This is slightly different from simply executing a script with the code inside.

As scripts are a self-contained executable, when running a script itself any errors will be printed and the program will attempt to continue.

When running a function, any errors will be fatal to the current program.

In other words, running a function is like running the code in the current script.

Data Import

Some scripts may define a data structure, such as an environment configuration file, that multiple scripts may want to access.

person.script

struct {
    name = "Jeremy"
    age = 40
    height = 1.7
}

The result of this import will be a copy of the data structure.

import [person]

if person[age] >= 21 {
    /print {person[name]} can drink in america
}

Value Import

Some scripts may simply return a concrete value from an import.

While this value cannot be based on variables (since imports do not take parameters when executing) it can be based on the environment, e.g. the current time.

Assume time.script is a native script providing the current time of day.

import [time]
/print The time is {time}!

Global variables are accessed using a value import.

import [global]
if global[greeting] == null {
    global[greeting="hello there!"]
}