Serapeum Documentation

Serapeum provides a family of sequence-related functions with distinctive names to avoid common 'split/divide/group' terminology. These functions are efficient, return like-for-like sequences (e.g., lists for lists, strings for strings), and accommodate generic sequences.

• runs: Returns runs of like elements in a sequence.
• batches: Returns a sequence in batches of a certain maximum size.
• assort: Groups like elements of a sequence based on a :key property.
• partition: Takes a predicate and returns two sequences: elements for which the predicate is true, and elements for which it is false.
• partitions: A generalized partition that takes multiple functions and returns items satisfying each condition. Items not satisfying any condition are returned as a second value.
• split-sequence: Serapeum re-exports this for string splitting.

;; runs: returns runs of like elements
(runs '(head tail head head tail))
;; => '((head) (tail) (head head) (tail))

;; batches: returns sequence in batches of max size
(batches (iota 11) 2)
;; => ((0 1) (2 3) (4 5) (6 7) (8 9) (10))

;; assort: groups elements by a key
(assort (iota 10) :key (lambda (n) (mod n 3)))
;; => '((0 3 6 9) (1 4 7) (2 5 8))

;; partition: splits sequence by predicate
(partition #'oddp (iota 10))
;; => (1 3 5 7 9), (0 2 4 6 8)

;; partitions: splits sequence by multiple predicates
(partitions (list #'primep #'evenp) (iota 10))
;; => ((2 3 5 7) (0 4 6 8)), (1 9)

Serapeum provides several functional combinators inspired by the J programming language.

Monadic Hook (hook)

The hook of f is defined as f(y, g(y)). Also known as Schoenfinkel's S combinator.

(hook #'= #'floor)
(funcall * 2.0) ; => T

Monadic Fork (fork)

The monadic fork of f, g, and h is defined as (f g h) y <-> (f y) g (h y).

(fork #'/ #'sum #'length)
(funcall * '(1.0 2.0 3.0 4.0)) ; => 2.5

Dyadic Hook (hook2)

Defined as (hook2 f g) x y <-> f(x, g(x, y)).

(hook2 #'+ (partial (flip #'/) 60))
(funcall * 3.0 15.0) ; => 3.25

Dyadic Fork (fork2)

Defined as x (f g h) y <-> (x f y) g (x h y).

(fork2 #'list #'+ #'-)
(funcall * 10 2) ; => '(12 8)

Capped Forks (capped-fork, capped-fork2)

These are versions of the fork where the first function F is omitted, effectively performing composition of G and H.

The with-type-dispatch macro is used to write fast, portable sequence functions by specializing code for different types. It produces one copy of BODY for each type in TYPES, allowing the Lisp to optimize each version.

Key Features:

• Transparent Portability: It deduplicates types that are not distinct on the current Lisp implementation.
• Vector Optimization: Inside the macro, vref is shadowed to expand into the appropriate specialized accessor (e.g., schar for simple-string) based on the specialized type. This is faster than aref on many implementations.
• Usage Note: VAR should be treated as read-only. This macro is intended for relatively expensive code, such as loops, to justify the dispatch overhead.

Specialized Variants:

• with-subtype-dispatch: Similar to with-type-dispatch, but all SUBTYPES must be subtypes of TYPE.
• with-string-dispatch: A specialized version of with-subtype-dispatch where the overall type is string.
• with-vector-dispatch: A specialized version of with-subtype-dispatch where the overall type is vector.
• with-simple-vector-dispatch: On supported implementations, dereferences the underlying simple vector of a displaced array to guarantee the type is a subtype of simple-array.

(with-type-dispatch (string simple-string) var
  (vref var 0))

The local macro allows you to define lexical variables, functions, and symbol macros within a specific scope, similar to Racket's internal definitions. It uses macroexpand-1 to recognize standard definition forms.

Supported definition forms:

• def: Lexical variables (like letrec).
• define-values: Multiple lexical variables.
• defun: Local functions (translated to defalias).
• defalias: Bind values in the function namespace.
• declaim: Local declarations.
• defconstant / defconst: Symbol macros.
• define-symbol-macro: Symbol macros.
• defmacro: Local macros (with restrictions).

Restrictions for defmacro:

1. Macros defined with defmacro must precede all other expressions in the local body.
2. Macros cannot be defined inside binding forms like let.
3. macrolet is not allowed at the top level of a local form.

Return Value: The value of the last form in the local body. Note that definitions themselves have return values (e.g., a defun returns the function symbol).

(local
  (def x 1)
  (def y (1+ x))
  y) ; => 2

(local
  (defun adder (y)
    (+ x y))
  (def x 2)
  (adder 1)) ; => 3

Serapeum provides macros to facilitate block compilation of top-level functions, which is useful for performance in Lisps that lack native syntax for it.

• local*: Similar to local, but leaves the last form in the body intact. This is useful for converting a progn block of top-level definitions into a block-compiled structure. Note that calls to entry points (including self-calls) may still be compiled as global calls.
• block-compile: A more robust option that allows you to specify :entry-points. This ensures that calls to the entry points are compiled as local calls.

To use block-compile, provide the entry point function names in the :entry-points keyword argument.

;; Using local*
(local*
  (defun aux-fn-1 ...)
  (defun aux-fn-2 ...)
  (defun entry-point ...))

;; Using block-compile for local calls
(block-compile (:entry-points (entry-point))
  (defun aux-fn-1 ...)
  (defun aux-fn-2 ...)
  (defun entry-point ...))

Serapeum provides Norvig-style queues wrapped in objects to prevent printer overflow, featuring a concise API inspired by Arc. Queues support standard FIFO operations as well as prepending and concatenation.

;; Creation and Inspection
(queue &rest initial-contents) ; Build a new queue
(queuep g)                     ; Test if g is a queue
(qlen queue)                   ; Number of items
(queue-empty-p queue)         ; Is it empty?
(qlist queue)                  ; Return items as a list (does not cons)

;; Basic FIFO Operations
(enq item queue)              ; Insert ITEM at the end
(deq queue)                    ; Remove item from the front
(front queue)                  ; Get first element
(qback queue)                  ; Get last element

;; Prepending and Undoing
(undeq item queue)             ; Add ITEM to the front (can undo a deq)
(qprepend list queue)          ; Insert LIST at the beginning

;; Concatenation and Copying
(qappend queue list)           ; Append LIST to the end
(qconc queue list)             ; Destructively concatenate LIST onto the end
(qpreconc list queue)           ; Destructively splice LIST at the beginning
(copy-queue queue)             ; Create a copy of the queue

;; Resetting
(clear-queue queue)             ; Return contents and reset queue