213 lines
5.8 KiB
Plaintext
213 lines
5.8 KiB
Plaintext
.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/
|