.Dd September 24, 2026
.Dt ENSIFER 7
.Os
.ds V 0.1.20
.Sh NAME
.Nm ensifer
.Nd small Model-T-style enfilade for C and S7 Scheme
.Sh SYNOPSIS
.Bd -literal -offset indent
./build/bin/logan

(define e (make-enfilade))
(enfilade-put-data e "1.2.3" 42)
(enfilade-get-by-tumbler e "1.2.3")
.Ed
.Sh DESCRIPTION
.Nm ensifer
is a small, working enfilade layer intended to be understandable and reusable
without requiring the larger Xanadu/Green architecture to be introduced first.
.Pp
The central idea is simple: a dotted tumbler is a path through an indexed tree.
Storing:
.Bd -literal -offset indent
1.2.3 -> 42
.Ed
.Pp
conceptually produces:
.Bd -literal -offset indent
root
  |
  +-- 1
       |
       +-- 2
            |
            +-- 3 -> 42
.Ed
.Pp
A node can contain a datum and a child at the same numeric key.  Lookup returns
the exact-key datum first and then recursively flattens the child.
.Sh FIRST USE
Configure and build the complete package:
.Bd -literal -offset indent
./configure
make
.Ed
.Pp
Run the REPL, which initializes the enfilade bindings automatically:
.Bd -literal -offset indent
./build/bin/logan
.Ed
.Pp
Install with
.Cm make install .
Use
.Cm ./configure --prefix=PATH
for a non-default prefix, or set
.Ev DESTDIR
when staging an install.
.Sh CORE OPERATIONS
The small reference consists of:
.Bl -tag -width tumbler-subtract
.It Fn make-enfilade
Create an empty enfilade.
.It Fn enfilade-put-data
Insert or replace a datum at a tumbler.
.It Fn enfilade-remove
Remove the datum at an exact tumbler key.
.It Fn enfilade-get-by-tumbler
Resolve a dotted tumbler and flatten the matching subtree.
.It Fn enfilade-get-range
Range over numeric keys at one enfilade level.
.It Fn tumbler-compare
Compare complete tumbler addresses.
.It Fn tumbler-add
Perform Xanadu tumbler addition.
.It Fn tumbler-subtract
Perform the generalized tumbler difference.
.El
.Sh TUMBLERS
Tumblers are unsigned integer fields separated by periods:
.Bd -literal -offset indent
1
1.2
1.2.3
1.0.7
.Ed
.Pp
The package stores each field as
.Vt uint64_t .
It does not implement the historical arbitrary-precision Humber encoding.
.Pp
Whole-tumbler comparison uses the infinitesimal-style order represented by the
small Udanax-derived implementations:
.Bd -literal -offset indent
1 < 1.1 < 1.1.1 < 1.2 < 2
.Ed
.Pp
The C tumbler module also implements Xanadu's non-commutative addition and
strong, weak, and generalized subtraction.  See
.Xr tumbler 3 .
.Sh RANGE
The name
.Dq range
is intentionally retained.
.Pp
.Fn enfilade-get-range
operates on the numeric keys of the current enfilade level, with inclusive
bounds.  A negative upper bound means through the end.
.Pp
It is not a dotted tumbler interval expression.
.Sh REMOVAL
.Fn enfilade-remove
removes only the datum at the exact final key.
If a child subtree exists at that key, it remains.
Empty intermediate children are pruned.
.Pp
In Scheme the operation returns
.Ql #t
on removal and
.Ql #f
when there was no datum at the exact key.
.Sh DATUM OWNERSHIP
C callers own the objects pointed to by datum entries.
The enfilade owns only its index nodes and never frees a datum pointer.
.Pp
In S7, datums are Scheme objects.  The c-object mark callback visits every
stored datum, making them reachable to the garbage collector while the
 enfilade remains live.
.Sh WHAT THIS IS
This is a small tumbler-addressed Model-T-style enfilade.
It is intended as a primitive that other structures can use directly.
.Pp
It is not a complete implementation of Udanax Green.
The broader historical system includes specialized enfilades and additional
machinery for WIDs, DISPs, rearrangement, versioning, spans, virtual copies,
and persistence.
.Pp
Those concepts are intentionally outside this layer so that the fundamental
indexing mechanism remains visible.
.Sh REFERENCE IMPLEMENTATION
The immediate behavioral reference is the `Enfilade.py` implementation in
.Dq ds-lib .
.Pp
Its `putValue`, `getByTumbler`, `get`, and `getRange` behavior correspond to the
operations in this package.
.Pp
The C `range` implementation deliberately merges a node's value keys and child
keys rather than traversing a duplicated combined-key list.  Thus a key shared
by a datum and child is visited once during a range traversal; the Python
reference can visit it twice in that particular case.  Exact tumbler lookup
retains the reference's datum-then-child result order.
.Sh ZIGZAG USE
A simple catalogue can use the enfilade without teaching the enfilade anything
about cells:
.Bd -literal -offset indent
cell ID (tumbler)
      |
      v
enfilade
      |
      v
cell pointer
.Ed
.Pp
This makes the enfilade a general index beneath a cell store rather than a
second representation of the cell itself.
.Sh FILES
.Bl -tag -width src/enfilade_s7.c
.It Pa src/enfilade.c
Enfilade tree implementation.
.It Pa inc/enfilade.h
Public C API.
.It Pa src/tumbler.c
Tumbler parser, comparison, and arithmetic.
.It Pa inc/tumbler.h
Public tumbler API.
.It Pa src/enfilade_s7.c
S7 bindings and c-object type.
.It Pa src/logan.c
Direct REPL.
.It Pa test/enfload.c
S7 smoke test.
.It Pa scheme/enf.scm
Scheme smoke-test procedure.
.It Pa test/tumbler-test.c
Tumbler regression tests.
.It Pa test/enfilade-test.c
Enfilade regression tests.
.El
.Sh VERSION
The package version is available as
.Dv ENSIFER_VERSION
from
.Pa inc/enfilade.h
and from
.Nm logan --version .
The current version is 0.1.20.
.Sh TRIVIA
Ensifer is called after the greatest frost mage on Zuluhed. He would duel glads naked & win.
.Sh SEE ALSO
.Xr enfilade 3 ,
.Xr tumbler 3 ,
.Xr enfilade-s7 7 ,
.Xr tumbler-s7 7
.Sh REFERENCES
.Lk https://raw.githubusercontent.com/enkiv2/ds-lib/refs/heads/master/Enfilade.py
.Pp
.Lk https://sentido-labs.com/en/library/201904240732/Xanadu%20Hypertext%20Documents.html
.Pp
.Lk https://www.mprove.de/visionreality/media/xuDation.html
.Pp
.Lk https://pypi.org/project/xanalogica.tumbler/