129 lines
3.5 KiB
Plaintext
129 lines
3.5 KiB
Plaintext
.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
|