[core] Add shell completion support + built-in completion (#4)

Author: forfudan

README.md

@@ -9,6 +9,9 @@ A command-line argument parser library for [Mojo](https://www.modular.com/mojo),
 [![pixi](https://img.shields.io/badge/pixi%20add-argmojo-brightgreen)](https://prefix.dev/channels/modular-community/packages/argmojo)
 [![User manual](https://img.shields.io/badge/user-manual-purple)](https://github.com/forfudan/argmojo/wiki)
 
+<video src="https://raw.githubusercontent.com/forfudan/forfudan-github-data/main/argmojo/completions.mp4" controls width="800"></video>
+<p align="center"><em>Shell auto-completion of a mock <code>git</code> CLI built with ArgMojo</em></p>
+
 <!-- 
 [![CI](https://img.shields.io/github/actions/workflow/status/forfudan/argmojo/run_tests.yaml?branch=main&label=tests)](https://github.com/forfudan/argmojo/actions/workflows/run_tests.yaml)
 [![License](https://img.shields.io/github/license/forfudan/argmojo)](LICENSE)
@@ -47,6 +50,7 @@ ArgMojo provides a builder-pattern API for defining and parsing command-line arg
 - **One-required groups**: require at least one argument from a group (e.g., must provide `--json` or `--yaml`)
 - **Value delimiter**: `--env dev,staging,prod` splits by delimiter into a list with `.delimiter(",")`
 - **Multi-value options (nargs)**: `--point 10 20` consumes N consecutive values with `.nargs(N)`
+- **Shell completion script generation**: `generate_completion("bash"|"zsh"|"fish")` produces a complete tab-completion script for your CLI
 
 ---
 
@@ -142,7 +146,7 @@ ArgMojo ships with two complete example CLIs:
 | Example                 | File                 | Features                                                                                                                                                                                                                                                                                                                       |
 | ----------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `grep` — simulated grep | `examples/grep.mojo` | Positional args, flags, count flags, negatable flags, choices, metavar, append/collect, value delimiter, nargs, mutually exclusive groups, required-together groups, conditional requirements, numeric range, key-value map, aliases, deprecated args, hidden args, negative-number passthrough, `--` stop marker, custom tips |
-| `git` — simulated git   | `examples/git.mojo`  | Subcommands (clone/init/add/commit/push/pull/log/remote/branch/diff/tag/stash), nested subcommands (remote add/remove/rename/show), persistent (global) flags, per-command args, mutually exclusive groups, choices, aliases, deprecated args, custom tips                                                                     |
+| `git` — simulated git   | `examples/git.mojo`  | Subcommands (clone/init/add/commit/push/pull/log/remote/branch/diff/tag/stash), nested subcommands (remote add/remove/rename/show), persistent (global) flags, per-command args, mutually exclusive groups, choices, aliases, deprecated args, custom tips, shell completion script generation                                 |
 
 Build both example binaries:
 
@@ -152,6 +156,8 @@ pixi run build
 
 ### `grep` (no subcommands)
 
+![grep CLI demo](https://raw.githubusercontent.com/forfudan/forfudan-github-data/main/argmojo/grep.png)
+
 ```bash
 # Help and version
 ./grep --help
@@ -175,6 +181,8 @@ pixi run build
 
 ### `git` (with subcommands)
 
+![git clone subcommand](https://raw.githubusercontent.com/forfudan/forfudan-github-data/main/argmojo/git-clone.png)
+
 ```bash
 # Root help — shows Commands section + Global Options
 ./git --help
@@ -195,6 +203,11 @@ pixi run build
 # Unknown subcommand → clear error
 ./git foo
 # error: git: Unknown command 'foo'. Available commands: clone, init, ...
+
+# Shell completion script generation
+./git --completions bash   # bash completion script
+./git --completions zsh    # zsh completion script
+./git --completions fish   # fish completion script
 ```
 
 ## Development

docs/argmojo_overall_planning.md

@@ -521,6 +521,7 @@ Before adding Phase 5 features, further decompose `parse_args()` for readability
 - [x] **Typo suggestions** — "Unknown option '--vrb', did you mean '--verbose'?" (Levenshtein distance; cobra, argparse 3.14)
 - [ ] **Flag counter with ceiling** — `.count().max(3)` caps `-vvvvv` at 3 (no major library has this)
 - [x] **Colored error output** — ANSI styled error messages (help output already colored)
+- [x] **Shell completion script generation** — `generate_completion("bash"|"zsh"|"fish")` returns a complete completion script; static approach (no runtime hook), covers options/flags/choices/subcommands (clap `generate`, cobra `completion`, click `shell_complete`)
 - [ ] **Argument groups in help** — group related options under headings (argparse add_argument_group)
 - [ ] **Usage line customisation** — two approaches: (1) manual override via `.usage("...")` for git-style hand-written usage strings (e.g. `[-v | --version] [-h | --help] [-C <path>] ...`); (2) auto-expanded mode that enumerates every flag inline like argparse (good for small CLIs, noisy for large ones). Current default `[OPTIONS]` / `<COMMAND>` is the cobra/clap/click convention and is the right default.
 - [ ] **Partial parsing** — parse known args only, return unknown args as-is (argparse `parse_known_args`)

docs/user_manual.md

@@ -57,6 +57,14 @@ from argmojo import Argument, Command
   - [Negative Number Passthrough](#negative-number-passthrough)
   - [Long Option Prefix Matching](#long-option-prefix-matching)
   - [The `--` Stop Marker](#the----stop-marker)
+- [Shell Completion](#shell-completion)
+  - [Built-in `--completions` Flag](#built-in---completions-flag)
+  - [Disabling the Built-in Flag](#disabling-the-built-in-flag)
+  - [Customising the Trigger Name](#customising-the-trigger-name)
+  - [Using a Subcommand Instead of an Option](#using-a-subcommand-instead-of-an-option)
+  - [Generating a Script Programmatically](#generating-a-script-programmatically)
+  - [Installing Completions](#installing-completions)
+  - [What Gets Completed](#what-gets-completed)
 
 ## Getting Started
 
@@ -2026,3 +2034,155 @@ myapp -- -10.18
 ```
 
 > **Tip:** ArgMojo's [Auto-detect](#negative-number-passthrough) can handle most negative-number cases without `--`. Use `--` only when auto-detect is insufficient (e.g., a digit short option is registered without `allow_negative_numbers()`).
+
+## Shell Completion
+
+ArgMojo can generate **shell completion scripts** for Bash, Zsh, and Fish. These scripts enable tab-completion for your CLI's options, flags, subcommands, and choice values — with zero runtime overhead.
+
+The generated scripts are **static**: they are produced once from your command tree and sourced by the user's shell. No runtime hook or callback mechanism is needed.
+
+### Built-in `--completions` Flag
+
+Every `Command` automatically responds to `--completions <shell>` — just like `--help` and `--version`. **No extra code is required.**
+
+```mojo
+var app = Command("myapp", "My application", version="1.0.0")
+app.add_argument(Argument("verbose", help="Verbose output").long("verbose").short("v").flag())
+app.add_argument(Argument("output", help="Output file").long("output").short("o").metavar("FILE"))
+var formats: List[String] = ["json", "csv", "table"]
+app.add_argument(Argument("format", help="Output format").long("format").choices(formats^))
+
+var sub = Command("serve", "Start a server")
+sub.add_argument(Argument("port", help="Port number").long("port").short("p"))
+app.add_subcommand(sub^)
+
+# parse() handles --completions automatically — no extra code needed
+var result = app.parse()
+```
+
+Users run:
+
+```bash
+myapp --completions bash   # prints Bash completion script and exits
+myapp --completions zsh    # prints Zsh completion script and exits
+myapp --completions fish   # prints Fish completion script and exits
+```
+
+The `--completions` option is shown in the help output alongside `--help` and `--version`:
+
+```bash
+Options:
+  --help                  Show this help message and exit
+  --version               Show the version and exit
+  --completions {bash,zsh,fish}
+                          Generate shell completion script
+```
+
+### Disabling the Built-in Flag
+
+If you want to use `completions` as a regular argument name — or handle completion triggering entirely on your own — call `disable_default_completions()`:
+
+```mojo
+var app = Command("myapp", "My CLI")
+app.disable_default_completions()   # --completions is now an unknown option
+```
+
+`disable_default_completions()` removes `--completions` from the parse loop, help output, and all generated completion scripts. The `generate_completion()` method remains available for programmatic use.
+
+### Customising the Trigger Name
+
+By default the option is called `--completions`. Use `completions_name()` to rename it:
+
+```mojo
+var app = Command("myapp", "My CLI")
+app.completions_name("autocomp")    # → --autocomp bash/zsh/fish
+```
+
+Help output, parse loop, and generated scripts all reflect the new name.
+
+### Using a Subcommand Instead of an Option
+
+To expose completion generation as a subcommand rather than a `--` option, call `completions_as_subcommand()`:
+
+```mojo
+var app = Command("myapp", "My CLI")
+app.completions_as_subcommand()     # → myapp completions bash
+```
+
+The trigger moves from `Options:` to `Commands:` in help output. This can be combined with `completions_name()`:
+
+```mojo
+app.completions_name("comp")
+app.completions_as_subcommand()     # → myapp comp bash
+```
+
+### Generating a Script Programmatically
+
+You can also call `generate_completion(shell)` directly to get a completion script as a `String`:
+
+```mojo
+# Generate for any supported shell
+var script = app.generate_completion("bash")   # or "zsh" or "fish"
+print(script)
+```
+
+The `shell` argument is **case-insensitive** (`"Bash"`, `"BASH"`, `"bash"` all work). An error is raised for unrecognised shell names.
+
+### Installing Completions
+
+After generating a script, users `source` it or place it in a shell-specific directory.
+
+---
+
+**Bash:**
+
+```bash
+# One-shot (current session only)
+eval "$(myapp --completions bash)"
+
+# Persistent
+myapp --completions bash > ~/.bash_completion.d/myapp
+# Then add to ~/.bashrc:  source ~/.bash_completion.d/myapp
+```
+
+---
+
+**Zsh:**
+
+```bash
+# Place in your fpath (file must be named _myapp)
+myapp --completions zsh > ~/.zsh/completions/_myapp
+
+# Make sure ~/.zsh/completions is in fpath (add to ~/.zshrc):
+#   fpath=(~/.zsh/completions $fpath)
+#   autoload -Uz compinit && compinit
+```
+
+---
+
+**Fish:**
+
+```bash
+# Fish auto-loads from this directory
+myapp --completions fish > ~/.config/fish/completions/myapp.fish
+```
+
+### What Gets Completed
+
+The generated scripts cover the full command tree:
+
+| Element                           | Completed?       | Notes                                                                |
+| --------------------------------- | ---------------- | -------------------------------------------------------------------- |
+| Long options (`--verbose`)        | Yes              | With description text from `help`                                    |
+| Short options (`-v`)              | Yes              | Paired with long option when both exist                              |
+| Boolean flags                     | Yes              | Marked as no-argument (no file/value completion after the flag)      |
+| Count flags (`-vvv`)              | Yes              | Treated like boolean flags (no value expected)                       |
+| Choices (`--format json`)         | Yes              | Tab-completes the allowed values (`json`, `csv`, `table`)            |
+| Subcommands                       | Yes              | Listed with descriptions; scoped completions for each subcommand     |
+| Built-in `--help` / `--version`   | Yes              | Automatically included                                               |
+| Built-in `--completions {bash,…}` | Yes              | Automatically included; disable with `disable_default_completions()` |
+| Hidden arguments                  | No (intentional) | `.hidden()` arguments are excluded from completion                   |
+| Positional arguments              | No (by design)   | Positionals use default shell completion (file paths, etc.)          |
+| Persistent (global) flags         | Yes (root level) | Inherited flags appear in the root command's completions             |
+
+> **Note:** Negatable flags (`--color` / `--no-color`) — the `--no-X` form is **not** separately listed in completions. The base `--color` flag is completed; users type `--no-` manually. This matches the behaviour of other CLI frameworks.

examples/git.mojo

@@ -9,7 +9,8 @@ required arguments, metavar, hidden arguments, append/collect, value
 delimiter, mutually exclusive groups, required-together groups, conditional
 requirements, numeric range validation, aliases, deprecated arguments,
 Commands section in help, Global Options heading, full command path in
-child help/errors, unknown subcommand error, and custom tips.
+child help/errors, unknown subcommand error, custom tips, and shell
+completion script generation.
 
 Try these:
   git --help                        # root help (Commands + Global Options)
@@ -20,6 +21,7 @@ Try these:
   git log --oneline -n 20 --author "Alice"
   git remote add origin https://example.com/repo.git
   git -v push origin main --force --tags
+  git --completions bash           # shell completion script (built-in)
 """
 
 from argmojo import Argument, Command

pixi.toml

@@ -35,7 +35,8 @@ test = """\
     && mojo run -I src tests/test_subcommands.mojo \
     && mojo run -I src tests/test_negative_numbers.mojo \
     && mojo run -I src tests/test_persistent.mojo \
-    && mojo run -I src tests/test_typo_suggestions.mojo"""
+    && mojo run -I src tests/test_typo_suggestions.mojo \
+    && mojo run -I src tests/test_completion.mojo"""
 
 # build example binaries
 build = """pixi run package \

src/argmojo/argument.mojo

@@ -2,7 +2,7 @@
 
 
 comptime Arg = Argument
-"""Shorthand alias for `Argument`."""
+"""Shorthand alias for ``Argument``."""
 
 
 struct Argument(Copyable, Movable, Stringable, Writable):
@@ -321,8 +321,8 @@ struct Argument(Copyable, Movable, Stringable, Writable):
     fn metavar(var self, name: String) -> Self:
         """Sets the display name for the value in help text.
 
-        For example, `.metavar("FILE")` causes help to show `--output FILE`
-        instead of `--output OUTPUT`.
+        For example, ``.metavar("FILE")`` causes help to show ``--output FILE``
+        instead of ``--output OUTPUT``.
 
         Args:
             name: The display name.
@@ -345,8 +345,8 @@ struct Argument(Copyable, Movable, Stringable, Writable):
     fn count(var self) -> Self:
         """Marks this argument as a counter flag.
 
-        Each occurrence increments a counter. For example, `-vvv` sets
-        the count to 3. Use `get_count()` on ParseResult to retrieve.
+        Each occurrence increments a counter. For example, ``-vvv`` sets
+        the count to 3. Use ``get_count()`` on ParseResult to retrieve.
 
         Returns:
             Self marked as a counter.
@@ -358,9 +358,9 @@ struct Argument(Copyable, Movable, Stringable, Writable):
     fn negatable(var self) -> Self:
         """Marks this flag as negatable.
 
-        A negatable flag accepts both `--X` (sets True) and `--no-X`
-        (sets False). For example, `.long("color").flag().negatable()`
-        accepts `--color` and `--no-color`.
+        A negatable flag accepts both ``--X`` (sets True) and ``--no-X``
+        (sets False). For example, ``.long("color").flag().negatable()``
+        accepts ``--color`` and ``--no-color``.
 
         Returns:
             Self marked as negatable.
@@ -372,7 +372,7 @@ struct Argument(Copyable, Movable, Stringable, Writable):
         """Marks this argument as an append/collect option.
 
         Each occurrence adds its value to a list. For example,
-        `--tag x --tag y` collects `["x", "y"]`. Use `get_list()`
+        ``--tag x --tag y`` collects ``["x", "y"]``. Use ``get_list()``
         on ParseResult to retrieve the collected values.
 
         Returns:
@@ -390,9 +390,9 @@ struct Argument(Copyable, Movable, Stringable, Writable):
         """Sets a value delimiter for splitting a single value into multiple.
 
         When set, each provided value is split by the delimiter, and each
-        piece is added to the list individually.  Implies `.append()`.
-        For example, `.delimiter(",")` causes `--tag a,b,c` to produce
-        `["a", "b", "c"]`.
+        piece is added to the list individually.  Implies ``.append()``.
+        For example, ``.delimiter(",")`` causes ``--tag a,b,c`` to produce
+        ``["a", "b", "c"]``.
 
         Args:
             sep: The delimiter string (e.g., ",").