# Chicanery: subtle, opinionated improvements to R7RS Scheme

While I was reading the [R7RS
specification](https://standards.scheme.org/official/r7rs.pdf), I was a little
annoyed by how broken up the standard library seemed to be.  While the most
egregious example is maybe `(scheme case-lambda)`, which exports ...  only
`case-lambda`, the other libraries like `(scheme write)` for `display`, `(scheme
cxr)` for functions like `caddr` but not `cddr`, and the rest didn't really seem
logical to me.  Plus, in CHICKEN scheme, the one I usually use, `utf8` is an egg
you need to install separately...

To ameliorate these minor warts in what I otherwise consider to be an excellent
language, `chicanery` was born.  It's kind of like a prelude, I suppose?  It
imports all `r7rs` modules and re-exports their identifiers, and makes sure the
implementation is Unicode-aware.  It also includes a few extras ;)

## Chicanery extras

I also thought it was strange that `map`, `for-each`, and `append` apply to
lists only, while `vector-map` and `string-for-each`, exist, for example.
`chicanery` prefixes the default `map`, `for-each`, and `append` functions with
`list-`, and redefines those identifiers to functions that are generic over
Scheme's base collection types (lists, strings, vectors, bytevectors where
applicable).  I didn't make the functions fully-generic to keep them efficient
and because I don't know how to do that, but you can still use `vector-append`
or `list-map` if you know what type you need and want speed.

In a similar vein, I've also added generic functions `ref` and `copy` that
dispatch to `string-ref`, `list-copy`, and the like.

Other extras include

- `(atom?  x)` determines whether `x` is an atom (i.e., not a pair or null)
- `(read-port)`, `(read-port port)` reads a port until hitting end-of-file (IDK
  why this isn't in R7RS!), in chunks of `read-port-chunk-size`
- `(defined?  x)` returns whether the symbol `x` is bound to a variable
- `(with-input-from-string str thunk)` calls `thunk` with `str` bound as the current-input-port.
- `(with-output-to-string thunk)` calls `thunk` and returns a string of the output.
- `(displayed x)`, `(->string x)` returns `x` as a string (via `display`)
- `(written x)` returns `x` as a string (via `write`)
- `(print x ...)` displays `x ...` followed by a newline

## Supported Scheme implementations

`chicanery` now supports multiple R7RS implementations!  The full list can be
found by running `make`, but here's what we have right now:

- [Chicken](https://call-cc.org/)
- [Guile](https://www.gnu.org/software/guile/)
- [Gambit](https://gambitscheme.org/)
- [Chibi](https://synthcode.com/scheme/chibi)

Other Scheme implementations have been minimally tested and I haven't been able to figure them out yet.  However, [Cyclone](https://justinethier.github.io/cyclone/) is definitively *not* compatible; see [issue #413](https://github.com/justinethier/cyclone/issues/413).

## License

This software is licensed under the GWL, v.  1.0.  See [COPYING](https://git.acdw.net/chicanery/tree/COPYING) for details.