Metadata-Version: 2.3
Name: command-router
Version: 1.0.0b1
Summary: Small, Brigadier-inspired command router.
Author: Ian Hylton
Author-email: Ian Hylton <dcxrpse@krwwstudios.com>
License: The Clear BSD License
         
         Copyright (c) 2026 Ian Hylton
         All rights reserved.
         
         Redistribution and use in source and binary forms, with or without
         modification, are permitted (subject to the limitations in the disclaimer
         below) provided that the following conditions are met:
         
              * Redistributions of source code must retain the above copyright notice,
              this list of conditions and the following disclaimer.
         
              * Redistributions in binary form must reproduce the above copyright
              notice, this list of conditions and the following disclaimer in the
              documentation and/or other materials provided with the distribution.
         
              * Neither the name of the copyright holder nor the names of its
              contributors may be used to endorse or promote products derived from this
              software without specific prior written permission.
         
         NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY
         THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
         CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
         LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
         PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
         CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
         EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
         PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
         BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
         IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
         ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
         POSSIBILITY OF SUCH DAMAGE.
Requires-Dist: click>=8.4.2
Requires-Dist: json5>=0.15.0
Requires-Dist: prompt-toolkit>=3.0.53
Requires-Dist: rapidfuzz>=3.14.6
Requires-Dist: textual>=8.2.8
Requires-Python: >=3.14
Project-URL: Repository, https://gitlab.com/denniscxrpse/command-router
Project-URL: Issues, https://gitlab.com/denniscxrpse/command-router/-/work_items
Project-URL: Documentation, https://gitlab.com/denniscxrpse/command-router/-/wikis/
Description-Content-Type: text/markdown

# command-router

Command Router is a small Python library for applications that accept textual commands. Define a command tree or load a
grammar file, convert input into typed arguments, and invoke the action attached to the matching path. The library keeps
syntax, application state, error details, completion, and process transports as separate pieces that can be used
together or independently.

The main user-facing features are:

- hand-built and fluent command trees with literals, typed arguments, choices, optionals, and greedy text;
- TOML and JSON5 grammar files for file-backed command surfaces;
- fixture classes that bind command names to application actions and state;
- structured parse, initialization, and execution results with useful expectations and partial arguments;
- prefix-first and typo-aware suggestions, including an optional HTTP suggestions endpoint;
- aliases and repeating modifier chains through redirect edges;
- embedded, interactive, and stdin/stdio service modes.

## Install

The [uv](https://docs.astral.sh/uv/) package manager can be used to install the library:

```sh
uv venv
uv add command-router
```

You may use [pip](https://pip.pypa.io/en/stable/) for a more conventional approach:

```sh
python -m venv ./venv
pip install command-router
```

## How it works

```mermaid
flowchart LR
    Input["Command text"] --> Control["Control checks input"]
    Control --> Dispatcher["Dispatcher walks command tree"]
    Dispatcher --> Action["Fixture action"]
    Dispatcher --> Failure["Structured error + suggestions"]
    Action --> Result["ControlResult"]
    Failure --> Result
    Result --> Consumer["Application, REPL, or process client"]
```

`Control` handles the command prefix and execution lifecycle. The dispatcher handles tokenization and tree matching.
Fixtures supply actions and state. Every path returns a result that can be inspected directly or serialized for another
process.

## Run it

```sh
just -l         # see available recipes
just test       # run the test suite
just run        # start the router
just run -L     # start the router in lazy grammar mode
```

[Install `just`](https://just.systems/man/en/packages.html) if you don't have it yet.

## Documentation

Start with the [project documentation](https://gitlab.com/denniscxrpse/command-router/-/wikis/home). It explains the
command tree, fixture SDK, grammar files, structured response contracts, suggestions, redirects, service modes, and
the external consumer example.

## Mirrors

- Primary: https://gitlab.com/denniscxrpse/command-router
- Mirror: https://github.com/denniscxrpse/command-router
