Added Cmd.macro_arg_complete() to allow custom tab completion for macro arguments.

Author: kmvanbrunt

CHANGELOG.md

@@ -7,10 +7,14 @@
       compatibility in `cmd2` 2.0 family.
 
 - Enhancements
+
     - Simplified the process to set a custom parser for `cmd2's` built-in commands. See
       [custom_parser.py](https://github.com/python-cmd2/cmd2/blob/main/examples/custom_parser.py)
       example for more details.
 
+    - Added `Cmd.macro_arg_complete()` which tab completes arguments to a macro. Its default
+      behavior is to perform path completion, but it can be overridden as needed.
+
 ## 2.7.0 (June 30, 2025)
 
 - Enhancements

cmd2/cmd2.py

@@ -2062,7 +2062,7 @@ def _perform_completion(
         if custom_settings is None:
             # Check if a macro was entered
             if command in self.macros:
-                completer_func = self.path_complete
+                completer_func = self.macro_arg_complete
 
             # Check if a command was entered
             elif command in self.get_all_commands():
@@ -3542,6 +3542,27 @@ def _alias_list(self, args: argparse.Namespace) -> None:
     # Parsers and functions for macro command and subcommands
     #############################################################
 
+    def macro_arg_complete(
+        self,
+        text: str,
+        line: str,
+        begidx: int,
+        endidx: int,
+    ) -> list[str]:
+        """Tab completes arguments to a macro.
+
+        Its default behavior is to call path_complete, but you can override this as needed.
+
+        The args required by this function are defined in the header of Python's cmd.py.
+
+        :param text: the string prefix we are attempting to match (all matches must begin with it)
+        :param line: the current input line with leading whitespace removed
+        :param begidx: the beginning index of the prefix text
+        :param endidx: the ending index of the prefix text
+        :return: a list of possible tab completions
+        """
+        return self.path_complete(text, line, begidx, endidx)
+
     # Top-level parser for macro
     @staticmethod
     def _build_macro_parser() -> Cmd2ArgumentParser:
@@ -3609,8 +3630,8 @@ def _build_macro_create_parser(cls) -> Cmd2ArgumentParser:
             "  macro create show_results print_results -type {1} \"|\" less",
             "\n",
             (
-                "Because macros do not resolve until after hitting Enter, tab completion "
-                "will only complete paths while typing a macro."
+                "Since macros don't resolve until after you press Enter, their arguments tab complete as paths. "
+                "This default behavior changes if custom tab completion for macro arguments has been implemented."
             ),
         )
         macro_create_parser.epilog = macro_create_parser.create_text_group("Notes", macro_create_notes)

docs/features/shortcuts_aliases_macros.md

@@ -78,8 +78,11 @@ Similar to aliases, pipes and redirectors need to be quoted in the definition of
 
     macro create lc !cat "{1}" "|" less
 
-To use the literal string `{1}` in your command, escape it this way: `{{1}}`. Because macros do not
-resolve until after hitting `<Enter>`, tab completion will only complete paths while typing a macro.
+To use the literal string `{1}` in your command, escape it this way: `{{1}}`.
+
+Since macros don't resolve until after you press `<Enter>`, their arguments tab complete as paths.
+You can change this default behavior by overriding `Cmd.macro_arg_complete()` to implement custom
+tab completion for macro arguments.
 
 For more details run: `help macro create`