[core] Implement response file (but temporarily not exposed to users due to issues when setting ASSERT=all) (#13)

This PR adds opt-in “response file” (`@args.txt`) expansion to ArgMojo
commands, plus documentation/examples/tests, and clarifies
`default_if_no_value` semantics.

However, this functionality is temporarily not exposed to users due to
issues when setting `ASSERT=all` (the issue is related to `with
open()`).

**Changes:**
- Add response-file parsing support to `Command` (prefix + recursion
depth), expanding `@file` tokens into per-line arguments.
- Add a dedicated response-file test suite and wire it into the test
runner.
- Update docs/examples/changelog and adjust `default_if_no_value`
wording + a related test rename.

Author: forfudan

docs/argmojo_overall_planning.md

@@ -65,7 +65,7 @@ These features appear across multiple libraries and depend only on string operat
 | Cap and floor (clamp) for ranges   | -        | ✓     | —     | —    | Click `IntRange(clamp=True)` | **Done**      |
 | Hidden subcommands                 | —        | —     | ✓     | ✓    |                              | **Done**      |
 | `NO_COLOR` env variable            | —        | —     | —     | —    | I need it personally         | **Done**      |
-| Response file (`@args.txt`)        | ✓        | —     | —     | —    | javac, MSBuild               | Phase 5       |
+| Response file (`@args.txt`)        | ✓        | —     | —     | —    | javac, MSBuild               | **Done**      |
 | Argument parents (shared args)     | ✓        | —     | —     | —    |                              | Phase 5       |
 | Interactive prompting              | —        | ✓     | —     | —    |                              | Phase 5       |
 | Password / masked input            | —        | ✓     | —     | —    |                              | Phase 5       |
@@ -154,7 +154,8 @@ tests/
 ├── test_subcommands.mojo       # Subcommand tests (dispatch, help sub, unknown sub, etc.)
 ├── test_negative_numbers.mojo  # Negative number passthrough tests
 ├── test_persistent.mojo        # Persistent (global) flag tests
-└── test_const_require_equals.mojo  # default_if_no_value and require_equals tests
+├── test_const_require_equals.mojo  # default_if_no_value and require_equals tests
+└── test_response_file.mojo        # response file (@args.txt) expansion tests
 examples/
 ├── mgrep.mojo                   # grep-like CLI example (no subcommands)
 └── mgit.mojo                    # git-like CLI example (with subcommands)
@@ -204,6 +205,7 @@ examples/
 | Range clamping (`.range[1, 100]().clamp()` → adjust + warn instead of error)                       | ✓      | ✓     |
 | Default-if-no-value (`.default_if_no_value("gzip")` → optional value with fallback)                | ✓      | ✓     |
 | Require equals syntax (`.require_equals()` → `--key=value` only)                                   | ✓      | ✓     |
+| Response file (`command.response_file_prefix()` → `@args.txt` expands file contents)               | ✓      | ✓     |
 
 ### 4.3 API Design (Current)
 
@@ -534,7 +536,7 @@ Before adding Phase 5 features, further decompose `parse_arguments()` for readab
 - [ ] **Partial parsing** — parse known args only, return unknown args as-is (argparse `parse_known_args`)
 - [ ] **Require equals syntax** — force `--key=value`, disallow `--key value` (clap `require_equals`)
 - [ ] **Default-if-no-value** — `--opt` (no value) → use default-if-no-value; `--opt=val` → use val; absent → use default (argparse `const`)
-- [ ] **Response file** — `mytool @args.txt` expands file contents as arguments (argparse `fromfile_prefix_chars`, javac, MSBuild)
+- [x] **Response file** — `mytool @args.txt` expands file contents as arguments (argparse `fromfile_prefix_chars`, javac, MSBuild)
 - [ ] **Argument parents** — share a common set of Argument definitions across multiple Commands (argparse `parents`)
 - [ ] **Interactive prompting** — prompt user for missing required args instead of erroring (Click `prompt=True`)
 - [ ] **Password / masked input** — hide typed characters for sensitive values (Click `hide_input=True`)

docs/changelog.md

@@ -13,10 +13,18 @@ Comment out unreleased changes here. This file will be edited just before each r
 1. Add `.default_if_no_value("value")` builder method for default-if-no-value semantics. When an option has a default-if-no-value, it may appear without an explicit value: `--compress` uses the default-if-no-value, while `--compress=bzip2` uses the explicit value. For long options, `.default_if_no_value()` implies `.require_equals()`. For short options, `-c` uses the default-if-no-value while `-cbzip2` uses the attached value (PR #12).
 2. Add `.require_equals()` builder method. When set, long options reject space-separated syntax (`--key value`) and require `--key=value`. Can be used standalone (the value is mandatory via `=`) or combined with `.default_if_no_value()` (the value is optional; omitting it uses default-if-no-value) (PR #12).
 3. Help output adapts to the new modifiers: `--key=<value>` for require_equals, `--key[=<value>]` for default_if_no_value (PR #12).
+4. ~~Add `response_file_prefix()` builder method on `Command` for response-file support. When enabled, tokens starting with the prefix (default `@`) are expanded by reading the referenced file — each non-empty, non-comment line becomes a separate argument. Supports comments (`#`), escape (`@@literal`), recursive nesting (configurable depth), and custom prefix characters (PR #12).~~ *(Temporarily disabled — triggers a Mojo compiler deadlock under `-D ASSERT=all`. The implementation is preserved as module-level functions and will be re-enabled when the Mojo compiler bug is fixed.)*
+
+### 🔧 Fixes
+
+- Clarify documentation and docstrings: `default_if_no_value` does not "reject" `--key value`; it simply does not consume the next token as a value (PR #12, review feedback).
+- Fix cross-library comparison: click is described as "Python CLI framework" instead of incorrectly saying "built on top of argparse" (PR #12, review feedback).
+- Reject `.require_equals()` / `.default_if_no_value()` combined with `.number_of_values[N]()` at `add_argument()` time with a clear error (PR #12, review feedback).
 
 ### 📚 Documentation and testing
 
 - Add `tests/test_const_require_equals.mojo` with 30 tests covering default_if_no_value, require_equals, and their interactions with choices, append, prefix matching, merged short flags, persistent flags, and help formatting (PR #12).
+- Add `tests/test_response_file.mojo` with 17 tests covering basic expansion, comments, whitespace stripping, escape, recursive nesting, depth limit, custom prefix, disabled-by-default, and error handling (PR #12).
 
 ---
 

docs/user_manual.md

@@ -68,6 +68,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)
+<!-- Response Files (temporarily disabled — Mojo compiler deadlock with -D ASSERT=all)
+- [Response Files](#response-files)
+  - [Enabling Response Files](#enabling-response-files)
+  - [File Format](#file-format)
+  - [Escaping the Prefix](#escaping-the-prefix)
+  - [Recursive Response Files](#recursive-response-files)
+  - [Custom Prefix](#custom-prefix)
+-->
 - [Shell Completion](#shell-completion)
   - [Built-in `--completions` Flag](#built-in---completions-flag)
   - [Disabling the Built-in Flag](#disabling-the-built-in-flag)
@@ -2062,7 +2070,7 @@ Options:
 
 Use `.default_if_no_value("value")` to make an option's value **optional**. When the option is present without an explicit value, the default-if-no-value is used. When an explicit value is provided (via `=` for long options, or attached for short options), that value is used instead.
 
-`.default_if_no_value()` automatically implies `.require_equals()` for long options, so `--key value` (space-separated) is rejected — the user must write `--key=value` to supply an explicit value.
+`.default_if_no_value()` automatically implies `.require_equals()` for long options in the sense that `=` is required to attach an *explicit* value. A bare `--key` is still accepted and uses the default-if-no-value; `--key value` (space-separated) does *not* treat `value` as the argument to `--key` but leaves it to be parsed as a positional argument or another option. To supply an explicit value to the option itself, the user must write `--key=value`.
 
 ```mojo
 command.add_argument(
@@ -2545,6 +2553,107 @@ 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()`).
 
+<!-- Response Files section temporarily disabled — Mojo compiler deadlock with -D ASSERT=all.
+     The implementation is preserved as module-level functions and will be re-enabled
+     when the Mojo compiler bug is fixed.
+
+## Response Files
+
+A **response file** (also called an **args file**) lets users store arguments in a text file and reference it on the command line with a prefix character (default `@`). This is useful when the argument list is very long or when the same set of arguments is reused frequently.
+
+> Libraries with similar support: **argparse** (`fromfile_prefix_chars`), **javac** (`@argfile`), **MSBuild** (`@file`), **gcc** (`@file`).
+
+### Enabling Response Files
+
+Call `response_file_prefix()` on your command to enable the feature:
+
+```mojo
+var command = Command("mytool", "My CLI tool")
+command.response_file_prefix()  # default '@'
+```
+
+Now `mytool @args.txt` reads arguments from `args.txt`, with each line becoming a separate argument.
+
+### File Format
+
+Each non-empty line in the response file becomes one argument. Lines starting with `#` are comments and are ignored. Leading and trailing whitespace per line is stripped.
+
+```text
+# args.txt — common flags for the build
+--verbose
+--output=build/release
+--jobs=4
+
+# source files
+src/main.mojo
+src/utils.mojo
+```
+
+```bash
+mytool @args.txt
+# equivalent to: mytool --verbose --output=build/release --jobs=4 src/main.mojo src/utils.mojo
+```
+
+Response file arguments can be mixed freely with direct CLI arguments:
+
+```bash
+mytool --debug @args.txt --extra-flag
+```
+
+### Escaping the Prefix
+
+To pass a literal token that starts with `@` (e.g., an email address), double the prefix:
+
+```bash
+mytool @@user@example.com
+# parsed as: @user@example.com
+```
+
+The same escape works inside response files:
+
+```text
+# users.txt
+@@admin
+@@guest
+```
+
+### Recursive Response Files
+
+Response files may reference other response files:
+
+```text
+# base-args.txt
+--verbose
+
+# build-args.txt
+@base-args.txt
+--output=build/release
+```
+
+```bash
+mytool @build-args.txt
+# expands to: mytool --verbose --output=build/release
+```
+
+Recursion depth is limited to 10 by default. Adjust with `response_file_max_depth()`:
+
+```mojo
+command.response_file_max_depth(5)
+```
+
+A self-referencing or circular response file triggers an error once the depth limit is reached.
+
+### Custom Prefix
+
+Use a different prefix character if `@` conflicts with your argument values:
+
+```mojo
+command.response_file_prefix("+")
+# Now: mytool +args.txt
+```
+
+end of Response Files section -->
+
 ## 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.
@@ -2701,7 +2810,7 @@ The generated scripts cover the full command tree:
 
 The table below maps every ArgMojo builder method / command-level method to its equivalent in four popular CLI libraries. **An empty cell means the name is identical (or near-identical) to ArgMojo's.** A filled cell shows the other library's name or approach. **—** means the library has no built-in equivalent.
 
-> Libraries compared: **argparse** (Python stdlib), **click** (Python, built on top of argparse), **clap** (Rust, derive & builder API), **cobra / pflag** (Go).
+> Libraries compared: **argparse** (Python stdlib), **click** (Python CLI framework), **clap** (Rust, derive & builder API), **cobra / pflag** (Go).
 
 ### Argument-Level Builder Methods
 
@@ -2742,6 +2851,7 @@ The table below maps every ArgMojo builder method / command-level method to its
 | `required_together(…)`      | —                                | —                               | `.requires("x")` per arg       | `MarkFlagsRequiredTogether()` ¹ |
 | `required_if(target, cond)` | —                                | —                               | `.required_if_eq("x","v")`     | `MarkFlagRequired…` ¹           |
 | `implies(trigger, implied)` | —                                | —                               | `.requires_if("v","x")` ¹⁰     | —                               |
+| `response_file_prefix()`    | `fromfile_prefix_chars="@"`      | —                               | —                              | —                               |
 
 ### Notes
 

examples/demo.mojo

@@ -10,7 +10,7 @@ conditional requirements, negatable flags, color customisation
 (header_color, arg_color), numeric range validation, append with range
 clamping, value delimiter, nargs, key-value map, aliases, deprecated args,
 negative number passthrough, allow_positional_with_subcommands, custom tips,
-help_on_no_arguments, default_if_no_value, and require_equals.
+help_on_no_arguments, default_if_no_value, require_equals, and response files.
 
 Note: This demo looks very strange, but useful :D
 
@@ -70,6 +70,10 @@ Try these (build first with: pixi run package && mojo build -I src -o demo examp
   ./demo input.txt --separator="|"
   ./demo input.txt --separator "|"            # error: requires '=' syntax
 
+  # response file: put arguments in a file and reference with @
+  echo '--verbose\n--level=5\n--color' > /tmp/demo_args.txt
+  ./demo input.txt @/tmp/demo_args.txt
+
   # negative number passthrough
   ./demo -- -42
 
@@ -105,6 +109,9 @@ fn main() raises:
     app.header_color("CYAN")
     app.arg_color("GREEN")
 
+    # ── Response file support ────────────────────────────────────────────
+    app.response_file_prefix()  # enables @args.txt expansion
+
     # ── Positional arguments ─────────────────────────────────────────────
     app.add_argument(
         Argument("input", help="Input file to process")

pixi.toml

@@ -27,18 +27,21 @@ package = "mojo package src/argmojo -o argmojo.mojopkg"
 test = """\
     pixi run format \
     && pixi run package \
-    && mojo run -I src tests/test_parse.mojo \
-    && mojo run -I src tests/test_groups.mojo \
-    && mojo run -I src tests/test_collect.mojo \
-    && mojo run -I src tests/test_help.mojo \
-    && mojo run -I src tests/test_extras.mojo \
-    && 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_completion.mojo \
-    && mojo run -I src tests/test_implies.mojo \
-    && mojo run -I src tests/test_const_require_equals.mojo"""
+    && mojo run -I src -D ASSERT=all tests/test_parse.mojo \
+    && mojo run -I src -D ASSERT=all tests/test_groups.mojo \
+    && mojo run -I src -D ASSERT=all tests/test_collect.mojo \
+    && mojo run -I src -D ASSERT=all tests/test_help.mojo \
+    && mojo run -I src -D ASSERT=all tests/test_extras.mojo \
+    && mojo run -I src -D ASSERT=all tests/test_subcommands.mojo \
+    && mojo run -I src -D ASSERT=all tests/test_negative_numbers.mojo \
+    && mojo run -I src -D ASSERT=all tests/test_persistent.mojo \
+    && mojo run -I src -D ASSERT=all tests/test_typo_suggestions.mojo \
+    && mojo run -I src -D ASSERT=all tests/test_completion.mojo \
+    && mojo run -I src -D ASSERT=all tests/test_implies.mojo \
+    && mojo run -I src -D ASSERT=all tests/test_const_require_equals.mojo"""
+    # NOTE: test_response_file.mojo is excluded — response file expansion
+    # is temporarily disabled to work around a Mojo compiler deadlock
+    # with -D ASSERT=all.  Re-enable when the compiler bug is fixed.
 
 # build example binaries
 build = """pixi run package \

src/argmojo/argument.mojo

@@ -619,9 +619,13 @@ struct Argument(Copyable, Movable, Stringable, Writable):
         or attached form for short options (``-cbzip2``), that explicit
         value is used instead.
 
-        For long options this implies ``require_equals()``, so
-        ``--compress val`` (space-separated) is rejected — the user
-        must write ``--compress=val`` to supply an explicit value.
+        For long options this implies ``require_equals()``.  A
+        space-separated token like ``--compress val`` is not accepted
+        as the option's value; in that case ``--compress`` uses its
+        default-if-no-value and ``val`` is parsed as a separate
+        argument (positional or another option).  To supply an
+        explicit value for the option, the user must write
+        ``--compress=val``.
 
         Examples::