Update README, misc cleanups

4 files changed, 97 insertions, 21 deletions

diff --git a/README.md b/README.md
index dd99d84..2536f35 100644
--- a/README.md
+++ b/README.md
@@ -1,23 +1,90 @@
-Cratera Compiler
-================
+The Cratera Programming Language
+================================
 
-This repo contains the Cratera to Lua compiler, as well as support components for the Cratera to Lua compiler, namely a pure-Lua Lua tokenizer and a table-based parser thing.
+Cratera is a language very similar to Lua, (in fact it's a fork of Lua's syntax) and as such most of the Lua manual applies to it, with the following differences.
 
-The Cratera Programming Language
---------------------------------
+Trait method call syntax
+------------------------
 
-Cratera is a language very similar to Lua, and as such most of the Lua manual applies to it. Additionally, it supports the following syntax sugar, called "traits":
+Cratera adds the following syntax on top of Lua, called a "trait method call":
 
-    mytable:[mytrait].myfunction(myargument)
+    mytable:[MyTrait].myfunction(myargument)
 
 which is equivalent to:
 
-    mytable[mytrait].myfunction(mytable, myargument)
+    mytable[MyTrait].myfunction(mytable, myargument)
 
 This syntax sugar is similar to the "methods" syntax sugar ([Lua 5.3 §3.4.10](http://www.lua.org/manual/5.3/manual.html#3.4.10),
 [Lua 5.2 §3.4.9](http://www.lua.org/manual/5.2/manual.html#3.4.9), [Lua 5.1 §2.5.8](http://www.lua.org/manual/5.1/manual.html#2.5.8)),
 and, indeed, `mytable` is only evaluated once.
 
+Traits
+------
+
+(TODO)
+
+Module layout
+-------------
+
+Cratera uses a module system that integrates with Lua's, effectively making Cratera modules interchangeable with Lua modules. However, the file layout is a bit different, particularly for submodules.
+
+For starters, Cratera module filenames end in `.cratera`, so the call:
+
+    local mymodule = require "mymodule"
+
+will look for the file `mymodule.cratera`. But when requiring a submodule, the call:
+
+    local submodule = require "mymodule.submodule"
+
+will look for the file `mymodule.cratera.d/submodule.cratera`. This uses the old UNIX convention of stuffing subfiles of a file `filename` into a directory `filename.d`, for example `profile.d` or `ld.so.conf.d`.
+
+Finally, the Cratera path can be set independently of the Lua path, with the environment variable `CRATERA_PATH` or the Cratera global `craterapath`.
+
+Lua interoperability
+--------------------
+
+### Bootstrapping
+
+Cratera can be bootstrapped from Lua by `require "cratera.bootstrap"`, this initializes the Cratera module system and the Cratera standard library. From here, it's possible to `require` Cratera modules or `load` Cratera scripts:
+
+    local cratera = require "cratera.bootstrap"
+    local cratera_module = require "cratera_module"
+    -- N.B. cratera.loadfile for Cratera scripts, loadfile for regular Lua scripts
+    return cratera.loadfile("myscript.cratera")(...)
+
+However, the provided bootstrap module may not be suitable for all Lua environments. The user is encouraged to bring their own bootstrap.
+
+### Using Lua from Cratera
+
+You can access Lua globals from Cratera using the `lua` table (including `lua.load` - the Lua load function). By default, the Cratera global environment also proxies over to the Lua environment, with a few overrides worth highlighting:
+
+- In Cratera, `load` and `loadfile` refer to the Cratera loader, and by default also set the environment of the loaded function to the Cratera environment.
+- Cratera does not expose `dofile` and `dostring` functions, their slots are set to `false`.
+- `_VERSION` refers to the Cratera version.
+
+### Using Cratera traits from Lua
+
+Since Cratera is simple syntax sugar on top of Lua, it is possible (tho not recommended) to use Cratera traits from plain Lua, by simply hand-coding the desugaring oneself.
+
+    local cratera_obj, CrateraTrait = ...
+    cratera_obj[CrateraTrait].func(cratera_obj)
+
+Building Cratera
+================
+
+Cratera needs to know a few things about the system before it can be used, so the `build.sh` script attempts to provide those things. Most importantly, it needs to know what Lua interpreter to use for the Cratera interpreter, as well as the default Cratera module path.
+
+You can get an overview of these settings and more by running `./build.sh help`. You can override these settings, for example to set a different Lua interpreter, `LUA_INTERPRETER=luajit ./build.sh [command]`.
+
+To build Cratera, run `./build.sh` or `./build.sh build`.
+
+Cratera Compiler
+================
+
+(FIXME clean this up)
+
+The files in `src/cratera/` include the Cratera to Lua compiler, as well as support components for the Cratera to Lua compiler, namely a pure-Lua Lua tokenizer and a table-based parser thing.
+
 Usage
 -----
 
diff --git a/build.sh b/build.sh
index 06686dd..325b3a3 100755
--- a/build.sh
+++ b/build.sh
@@ -8,6 +8,7 @@ case "$LUA_INTERPRETER" in
 		ENV_WRAPPER=${ENV_WRAPPER:-"$(command -v env)"}
 		;;
 esac
+cratera_path_for_display="$(env -i "$LUA_INTERPRETER" src/host/genpath.lua display)"
 
 do_build() {
 	mkdir -p out/lua/cratera/prebuilt/ || exit 1
@@ -23,11 +24,15 @@ do_build() {
 	fi
 	tail -n +2 src/bin/cratera.lua >>out/bin/cratera || exit 1
 	chmod +x out/bin/cratera || exit 1
-	env -i "$LUA_INTERPRETER" src/host/genpath.lua >out/lua/cratera/prebuilt/path.lua || exit 1
+	if [ -n "${DEFAULT_CRATERA_PATH+x}" ]; then
+		env -i "DEFAULT_CRATERA_PATH=$DEFAULT_CRATERA_PATH" "$LUA_INTERPRETER" src/host/genpath.lua >out/lua/cratera/prebuilt/path.lua || exit 1
+	else
+		env -i "$LUA_INTERPRETER" src/host/genpath.lua >out/lua/cratera/prebuilt/path.lua || exit 1
+	fi
 }
 
 test_wrapper() {
-	eval "$@" || {
+	eval "$*" || {
 		printf 'Test failed:'
 		printf ' %s' "$@"
 		printf '\n'
@@ -74,11 +79,15 @@ case "$1" in
 		printf '%s\n' \
 			'The Cratera "Build System"' \
 			'To build, use '\''./build.sh build'\''. Files will be put in '\''out/'\''.' \
-			'To run tests, use '\''./build.sh test'\''.' \
+			'To run tests, use '\''./build.sh test'\'', this will also rebuild cratera.' \
+			'To run tests without rebuilding, use '\''./build.sh test-only'\''.' \
+			'    (Note: you must build at least once before using this option.)' \
 			'The currently selected Lua interpreter is:' \
 			"$(printf '    LUA_INTERPRETER=%s' "$LUA_INTERPRETER")" \
 			'The currently selected env wrapper is:' \
-			"$(printf '    ENV_WRAPPER=%s' "$ENV_WRAPPER")"
+			"$(printf '    ENV_WRAPPER=%s' "$ENV_WRAPPER")" \
+			'The default Cratera path is:' \
+			"$(printf '    CRATERA_DEFAULT_PATH=%s' "$cratera_path_for_display")" \
 		;;
 	interp)
 		do_build
diff --git a/src/cratera.cratera.d/lib.cratera b/src/cratera.cratera.d/lib.cratera
index 6e1627e..69ca476 100644
--- a/src/cratera.cratera.d/lib.cratera
+++ b/src/cratera.cratera.d/lib.cratera
@@ -39,9 +39,5 @@ function cratera_env.load(chunk, chunkname, mode, env)
 end
 
 -- cratera opts not to support dostring/dofile.
-if lua.dostring then
-    cratera_env.dostring = false
-end
-if lua.dofile then
-    cratera_env.dofile = false
-end
+cratera_env.dostring = false
+cratera_env.dofile = false
diff --git a/src/host/genpath.lua b/src/host/genpath.lua
index e12e9a8..c11caab 100644
--- a/src/host/genpath.lua
+++ b/src/host/genpath.lua
@@ -2,8 +2,8 @@
 -- package.path, but every .lua is replaced with .cratera
 -- or use an explicit CRATERA_PATH
 
-if os.getenv("DEFAULT_CRATERA_PATH") then
-    print(string.format("return %q", os.getenv("DEFAULT_CRATERA_PATH")))
+if os.getenv("CRATERA_DEFAULT_PATH") then
+    print(string.format("return %q", os.getenv("CRATERA_DEFAULT_PATH")))
     return
 end
 
@@ -22,4 +22,8 @@ for path_part in possible_cratera_path:gmatch(pathfinder) do
     end
 end
 
-print(string.format("return %q", table.concat(path_parts, pathsep)))
+if arg[1] == "display" then
+    print(table.concat(path_parts, pathsep))
+else
+    print(string.format("return %q", table.concat(path_parts, pathsep)))
+end