1 files changed, 46 insertions, 7 deletions

@@ -1,14 +1,53 @@
-# Chicanery: subtle, opinionated improvements to R7RS in CHICKEN
+# Chicanery: subtle, opinionated improvements to R7RS Scheme
 
-`chicanery` is my attempt at a prelude module for CHICKEN scheme.  It imports and re-exports all `r7rs` modules, using `utf8` where possible, and it corrects a few (in my mind) rough spots in the language, to whit:
+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...
 
-- `map`, `for-each`, and `append` are now generalized over lists, vectors, strings, and bytevectors (where appropriate).  The list versions of these procedures have been named `list-map`, `list-for-each`, and `list-append` respectively.
-- `ref` and `copy` have been defined as generalized functions over the above data types.
+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 ;)
 
-## Todo
+## Chicanery extras
 
-- Make sure `set!` works in, like, `(set! (ref 5 '(1 2 3 4 5)) 10)`
+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
+- `(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
+- guile
+- gambit
+- chibi
 
 ## License
 
-This software is licensed under the GWL, v. 1.0.  See COPYING for details.
+This software is licensed under the GWL, v.  1.0.  See COPYING for details.