Console I/O streams

Platform spec feature

Console I/O streams

Back to Terminal and console ◎ Open in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (3)

1. 0010-split-stream-modules Split stream modules per fd Accepted

   stdin/stdout/stderr use separate System modules.

   Context

   A single Console IO type obscures direction and syscall descriptors.

   Decision

   Rule	Detail
   Modules	System.Input, System.Output, System.Error
   Forbidden	Monolithic console IO type for standard streams

   Consequences

   Each module binds one StandardStream descriptor; cross-stream APIs stay separate.

   Verification anchors

   packages/runtime/src/System/Input.bd, Output.bd, Error.bd.

   Open full ADR page

2. 0011-write-panic-read-result Write panics; read returns Result Accepted

   Syscall write failures panic; reads surface Result.

   Context

   v1 write helpers are infallible at the type level; read paths need explicit error handling.

   Decision

   Rule	Detail
   Write	Write / WriteLine must panic on WriteWith failure
   Read	Read / ReadLine return Result<string, SyscallError>

   Consequences

   Diagnostics for write failures use fixed panic strings; callers cannot catch write errors in Beskid v1.

   Verification anchors

   Corelib stream tests; syscall integration in beskid_runtime.

   Open full ADR page

3. 0012-writeline-unix-lf WriteLine emits Unix LF Accepted

   WriteLine appends a single LF byte sequence.

   Context

   Cross-platform hosts may translate line endings below the Beskid API.

   Decision

   Rule	Detail
   Ending	WriteLine must append \n only
   Windows	Host/platform layer may translate later without API change

   Consequences

   Authors see consistent Beskid source semantics; CRLF is not encoded in corelib strings.

   Verification anchors

   Output.bd / Error.bd tests; platform IO docs.

   Open full ADR page

Articles

• Contracts and edge cases MUST rules for standard stream reads, writes, and error handling. article Standard Reviewed Thu May 21
• Design model Stream module boundaries and syscall descriptor model for standard I/O. article Standard Reviewed Thu May 21
• Examples Standard stream read and write usage patterns. article Standard Reviewed Thu May 21
• Flow and algorithm Read and write algorithms for standard stream helpers. article Standard Reviewed Thu May 21
• Verification and traceability Runtime syscall and corelib anchors for standard stream I/O. 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

• Area
  Terminal and console

  Parent area

• Feature
  Panic, IO, and syscalls

  Syscall builtins underpin stream I/O

• Feature
  ANSI escape model

  Styled bytes are written through stdout after composition

What this feature specifies

Split standard stream helpers in corelib_runtime: System.Input (stdin), System.Output (stdout), and System.Error (stderr). All traffic uses System.Syscall.ReadWith / WriteWith with typed Descriptor::Standard(StandardStream::*) selectors—no direct fd integers in user code.

Contract statement

Stream	Module	Syscall descriptor	Read	Write
stdin	System.Input	Stdin	Read, ReadLine → Result<string, SyscallError>	Not supported
stdout	System.Output	Stdout	Not supported	Write, WriteLine
stderr	System.Error	Stderr	Not supported	Write, WriteLine

• Encoding at the boundary is UTF-8 bytes of the Beskid string type.
• WriteLine must write the text then a single "\n" line feed (corelib policy; not CRLF unless host translates).
• Write / WriteLine failures from WriteWith must panic with __panic_str("System.Output.Write failed") or the stderr equivalent—there is no Result on write helpers in v1.
• ANSI and markup must not be interpreted in these modules; escape bytes are ordinary string contents (see ANSI escape model).

Implementation anchors

• compiler/corelib/packages/runtime/src/System/Input.bd, Output.bd, Error.bd
• compiler/corelib/packages/runtime/src/System/Syscall/
• Informative module docs: compiler/corelib/beskid_corelib/docs/System/Input.md, Output.md, Error.md

Decisions

No open decisions. Closed choices are normative ADRs under adr/ (D-CORE-TERM-0010 … D-CORE-TERM-0012); use the reader ADRs tab for expandable detail.

Articles

• Split stream modules per fdstdin/stdout/stderr use separate System modules.
• Contracts and edge casesMUST rules for standard stream reads, writes, and error handling.
• Design modelStream module boundaries and syscall descriptor model for standard I/O.
• ExamplesStandard stream read and write usage patterns.
• Flow and algorithmRead and write algorithms for standard stream helpers.
• Verification and traceabilityRuntime syscall and corelib anchors for standard stream I/O.