VERSE
078e5e817c
- macOS, Linux badge and AI suggestions showcase in README - Update user guide and docs for development
38 lines
1.7 KiB
Markdown
38 lines
1.7 KiB
Markdown
# Command specification & lookup engine (`spec/`)
|
|
|
|
The `spec` module is the language parser of Iris. It understands the relationship between commands, subcommands, and flags.
|
|
|
|
## Data structures
|
|
|
|
- **`Spec`**: Top-level command definition (e.g. `git`).
|
|
- **`Subcommand`**: Recursively defined children (e.g. `commit` under `git`).
|
|
- **`Generator`**: A function providing dynamic content (e.g. file paths, docker IDs).
|
|
|
|
## The `Lookup` algorithm
|
|
|
|
The core path-traversal function:
|
|
|
|
1. **Tokenization**: Splits `"git commit -m"` into `["git", "commit", "-m"]`. Empty tokens (from trailing space) indicate the user is ready for the next suggestion level.
|
|
2. **Tree walking**: Starts at the root node (`git`) and matches each token against available subcommands.
|
|
3. **Context identification**: When traversal stops (partial word or option prefix), it defines:
|
|
- `prefix`: the path already traversed.
|
|
- `partial`: the word currently being typed.
|
|
4. **Result collection**: Gathers all subcommands and options matching the `partial` prefix.
|
|
|
|
## Example
|
|
|
|
Input: `git com`
|
|
1. Tokens: `["git", "com"]`.
|
|
2. Walk: root is `git`.
|
|
3. Next token `com` doesn't match `commit` exactly.
|
|
4. Stop. `partial = "com"`.
|
|
5. Suggestions: subcommands of `git` starting with `com`.
|
|
6. Return: `git commit`.
|
|
|
|
## Shell aliases & priority
|
|
|
|
- **Dynamic alias parsing**: Scans shell config files (`.bashrc`, `.zshrc`) for defined aliases.
|
|
- **Highest priority**: Aliases appear above spec and system command suggestions.
|
|
- **Token injection**: When a root command is an alias (e.g. `gr` for `go run`), Iris injects expanded tokens into the lookup engine for accurate subcommand suggestions.
|
|
- **Display**: Shows the expanded command (e.g. `tmux a -t`) with the alias name in the description (e.g. `alias: ta`).
|