Brummel
26fb3459d8
The runtime print path now writes exactly the bytes of its
argument with no implicit trailing newline. `io/print_str` is
byte-faithful; authors who want a newline emit `(do io/print_str
"\n")` themselves.
## Codegen
`crates/ailang-codegen/src/lib.rs`:
- Module preamble: `@puts(ptr)` → `@fputs(ptr, ptr)` plus
`@stdout = external global ptr` (libc's `FILE *stdout`).
- Effect-op lowering for `io/print_str`: emit
`getelementptr +8` then `load ptr, ptr @stdout` then
`call/tail call i32 @fputs(ptr bytes, ptr fp)`. Identical
bytes-pointer GEP, distinct sink.
- The pinned IR-shape test renames from
`print_str_calls_puts_with_bytes_pointer` to
`print_str_calls_fputs_with_bytes_pointer_and_stdout` and now
asserts: bytes-GEP present, stdout-load present, both module-
preamble declarations present, and no `@puts(` call anywhere
in the emitted IR.
## Why this shape, and not the alternatives
- *Rename `io/print_str` to `io/println_str` (issue #29 option 2)*
— kept the auto-newline, just relabelled it. AILang's design
bias is explicit-over-implicit (CLAUDE.md: implicit conversions
cut). Auto-newline is a hidden runtime augmentation; the rename
would have preserved it. Rejected.
- *Append `\n` inside the polymorphic `print` (Show-mediated)
function in `examples/prelude.ail`* — would have been a one-line
fix. Rejected: `print` is the Show-mediated formatter, not a
newline emitter; baking a newline into it would have re-imposed
the same implicit-augmentation problem one layer up, breaking
callers that legitimately want pure-bytes output.
## Fixture / test sweep
30 `.ail` fixtures whose owning tests asserted line-separated
stdout now emit explicit `(do io/print_str "\n")` after each
print. Tests that asserted on multi-line stdout (`show_print_e2e`,
`floats_e2e`, `str_concat_e2e`, `eq_ord_e2e`, several `print_*`
smoke tests) had their fixtures sweetened the same way; assertions
themselves remain the canonical observable output. Fixtures that
never relied on the newline (no test ever read the absence of one)
were left untouched.
## Migrated metadata
- `crates/ailang-core/tests/hash_pin.rs`: the `ordering_match::main`
canonical hash is refreshed (`b65a7f834703ffb4` →
`8ed47b4062ce00f5`). The comment now names both successive
corpus migrations honestly: the per-type-print-retirement (which
moved `(do io/print_int x)` to `(app print x)`) AND this
fputs swap (which wrapped that with `(seq ... (do io/print_str
"\n"))`).
- `design/contracts/str-abi.md`: the consumer-ABI table now lists
`@fputs` as the print sink. A prose paragraph documents the
byte-faithful semantics and references this issue.
- `examples/ordering_match.prose.txt`: regenerated from the
updated `ordering_match.ail`.
- `crates/ail/tests/snapshots/{hello,sum,max3,list,ws_main}.ll`:
IR snapshots regenerated via `UPDATE_SNAPSHOTS=1`.
- Stale `@puts` comments in `runtime/str.c`,
`crates/ail/tests/{e2e,show_print_e2e,print_no_leak_pin}.rs`
replaced with `@fputs`.
## Verification
- `cargo test -p ail --test print_str_no_auto_newline_e2e` — both
RED tests from commit c8ecfa3 now pass.
- `cargo test --workspace` — 90 test groups GREEN, 0 failures.
- `cargo build --workspace` — GREEN.
- No new clippy lints (24 warnings pre-existing in
`crates/ailang-core/src/lib.rs:129`).
- Stats: `bench/orchestrator-stats/2026-05-21-iter-bugfix-print-
str-fputs.json` — 1/1 tasks, 0 re-loops, 0 review loops.
## Empirical evidence cited
Caught in the 2026-05-21 Qwen3-Coder naming-A/B run
(`experiments/2026-05-21-naming-ab/runs/r1/`): every cohort wrote
`(do io/print_str "...\n")` with explicit `\n` and got doubled
newlines, failing the `t3_main_prints` stdout match across all
three cohorts. The empirical LLM-natural form already assumes the
new (post-this-commit) semantics — confirming the
feature-acceptance test in CLAUDE.md.
closes #29
96 lines
4.9 KiB
Markdown
96 lines
4.9 KiB
Markdown
# Str ABI
|
|
|
|
## Heap-Str primitives
|
|
|
|
The runtime ships a small family of operations that produce or
|
|
transform heap-allocated `Str` values uniformly across static-Str
|
|
and heap-Str inputs (the consumer ABI is identical between
|
|
realisations — see the Str ABI table below). All take their
|
|
input(s) by `borrow` and return an owned `Str`. Each is registered as a builtin in
|
|
`crates/ailang-check/src/builtins.rs`, lowered inline in
|
|
`crates/ailang-codegen/src/lib.rs::lower_app` to a `call ptr @ailang_<name>`,
|
|
and backed by a `runtime/str.c` C helper.
|
|
|
|
- `int_to_str : (borrow Int) -> Str` — decimal rendering
|
|
of an `Int`. Backs `Show Int` in the
|
|
[prelude](prelude-classes.md).
|
|
- `bool_to_str : (borrow Bool) -> Str` — `"true"`/`"false"`.
|
|
Backs `Show Bool` in the [prelude](prelude-classes.md).
|
|
- `float_to_str : (borrow Float) -> Str` —
|
|
type-installed; codegen is reserved and not yet shipped.
|
|
- `str_clone : (borrow Str) -> Str` — allocates a fresh
|
|
heap-Str copy of the input's bytes. Backs `Show Str` in the
|
|
[prelude](prelude-classes.md).
|
|
- `str_concat : (borrow Str, borrow Str) -> Str` — combines two `Str`
|
|
values into a single owned `Str`.
|
|
General-purpose; commonly used in Show bodies for labelled output
|
|
(`(app str_concat "label=" (app int_to_str x))`).
|
|
|
|
The four Show-backers above are not directly observable to the
|
|
LLM-author writing a `Show <T>` instance — the prelude's instance
|
|
bodies dispatch into them. `str_concat` IS directly observable
|
|
because the LLM-author calls it explicitly when authoring an
|
|
instance body that wants to combine fragments.
|
|
|
|
Primitive output for `Str` values goes through `io/print_str`
|
|
directly; values of other primitive types route through the
|
|
polymorphic `print` helper (see [prelude classes](prelude-classes.md)),
|
|
which feeds the heap-Str result of `show x` into `io/print_str`.
|
|
|
|
Equality on `Str` dispatches via `prelude.Eq.eq` (Str instance,
|
|
lowered by `try_emit_primitive_instance_body::eq__Str` to a call
|
|
into `@ail_str_eq` with the `alwaysinline` attribute). Ordering on
|
|
`Str` dispatches via `prelude.Ord.compare` (Str instance, lowered
|
|
by `try_emit_primitive_instance_body::compare__Str` to a call into
|
|
`@ail_str_compare` then a three-way branch ladder constructing
|
|
`LT`/`EQ`/`GT`). The polymorphic helpers `ne` / `lt` / `le` / `gt`
|
|
/ `ge` resolve via the class layer on top of `eq` / `compare`.
|
|
There are no primitive operator names `==` / `<` / `!=` / etc. in
|
|
the language.
|
|
|
|
Arithmetic operators (`+`, `-`, `*`, `/`, `%`) stay primitive and
|
|
per-type.
|
|
|
|
**Str ABI.** A `Str` is a pointer to a structure with `i64 len` at
|
|
offset 0 followed by `len` bytes plus a trailing `NUL` at offset 8.
|
|
Two realisations share this consumer ABI:
|
|
|
|
| Realisation | Origin | rc_header | Memory |
|
|
|-------------|-------------------------------------------------|-----------|-----------------------------------------|
|
|
| static-Str | string literals (`@.str_*` LLVM globals) | none | `.rodata`, packed-struct `<{ i64, [N+1 x i8] }>` |
|
|
| heap-Str | runtime allocations (`int_to_str`, `float_to_str`, ...) | yes, at `payload - 8` | `malloc`'d via `ailang_rc_alloc(8 + len + 1)` |
|
|
|
|
Every consumer (`@fputs`, `@strcmp`, `@ail_str_eq`,
|
|
`@ail_str_compare`) GEPs `+8` from the Str pointer to reach the
|
|
bytes, regardless of realisation. The byte-comparison semantics
|
|
are inherited from libc `strcmp` — locale-independent, NUL-
|
|
terminated. The print path uses `@fputs(bytes, @stdout)` so that
|
|
`(do io/print_str s)` writes exactly the bytes of `s` with no
|
|
implicit trailing newline (Gitea #29; the earlier `@puts` lowering
|
|
appended a newline per call).
|
|
|
|
The heap-Str realisation participates in standard RC (see
|
|
[memory model](memory-model.md)): the
|
|
`rc_header` slot eight bytes before the `len` field is managed
|
|
by `ailang_rc_alloc` / `ailang_rc_inc` / `ailang_rc_dec` exactly
|
|
like any other RC-allocated cell. The static-Str realisation has
|
|
no `rc_header` slot at all; the bytes at `payload - 8` belong to
|
|
the previous global in `.rodata` and reading them is undefined.
|
|
|
|
**The static-Str non-RC invariant is enforced at codegen.** Two
|
|
mechanisms keep static-Str pointers out of `ailang_rc_dec` along
|
|
every shipping execution path: (1) the non-escape lowering pass
|
|
and the move-tracking partial-drop logic
|
|
prevent let-binders or pattern-binders for static-Str literals
|
|
from reaching scope-close drop emission; (2) the `Type::Con { name: "Str" }`
|
|
carve-outs in `field_drop_call` and in the `Term::App` arm of
|
|
`drop_symbol_for_binder` (both in `crates/ailang-codegen/src/drop.rs`)
|
|
route the rare case that *does* reach drop emission through
|
|
`ailang_rc_dec`, which itself only fires for heap-Str at runtime
|
|
(static-Str pointers never carry a live rc_header; if codegen ever
|
|
let one through, the runtime would corrupt `.rodata`-adjacent
|
|
memory). No runtime guard backs the invariant up; the codegen
|
|
proof is the protection.
|
|
|
|
Ratified by: `crates/ail/tests/e2e.rs`.
|