Shen Batteries

Collection of libraries for Shen.

Loading libraries

Load the module loader, point it at this repository, and use one or more libraries:

(load "library.shen")
(library.set-home "/path/to/shen-batteries")
(library.use [box lazy])

library.use loads dependencies and sources once. Loading is permanent for the current Shen image; there is no unload operation. Set the module home before the first call to library.use; it cannot change after modules are loaded. See the loader API for the exact behavior.

Dependencies are loaded automatically, so loading an adapter is enough to load its base library:

(library.use [seq/cexpr])

Modules use the portable shen.module version 1 format. Descriptors are found at <module-root>/<module-name>.shenmod, and their source paths are relative to the descriptor. Port-specific settings belong in namespaced extension fields and are ignored by the portable source loader. See the normative shen.module version 1 specification, or follow the checked module-authoring walkthrough to build and run a small module tree. Port and loader authors can run the reusable shen.module conformance fixtures.

Module catalog

The requirements below are the direct requirements declared by each module; library.use resolves their transitive dependencies. A module's feature requirements are checked against the current Shen implementation before that module's dependencies or sources are loaded. API references are generated from the modules' source documentation; task-oriented guides and the port-neutral module-format specification are maintained by hand.

Module	Purpose	Declared requirements	Reference
box	Mutable references	typ/void	API
cexpr	Generic computation-expression parser and expander	typ/sexp	Guide and API
defpattern	Definition helper for programmable pattern-matching handlers	typ/sexp	Guide, API
dict	Typed public API for Shen dictionaries	—	API
features	Feature registration, discovery, and conditional expansion	—	API
iter	Push-based iterators	typ/void, maybe, box, let-match, with-exit	Guide, API
iter/cexpr	iter.do computation-expression frontend	iter, typ/sexp, cexpr	API
lazy	Memoization for frozen computations	box	API
lazy/pattern	Programmable matching of frozen computations	defpattern, lazy	API
let-match	List and tuple destructuring in let bindings	—	API
maybe	Tagged optional values and programmable patterns	typ/void, defpattern	Guide, API
maybe/cexpr	maybe.do computation-expression frontend	maybe, typ/sexp, cexpr	Guide, API
nullable	Identity-represented nullable values and programmable patterns	defpattern	Guide, API
pipe-macro	Thread-first, thread-last, and doto macros	—	Guide, API
queue	Immutable first-in, first-out queues	maybe	API
record	Closed, nominal records with named construction, matching, and persistent updates	typ/sexp, defpattern, features	API
result	Tagged success or error values and programmable patterns	defpattern	API
seq	Pull-based lazy sequences	typ/void, typ/or, maybe, lazy	Guide, API
seq/cexpr	seq.do computation-expression frontend	seq, typ/sexp, cexpr	API
seq/dict	Snapshot conversions between sequences and dictionaries	seq, dict	API
shendoc	AsciiDoc generator for Shen source comments	—	API
typ/or	Untagged union introduction rules	—	API
typ/sexp	Proper S-expression tree type	—	API
typ/verified-and-head	Ordered refinement from the head to the tail of and	—	API
typ/verified-if	Verified-test refinement in the true branch of if	—	API
typ/verified-objects	Refinement rules for primitive object predicates	—	API
typ/void	Discarded-result type and conventional value	—	API
with-exit	Portable early-return and early-break forms	box, features, maybe, typ/void, typ/sexp	API

No production module currently declares a port feature requirement.

Testing

Provide the Shen executable explicitly:

make test SHEN=/absolute/path/to/shen

To run only the port-neutral module-format cases, each in a fresh process:

make test-module-conformance SHEN=/absolute/path/to/shen

The current reference runtime is Shen 41.3 on Shen/Scheme 0.46.1. The earlier Shen/Scheme 0.46 release predates the required programmable-pattern typechecking and dictionary traversal fixes.

A Shen/Scheme build after 0.46.1 that advertises shen/scheme.records can also compile and load the native module smoke graph, including the native Chez-record backend:

make test-native SHEN=/absolute/path/to/shen-scheme

This target is intentionally separate from the portable source-loader tests.

Regenerate the tracked API documentation from source comments with:

make docs SHEN=/absolute/path/to/shen

From a clean checkout, verify that the tracked pages match their source comments with:

make check-docs SHEN=/absolute/path/to/shen

License

Copyright © 2019 Bruno Deferrari under BSD 3-Clause License.