77 lines
4.5 KiB
Markdown
77 lines
4.5 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
# Run all specs
|
|
crystal spec
|
|
|
|
# Run a single spec file
|
|
crystal spec spec/command_spec.cr
|
|
|
|
# Type-check without running
|
|
crystal build src/cligen.cr --no-codegen
|
|
|
|
# Install dependencies
|
|
shards install
|
|
```
|
|
|
|
## What This Is
|
|
|
|
`cligen` is a Crystal **shard (library)** — not a standalone application. It wraps Crystal's built-in `OptionParser` with an annotation- and macro-driven system that auto-generates CLI parsers from class definitions. Users of the shard subclass `CliGen::Command` and annotate methods; the library generates the `OptionParser` wiring at compile time via Crystal macros.
|
|
|
|
## Architecture
|
|
|
|
### Entry point: `src/cligen.cr`
|
|
|
|
Defines the `CliGen` module. The `macro finished` hook calls `define_root_parser`, which scans all `CliGen::Command` subclasses at compile time and registers each as a subcommand on the root `OptionParser`. `CliGen.parse` runs the root parser.
|
|
|
|
`ADDITIONAL_DEFAULT_FLAGS` / `add_default_flag` let users inject extra flags into every parser (root and subcommand).
|
|
|
|
### Command definition: `src/cligen/command.cr`
|
|
|
|
`CliGen::Command` is the base class. When subclassed, `macro inherited` installs a `macro finished` block that triggers four code-generation macros in order:
|
|
|
|
1. `define_actions` — collects all `@[SubCommand]`-annotated class methods into `ACTIONS : Array(String)` and `@@action : String`.
|
|
2. `define_header` — builds the `HEADER` string (banner + examples) from `@[SubCommand]` and `@[CommandSelection]` annotation metadata.
|
|
3. `define_runner` (skipped if `@[CommandInfo(def_runner: false)]`) — generates a `self.run` method that dispatches on `@@action` or a selection variable via a `case` statement.
|
|
4. `define_action_setter` — generates `self.action=` with bounds-checking against `ACTIONS`.
|
|
|
|
#### Key macros on `Command`
|
|
|
|
- **`define_argument`** — declares a class-level variable (`@@`) and an annotated setter method (`@[CommandArgument]`). Handles `String`, `Bool`, `Int32`, `Array(String|Int32)`, and `Time`. Optional `check:` proc, `logger:` method, and `def_getter:` flag.
|
|
- **`define_selection`** — like `define_argument` but validates against a fixed list of values; annotated with `@[CommandArgument]` and participates in selection-based dispatch.
|
|
|
|
### Parser generation: `src/cligen/command/parser.cr`
|
|
|
|
`CliGen::Parser` is `extend`ed by `Command`. It provides `define_parser`, which generates `self.make_parser(parent_parser)`. That method:
|
|
|
|
1. Creates a subparser `OptionParser` with the command's `HEADER` as banner.
|
|
2. Wires `@[CommandSelection]`-annotated methods as `parser.on(name, description)` that set the selection variable.
|
|
3. Wires `@[SubCommand]`-annotated methods as subcommand strings that set `@@action`.
|
|
4. Wires `@[CommandArgument]`-annotated methods as `parser.on(short, long, description)` flag handlers.
|
|
5. Calls `CliGen.define_default_flags` (adds `-h`/`--help`, error handlers).
|
|
6. Registers the whole subparser on `parent_parser` under the command's lowercase class name.
|
|
|
|
### Annotations
|
|
|
|
| Annotation | Applied to | Purpose |
|
|
|---|---|---|
|
|
| `@[CommandInfo(description:, def_runner:)]` | Command subclass | Required; provides the description shown in root help; `def_runner: false` skips auto-generating `run` |
|
|
| `@[SubCommand(description:, examples:)]` | class method on Command | Marks a method as a dispatachable subcommand |
|
|
| `@[CommandArgument(short:, long:, description:, type:)]` | class method on Command | Generated automatically by `define_argument`/`define_selection`; drives parser wiring |
|
|
| `@[CommandSelection(selector:, description:, examples:)]` | class method on Command | Alternative to `SubCommand`; dispatches via a named selector variable instead of `@@action` |
|
|
| `@[CommandPreRun]` | class method on Command | Methods run unconditionally before dispatch inside `self.run` |
|
|
| `@[DefaultFlag]` | (reserved) | Defined but not currently used in generation |
|
|
|
|
### Supporting files
|
|
|
|
- `src/cligen/format.cr` — date/datetime format strings used by `Time` argument parsing.
|
|
- `src/cligen/regex.cr` — regexes for validating date/datetime input strings.
|
|
|
|
## Spec structure
|
|
|
|
`spec/command_spec.cr` uses Crystal's macro system heavily: most `it` blocks are generated at compile time by inspecting `CommandSubclass` via `@type` introspection. The `macro finished` wrapper around the entire `describe` block is required because `make_parser` and `run` don't exist until all `macro finished` hooks have fired.
|