From 7267e4e409820200e2f0382464d4482ad0594290 Mon Sep 17 00:00:00 2001 From: Case Duckworth Date: Wed, 9 Aug 2023 12:55:32 -0500 Subject: Update README --- README.md | 53 ++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 46 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 1d5e86b..08a0132 100644 --- a/README.md +++ b/README.md @@ -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. -- cgit 1.4.1-21-gabe81