Format

Author: lucic71

docs/src/SUMMARY.md

@@ -2,26 +2,26 @@
 
 # The Project
 
-* [Introduction](./project/introduction.md)
-* [Building](./project/building.md)
-* [Usage](./project/usage.md)
-* [Test Suite](./project/test-suite.md)
+- [Introduction](./project/introduction.md)
+- [Building](./project/building.md)
+- [Usage](./project/usage.md)
+- [Test Suite](./project/test-suite.md)
 
 # Translation Rules
 
-* [Overview](./rules/overview.md)
-* [Rule Format](./rules/format.md)
-* [Writing Rules](./rules/writing-rules.md)
-* [Compat Shims](./rules/compat.md)
-* [Conventions](./rules/conventions.md)
-* [The Rule Preprocessors](./rules/preprocessors.md)
-* [The Rules IR](./rules/ir.md)
-* [Loading and Matching](./rules/loading.md)
-* [The Matching Engine](./rules/matching.md)
-* [Rule Rewriting](./rules/rewriting.md)
+- [Overview](./rules/overview.md)
+- [Rule Format](./rules/format.md)
+- [Writing Rules](./rules/writing-rules.md)
+- [Compat Shims](./rules/compat.md)
+- [Conventions](./rules/conventions.md)
+- [The Rule Preprocessors](./rules/preprocessors.md)
+- [The Rules IR](./rules/ir.md)
+- [Loading and Matching](./rules/loading.md)
+- [The Matching Engine](./rules/matching.md)
+- [Rule Rewriting](./rules/rewriting.md)
 
 # Code Generation
 
-* [Overview](./codegen/overview.md)
-* [Pointers and References](./codegen/pointers.md)
-* [Temporary Materialization](./codegen/temporaries.md)
+- [Overview](./codegen/overview.md)
+- [Pointers and References](./codegen/pointers.md)
+- [Temporary Materialization](./codegen/temporaries.md)

docs/src/codegen/overview.md

@@ -3,6 +3,6 @@
 This part of the book documents the internals of the code generator: how the
 clang AST is traversed and how Rust code is emitted.
 
-TODO: document the converter plugin mechanism
-(`cpp2rust/converter/plugins/`), which intercepts constructs ahead of the
-translation rules (currently `emplace_back`).
+TODO: document the converter plugin mechanism (`cpp2rust/converter/plugins/`),
+which intercepts constructs ahead of the translation rules (currently
+`emplace_back`).

docs/src/codegen/temporaries.md

@@ -1,5 +1,5 @@
 # Temporary Materialization
 
-> TODO: explain how the converter materializes temporaries for expressions
-> that need an address but have none (e.g. literals passed where a pointer is
+> TODO: explain how the converter materializes temporaries for expressions that
+> need an address but have none (e.g. literals passed where a pointer is
 > expected).

docs/src/project/introduction.md

@@ -9,21 +9,19 @@ published at PLDI 2026.
 
 ## Overview
 
-Cpp2Rust first parses the input C++ file(s) with clang and produces an AST.
-It then traverses the AST and emits Rust code as strings, inserting
-calls to the `libcc2rs` runtime library where needed (e.g., for raw pointer
-semantics).
+Cpp2Rust first parses the input C++ file(s) with clang and produces an AST. It
+then traverses the AST and emits Rust code as strings, inserting calls to the
+`libcc2rs` runtime library where needed (e.g., for raw pointer semantics).
 Finally, the Rust code is pretty-printed using `rustfmt` to a single `.rs` file.
 
-By default the *reference counting model* is used, which produces fully safe
-Rust.
-A generator of unsafe Rust is also available through the `--model=unsafe`
+By default the _reference counting model_ is used, which produces fully safe
+Rust. A generator of unsafe Rust is also available through the `--model=unsafe`
 command line argument for debugging and performance comparisons.
 
 ## Runtime library (`libcc2rs`)
 
 The generated code relies on a runtime library designed to simplify the
-translation process.
-C pointers are converted into the `Ptr<T>` type provided by `libcc2rs`.
-`Ptr<T>` models C pointer semantics, including null, arithmetic, and aliasing,
-while satisfying Rust's borrow checker through checked run-time operations.
+translation process. C pointers are converted into the `Ptr<T>` type provided by
+`libcc2rs`. `Ptr<T>` models C pointer semantics, including null, arithmetic, and
+aliasing, while satisfying Rust's borrow checker through checked run-time
+operations.

docs/src/project/usage.md

@@ -6,8 +6,8 @@
 ./build/cpp2rust/cpp2rust --file=<file>.cpp -o=<file>.rs
 ```
 
-By default, the reference counting model is used (fully safe output).
-To generate unsafe Rust instead:
+By default, the reference counting model is used (fully safe output). To
+generate unsafe Rust instead:
 
 ```bash
 ./build/cpp2rust/cpp2rust --file=<file>.cpp -o=<file>.rs --model=unsafe

docs/src/rules/compat.md

@@ -1,46 +1,45 @@
 # Compat Shims
 
-Rule matching needs a resolvable callee. The preprocessor keys every
-expression rule on the function, method, constructor, constant, or global
-that the pattern's `return` expression resolves to, and the only macros it
-can record are those that
+Rule matching needs a resolvable callee. The preprocessor keys every expression
+rule on the function, method, constructor, constant, or global that the
+pattern's `return` expression resolves to, and the only macros it can record are
+those that
 [expand to an integer literal](./writing-rules.md#enum-values-constants-and-macros),
-which match by macro name. Any other macro is invisible to the rule system:
-by the time clang has built the AST, the macro is gone and only its expansion
+which match by macro name. Any other macro is invisible to the rule system: by
+the time clang has built the AST, the macro is gone and only its expansion
 remains.
 
-That is a problem for a small set of libc APIs that are specified as macros
-over platform internals:
+That is a problem for a small set of libc APIs that are specified as macros over
+platform internals:
 
-* `errno` is an object-like macro; glibc expands it to
-  `(*__errno_location())`, macOS to `(*__error())`.
-* `assert` expands to a conditional that stringifies the condition and calls
-  a platform-specific failure handler with file and line arguments.
-* `FD_SET`, `FD_CLR`, `FD_ISSET`, and `FD_ZERO` expand to bit manipulation
-  on the `fd_set` representation, through helpers that differ per platform.
-* `ntohl`, `ntohs`, `htonl`, and `htons` expand to byte-swap builtins or to
+- `errno` is an object-like macro; glibc expands it to `(*__errno_location())`,
+  macOS to `(*__error())`.
+- `assert` expands to a conditional that stringifies the condition and calls a
+  platform-specific failure handler with file and line arguments.
+- `FD_SET`, `FD_CLR`, `FD_ISSET`, and `FD_ZERO` expand to bit manipulation on
+  the `fd_set` representation, through helpers that differ per platform.
+- `ntohl`, `ntohs`, `htonl`, and `htons` expand to byte-swap builtins or to
   nothing at all, depending on endianness.
 
 There is no stable, platform-independent callee here to key a rule on. The
-*compat headers* in `cpp2rust/compat/` fix this by rewriting each such macro
+_compat headers_ in `cpp2rust/compat/` fix this by rewriting each such macro
 into a call to a synthetic, well-known function before matching happens.
 
 ## How the shims work
 
 `cpp2rust/compat` is injected as a system include directory ahead of the
 platform headers in every clang invocation the project makes: both when
 `cpp2rust` parses the input program and when `cpp-rule-preprocessor` compiles
-rule sources. The shared flag list lives in
-`cpp2rust/compat/platform_flags.h` (`getPlatformClangBeginFlags`), and the
-directory path is baked in at build time via the `COMPAT_INCLUDE_DIR`
-definition.
+rule sources. The shared flag list lives in `cpp2rust/compat/platform_flags.h`
+(`getPlatformClangBeginFlags`), and the directory path is baked in at build time
+via the `COMPAT_INCLUDE_DIR` definition.
 
 A shim header sits at the same relative path as the real header it shadows
 (`errno.h`, `sys/select.h`, `arpa/inet.h`, ...), so an ordinary
 `#include <errno.h>` finds the shim first. The header then:
 
-1. pulls in the real platform header with `#include_next` (a GNU extension;
-   the shared flags pass `-Wno-gnu-include-next` for it),
+1. pulls in the real platform header with `#include_next` (a GNU extension; the
+   shared flags pass `-Wno-gnu-include-next` for it),
 2. `#undef`s the macro,
 3. declares a `cpp2rust_*` shim function,
 4. redefines the macro to call the shim.
@@ -57,12 +56,12 @@ int *cpp2rust_errno(void);
 #define errno (*cpp2rust_errno())
 ```
 
-The redefinition keeps `errno` an lvalue by dereferencing the returned
-pointer, so both reads and assignments like `errno = 0` still parse; what
-the matcher sees in either case is a call to `int *cpp2rust_errno()`.
+The redefinition keeps `errno` an lvalue by dereferencing the returned pointer,
+so both reads and assignments like `errno = 0` still parse; what the matcher
+sees in either case is a call to `int *cpp2rust_errno()`.
 
-Because the input program and the rule sources are compiled with the same
-shim headers, both sides canonicalize to the same signature, and an ordinary
+Because the input program and the rule sources are compiled with the same shim
+headers, both sides canonicalize to the same signature, and an ordinary
 [expression rule](./writing-rules.md) matches it:
 
 ```c
@@ -72,10 +71,10 @@ shim headers, both sides canonicalize to the same signature, and an ordinary
 int *f1(void) { return cpp2rust_errno(); }
 ```
 
-The shim functions are declared but never defined on the C side. They only
-exist so that the callee resolves; translation replaces the call with the
-rule body, so no C implementation is ever linked. Whatever the shim is
-supposed to *do* is supplied by the Rust targets:
+The shim functions are declared but never defined on the C side. They only exist
+so that the callee resolves; translation replaces the call with the rule body,
+so no C implementation is ever linked. Whatever the shim is supposed to _do_ is
+supplied by the Rust targets:
 
 ```rust
 // rules/errno/tgt_unsafe.rs
@@ -91,11 +90,11 @@ fn f1() -> Ptr<i32> {
 }
 ```
 
-In the unsafe model `libcc2rs::cpp2rust_errno_unsafe` wraps the real
-platform errno location (`__errno_location` on Linux, `__error` on macOS).
-The refcount model instead *virtualizes* errno as a thread-local
-`Value<i32>` inside `libcc2rs`; this is the same cell that other refcount
-rules write when they translate a failing libc call into
+In the unsafe model `libcc2rs::cpp2rust_errno_unsafe` wraps the real platform
+errno location (`__errno_location` on Linux, `__error` on macOS). The refcount
+model instead _virtualizes_ errno as a thread-local `Value<i32>` inside
+`libcc2rs`; this is the same cell that other refcount rules write when they
+translate a failing libc call into
 `libcc2rs::cpp2rust_errno().write(__e as i32)`.
 
 A rule pattern may spell either the macro or the shim directly; the two are
@@ -109,17 +108,17 @@ void f2(int fd, fd_set *set) { return FD_SET(fd, set); }
 
 ## The current shims
 
-| Header | Macros | Shim functions | Rules |
-|---|---|---|---|
-| `assert.h` | `assert` | `cpp2rust_assert_fail(bool)` | `rules/assert` maps it to `assert!(a0)` |
-| `errno.h` | `errno` | `cpp2rust_errno()` | `rules/errno`, see above |
-| `arpa/inet.h` | `ntohl`, `ntohs`, `htonl`, `htons` | `cpp2rust_ntohl(x)`, ... | `rules/arpa_inet` maps them to `u32::from_be`, `u16::to_be`, ... |
+| Header         | Macros                                    | Shim functions                  | Rules                                                                                   |
+| -------------- | ----------------------------------------- | ------------------------------- | --------------------------------------------------------------------------------------- |
+| `assert.h`     | `assert`                                  | `cpp2rust_assert_fail(bool)`    | `rules/assert` maps it to `assert!(a0)`                                                 |
+| `errno.h`      | `errno`                                   | `cpp2rust_errno()`              | `rules/errno`, see above                                                                |
+| `arpa/inet.h`  | `ntohl`, `ntohs`, `htonl`, `htons`        | `cpp2rust_ntohl(x)`, ...        | `rules/arpa_inet` maps them to `u32::from_be`, `u16::to_be`, ...                        |
 | `sys/select.h` | `FD_SET`, `FD_CLR`, `FD_ISSET`, `FD_ZERO` | `cpp2rust_fd_set(fd, set)`, ... | `rules/select` maps them to `libc::FD_SET(...)` (unsafe) or `CFdSet` methods (refcount) |
 
-Note how the shim also normalizes the *shape* of the API. C's `assert` is a
-macro precisely so it can stringify its condition and capture file and line;
-the shim reduces it to a plain `void(bool)` function, and the Rust side
-regains the diagnostics by mapping it to the `assert!` macro.
+Note how the shim also normalizes the _shape_ of the API. C's `assert` is a
+macro precisely so it can stringify its condition and capture file and line; the
+shim reduces it to a plain `void(bool)` function, and the Rust side regains the
+diagnostics by mapping it to the `assert!` macro.
 
 ## Adding a new shim
 
@@ -132,15 +131,15 @@ To make another macro-based API matchable:
    signature, and redefine the macro to call it.
 3. Write rules for the shim in a `rules/` module as for any other function,
    including the corresponding header in `src.c`/`src.cpp`.
-4. If a model needs runtime support (as refcount errno does), implement it
-   in `libcc2rs` and call it from the rule target.
+4. If a model needs runtime support (as refcount errno does), implement it in
+   `libcc2rs` and call it from the rule target.
 
-Keep the shim's signature platform-independent; the whole point is that
-both sides of every rule see one canonical declaration on every platform.
+Keep the shim's signature platform-independent; the whole point is that both
+sides of every rule see one canonical declaration on every platform.
 
 ## Related normalization
 
-The same shared flag list also passes `-D_FORTIFY_SOURCE=0`, which keeps
-glibc from substituting fortified variants (`__printf_chk` and friends) for
-standard calls. Like the shims, this ensures that calls in the input program
-resolve to the standard declarations the rules are written against.
+The same shared flag list also passes `-D_FORTIFY_SOURCE=0`, which keeps glibc
+from substituting fortified variants (`__printf_chk` and friends) for standard
+calls. Like the shims, this ensures that calls in the input program resolve to
+the standard declarations the rules are written against.