Black Hole is an R5RS compatible module system for Gambit which allows you to easily import libraries into your code including macros, which previously has been tricky on Gambit. Conversely you can also export your own code and create your own libraries to fully modularise your development.
Black Hole is a layer written on top of Gambit Scheme. Practical use
of Black Hole goes through its command line interface: bh. Here's
how to install Black Hole
- Download Black Hole
- Compile Black Hole by running
./compile.shfrom a terminal inside the Black Hole source directory. - Make a symbolic link somewhere in your path that points
to the newly created
bhbinary in the Black Hole source directory. - You can now run Black Hole with the command
bh. To see what you can do with thebhcommand, runbh help.
In Black Hole, a module corresponds directly to a .scm source code
file. To create a new module, create a .scm file.
Black Hole is designed to add as little extra syntax as possible from plain R5RS code. A simple R5RS .scm file without any external dependencies is without modification a valid Black Hole module.
By default, all defined functions, globals and macros are exported. To
control that, place an export form at the top of the file, that
enumerates the names that should be exported. For instance you could
create a file named "a-module.scm" with the following contents:
(export a-procedure a-number)
(define secret-number 1)
(define (a-procedure var) (+ secret-number var))
(define a-number 5)
For a module system to be useful, a module has to be able to use code
from other modules. That is done with the import form. import
takes one or more module identifiers. A module identifier can be
several things, but the most common kind of module identifier is a
symbol. (import a-module) will import the module in the file
"a-module.scm".
These paths are always relative to the directory where the module file
is located (or the working directory if in the REPL).
(import ../dir/module) imports the module that is found at
"../dir/module.scm"
Modules are compiled using the bh command.
bh compile test.scmcompiles the module found in "test.scm".bh compile -r test.scmcompiles the module found in "test.scm" and all its dependencies.bh exe --output=a.out test.scmcompiles the module found in "test.scm" to a standalone executable "a.out"
In essence, Black Hole is a macro expander. Black Hole extends Gambit
with hygienic macros. It adds support for the special forms
define-syntax, let-syntax and letrec-syntax. Currently, Black
Hole supports macros through explicit renaming
(er-macro-transformer), syntactic closures (sc-macro-transformer
and rsc-macro-transformer) and R5RS syntax-rules.
It also adds a macro expansion function, expand-macro. It can be
used to inspect what is happening with the macro expansion:
> (expand-macro '(let ((a 'hello)) a))
(let ((1#a 'hello)) 1#a)
>
define-macro macros are supported, but beware that they might get
special identifier objects instead of just symbols when combined with
hygienic macros. Usage of the other forms of macros is strongly
recommended.
If you want to contribute to Black Hole, either with small bugfix patches or bigger things, feel free to do so! For bigger things, it's good to keep in touch with me at per dot eckerdal at gmail dot com, to make sure that we're on the same page.
I prefer getting patches through GitHub pull requests.
To actually work on the Black Hole code base, I strongly recommend
using the script src/deventry.scm instead of compiling the bh
binary over and over again. That file has instructions on how to use
it.
Please drop me a line at per dot eckerdal at gmail dot com or use the Gambit mailing list if you have any questions.
The Black Hole page at the Gambit wiki might also be of interest.