amr/cl-tty
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.8.0: tangle to XDG (~/.local/share/cl-tty/), remove stale memex .lisp files

Browse Source
This commit is contained in:
Amr Gharbeia
2026-05-18 13:04:10 -04:00
parent e3415cee73
commit af572d5a8c
67 changed files with 518 additions and 6301 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
org/layout-engine.org
View File

@@ -47,7 +47,7 @@ unnecessary — ~200 lines of CL math suffices.
The test package uses ~:fiveam~ for the test framework and imports
all exported symbols from ~cl-tty.layout~.
#+BEGIN_SRC lisp :tangle ../src/layout/tests.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/tests.lisp
(defpackage :cl-tty-layout-test
(:use :cl :fiveam :cl-tty.layout)
(:export #:run-tests))
@@ -59,7 +59,7 @@ all exported symbols from ~cl-tty.layout~.
~fiveam~ suites collect related tests under a descriptive name for
batch execution.
#+BEGIN_SRC lisp :tangle ../src/layout/tests.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/tests.lisp
(def-suite layout-suite :description "Layout engine tests")
(in-suite layout-suite)
#+END_SRC
@@ -69,7 +69,7 @@ batch execution.
~run-tests~ provides a convenient entry point that prints results and
exits cleanly for CI or batch runs.
#+BEGIN_SRC lisp :tangle ../src/layout/tests.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/tests.lisp
(defun run-tests ()
(let ((result (run 'layout-suite)))
(fiveam:explain! result)
@@ -81,7 +81,7 @@ exits cleanly for CI or batch runs.
Verify that a node created with no arguments has the correct default
direction ~:column~ and is of type ~layout-node~.
#+BEGIN_SRC lisp :tangle ../src/layout/tests.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/tests.lisp
(test make-layout-node-defaults
(let ((n (make-layout-node)))
(is (typep n 'layout-node))
@@ -93,7 +93,7 @@ direction ~:column~ and is of type ~layout-node~.
Verify that passing ~:direction :row~ produces a node whose direction
slot reflects that choice.
#+BEGIN_SRC lisp :tangle ../src/layout/tests.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/tests.lisp
(test make-layout-node-row
(let ((n (make-layout-node :direction :row)))
(is (eql (layout-node-direction n) :row))))
@@ -104,7 +104,7 @@ slot reflects that choice.
Children must have their ~parent~ back-pointer set when added, and
the parent's ~children~ list must contain the child.
#+BEGIN_SRC lisp :tangle ../src/layout/tests.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/tests.lisp
(test add-child-sets-parent
(let ((parent (make-layout-node)) (child (make-layout-node)))
(layout-node-add-child parent child)
@@ -117,7 +117,7 @@ the parent's ~children~ list must contain the child.
Removing a child should clear its parent reference and remove it
from the parent's ~children~ list.
#+BEGIN_SRC lisp :tangle ../src/layout/tests.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/tests.lisp
(test remove-child-clears-parent
(let ((parent (make-layout-node)) (child (make-layout-node)))
(layout-node-add-child parent child)
@@ -131,7 +131,7 @@ from the parent's ~children~ list.
In a column layout, children stack top-to-bottom. The first child
starts at y=0; the second starts below the first.
#+BEGIN_SRC lisp :tangle ../src/layout/tests.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/tests.lisp
(test column-two-children-vertical
(let* ((root (make-layout-node :direction :column))
(c1 (make-layout-node :height 3))
@@ -147,7 +147,7 @@ starts at y=0; the second starts below the first.
In a row layout, children stack left-to-right. The first child starts
at x=0; the second starts to the right of the first.
#+BEGIN_SRC lisp :tangle ../src/layout/tests.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/tests.lisp
(test row-two-children-horizontal
(let* ((root (make-layout-node :direction :row))
(c1 (make-layout-node :width 10))
@@ -164,7 +164,7 @@ When children have different ~grow~ values, remaining space is
divided in proportion to those values. A child with grow=2 gets
twice as much extra space as a child with grow=1.
#+BEGIN_SRC lisp :tangle ../src/layout/tests.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/tests.lisp
(test flex-grow-distributes-space
(let* ((root (make-layout-node :direction :row :width 20))
(c1 (make-layout-node :width 4 :grow 1))
@@ -179,7 +179,7 @@ twice as much extra space as a child with grow=1.
A single flexible child with ~grow~ set should expand to fill all
available space in the container.
#+BEGIN_SRC lisp :tangle ../src/layout/tests.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/tests.lisp
(test flex-grow-single-child
(let* ((root (make-layout-node :direction :row :width 20))
(c (make-layout-node :width 5 :grow 1)))
@@ -193,7 +193,7 @@ available space in the container.
When children exceed the container size, each child shrinks in
proportion to its ~shrink~ value.
#+BEGIN_SRC lisp :tangle ../src/layout/tests.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/tests.lisp
(test flex-shrink-reduces-overflow
(let* ((root (make-layout-node :direction :row :width 10))
(c1 (make-layout-node :width 8 :shrink 1))
@@ -208,7 +208,7 @@ proportion to its ~shrink~ value.
Padding insets the child rendering area. Children are offset by the
padding values and sized to the remaining space.
#+BEGIN_SRC lisp :tangle ../src/layout/tests.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/tests.lisp
(test padding-reduces-content-area
(let* ((root (make-layout-node :direction :column :padding '(:top 1 :left 1 :bottom 1 :right 1)))
(c (make-layout-node :height 3)))
@@ -223,7 +223,7 @@ padding values and sized to the remaining space.
The ~gap~ property inserts spacing between consecutive children
without adding space before the first or after the last.
#+BEGIN_SRC lisp :tangle ../src/layout/tests.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/tests.lisp
(test gap-between-children
(let* ((root (make-layout-node :direction :column :gap 2))
(c1 (make-layout-node :height 3))
@@ -239,7 +239,7 @@ The ~vbox~ macro creates a column-direction container and adds
children in one expression. The second child's y-offset should be
the sum of the first child's height plus gap.
#+BEGIN_SRC lisp :tangle ../src/layout/tests.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/tests.lisp
(test vbox-macro
(let ((r (vbox () (make-layout-node :height 3) (make-layout-node :height 5))))
(compute-layout r 20 20)
@@ -252,7 +252,7 @@ the sum of the first child's height plus gap.
The ~hbox~ macro creates a row-direction container. The second
child's x-offset should equal the first child's width.
#+BEGIN_SRC lisp :tangle ../src/layout/tests.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/tests.lisp
(test hbox-macro
(let ((r (hbox () (make-layout-node :width 5) (make-layout-node :width 3))))
(compute-layout r 20 10)
@@ -266,7 +266,7 @@ The ~spacer~ macro creates a flexible node that pushes siblings
apart. With two fixed-width children and a spacer between them, the
spacer absorbs all remaining width.
#+BEGIN_SRC lisp :tangle ../src/layout/tests.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/tests.lisp
(test spacer-takes-grow
(let ((r (hbox (:width 20) (make-layout-node :width 5) (spacer :grow 1) (make-layout-node :width 5))))
(compute-layout r 20 10)
@@ -279,7 +279,7 @@ spacer absorbs all remaining width.
Nesting a column layout inside a row layout exercises the recursive
solver. Sidebar gets fixed width; main content stretches.
#+BEGIN_SRC lisp :tangle ../src/layout/tests.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/tests.lisp
(test nested-vbox-in-hbox
(let* ((sidebar (vbox (:width 5 :height 10) (make-layout-node :height 3) (make-layout-node :height 7)))
(main (vbox (:grow 1 :height 10) (make-layout-node :height 2) (make-layout-node :grow 1)))
@@ -297,7 +297,7 @@ solver. Sidebar gets fixed width; main content stretches.
Layout must gracefully handle containers with no children, returning
valid integer dimensions.
#+BEGIN_SRC lisp :tangle ../src/layout/tests.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/tests.lisp
(test empty-container-does-not-crash
(let ((r (make-layout-node)))
(compute-layout r 20 20)
@@ -310,7 +310,7 @@ valid integer dimensions.
A column with one child positions it at the origin and sizes it to
its requested height. Width is inherited from the container.
#+BEGIN_SRC lisp :tangle ../src/layout/tests.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/tests.lisp
(test single-child-in-column
(let* ((r (make-layout-node :direction :column :width 10 :height 20))
(c (make-layout-node :height 5)))
@@ -325,7 +325,7 @@ its requested height. Width is inherited from the container.
When available space is zero, the solver must still produce valid
integer coordinates without crashing or producing NaN/infinite values.
#+BEGIN_SRC lisp :tangle ../src/layout/tests.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/tests.lisp
(test zero-size-container
(let* ((r (make-layout-node :direction :column))
(c (make-layout-node :height 5)))
@@ -340,7 +340,7 @@ integer coordinates without crashing or producing NaN/infinite values.
Three levels of nested vboxes ensure that layout is computed
correctly for deeply nested subtrees.
#+BEGIN_SRC lisp :tangle ../src/layout/tests.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/tests.lisp
(test deep-nesting-three-levels
(let* ((out (vbox ()
(vbox (:grow 1)
@@ -356,7 +356,7 @@ correctly for deeply nested subtrees.
Substantial padding on all sides should offset children inward by the
full padding amount.
#+BEGIN_SRC lisp :tangle ../src/layout/tests.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/tests.lisp
(test large-padding-leaves-room
(let* ((r (make-layout-node :direction :column
:padding '(:top 5 :left 5 :bottom 5 :right 5)))
@@ -372,7 +372,7 @@ full padding amount.
A negative ~grow~ value should not cause layout errors. The solver
treats it as zero for distribution purposes and produces valid output.
#+BEGIN_SRC lisp :tangle ../src/layout/tests.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/tests.lisp
(test negative-grow-is-clamped
(let* ((r (make-layout-node :direction :row :width 10))
(c (make-layout-node :width 5 :grow -1)))
@@ -390,7 +390,7 @@ and manipulating layout trees. Internal accessors like
~layout-node-parent~ and helpers like ~normalize-box~ are also
exported for testing.
#+BEGIN_SRC lisp :tangle ../src/layout/layout.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/layout.lisp
(defpackage :cl-tty.layout
(:use :cl)
(:export
@@ -417,7 +417,7 @@ exported for testing.
plist. This normalisation layer means users can pass ~:padding 2~ or
~:padding '(:top 1 :left 2)~ interchangeably throughout the API.
#+BEGIN_SRC lisp :tangle ../src/layout/layout.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/layout.lisp
(defun normalize-box (spec)
(cond ((null spec) (list :top 0 :right 0 :bottom 0 :left 0))
((numberp spec) (list :top spec :right spec :bottom spec :left spec))
@@ -432,7 +432,7 @@ plist. This normalisation layer means users can pass ~:padding 2~ or
~box-edge~ extracts the value for a specific edge keyword from a
canonical box plist, defaulting to zero if the key is not present.
#+BEGIN_SRC lisp :tangle ../src/layout/layout.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/layout.lisp
(defun box-edge (box edge)
(or (getf box edge) 0))
#+END_SRC
@@ -446,7 +446,7 @@ and input constraints (~direction~, ~grow~, ~shrink~, ~padding~,
~margin~, ~gap~, ~position-type~, ~position-offset~, ~fixed-width~,
~fixed-height~).
#+BEGIN_SRC lisp :tangle ../src/layout/layout.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/layout.lisp
(defclass layout-node ()
((parent :initform nil :accessor layout-node-parent)
(children :initform nil :accessor layout-node-children)
@@ -472,7 +472,7 @@ and input constraints (~direction~, ~grow~, ~shrink~, ~padding~,
keyword arguments through ~normalize-box~ for padding/margin, fills
defaults for missing values, and delegates to ~make-instance~.
#+BEGIN_SRC lisp :tangle ../src/layout/layout.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/layout.lisp
(defun make-layout-node (&key direction grow shrink padding margin gap
position-type position-offset width height)
(make-instance 'layout-node
@@ -493,7 +493,7 @@ defaults for missing values, and delegates to ~make-instance~.
child's parent back-pointer and appending to the parent's children
list. Returns the child for convenience in chaining or ~let~ forms.
#+BEGIN_SRC lisp :tangle ../src/layout/layout.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/layout.lisp
(defun layout-node-add-child (parent child)
(setf (layout-node-parent child) parent)
(setf (layout-node-children parent)
@@ -507,7 +507,7 @@ list. Returns the child for convenience in chaining or ~let~ forms.
back-pointer and removing it from the parent's children list.
Returns the child.
#+BEGIN_SRC lisp :tangle ../src/layout/layout.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/layout.lisp
(defun layout-node-remove-child (parent child)
(setf (layout-node-parent child) nil)
(setf (layout-node-children parent)
@@ -524,7 +524,7 @@ gap. Each child starts from its fixed size. Remaining space is
distributed by grow ratio; overflow is reduced by shrink ratio.
Rounding errors are amortized across the first N children.
#+BEGIN_SRC lisp :tangle ../src/layout/layout.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/layout.lisp
(defun distribute-sizes (children avail gap horizontal)
(let* ((n (length children))
(gap-total (* gap (max 0 (1- n))))
@@ -563,7 +563,7 @@ within given dimensions. It positions each child at the correct
inner ~labels~ form ~place-children~ handles the recursive descent,
adjusting for padding and direction at each level.
#+BEGIN_SRC lisp :tangle ../src/layout/layout.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/layout.lisp
(defun compute-layout (root available-width available-height)
(labels ((place-children (node x y max-w max-h)
(let* ((children (layout-node-children node))
@@ -628,7 +628,7 @@ adjusting for padding and direction at each level.
properties and adds all children via ~layout-node-add-child~. The
~gensym~ ensures no variable capture in the expansion.
#+BEGIN_SRC lisp :tangle ../src/layout/layout.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/layout.lisp
(defmacro vbox ((&key grow shrink padding margin gap width height) &body children)
(let ((n (gensym)))
`(let ((,n (make-layout-node :direction :column
@@ -648,7 +648,7 @@ properties and adds all children via ~layout-node-add-child~. The
~hbox~ creates a row-direction container, structurally identical to
~vbox~ except the ~:direction~ is ~:row~.
#+BEGIN_SRC lisp :tangle ../src/layout/layout.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/layout.lisp
(defmacro hbox ((&key grow shrink padding margin gap width height) &body children)
(let ((n (gensym)))
`(let ((,n (make-layout-node :direction :row
@@ -668,7 +668,7 @@ properties and adds all children via ~layout-node-add-child~. The
~spacer~ creates a minimal flex-grow node that fills remaining space,
defaulting to ~grow 1~ when no keyword is given.
#+BEGIN_SRC lisp :tangle ../src/layout/layout.lisp
#+BEGIN_SRC lisp :tangle ~/.local/share/cl-tty/src/layout/layout.lisp
(defmacro spacer (&key grow)
`(make-layout-node :grow ,(or grow 1)))
#+END_SRC