wren

Modularity

Once you start writing programs that are more than little toys, you quickly run into two problems:

1. You want to break them down into multiple smaller files to make it easier to find your way around them.

2. You want to reuse pieces of them across different programs.

To address those, Wren has a simple module system. A file containing Wren code defines a module. A module can use the code defined in another module by importing it. You can break big programs into smaller modules that you import, and you can reuse code by having multiple programs share the use of a single module.

Wren does not have a single global scope. Instead, each module has its own top-level scope independent of all other modules. This means, for example, that two modules can define a top-level variable with the same name without causing a name collision. Each module is, well, modular.

Importing, briefly #

When you run Wren and give it a file name to execute, the contents of that file define the “main” module that execution starts at. To load and execute other modules, you use an import statement:

import "beverages" for Coffee, Tea

This finds a module named “beverages” and executes its source code. Then, it looks up two top-level variables, Coffee and Tea in that module and creates new variables in this module with their values.

This statement can appear anywhere a variable declaration is allowed, even inside blocks:

if (thirsty) {
  import "beverages" for Coffee, Tea
}

If you need to import a variable under a different name, you can use import "..." for Name as OtherName. This looks up the top-level variable Name in that module, but declares a variable called OtherName in this module with its value.

import "liquids" for Water //Water is now taken
import "beverages" for Coffee, Water as H2O, Tea
// var water = H2O.new()

If you want to load a module, but not bind any variables from it, you can omit the for clause:

import "some_imperative_code"

That’s the basic idea. Now let’s break it down into each of the steps it performs:

1. Locate the source code for the module.
2. Execute the imported module’s code.
3. Bind new variables in the importing module to values defined in the imported module.

We’ll go through each step:

Locating a module #

The first thing you need to do to import a module is actually find the code for it. The import specifies a name—some arbitrary string that is used to uniquely identify the module. The embedding application controls how that string is used to locate a blob of source code.

When the host application creates a new Wren VM, it provides a module loader function:

WrenConfiguration config;
config.loadModuleFn = loadModule;

// Other configuration...

WrenVM* vm = wrenNewVM(&config);

That function has this signature:

WrenLoadModuleResult WrenLoadModuleFn(WrenVM* vm, const char* name);

Whenever a module is imported, the VM calls this and passes it the name of the module. The embedder is expected to return the source code contents of the module in a WrenLoadModuleResult. When you embed Wren in your app, you can handle this however you want: reach out to the file system, look inside resources bundled into your app, whatever.

You can return the source field as NULL from this function to indicate that a module couldn’t be found. When you do this, Wren will report it as a runtime error.

The command-line loader #

The Wren CLI command-line tool has a very simple lookup process. It appends the module name and “.wren” to the directory where the main module was loaded and looks for that file. So, let’s say you run:

$ wren code/my_program.wren

And that main module has:

import "some/module"

Then the command-line VM will try to find /code/some/module.wren. By convention, forward slashes should be used as path separators, even on Windows, to help ensure your scripts are platform-independent. (Forward slashes are a valid separator on Windows, but backslashes are not valid on other OSes.)

Executing the module #

Once we have the source code for a module, we need to run it. First, the VM takes the fiber that is executing the import statement in the importing module and pauses it.

Then it creates a new module object—a new fresh top-level scope, basically—and a new fiber. It executes the new module’s code in that fiber and scope. The module can run whatever imperative code it wants and define whatever top-level variables it wants.

When the module’s code is done being executed and its fiber completes, the suspended fiber for the importing module is resumed. This suspending and resuming is recursive. So, if “a” imports “b” which imports “c”, both “a” and “b” will be suspended while “c” is running. When “c” is done, “b” is resumed. Then, when “b” completes, “a” is resumed.

Think of it like traversing the tree of imports, one node at a time. At any given point in time, only one module’s code is running.

Binding variables #

Once the module is done executing, the last step is to actually import some data from it. Any module can define “top-level” variables. These are simply variables declared outside of any method or function.

These are visible to anything inside the module, but they can also be exported and used by other modules. When Wren executes an import like:

import "beverages" for Coffee, Tea

First it runs the “beverages” module. Then it goes through each of the variable names in the for clause. For each one, it looks for a top-level variable with that name in the imported module. If a variable with that name can’t be found in the imported module, it’s a runtime error.

Otherwise, it gets the current value of the variable and defines a new variable in the importing module with the same name and value. It’s worth noting that the importing module gets its own variable whose value is a snapshot of the value of the imported variable at the time it was imported. If either module later assigns to that variable, the other won’t see it. It’s not a “live” connection.

In practice, most top-level variables are only assigned once anyway, so this rarely makes a difference.

Shared imports #

Earlier, I described a program’s set of modules as a tree. Of course, it’s only a tree of modules if there are no shared imports. But consider a program like:

// main.wren
import "a"
import "b"

// a.wren
import "shared"

// b.wren
import "shared"

// shared.wren
System.print("Shared!")

Here, “a” and “b” both want to use “shared”. If “shared” defines some top-level state, we only want a single copy of that in memory. To handle this, a module’s code is only executed the first time it is loaded. After that, importing the module again just looks up the previously loaded module.

Internally, Wren maintains a map of every module it has previously loaded. When a module is imported, Wren looks for it in that map first before it calls out to the embedder for its source.

In other words, in that list of steps above, there’s an implicit zeroth step: “See if we already loaded the module and reuse it if we did”. That means the above program only prints “Shared!” once.

Cyclic imports #

You can even have cycles in your imports, provided you’re a bit careful with them. The loading process, in detail, is:

1. See if we have already created a module with the given name.
2. If so, use it.
3. Otherwise, create a new module with the name and store it in the module registry.
4. Create a fiber for it and execute its code.

Note the order of the last two steps. When a module is loaded, it is added to the registry before it is executed. This means if an import for that same module is reached while the module itself or one of its imports is executing, it will be found in the registry and the cycle is short-circuited.

For example:

// main.wren
import "a"

// a.wren
System.print("start a")
import "b"
System.print("end a")

// b.wren
System.print("start b")
import "a"
System.print("end b")

This program runs successfully and prints:

start a
start b
end b
end a

Where you have to be careful is binding variables. Consider:

// main.wren
import "a"

// a.wren
import "b" for B
var A = "a variable"

// b.wren
import "a" for A
var B = "b variable"

The import of “a” in b.wren will fail here. If you trace the execution, you get:

1. Execute import "a" in “main.wren”. That suspends “main.wren”.
2. Execute import "b" in “a.wren”. That suspends “a.wren”.
3. Execute import "a" in “b.wren”. Since “a” is already in the module map, this does not suspend it.

Instead, we look for a variable named A in that module. But it hasn’t been defined yet since “a.wren” is still sitting on the import "b" for B line before the declaration. To get this to work, you would need to move the variable declaration above the import:

// main.wren
import "a"

// a.wren
var A = "a variable"
import "b" for B

// b.wren
import "a" for A
var B = "b variable"

Now when we run it, we get:

1. Execute import "a" in “main.wren”. That suspends “main.wren”.
2. Define A in “a.wren”.
3. Execute import "b" in “a.wren”. That suspends “a.wren”.
4. Execute import "a" in “b.wren”. Since “a” is already in the module map, this does not suspend it. It looks up A, which has already been defined, and binds it.
5. Define B in “b.wren”.
6. Complete “b.wren”.
7. Look up B in “b.wren” and bind it in “a.wren”.
8. Resume “a.wren”.

This sounds super hairy, but that’s because cyclic dependencies are hairy in general. The key point here is that Wren can handle them in the rare cases where you need them.

Exiting a module early #

Although the return statement is normally used to exit from a method or a function, it can also be used from a module’s top-level code to exit the module. For example, if the script consists of a single module, this code would exit the module (and therefore the script) early:

for (i in 1..2) {
  if (i == 2) return
  System.print(i)  //>  prints 1 but not 2
}
System.print(3)    //>  not reached

Although it is not invalid to return a value, there is no way to access that value and it is therefore simply discarded.