Builtin modules

This changeset adds a fixed version of the Numbat standard library
(`prelude`) to the binary itself. This way, the installation procedure
for the typical user is greatly simplified. They just need one
executable.

Customization is still possible, as described here:
https://numbat.dev/doc/cli-customization.html

closes #165

README.md

@@ -141,10 +141,6 @@ please consider contributing. Or try [GNU units](https://www.gnu.org/software/un
 
 ## Development
 
-Clone the repository and make sure to properly set up the Numbat modules path. This can
-either be done by copying the `modules/` folder to the [appropriate location](https://numbat.dev/doc/cli-customization.html#module-paths)
-on your operating system, or by pointing the `NUMBAT_MODULES_PATH` environment variable to the `modules/` folder.
-
 Run Numbat CLI
 ```
 cargo run -- <numbat args>
@@ -159,3 +155,13 @@ Run all tests
 ```
 cargo test
 ```
+
+### Working on the `prelude`
+
+If you are working on [Numbats standard library](modules/), it is convenient to point
+the `NUMBAT_MODULES_PATH` environment variable to the `modules/` folder. This way,
+you don't have to recompile Numbat to see your changes.
+
+Alternatively, you can create a symlink from `~/.config/numbat/modules` to the `modules/`
+folder in the repository (see [this page](https://numbat.dev/doc/cli-customization.html#module-paths)
+for the standard paths on other operating systems.

book/src/cli-customization.md

@@ -2,9 +2,9 @@
 
 ## Startup
 
-By default, Numbat will load the following files during startup:
+By default, Numbat will load the following modules/files during startup, in order:
 
-- Numbat Prelude (a module called `prelude`, from `<module-path>/prelude.nbt`)
+- Numbat Prelude (a module called `prelude`, either from `<module-path>/prelude.nbt` if available, or the builtin version)
 - The user initialization file, if available (a file called `init.nbt` from `<config-path>/init.nbt`)
 
 ### Config path
@@ -19,12 +19,14 @@ Numbat's configuration folder (`<config-path>` above) can be found under:
 
 ## Module paths
 
-Numbat will load modules from the following directories (`<module-path>` above).
+Numbat will load modules from the following sources.
 Entries higher up in the list take precedence.
 
+* `$NUMBAT_MODULES_PATH` — If present, this environment variable can point to a single directory or contain a `:`-separated list of paths
 * `<config-path>/modules` — User-customized module folder
-* `/usr/share/numbat/modules` — on Linux and macOS
-* `C:\Program Files\numbat\modules` — on Windows
+* `/usr/share/numbat/modules` — System-wide module folder (Linux and macOS)
+* `C:\Program Files\numbat\modules` — System-wide module folder (Windows)
+* Builtin modules inside the `numbat` binary
 
 ## Customization
 
@@ -36,17 +38,23 @@ create a `init.nbt` file in your config folder (e.g. `~/.config/numbat/init.nbt`
 ### Custom modules
 
 You can also create your own modules that can be loaded on demand. To this end,
-create a new file, say `<module-path>/finance.nbt` in one of the module folders (e.g. `~/.config/numbat/modules/finance.nbt` on Linux). This module can then be loaded using
+create a new file, say `<module-path>/user/finance.nbt` in one of the module folders
+(e.g. `~/.config/numbat/modules/custom/finance.nbt` on Linux). This module can then be
+loaded using
 
 ``` numbat
-use finance
+use custom::finance
 ```
 
 in your Numbat scripts or in the REPL. You can also load custom modules from `init.nbt`
 if you want to have them available all the time.
 
-You can also organize modules into subfolders (e.g. `<module-path>/finance/functions.nbt`). In that case, you can load them using
+You can also organize modules into subfolders (e.g. `<module-path>/custom/finance/functions.nbt`).
+In that case, you can load them using
 
 ``` numbat
-use finance::functions
+use custom::finance::functions
 ```
+
+In fact, the `custom` folder is just a convention to avoid name clashes with the
+[standard library](https://github.com/sharkdp/numbat/tree/master/modules).

book/src/cli-installation.md

@@ -17,14 +17,6 @@ to try it immediately (unpacks to `/tmp` and executes from there).
 For a proper installation, download the latest release
 [here](https://github.com/sharkdp/numbat/releases).
 
-Unpack the archive and move the `modules/` folder to `~/.config/numbat`,
-or one of the [other supported directories](./cli-customization.md#module-paths).
-
-``` bash
-mkdir -p ~/.config/numbat
-cp -r numbat/modules ~/.config/numbat/
-```
-
 ## From source
 
 Clone the Git repository, and build Numbat with `cargo`:
@@ -35,10 +27,8 @@ cd numbat/
 cargo install -f --path numbat-cli
 ```
 
-And copy the `modules/` folder to `~/.config/numbat/`, or the
-[respective folder on your operating system](./cli-customization.md#module-paths).
+Or install the latest release using
 
 ``` bash
-mkdir -p ~/.config/numbat
-cp -r modules/ ~/.config/numbat/
+cargo install numbat-cli
 ```