diff --git a/README.md b/README.md index be26ebe..2be9534 100644 --- a/README.md +++ b/README.md @@ -141,15 +141,17 @@ $users = new Collection( vendor/bin/xphp compile ``` -| Argument | Purpose | -|------------|--------------------------------------------------------------------------------------| -| `` | Directory of `.xphp` files (PSR-4 layout) | -| `` | Where rewritten `.php` files land -- your user code with generic call sites replaced | -| `` | Where specialized classes live | +| Argument | Required | Default | Purpose | +|------------|----------|----------------|--------------------------------------------------------------------------------------| +| `` | yes | -- | Directory of `.xphp` files (PSR-4 layout) | +| `` | no | `dist` | Where rewritten `.php` files land -- your user code with generic call sites replaced | +| `` | no | `.xphp-cache` | Where specialized classes live | p.s. you can `gitignore` files in `` and `` as they can be generated in your CI/CD pipeline. -#### Sample output +#### Sample output + +The sample below uses a readable name (`Collection_User`) for clarity. The compiler actually emits hashed FQNs of the form `\XPHP\Generated\App\Collection\T_` -- see the [generics reference](docs/type-system/generics/index.md) for the real scheme. ```php // /Generated/Collection_User.php @@ -157,9 +159,6 @@ namespace XPHP\Generated; use App\User; -// p.s. in reality it uses a hash in the class name, -// but developers won't touch that, -// only php runtime will see the hashed names. class Collection_User { private array $items; @@ -205,5 +204,5 @@ Meaning every place where generics are declared or used is converted into normal ## See also -- [Type-system comparison](core/docs/type-system/comparison.md) -- [Full generics reference](core/docs/type-system/generics/index.md) +- [Type-system comparison](docs/type-system/comparison.md) +- [Full generics reference](docs/type-system/generics/index.md) diff --git a/docs/compiler.md b/docs/compiler.md index 75256bb..1e8c911 100644 --- a/docs/compiler.md +++ b/docs/compiler.md @@ -1,23 +1,25 @@ # How the xphp compiler works -Narrative walkthrough of the `core/` pipeline -- what `bin/xphp compile` +Narrative walkthrough of the compile pipeline -- what `bin/xphp compile` does between reading `.xphp` source and writing vanilla `.php` files that any stock PHP 8.4 runtime can execute. Each phase is paired with a Mermaid diagram so the same information is available both visually and in prose. For the feature inventory ("what does xphp support today?") see -[generics reference](generics/index.md). For the strategic comparison -against TypeScript / Kotlin / Rust see [comparison](type-system/comparison.md). -For the forward-looking inventory see [roadmap](roadmap.md). +[generics reference](type-system/generics/index.md). For the strategic +comparison against TypeScript / Kotlin / Rust see +[comparison](type-system/comparison.md). For the forward-looking inventory +see [roadmap](roadmap.md). --- ## Pipeline overview -`bin/xphp compile ` runs a single +`bin/xphp compile [target-dir] [cache-dir]` runs a single function -- [`Compiler::compile()`](../src/Transpiler/Monomorphize/Compiler.php) --- that orchestrates five phases. The data flows top-down: source bytes +-- that orchestrates five phases. Only `` is required; `[target-dir]` +defaults to `dist` and `[cache-dir]` defaults to `.xphp-cache`. The data flows top-down: source bytes turn into AST, the AST populates a Registry and a TypeHierarchy, a fixed-point loop expands every concrete instantiation into a specialized class file, and finally the rewritten user code lands in the target @@ -119,8 +121,8 @@ Two parser entry points exist: source. - `parseTolerantWithMap()` -- recovers from trailing parse errors by feeding the stripped source through nikic's error-handler- - collecting mode. Used by the LSP path so mid-edit source still - yields useful results. + collecting mode. Used when callers need partial results from + incomplete source. --- @@ -370,16 +372,14 @@ birthday collisions are impossible at any practical project size. `ByteOffsetMap` carries the bytes-stripped-and-where info so any diagnostic span computed after the strip can be translated back to -the original `.xphp` source. The map gets serialised through to -the LSP layer too, so editor squiggles land on the right column -even though the parsed AST was built from stripped source. +the original `.xphp` source. --- ## Class roster Every class under -[`core/src/Transpiler/Monomorphize/`](../src/Transpiler/Monomorphize/), +[`src/Transpiler/Monomorphize/`](../src/Transpiler/Monomorphize/), grouped by role. ```mermaid diff --git a/docs/roadmap.md b/docs/roadmap.md index 4ecfeff..233a0ec 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -31,7 +31,6 @@ timeline : XPHP_HASH_LENGTH configurable (16..64) Developer experience : PSR-4 fixtures - : --lint headless CLI for CI (file,line,col error output) section Next Type system depth : default type parameters diff --git a/docs/type-system/comparison.md b/docs/type-system/comparison.md index 9fb3cac..61c5000 100644 --- a/docs/type-system/comparison.md +++ b/docs/type-system/comparison.md @@ -105,10 +105,8 @@ class) is supported. `$obj->method(...)` requires knowing the static type of properties, the static type is usually known at the call site; the unsolved part is the dispatch table when `$obj` is a union / intersection / interface. -Tracked in `core/roadmap.md` under "Next". The LSP already substitutes -type-args at instance call sites for hover / signature help / inlay hints -- -that's display-only inference; the compiler-level lowering for runtime dispatch -is the gap. +Tracked in the [roadmap](../roadmap.md) under "Next". The compiler-level +lowering for runtime dispatch is the gap. ### 5. Reified type parameters diff --git a/docs/type-system/generics/index.md b/docs/type-system/generics/index.md index a0d537d..c08f906 100644 --- a/docs/type-system/generics/index.md +++ b/docs/type-system/generics/index.md @@ -4,7 +4,7 @@ This document covers how `xphp` implements generics: what the compiler emits, what's supported today, the naming scheme for generated classes, and the trade-offs the monomorphization model accepts. -For the broader project context, see the [README](/README.md). +For the broader project context, see the [README](../../../README.md). --- @@ -23,7 +23,7 @@ For comparison, Rust does also apply monomorphization. Kotlin and TypeScript don't do that, and there they have no runtime safety. Variance annotations based on monomorphization become real subtype edges between -specialized classes -- that's in the [roadmap](../roadmap.md). +specialized classes -- that's in the [roadmap](../../roadmap.md). --- @@ -263,5 +263,5 @@ intentional. ## Type-system comparison -See a [side-by-side comparison](./comparison.md) against TypeScript, Kotlin, +See a [side-by-side comparison](../comparison.md) against TypeScript, Kotlin, and Rust -- including the features `xphp` doesn't have yet.