Schemepunk

A kitchen-sink utility library for several R7RS Scheme dialects.

This library is unfinished and under heavy development. It's optimized for the needs of a few related projects I'm working on, mostly programming language interpreters and compilers.

To use this library, drop this repository in a schemepunk directory in your project, ideally as a Git submodule. The shell scripts in scripts can run unit tests or Scheme applications in all of Schemepunk's supported Scheme dialects, and they know how to find and include .sld library dependencies, even in Schemes that don't natively support this.

Supported Schemes

• [Chibi][chibi]
• [Chicken][chicken]*
• [Gauche][gauche]
• [Gerbil][gerbil]
• [Kawa][kawa]
• [Larceny][larceny]
• [Sagittarius][sagittarius]

* Chicken requires these eggs: r7rs, utf8, box, srfi-41, srfi-69, srfi-99, srfi-113, srfi-128, srfi-133, and ioctl. (ioctl is only required on Unix-based OSes.)

Schemepunk can also be built as a Chicken egg. Just run chicken-install (possibly with -sudo) in the repo's root directory.

Modules

• (schemepunk box) - Boxes
• (schemepunk btree) - Persistent B-trees
• (schemepunk command) - Command-line argument parsing
• (schemepunk comparator) - Comparators
• (schemepunk datalog) - Logic programming (WIP)
• (schemepunk flexvector) - Flexvectors (dynamic arrays)
• (schemepunk function) - Functional programming utilities
• (schemepunk generator) - Generators and accumulators
• (schemepunk hash-table) - Hash tables
• (schemepunk hook) - Hooks
• (schemepunk json) - JSON
• (schemepunk list) - List utilities
• (schemepunk mapping) - Persistent mappings
• (schemepunk multimap) - Multimaps
• (schemepunk path) - File path utilities
• (schemepunk random) - Random number generation
• (schemepunk set) - Sets and bags
• (schemepunk show) - Monadic text formatting
  • (schemepunk show debug) - Simple pretty-printing
  • (schemepunk show report) - Stylish error reports
• (schemepunk sort) - Sorting
• (schemepunk stream) - Streams
• (schemepunk string) - String utilities
• (schemepunk syntax) - Utility macros
• (schemepunk term-colors) - ANSI terminal colors
• (schemepunk test) - Unit test framework
• (schemepunk vector) - Vector library

(schemepunk box)

Polyfilled alias for [SRFI 111 (Boxes)][srfi111]. Exports one additional procedure:

• (update-box! <box> <proc>) is equivalent to (set-box! <box> (<proc> (unbox <box>))).

(schemepunk btree)

An original implementation of persistent B-trees, used to implement (schemepunk mapping) on all Schemes except Gauche¹.

Schemepunk's B-tree mappings are frequently 2-3 times faster than the red-black-tree reference implementation of SRFI 146, and significantly faster when constructing large mappings. This library includes linear-update !-suffixed mutation procedures, for yet another performance boost.

You usually want to use this module through (schemepunk mapping), but, if you want to use the B-tree data structure directly, this module provides these low-level procedures:

• (btree <comparator> <max-size>)
• (btree? <btree>)
• (btree-key-comparator <btree>)
• (btree-empty? <btree>)
• (btree-copy <btree>)
• (btree-ref <key> <value> <failure-proc>) (failure-proc is optional)
• (btree-set <btree> <key> <value>)
• (btree-set! <btree> <key> <value>)
• (btree-delete <btree> <key>)
• (btree-delete! <btree> <key>)
• (btree-pop <btree> <key>) (returns two values: (key . value) and modified btree)
• (btree-pop! <btree> <key>) (returns one value: (key . value))
• (btree-fold <fn> <seed> <btree>)
• (btree-fold-right <fn> <seed> <btree>)
• (alist->btree <alist> <comparator> <max-size>)
• (btree->alist <btree>)
• (btree-subset? <value-comparator> <btree1> <btree2>)
• (btree=? <value-comparator> <btree1> <btree2>)
• (btree<? <value-comparator> <btree1> <btree2>)
• (btree-hash <value-comparator> <btree>)
• (make-btree-comparator <value-comparator>)
• btree-comparator

¹ B-trees are faster than most Schemes' SRFI 146, but Gauche's <tree-map> is usually even faster.

(schemepunk command)

A command-line argument parser, loosely based on Chibi Scheme's [(chibi app)][chibi-app]. The parser procedures take app specifications, which are nested alists. For example, the zoo demo from the (chibi app) documentation can be written like this for (schemepunk command):

'((name "Zookeeper Application")
  (doc "Example application from (chibi app) documentation, adapted for \
        (schemepunk command).")
  (copyright "Copyright (c) 2020")
  (options
    (animals
      (type (list symbol))
      (doc "list of animals to act on (default all)"))
    (lions
      (short #\l)
      (doc "also apply the action to lions")))
  (commands
    (feed
      (short-doc "feed the animals")
      (doc-args <animals> ...))
    (wash
      (short-doc "wash the animals")
      (doc-args <animals> ...)
      (options (soap)))
    (help
      (short-doc "print help")))
  (require-command #t))

(schemepunk command) supports both - short options and -- long options. Short options can be grouped: -xyz = -x -y -z. Values after option names can follow either a space or =. Git-style commands, with their own documentation and option lists, are also supported.

Procedures

• (run-application <spec> <command-line> <proc>) parses the list of command-line arguments <command-line> using the specification <spec>. The first element of <command-line> should be the executable name.

  If parsing is successful, <proc> is tail-called with five arguments:

  • options, an alist of the - or -- options passed to the app
  • args, a list of all non-option and non-command arguments passed to the app, as strings
  • command, the command name passed to the app, or #f if there is no command
  • command-options, an alist of all options that occurred after the command name
  • command-args, a list of all non-option arguments that occurred after the command name, as strings

  If parsing fails, a usage message is printed to (current-error-port), and then Scheme is terminated with (exit 1).

• (parse-app <spec> <command-line>) parses the list of command-line arguments <command-line> using the specification <spec>, and returns five values, corresponding to the five arguments passed to run-application's <proc>. If parsing fails, it will raise an error object for which command-error? is #t.

• (app-usage <spec> <command-line>) is a (schemepunk show) formatter that prints a usage message for the app specification <spec>. The executable name is taken from the first element of the list <command-line>.

• (command-usage <spec> <command> <command-line>) is a (schemepunk show) formatter that prints a usage message for the command <command> in the app specification <spec>. The executable name is taken from the first element of the list <command-line>.

• app-help and command-help are like app-usage and command-usage, but also include name, doc, and copyright if they are present in the specification.

  

• (command-error? <datum>) is a type predicate for the error objects raised by parse-app.

App specification

All alist keys are optional; the empty specification '() is valid but has no documentation and accepts no options.

• name - name of the application, displayed at the start of the app's help text
• doc - documentation paragraph, displayed at the start of the app's help text
• doc-args - symbols or strings that describe the app's arguments in usage text; e.g., <input-file> "[<output-file>]"
• copyright - copyright message displayed at bottom of help text
• options - alist of options for the app; each option's key is also its default long option name
• commands - alist of commands for the app; each command's key is also its name
• require-command - if #t, app exits with an error if no command is provided
• default-help-option - if #t, an option is added with long name --help and short name -h that, if present, causes run-application to print the app's help text and exit
• default-help-command - if #t, a command named help is added that, if selected and passed a command name as its only argument, causes run-application to display that command's help text and exit

Option

• type - data type of the option's value, defaults to boolean; options are boolean, symbol, char, string, integer, real, sexp, and (list <type>)
• long - long option aliases for this option (symbols or strings)
• short - short option aliases for this option (chars)
• doc - description of this option, displayed in usage text
• doc-value - name of the option's value, displayed in usage text, defaults to value of type

Command

• short-doc - documentation shown in the app's usage text
• doc - longer documentation shown in the command's usage text
• doc-args - symbols or strings that describe the command's arguments in usage text; e.g., <input-file> "[<output-file>]"
• options - alist of opt