init commit
This commit is contained in:
divorce committed
commit
6300e42bb2
28 files changed
+104005
No files matched your search
+212
@@ -0,0 +1,212 @@
|
||||
.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/
|
||||
Reference in new issue
Block a user