add reference/modules-and-loading

2 files changed, 101 insertions, 1 deletions

diff --git a/docs/reference/03-6_modules-and-loading.md b/docs/reference/03-6_modules-and-loading.md
new file mode 100644
index 0000000..4735d60
--- /dev/null
+++ b/docs/reference/03-6_modules-and-loading.md
@@ -0,0 +1,100 @@
+To reuse code across projects, `alv` code can be split up over multiple files
+and loaded as *modules*.
+
+## loading modules
+
+To load modules, [require][], [import][] and [import*][] can be used:
+
+- [require][] loads a module and returns its value.
+- [import][] requires a module and makes its value available in a
+  symbol with the same name. `(import my-module)` is equivalent to
+  `(def my-module (require "my-module"))`.
+- [import*][] loads a module and merges all exported symbols into the active
+  scope. `(import* my-module)` is equivalent to `(use (require "my-module"))`.
+  It assumes the module exports a scope with definitions to be imported.
+
+[require][] can load two types of modules: *native* modules written in
+Lua/MoonScript (such as everything listed in this reference), and modules
+written in `alv` itself. The latter are looked up relative to the file
+containing the `(require …)` expression, and are should match the module name
+with the file extension `.alv`; i.e. `my-module.alv` for the example above.
+
+If a module is imported multiple times, it is only evaluated once and its
+result is reused.
+
+## writing modules
+When an alv script file is imported, its 'value' is that of the last expression
+inside it:
+
+`my-module.alv`
+
+    (print "loading my-module...")
+    
+    4
+
+`main.alv`
+
+    (import* string)
+    (print (str "my-module's value is " (require "my-module")))
+    
+    #(output:
+      loading my-module...
+      my-module's value is 4)
+
+Often it is useful to export multiple values from a file, for example when
+writing a library containing multiple functions. There are two operators to
+allow this: [export][] and [export*][].
+
+[export][] creates a new *scope* and evaluates all its arguments in it, just
+like [do][]. However it doesn't return the result of the evaluations, but
+rather the newly created scope. It can therefore be combined with [def][],
+[defn][] etc. to export symbol definitions:
+
+`my-module.alv`
+
+    (import* math string)
+    (export
+      (def a-value 7)
+      
+      (defn print-doubled (x) (print (str x " doubled is " (* x 2)))))
+
+`main.alv`
+
+    (import* string)
+    (import my-module)
+    
+    (print (str "my-module/a-value is " my-module/a-value))
+    (my-module/print-doubled 4)
+    
+    #(output:
+      my-module/a-value is 7
+      4 doubled is 8)
+
+[export*][] on the other hand operates on the containing scope rather than
+creating a new one. When Used without any arguments, it returns the containing
+scope itself and can be used to (re-)export everything that is currently
+defined. When arguments are passed, only those symbols that are explicitly
+mentioned are exported:
+
+`my-module.alv`
+
+    (def a 1)
+    (def b 2)
+    (def c 3)
+    
+    (export* a b)
+
+`main.alv`
+
+    (import* string)
+    (import* my-module)
+    
+    (print (str "a is " a))
+    (print (str "b is " b))
+    (print (str "c is " c))
+    
+    #(output:
+      a is 1
+      b is 2
+      reference error: undefined symbol 'c')
+
diff --git a/docs/reference/index.md b/docs/reference/index.md
index bf8e5f3..61fa464 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -18,7 +18,7 @@ own module or contributing to alive, check out the
    3. [functions](03-3_functions.html)
    4. [dynamic symbols](03-4_dynamic-symbols.html)
    5. [loops](03-5_loops.html)
-   6. modules and loading
+   6. [modules and loading](03-6_modules-and-loading.html)
 4. runtime
    1. result kinds
    2. pure operators