----
title: Beastie and Scheme
SPDX-FileCopyrightText: 2025 Norman Gray <https://nxg.me.uk>
SPDX-License-Identifier: BSD-2-Clause

Resources:

  * There is a collection of per-procedure documentation in the
    [procedure list](procedures.xhtml).
  * Within the REPL, `(help foo)` will show brief documentation
    for the `foo` procedure.
  * There are some [examples][] in the directory `examples/`.


Scheme
======

There are numerous introductions to Scheme; regarding reference
material, the terse classic ‘R5RS’ is the mostly widely known and
implemented standard, and ‘R7RS’ the most recent (s7 asserts
compatibility with R5RS and R7RS).  There is a short list of standards
texts at the [Scheme conservancy][].

Ths Scheme here is that of [s7][], which is pretty standard, but with
some eccentricities.  This is a mini-scheme, intended as an extension
language, and its source is entirely contained within the Beastie
sources.  The [s7 manual][] has notes on the details and quirks of
this implementation and its (very good!) FFI.

As a dialect (and Scheme has _lots_ of dialects!), s7 is quite close
to Guile, and the [tutorial for that][guile] is therefore a good
introduction to Beastie's scheme as well.

As well as the functions described here, Beastie/s7 has some
additional peculiarities:

  * `lambda` can be written `λ` (just because it looks nicer).

  * We implement [srfi-62][] comments, thus the form `#;(foo ...)`, if
    found in the input, is ignored

  * We also (mostly) implement Julia-like strings: `#"""foo bar"""` will be
    parsed as a possibly multi-line string (Julia triple-quote strings
    are like Python ones, but they always dedent by removing the
    shortest common whitespace prefix).  The only deficiency in the
    implementation is that Julia strings can be continued with a
    trailing backslash, and ours can't be.

  * Beastie includes ‘normal’ Scheme strings `"..."`, of course, but
    adds to these ‘Unicode-strings’, written `#"..."`, which have
    Unicode-specific operations defined on them.  See the [Unicode
    module](unicode.xhtml) for details.

  * Function `(printf "fmt" args...)` will format and print to stdout,
    and `eprintf` and `sprintf` will do the same to stderr and a
    string (yes, these are just wrappers for the usual `format` procedure).

  * We implement a _basic_ module system for _built-in_ modules.
    The form `(module 'bibtex)`, for example, will load the
    definitions which are probably helpful for working with BibTeX
    files.  These modules are documented [together](procedures.xhtml).
    This is in addition to s7's support for loading.

  * See also the collection of [core functions](core.xhtml) which
    extend the basic s7 runtime.

I am not 100% committed to the implementation in s7.  As a Scheme, s7
does have its little foibles, which occasionally grate, but which are
compensated for by s7 being _very_ easy to work with and extend.  It
is possible (though, I should concede, unlikely) that the balance of
the various considerations may change in future, enough that I might
enjoy the amusement of reimplementing this in a different Scheme.

[s7]: https://ccrma.stanford.edu/software/s7/
[examples]: examples/index.xhtml
[srfi-62]: https://srfi.schemers.org/srfi-62/
[Scheme conservancy]: https://conservatory.scheme.org/schemers/Documents/Standards/
[guile]: https://www.gnu.org/software/guile/learn/
[s7 manual]: https://ccrma.stanford.edu/software/s7/s7.html