# CommonRails — SST + Sleela edition
Professional printing component for the SLeeLa toolchain, ported from the Java
`CommonRails` in the Tiamat project. It provides:
1. **Professional component lines** — an aligned, column-formatted status line:
```
-- : [Object ID: 0000001234] [Date: 1] [Current: @SearchEngineClient ] . category images now crawling .
```
Object ID is zero-padded to 10 digits, `Current` is padded to a fixed inner
width for column alignment, and the message is bracketed with `.` decorators
— the same layout as the Java edition's `print-method.xml`.
2. **A 21×21 progress square (441 cells)** that fills **bottom-right → left**
across a row, then **up** one row at a time. One filled cell lights the
bottom-right corner; 100% fills all 441 cells.
```
░░░░░░░░░░░░░░░░░░░░░ █████████████████████
░ ... (21 rows) ... ░ ... █ ... (21 rows) ... █
░░░░░░░░░░░░░░░░░░░░█ █████████████████████
1 cell (corner) 100% (441 cells)
```
3. **A single-pixel progress indicator** — the most compact rendering: the
square collapsed to one cell (one glyph). It reads `░` while at 0% and `█`
as soon as there is any progress. Call `printPixel(filledCells)` or
`printPixelPercent(percent)`.
```
░ (0%) █ (started)
```
4. **A sophisticated bordered table** — a clean, Unicode box-drawing frame
around fixed-width, aligned columns:
```
┌────────────────────┬────────────┐
│ Component │ State │
├────────────────────┼────────────┤
│ SearchEngineClient │ WORKING │
│ CommonRails │ COMPLETE │
└────────────────────┴────────────┘
```
The table is opt-in through a **`table` flag**: renderers such as
`printPair(field, fieldChars, value, valueChars, table)` emit a framed
table when `table` is `true` and a plain fixed-width line when it is
`false` — the single flag tells the printer which form to produce for the
same data. Cells are padded, never truncated, and respect per-column widths
and left/right alignment.
This directory ships the printer in a **procedural** and an **object-oriented**
Sleela edition, plus the SST control sheet and the C/C++/Java Heritage layer.
## Files
| File | Edition | What it is |
|------|---------|------------|
| [`CommonRails.sleela`](CommonRails.sleela) | **Sleela** (Wrapper™) | The program — the printer written as flat helper methods. |
| [`PrinterConfig.sleela`](PrinterConfig.sleela) | **Sleela** (OO) | The object-oriented edition — configurable `struct` objects (`PadConfig`, `ColumnConfig`, `TableStyle`, `StateStyle`, `PrinterConfig`) consumed by a `Printer`, so a developer composes their own print method. |
| [`PRINTER.OOD.md`](PRINTER.OOD.md) | — | The object-oriented design: the object model, developer recipe, and growth plan. |
| [`common-rails.sst`](common-rails.sst) | **SST** (Nordshrift) | The control sheet — declares the square geometry as a semantic subject and drives the Wrapper™ through the triplet. |
| `.gitignore` | — | Excludes generated `build/` / `out/` artifacts. |
### The object-oriented edition — `PrinterConfig.sleela`
Each printing concern is a configurable object (a Sleela `struct`, a reference
type built with `new`): `PadConfig` (width + fill + alignment), `ColumnConfig`
(a table column), `TableStyle` (the box-drawing glyph set), `StateStyle`, and
the top-level `PrinterConfig`. A `Printer` class supplies factories that build
them and renderers that consume them, so a developer assembles a print method
by constructing and wiring objects instead of threading long argument lists.
Restyling every table is a one-object swap (`cfg.table = p.asciiTable()`). The
full object model and a worked developer recipe are in
[`PRINTER.OOD.md`](PRINTER.OOD.md).
```sh
# from the repository root
./impl/build/sleela check common-rails/PrinterConfig.sleela
./impl/build/sleela run common-rails/PrinterConfig.sleela
```
### The Sleela edition — `CommonRails.sleela`
A `#sleela 1.3` Wrapper™ written against the accepted Sleela surface
(`impl/README.md`): classes, `int`/`String`/`boolean`, `if`/`else`,
`while`/`for`, arithmetic and comparisons, `+` string concatenation, `print`,
recursion, and class fields. Because the core value model has no arrays or
character indexing, the square is produced entirely with nested integer loops,
field widths are measured arithmetically, and every content primitive takes an
explicit character count. The lexer decodes only `\n \t \r \\ \"`, so the block
glyphs `█` / `░` and the box-drawing glyphs `┌ ┬ ┐ │ ├ ┼ ┤ └ ┴ ┘ ─` are
embedded as raw UTF-8.
> **Syntax note.** The Sleela lexer folds a hyphen into an identifier, so every
> binary operator — including `-` — must be surrounded by spaces (`w - chars`,
> not `w-chars`). The source previously declared `#sleela 1.1`, which the
> current compiler (supported range `1.3 .. 1.10`) rejects; it now declares
> `1.3` and passes `sleela check`.
```sh
# from the repository root
./impl/build/sleela check common-rails/CommonRails.sleela # validate (incl. #sleela version)
./impl/build/sleela run common-rails/CommonRails.sleela # run on the C/C++ core
```
### The SST edition — `common-rails.sst`
A Nordshrift control sheet (`#nordshrift 1.0` pragma, using the **2.0 semantic
layer** from NS-SST-0001 Part XVII — the same combination the shipped
`kinematics-subject.sst` uses). It names the `.sleela` source, selects the
`sleela` target, and declares the square as an explicit **math subject**
`CommonRailsSquare`: the side (21 cells), the derived cell count (441), the
per-cell percent, the fill-index relation, the bottom-right→left→up fill
`transformation`, a comparison against the prior 10×10 square, evidence
provenance, an explanation chain, and a colorization work-plan item.
```sh
# from the repository root
./impl/build/nordshrift check common-rails/common-rails.sst # validate; NSS-* diagnostics
./impl/build/nordshrift build common-rails/common-rails.sst # transpile + run on the core
```
## Building and checking CommonRails
From this directory, run:
```sh
make check
make clean
```
The CommonRails Makefile builds and runs the C and C++ contract tests, compiles
and runs the Java contract test, and checks the Sleela and SST sources when the
local toolchain binaries are available. If those binaries are missing, the two
toolchain checks report a clear skip; build them first with `make -C ../impl all`
to run the complete set. The C, C++, and Java checks require their respective
native compiler/JDK.
The repository-root dispatcher also exposes `make common-rails`.
## Building the toolchain
Both binaries come from the `impl/` tree (C11 + C++17):
```sh
cd impl && make # produces build/sleela and build/nordshrift
```
## Relation to the Java edition
The fill mathematics are identical to the Java `CommonRails`: a display cell at
`(displayRow, displayCol)` maps to fill index
`((size-1)-displayRow)*size + ((size-1)-displayCol)`, and a cell is filled when
its fill index is `< filledCells`. The Java edition uses ANSI color (orange
filled on white empty); here the filled/empty distinction is carried by the
`█` / `░` glyphs, and colorizing the `c`/`java` targets is tracked as the
`colorizeTargets` work-plan item in the SST sheet.
---
# SLeeLa

