init commit

doc/enfilade-s7.7

@@ -0,0 +1,128 @@
+.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