.Dd September 24, 2026
.Dt ENFILADE-S7 7
.Os
.Sh NAME
.Nm enfilade-s7
.Nd S7 Scheme bindings for the small enfilade
.Sh SYNOPSIS
.Bd -literal -offset indent
(load "./build/lib/enfilade.so" (inlet 'init_func 'init_enfilade_s7))

(define e (make-enfilade))
(enfilade-put-data e "1.2.3" 42)
(enfilade-get-by-tumbler e "1.2.3")
.Ed
.Sh DESCRIPTION
The module wraps the C
.Vt enfilade_t
in an S7 c-object of type
.Ql <enfilade> .
The Scheme datum passed to
.Fn enfilade-put-data
is retained in the C tree as an S7 pointer.
The c-object mark callback marks every stored datum during garbage collection.
.Sh LOADING
Configure and build the S7 module:
.Bd -literal -offset indent
./configure
make
.Ed
.Pp
Load it into an S7 host with:
.Bd -literal -offset indent
(load "./build/lib/enfilade.so" (inlet 'init_func 'init_enfilade_s7))
.Ed
.Sh FUNCTIONS
.Bl -tag -width enfilade-get-by-tumbler
.It Fn make-enfilade
Returns a new
.Ql <enfilade>
object.
.It Fn enfilade-put-data enfilade tumbler datum
Stores
.Fa datum
at
.Fa tumbler .
The tumbler is a string of unsigned decimal fields separated by periods.
Missing intermediate child enfilades are created automatically.
The return value is unspecified.
.It Fn enfilade-remove enfilade tumbler
Removes the datum at the exact final key.
Returns
.Ql #t
when a datum was removed and
.Ql #f
when the exact final datum was not present.
A child subtree at that key is retained.
.It Fn enfilade-get-by-tumbler enfilade tumbler
Returns a Scheme list containing the datum at the exact final key, followed by
the flattened contents of a child subtree at that key, if present.
Missing intermediate children and malformed tumblers raise
.Ql TumblerAddressException .
A valid final key with nothing stored there returns
.Ql () .
.It Fn enfilade-get-range enfilade start end
Visits numeric keys from
.Fa start
through
.Fa end ,
inclusive, and flattens their contents.
A negative end means through the end.
This is a one-level numeric range, not a dotted tumbler interval.
.It Fn tumbler-compare a b
Returns a negative integer, zero, or a positive integer according to the
whole-tumbler ordering of the two strings.
.It Fn tumbler-add position offset
Returns the dotted-string result of Xanadu tumbler addition.
.It Fn tumbler-subtract a b
Returns the generalized non-negative tumbler difference.
.El
.Sh EXAMPLE
.Bd -literal -offset indent
(define e (make-enfilade))

(enfilade-put-data e "1.2.3" 42)
(enfilade-put-data e "1.2.4" 43)
(enfilade-put-data e "1.3.1" 99)

(enfilade-get-by-tumbler e "1.2.3")
; => (42)

(enfilade-get-by-tumbler e "1.2")
; => (42 43)

(enfilade-get-range e 1 3)
; => (42 43 99)

(enfilade-remove e "1.2.3")
; => #t
.Ed
.Sh DATUM LIFETIME
The C tree does not copy or free Scheme datums.
The S7 c-object retains them by marking them during garbage collection.
When the c-object is finally freed, the C tree is destroyed.
Do not call
.Fn destroy_enfilade
on the pointer owned by a live S7 c-object.
.Sh ERRORS
Malformed tumbler strings and missing intermediate children raise
.Ql TumblerAddressException .
Allocation failures raise
.Ql memory-error .
Wrong Scheme argument types use S7's normal wrong-type condition.
.Sh FILES
.Bl -tag -width src/enfilade_s7.c
.It Pa src/enfilade_s7.c
S7 binding implementation.
.It Pa src/logan.c
Direct minimal REPL for the module.
.It Pa test/enfload.c
Non-interactive S7 smoke test.
.El
.Sh SEE ALSO
.Xr tumbler-s7 7 ,
.Xr enfilade 3 ,
.Xr tumbler 3 ,
.Xr ensifer 7
.Sh REFERENCES
.Lk https://raw.githubusercontent.com/enkiv2/ds-lib/refs/heads/master/Enfilade.py