One command-line spec, two notations. An alux-cli program can be declared in Rust or written in Markdown, and each compiles to the other:
- Rust → Markdown.
Describeis one more interpreter of thealux-clialgebras. It applies nothing and folds a program into aCliSpec, whichnotes-cli-markdownrenders. - Markdown → Rust.
notes-cli-markdownreads the same format back into aCliSpec, andnotes-cli-rust-gengenerates the#[ext(defunc(via = cli))]declaration from it, whichnotes-cli-macroexpands in place from a file or inline Markdown: the same aligned table a person writes. - Both, as commands. Every binary has a
docscommand that folds its own program back to Markdown, so the spec a binary prints is the spec it runs.
What the notes app means, with no interpreter in it. They sit at the top level; x-y is x over y, and a specification stated over another is listed after it.
| Crate | Responsibility | |
|---|---|---|
notes |
Notes in named stores, added, listed, removed | |
notes-search |
Finding notes by their words |
One command line, stated three ways; each folds back to the same cli.md. notes-cli-mixed declares add, list, and remove in Rust and states search and docs in inline Markdown.
| Crate | States the command line | |
|---|---|---|
notes-cli-rust |
declared in Rust | |
notes-cli-md |
stated in Markdown | |
notes-cli-mixed |
Rust and inline Markdown, merged |
In Rust, a command line reads as a table too: one row per argument, its help, shape, flag, variable, and default in columns.
Interpreters, or implementations, of the specifications above, under crates/. The specifications use none of them, and each specification can have several.
| Crate | Responsibility | |
|---|---|---|
notes-files |
The notebook in a store file | |
notes-memory |
The notebook in memory, for tests | |
notes-conformance |
The laws every interpreter passes |
Each runs its spec with alux-cli-direct over notes-files.
| Crate | Runs | |
|---|---|---|
notes-cli-md-direct |
notes-cli-md, the default cargo run |
|
notes-cli-rust-direct |
notes-cli-rust |
| Crate | Provides | |
|---|---|---|
notes-cli-describe |
Describe, a program as a CliSpec |
|
notes-cli-markdown |
render and parse, a CliSpec as Markdown |
|
notes-cli-rust-gen |
generate, a CliSpec as Rust |
|
notes-cli-macro |
markdown_cli! and markdown_cli_src! |
|
notes-cli-md-tool |
A spec tool, itself stated in Markdown |
The tests pin the round trips as laws:
- Both notes binaries, and
notes-cli-mixed, fold their command line back tonotes-cli-md/src/cli.md, so every notation states one spec. notes-cli-md-toolfolds back to the Markdown it is compiled from, and checks every spec in the workspace.notes-cli-markdownreads back every spec it renders, and renders back every Markdown it reads.
just docs notes-cli-rust-direct # Rust -> Markdown
just rust notes-cli-md/src/cli.md # Markdown -> Rustcargo run runs the notes app, notes-cli-md-direct; the words after -- are the app's.
# Lists the commands; `<command> --help` shows one command's arguments.
cargo run -q -- --help
# Usage: notes <command>
#
# Commands:
# add Adds a note to the store.
# list Lists the notes in the store, oldest first.
# remove Removes a note from the store.
# search Finds the notes holding every word, pinned first.
# docs Prints this command line's spec as Markdown.
# Adds "buy milk" tagged `home` to ./notes.db and prints its number.
cargo run -q -- add "buy milk" --tag home
# Pins a note, in a store named by the variable instead of the default.
NOTES_STORE=work.db cargo run -q -- add "send report" --pinned
# Lists the notes, oldest first, and then only those tagged `home`.
cargo run -q -- list
cargo run -q -- list home
# Finds the notes holding every word, pinned first.
cargo run -q -- search milk
# Removes note 1.
cargo run -q -- remove 1
# Prints the command line's own spec, `notes-cli-md/src/cli.md`.
cargo run -q -- docs# notes
## `notes add`
Adds a note to the store.
- Operation: `add_note`
- Outcome: fallible
| Argument | Source | Shape | Variable | Default | Delimiter | Help |
| -------- | --------------- | ----- | ------------- | ---------- | --------- | ----------------------- |
| `store` | `--store`, `-s` | one | `NOTES_STORE` | `notes.db` | | Store to read and write |
| `text` | positional | one | | | | Text of the note |The title is the program name and each ## heading a command path; a heading with the program name alone is the root command. The paragraphs under it are the operation's documentation, which is the command's help. Operation names the extension method the command applies, and Outcome is total, fallible, fallible with status N, or fallible by error. Each table row is one argument, in the operation's order.
A command line is checked against its operations when it compiles, so a mistake in Markdown is a compile error at the macro, and rust-analyzer shows it while you type. Here, an argument named limits where the operation's argument is limit, first in Rust, then in inline Markdown, and then in a cli.md file:



