Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/cli-drift.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ on:
- cron: '0 7 * * 1'
pull_request:
paths:
- 'docs/docs/reference/tools/cli.md'
- 'docs/docs/reference/tools/cli/index.md'
- 'scripts/check-cli-drift.py'
- '.github/workflows/cli-drift.yml'
workflow_dispatch:
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/conduct/readiness.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,11 +80,11 @@ Semver for a user's schema package means nothing until a break is defined.
reviewed and numbered for 1.0:
- the [generator protocol](../reference/generator-protocol.md), including
its render request (version 0 today);
- encoding profiles and the [conformance](../reference/conformance.md)
- encoding profiles and the [conformance](../reference/conformance/index.md)
corpus and ops protocol;
- the documentation model behind [`comline doc`](../reference/tools/cli/doc.md)
(version 1 today);
- the [`comline.toml` schema](../reference/congregation/comline-toml.md)
- the [`comline.toml` schema](../reference/package/congregation/comline-toml.md)
(`0.x` today);
- the JSON from [`comline inspect --json`](../reference/tools/cli/inspect.md).
- The extension API is part of 1.0, so it is designed, built and frozen
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/design/validators.md
Original file line number Diff line number Diff line change
Expand Up @@ -257,7 +257,7 @@ left to right, parenthesising each comparison.
Whether decode runs the checks is the **consumer's** call, not the schema's — it
changes the shape and cost of generated decode (a clone per decode, no "parse
now, validate later"), which is a codegen concern. So it's a `[generate]` key in
the consumer's [`comline.toml`](../reference/congregation/comline-toml.md), overridable per
the consumer's [`comline.toml`](../reference/package/congregation/comline-toml.md), overridable per
`[[generate.target]]`, slotting into the existing
`defaults → [generate] → [[generate.target]] → env → CLI` precedence:

Expand All @@ -279,7 +279,7 @@ validate_on_decode = "collect"
in its `TryFrom`); `"off"` leaves decode untouched.
- Matching `COMLINE_GENERATE_VALIDATE_ON_DECODE` env var and
`--validate-on-decode` flag, like the other `[generate]` keys.
- Folds into [`comline.toml`](../reference/congregation/comline-toml.md) when 4c ships.
- Folds into [`comline.toml`](../reference/package/congregation/comline-toml.md) when 4c ships.

### Decided

Expand Down
4 changes: 2 additions & 2 deletions docs/docs/developer/extending/encodings.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,7 +129,7 @@ path with `.json` replaced by `.vectors.json`, so `profiles/lines.json` has
- Every `proven_by` entry in the profile names a case in this file.

The case format is a public, versioned spec: see the
[conformance reference](../../reference/conformance.md) for the ops, the value
[conformance reference](../../reference/conformance/wire.md) for the ops, the value
encoding and the rules a case is judged by.

To run it, write a small program that speaks the **ops protocol**: one JSON
Expand All @@ -144,7 +144,7 @@ The report gives, per encoding, how many cases pass, whether each profile fact
is **proven** (every case it names passes and shows its value), and a byte diff
for each failed encode. A failed or unimplemented case, or an unproven fact,
exits with `1`. The flags, limits and report are in the
[CLI reference](../../reference/tools/cli.md#commands).
[CLI reference](../../reference/tools/cli/index.md#commands).

- `comline conformance` runs every encoding the package declares. An encoding
with no vectors file is an error, so name the ones you mean with
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/developer/extending/handshakes.md
Original file line number Diff line number Diff line change
Expand Up @@ -164,7 +164,7 @@ A fact stated `true` is **proven by vectors**: cases of the decode-only op
agrees, which the handshake accepts. For each thing the fact covers there is
a peer frame that differs in only that, which it refuses: the IR hash for
`schema_agreement`, the format and the framing for `encoding_agreement`. See
the [`handshake_check` op](../../reference/conformance.md#ops). A fact stated
the [`handshake_check` op](../../reference/conformance/wire.md#ops). A fact stated
`false` claims nothing, so it names no cases.

A protocol **gives up every agreement its handshake's profile doesn't
Expand All @@ -191,7 +191,7 @@ gives up schema agreement (handshake `com.acme.hello@1` doesn't establish it)
For a handshake that states nothing, the `@unverified` marker is your word
that something else covers both.

```ids
```ids title="giving_up_guarantee.ids"
@handshake = "com.acme.hello@1"
@unverified = "the gateway checks the schema itself in its HELLO reply"
protocol Gateway { /* ... */ }
Expand Down
9 changes: 8 additions & 1 deletion docs/docs/developer/extending/index.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,12 @@
# Extending Comline

In this section you will find guides that are for people <u>_that want to make implementations
that extend Comline_</u>, either for your own specific personal use cases or to extend the
Comline Project itself upstream.

If you simply want to use Comline (writting schemas, configuring your package, implement generated
code), then you should go to the regular [Guides](../../guides/index.md) instead

Comline has five places where you can bring your own code. This section is a
guide to each. What a page describes is built and shipped; what isn't is
listed under [What isn't built](#what-isnt-built).
Expand Down Expand Up @@ -29,7 +36,7 @@ listed under [What isn't built](#what-isnt-built).
`@` and a whole number. A bare name such as `json@1` is reserved for the
official package, and `comline build` rejects it anywhere else.
- **Proof is optional but visible.** An encoding can ship test vectors that
prove an implementation, run with [`comline conformance`](../../reference/tools/cli.md#commands).
prove an implementation, run with [`comline conformance`](../../reference/tools/cli/index.md#commands).
Nothing forces you to write them, but a format or framing without them, and
a handshake whose profile doesn't state what it establishes, give up a
guarantee that the schema must mark with `@unverified`. See
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/developer/extending/transports.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ handshake never sees which one it is.
A transport carries **whole frames**. A medium that has message boundaries
carries one frame per message. A byte stream has none, so it adds a `u32`
little-endian length prefix per frame, as the runtime's own TCP transport does.
The [conformance reference](../../reference/conformance.md#stream-framing)
The [conformance reference](../../reference/conformance/wire.md#stream-framing)
has the exact rules.

## Rust
Expand Down
7 changes: 0 additions & 7 deletions docs/docs/developer/index.md
Original file line number Diff line number Diff line change
@@ -1,8 +1 @@
# Overview

In this section you will find guides that are for people <u>_that want to make implementations
that extend Comline_</u>, either for your own specific personal use cases or to extend the
Comline Project itself upstream.

If you simply want to use Comline (writting schemas, configuring your package, implement generated
code), then you should go to the regular [Guides](../guides/index.md) instead
24 changes: 11 additions & 13 deletions docs/docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,15 @@
from source. You need a Rust toolchain ([rustup](https://rustup.rs/)) and
`git`:

```bash
```shell
git clone https://github.com/ComlineProject/cli
cd cli
cargo install --path .
```

This puts the `comline` binary in `~/.cargo/bin`. Check it's on your `PATH`:

```bash
```shell
comline --help
```

Expand All @@ -24,14 +24,14 @@ planned; packaging is tracked in

## Create a project

```bash
```shell
comline new my-api
cd my-api
```

You get:

```text
```shell
my-api/
├── config.idp # package manifest
├── comline.toml # where generated code goes (all-commented by default)
Expand All @@ -40,9 +40,7 @@ my-api/
└── .gitignore # ignores .comline/deps-cache/
```

`src/main.ids`:

```ids
```ids title="src/main.ids"
/// The language a greeting is written in.
enum Language {
English
Expand All @@ -64,7 +62,7 @@ characters. To set one for the whole package instead, see

## Build

```bash
```shell
comline build
```

Expand All @@ -77,21 +75,21 @@ since the last one.

Validate without freezing — safe for editors and pre-commit hooks:

```bash
```shell
comline check
```

## Generate code

```bash
```shell
comline generate
```

Targets come from `code_generation.languages` in `config.idp` (the scaffold
declares `rust#1.85.0`, the Rust generator's floor); output lands under `generated/` by default. Change where
and how in [`comline.toml`](reference/congregation/comline-toml.md):
and how in [`comline.toml`](reference/package/congregation/comline-toml.md):

```toml
```toml title="comline.toml"
[generate]
out = "src/generated"
layout = "{{language}}/{{namespace}}.{{ext}}"
Expand All @@ -104,4 +102,4 @@ Today `rust` and `typescript` are the generators.
- [Overview](guides/index.md) — the whole pipeline
- [IDL guide](guides/idl/index.md) — the schema language
- [Generating code](guides/codegen/generating-code.md) — the full `generate` surface
- [CLI reference](reference/tools/cli.md) — every command and flag
- [CLI reference](reference/tools/cli/index.md) — every command and flag
4 changes: 2 additions & 2 deletions docs/docs/guides/codegen/generating-code.md
Original file line number Diff line number Diff line change
Expand Up @@ -267,7 +267,7 @@ using cross-schema references in `code` mode needs to declare matching `mod`
statements itself.

`std` is the exception, because
[`external_std`](../../reference/congregation/comline-toml.md#external_std)
[`external_std`](../../reference/package/congregation/comline-toml.md#external_std)
is on by default in `lib` mode: a std type then resolves to
`comline_std::http::Request` and the crate depends on `comline_std` rather
than carrying a copy of it.
Expand All @@ -293,7 +293,7 @@ An alias imports the name the other module actually exports
nothing refers to produces no import at all.

`std` again resolves to its own package when
[`external_std`](../../reference/congregation/comline-toml.md#external_std)
[`external_std`](../../reference/package/congregation/comline-toml.md#external_std)
is on, by subpath import — the leading `std` segment drops, since
`@comline/std` is its own package root:

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/guides/codegen/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ detail that the generated code is pleasant to use directly rather than only as a
## Using it

`comline generate` is the command; [Generating code](generating-code.md) is the
full guide, and [`comline.toml`](../../reference/congregation/comline-toml.md) is where a
full guide, and [`comline.toml`](../../reference/package/congregation/comline-toml.md) is where a
consumer sets the output location, layout and mode.

Today there are `rust` and `typescript` generators, and both do `code` and
Expand Down
6 changes: 3 additions & 3 deletions docs/docs/guides/codegen/library-generation.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ the module layout. A planned third mode, `dylib`, would compile it to a library
any language's [runtime](../runtime/index.md) can load.

`comline generate`'s `mode` chooses how far generation goes. It is set per target
in [`comline.toml`](../../reference/congregation/comline-toml.md) (`[generate] mode` or
in [`comline.toml`](../../reference/package/congregation/comline-toml.md) (`[generate] mode` or
`[[generate.target]] mode`).

| `mode` | Output | Status |
Expand Down Expand Up @@ -71,7 +71,7 @@ import { Greeting } from "my-api/types";
Comline's standard library is implicitly part of every package, so without
help a `lib` build would vendor `std/http` and `std/validators` into every
generated package. It doesn't:
[`external_std`](../../reference/congregation/comline-toml.md#external_std)
[`external_std`](../../reference/package/congregation/comline-toml.md#external_std)
defaults to **on** in `lib` mode, so std's schemas are left out and the
manifest depends on std's own pre-generated package instead —
`comline_std` for rust, `@comline/std` for typescript. Your own nested
Expand All @@ -89,7 +89,7 @@ with a message naming the pair.
In either language, `<language>/` keeps this target's package from colliding
with another `lib` target sharing the same `out`; a target with `out` to
itself can set
[`flatten = true`](../../reference/congregation/comline-toml.md#flatten) to skip that and
[`flatten = true`](../../reference/package/congregation/comline-toml.md#flatten) to skip that and
land the package straight into `out`. `layout` plays no part in any of this —
it only applies to `code` mode. Multi-version `lib` output is not done yet.

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/guides/documenting.md
Original file line number Diff line number Diff line change
Expand Up @@ -211,7 +211,7 @@ and every path it returns is checked before anything is written.

## Settings

Every flag has a `[doc]` key in [`comline.toml`](../reference/congregation/comline-toml.md#doc),
Every flag has a `[doc]` key in [`comline.toml`](../reference/package/congregation/comline-toml.md#doc),
and the flag wins:

| Key | Flag | Default |
Expand Down
5 changes: 2 additions & 3 deletions docs/docs/guides/idl/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,7 @@ write by hand. A schema file has the extension `.ids` and lives under a project'
`src/` directory. It defines the data shapes and the protocols that carry them,
independent of any language.

```ids
// greeting.ids
```ids title="greeting.ids"
const GREETING_MAX: u16 = 280

enum Language {
Expand Down Expand Up @@ -57,7 +56,7 @@ next declaration. `//!` lines at the top of a file are its

## Imports

```ids
```ids title="imports.ids"
use std::http::Request
use mypackage::{User, Post}
use external::uuid::Uuid as UUID
Expand Down
22 changes: 11 additions & 11 deletions docs/docs/guides/idl/types.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
Primitives:

| Group | Types |
|---|---|
| --- | --- |
| signed integers | `s8` `s16` `s32` `s64` `s128` |
| unsigned integers | `u8` `u16` `u32` `u64` `u128` |
| floats | `f32` `f64` |
Expand All @@ -18,7 +18,7 @@ type or given by a [setting](settings.md#default-maximums). The examples in this
carry maxima so they build as written; a bare `string` or `T[]` in one of your
schemas builds only once a default is set.

### Text: `string` and `char`
## Text: `string` and `char`

- **`char`** is one Unicode scalar value: a single character, not a byte or a
UTF-16 unit. Its literal is a string of exactly one character, `"a"`; any
Expand Down Expand Up @@ -79,7 +79,7 @@ A schema builds only when every string and dynamic array, at every position
There is no built-in default, so a position with none of these is an error that
names it and the fix:

```
```sh
struct `Greeting`, field `message`: `string` has no maximum
Help: write `char[max N]`, or set `bounds.string.max` in settings
```
Expand All @@ -97,7 +97,7 @@ A [type alias](#type-aliases) carries its bound, and the limit is changed
there. Where an alias of a string or of a dynamic array is used (a field,
argument, return or union member), it takes **no `[…]` suffix** of its own:

```ids
```ids title="bounds.ids"
type Name = char[max 32]
type Names = Name[max 10] // a list of an alias is its own alias

Expand All @@ -116,9 +116,9 @@ Writing an alias in a list inside another alias, as `Names` does, is allowed.

## Type aliases

`type NAME = TYPE` gives a type a second name:
Writting `#!ids type NAME = TYPE` gives a type a second name:

```ids
```ids title="type_alias.ids"
type UserId = u64
type Handle = char[max 32]

Expand All @@ -128,17 +128,17 @@ struct User {
}
```

An alias is transparent: `UserId` is a `u64` everywhere, in the wire format and
in generated code (`pub type UserId = u64;`, `export type UserId = number;`).
An alias is transparent: `#!ids UserId` is a `#!ids u64` everywhere, in the wire format and in generated code. (In Rust is: `#!rust pub type UserId = u64;`, in Typescript being: `#!typescript export type UserId = number;` etc).

An alias can name another alias.

An alias can carry [`@validators`](validator.md#on-a-type-alias), which then
check every value of it, and `@deprecated`, which warns wherever it's used.
An alias can carry [Validators](validator.md#on-a-type-alias), which then
check every value of it.

## In generated code

| Comline | Rust | TypeScript |
|---|---|---|
| --- | --- | --- |
| `s8` … `s32` | `i8` … `i32` | `number` |
| `u8` … `u32` | `u8` … `u32` | `number` |
| `s64`, `s128` | `i64`, `i128` | `bigint` |
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/guides/idl/validator.md
Original file line number Diff line number Diff line change
Expand Up @@ -199,7 +199,7 @@ an alias: innermost first), then by the field's own.
- An alias is the only way to check a **function argument**: arguments take no
annotations of their own, but `to: Handle` runs `Handle`'s checks.

`@deprecated` works on an alias too, and warns wherever the alias is used.
`#!ids @deprecated` works on an alias too, and warns wherever the alias is used.

## In generated code

Expand All @@ -225,7 +225,7 @@ in `comline.toml`; `"first"` stops at the first failure), and a provider
refuses a call whose arguments fail them. Turning that off is a give-up with
its reason, `validate_on_decode = { off = "why" }`; then nothing runs until you
call `validate()`. See
[`validate_on_decode`](../../reference/congregation/comline-toml.md#validate_on_decode).
[`validate_on_decode`](../../reference/package/congregation/comline-toml.md#validate_on_decode).

Properties are filled in when the code is generated: the argument you wrote,
else the property's default, with constants resolved. Nothing about the
Expand Down
Loading
Loading