Examples

Platform spec article

Examples

Back to ANSI escape model ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (4)

1. 0001-dec-save-restore-cursor DEC save/restore cursor pair Accepted

   Normative cursor save/restore uses DEC sequences, not SCO.

   Context

   Authors need portable cursor stacking without SCO-specific CSI variants in typed builders.

   Decision

   Rule	Detail
   Save/restore	DEC ESC 7 / ESC 8 is the normative pair
   SCO	CSI s / CSI u are not required in v1 typed builders

   Consequences

   Typed Ansi.Cursor helpers emit DEC only; raw Csi may still be used in tests.

   Verification anchors

   AnsiEscapeTests.bd; ANSI.md tables.

   Open full ADR page

2. 0002-capability-gating-strips-ansi Capability gating strips ANSI Accepted

   Styled emission must respect ShouldEmitAnsi and non-TTY hosts.

   Context

   Programs must not leak escapes to pipes, log files, or NO_COLOR environments.

   Decision

   Rule	Detail
   Gating	User-visible styled output must pass Ansi.Escape.WhenEnabled
   Tests	Ungated Csi remains for golden tests

   Consequences

   When ShouldEmitAnsi() is false, gated builders return empty strings.

   Verification anchors

   AnsiEscapeTests.bd; console capability integration.

   Open full ADR page

3. 0003-sgr-color-downgrade-ladder SGR color downgrade ladder Accepted

   Truecolor sequences downgrade via EffectiveColorModel.

   Context

   Terminals differ in color depth; emitting unsupported 38;2 breaks dumb hosts.

   Decision

   Rule	Detail
   Ladder	truecolor → 256 → basic per EffectiveColorModel
   Policy	Callers do not pick per-sequence models manually

   Consequences

   SGR builders consult capability probes before emitting RGB CSI.

   Verification anchors

   AnsiSgrGoldenTests.bd; CapabilitiesTests.bd.

   Open full ADR page

4. 0004-osc-bel-termination-v1 OSC BEL termination in v1 Accepted

   OSC payloads terminate with BEL, not ST.

   Context

   OSC framing varies across terminals; v1 picks one terminator for golden tests.

   Decision

   Rule	Detail
   Terminator	BEL (0x07) in v1
   ST	ESC termination is not required

   Consequences

   OSC helpers emit BEL-terminated sequences only until a future ADR extends ST.

   Verification anchors

   AnsiEscapeTests.bd; Ansi.Osc sources.

   Open full ADR page

Articles

• Contracts and edge cases MUST/SHOULD rules for escape emission and supported sequence subsets. article Standard Reviewed Thu May 21
• Design model ESC/CSI/OSC taxonomy and normative control-character tables for terminal output. article Standard Reviewed Thu May 21
• Examples Representative escape composition and gated emission patterns. article Standard Reviewed Thu May 21
• Flow and algorithm How escape bytes are composed, gated, and written to stdout. article Standard Reviewed Thu May 21
• Verification and traceability Golden tests and source anchors for ANSI escape framing. article Standard Reviewed Thu May 21

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 3 SpecSection(s) · 1 H2 heading(s)

Section id	Required	Found
what-this-feature-specifies	yes	yes
implementation-anchors	yes	yes

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Feature
  ANSI escape model

  Parent feature hub

Purpose

Document examples for the Ansi Escape Model feature: role-specific normative detail beyond the feature hub.

Canonical references

• Feature hub: Ansi Escape Model
• Sibling articles in this bundle (design model, contracts, flow, examples, verification)

Detailed behavior

Bold red foreground (CSI m)

string esc = Ansi.Escape.Esc();
string seq = Ansi.Escape.EmitCsi("1;31", "m");
System.Output.Write("${seq}Hello${Ansi.Sgr.ResetSuffix()}");

Ungated framing for tests:

string raw = Ansi.Escape.CsiSequence("1;31", "m");
// raw == "\x1b[1;31m" when Esc() is U+001B

Cursor home and clear display

string moves = Ansi.Cursor.IntoSequence(
    Ansi.Cursor.Home(Ansi.Cursor.Start())
);
string clear = Ansi.Erase.IntoSequence(
    Ansi.Erase.DisplayAll(Ansi.Erase.Start())
);
System.Output.Write("${moves}${clear}");

When ShouldEmitAnsi() is false, IntoSequence returns "" for both builders.

Alternate screen buffer

string on = Ansi.Escape.WhenEnabled(Ansi.Escape.PrivateMode("1049", true));
string off = Ansi.Escape.WhenEnabled(Ansi.Escape.PrivateMode("1049", false));

Golden tests call PrivateMode without gating to assert framing bytes.

Fluent SGR with automatic reset

string line = Ansi.Sgr.Start()
    .Bold()
    .FgBasic(31)
    .ApplyTo("error");
System.Output.WriteLine(line);

ApplyTo appends gated ESC[0m when attributes were applied.

DEC save / restore around progress render

string save = Ansi.Escape.EmitDec("7");
string restore = Ansi.Escape.EmitDec("8");
System.Output.Write("${save}");
// draw status line
System.Output.Write("${restore}");

Prefer DEC sequences over SCO ESC[s / ESC[u per decision D-TC-001.

Verification

See the verification and traceability article in this bundle and compiler/corelib/beskid_corelib/tests/corelib_tests/src/console/.

Related topics

• Parent feature hub and Terminal and console area