diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 83 |
1 files changed, 75 insertions, 8 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 ----- |