First pass at docs for modules.

doc/site/error-handling.markdown

@@ -28,7 +28,7 @@ same name in the same scope. So if you do:
 Wren tells you:
 
     :::text
-    [script.wren line 2] Error on 'a': Global variable is already defined.
+    [script.wren line 2] Error on 'a': Top-level variable is already defined.
 
 Note that it does this before it executes *any* code. Unlike some other
 scripting languages, Wren tries to help you find your errors as soon as

doc/site/modules.markdown

@@ -0,0 +1,202 @@
+^title Modules
+^category language
+
+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:
+
+    :::dart
+    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:
+
+    :::dart
+    if (thirsty) {
+      import 'beverages' for Coffee, Tea
+    }
+
+If you want to load a module, but not bind any variables from it, you can omit the `for` clause:
+
+    :::dart
+    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:
+
+    :::c
+    WrenConfiguration config;
+    config.loadModuleFn = loadModule;
+
+    // Other configuration...
+
+    WrenVM* vm = wrenNewVM(&config);
+
+That function has this signature:
+
+    :::c
+    char* 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. 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 `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 default little command-line VM that comes with Wren 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:
+
+    :::bash
+    $ wren /code/my_program.wren
+
+And that main module has:
+
+    :::dart
+    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](variables.html). These are simply variables declared outside of any [method](classes.html#methods) or [function](functions.html).
+
+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:
+
+    :::dart
+    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 programs 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:
+
+    :::dart
+    // main.wren
+    import "a"
+    import "b"
+
+    // a.wren
+    import "shared"
+
+    // b.wren
+    import "shared"
+
+    // shared.wren
+    IO.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:
+
+    :::dart
+    // main.wren
+    import "a"
+
+    // a.wren
+    IO.print("start a")
+    import "b"
+    IO.print("end a")
+
+    // b.wren
+    IO.print("start b")
+    import "a"
+    IO.print("end b")
+
+This program runs successfully and prints:
+
+    :::text
+    start a
+    start b
+    end b
+    end a
+
+Where you have to be careful is binding variables. Consider:
+
+    :::dart
+    // 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:
+
+    :::dart
+    // main.wren
+    import "a"
+
+    // a.wren
+    import "b" for B
+    var A = "a variable"
+
+    // b.wren
+    var B = "b variable"
+    import "a" for A
+
+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.

doc/site/template.html

@@ -31,6 +31,7 @@
         <li><a href="variables.html">Variables</a></li>
         <li><a href="control-flow.html">Control Flow</a></li>
         <li><a href="error-handling.html">Error Handling</a></li>
+        <li><a href="modules.html">Modules</a></li>
       </ul>
     </section>
     <section>

doc/site/variables.markdown

@@ -28,10 +28,11 @@ until the end of the [block](syntax.html#blocks) where that definition appears.
     }
     IO.print(a) // ERROR! a doesn't exist anymore.
 
-Variables defined at the top level of a script are *global*. All other
-variables are *local*. Declaring a variable in an inner scope with the same
-name as an outer one is called *shadowing* and is not an error (although it's
-not something you likely intend to do much).
+Variables defined at the top level of a script are *top-level* and are visible
+to the [module](modules.html) system. All other variables are *local*.
+Declaring a variable in an inner scope with the same name as an outer one is
+called *shadowing* and is not an error (although it's not something you likely
+intend to do much).
 
     :::dart
     var a = "outer"