Restore macros (#1464)

* Restored macros.

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

Author: kmvanbrunt

CHANGELOG.md

@@ -2,16 +2,19 @@
 
 - Breaking Changes
 
-    - Removed macros
     - No longer setting parser's `prog` value in `with_argparser()` since it gets set in
       `Cmd._build_parser()`. This code had previously been restored to support backward
       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

README.md

@@ -69,10 +69,10 @@ first pillar of 'ease of command discovery'. The following is a list of features
 
 <a href="https://imgflip.com/i/66t0y0"><img src="https://i.imgflip.com/66t0y0.jpg" title="made at imgflip.com" width="70%" height="70%"/></a>
 
-cmd2 creates the second pillar of 'ease of transition to automation' through alias creation, command
-line argument parsing and execution of cmd2 scripting.
+cmd2 creates the second pillar of 'ease of transition to automation' through alias/macro creation,
+command line argument parsing and execution of cmd2 scripting.
 
-- Flexible alias creation for quick abstraction of commands.
+- Flexible alias and macro creation for quick abstraction of commands.
 - Text file scripting of your application with `run_script` (`@`) and `_relative_run_script` (`@@`)
 - Powerful and flexible built-in Python scripting of your application using the `run_pyscript`
   command

cmd2/cmd2.py

@@ -35,6 +35,56 @@ def shlex_split(str_to_split: str) -> list[str]:
     return shlex.split(str_to_split, comments=False, posix=False)
 
 
+@dataclass(frozen=True)
+class MacroArg:
+    """Information used to replace or unescape arguments in a macro value when the macro is resolved.
+
+    Normal argument syntax:    {5}
+    Escaped argument syntax:  {{5}}.
+    """
+
+    # The starting index of this argument in the macro value
+    start_index: int
+
+    # The number string that appears between the braces
+    # This is a string instead of an int because we support unicode digits and must be able
+    # to reproduce this string later
+    number_str: str
+
+    # Tells if this argument is escaped and therefore needs to be unescaped
+    is_escaped: bool
+
+    # Pattern used to find normal argument
+    # Digits surrounded by exactly 1 brace on a side and 1 or more braces on the opposite side
+    # Match strings like: {5}, {{{{{4}, {2}}}}}
+    macro_normal_arg_pattern = re.compile(r'(?<!{){\d+}|{\d+}(?!})')
+
+    # Pattern used to find escaped arguments
+    # Digits surrounded by 2 or more braces on both sides
+    # Match strings like: {{5}}, {{{{{4}}, {{2}}}}}
+    macro_escaped_arg_pattern = re.compile(r'{{2}\d+}{2}')
+
+    # Finds a string of digits
+    digit_pattern = re.compile(r'\d+')
+
+
+@dataclass(frozen=True)
+class Macro:
+    """Defines a cmd2 macro."""
+
+    # Name of the macro
+    name: str
+
+    # The string the macro resolves to
+    value: str
+
+    # The minimum number of args the user has to pass to this macro
+    minimum_arg_count: int
+
+    # Used to fill in argument placeholders in the macro
+    arg_list: list[MacroArg] = field(default_factory=list)
+
+
 @dataclass(frozen=True)
 class Statement(str):  # type: ignore[override]  # noqa: SLOT000
     """String subclass with additional attributes to store the results of parsing.
@@ -155,10 +205,10 @@ def expanded_command_line(self) -> str:
     def argv(self) -> list[str]:
         """A list of arguments a-la ``sys.argv``.
 
-        The first element of the list is the command after shortcut expansion.
-        Subsequent elements of the list contain any additional arguments,
-        with quotes removed, just like bash would. This is very useful if
-        you are going to use ``argparse.parse_args()``.
+        The first element of the list is the command after shortcut and macro
+        expansion. Subsequent elements of the list contain any additional
+        arguments, with quotes removed, just like bash would. This is very
+        useful if you are going to use ``argparse.parse_args()``.
 
         If you want to strip quotes from the input, you can use ``argv[1:]``.
         """

cmd2/parsing.py

@@ -7,7 +7,7 @@ Here's a quick walkthrough of a simple application which demonstrates 8 features
 - [Argument Processing](../features/argument_processing.md)
 - [Generating Output](../features/generating_output.md)
 - [Help](../features/help.md)
-- [Shortcuts](../features/shortcuts_aliases.md#shortcuts)
+- [Shortcuts](../features/shortcuts_aliases_macros.md#shortcuts)
 - [Multiline Commands](../features/multiline_commands.md)
 - [History](../features/history.md)
 
@@ -166,9 +166,10 @@ With those few lines of code, we created a [command](../features/commands.md), u
 ## Shortcuts
 
 `cmd2` has several capabilities to simplify repetitive user input:
-[Shortcuts and Aliases](../features/shortcuts_aliases.md). Let's add a shortcut to our application.
-Shortcuts are character strings that can be used instead of a command name. For example, `cmd2` has
-support for a shortcut `!` which runs the `shell` command. So instead of typing this:
+[Shortcuts, Aliases, and Macros](../features/shortcuts_aliases_macros.md). Let's add a shortcut to
+our application. Shortcuts are character strings that can be used instead of a command name. For
+example, `cmd2` has support for a shortcut `!` which runs the `shell` command. So instead of typing
+this:
 
 ```shell
 (Cmd) shell ls -al

docs/examples/first_app.md

@@ -9,7 +9,7 @@ to be part of the application.
 ### alias
 
 This command manages aliases via subcommands `create`, `delete`, and `list`. See
-[Aliases](shortcuts_aliases.md#aliases) for more information.
+[Aliases](shortcuts_aliases_macros.md#aliases) for more information.
 
 ### edit
 
@@ -38,6 +38,12 @@ history. See [History](history.md) for more information.
 This optional opt-in command enters an interactive IPython shell. See
 [IPython (optional)](./embedded_python_shells.md#ipython-optional) for more information.
 
+### macro
+
+This command manages macros via subcommands `create`, `delete`, and `list`. A macro is similar to an
+alias, but it can contain argument placeholders. See [Macros](./shortcuts_aliases_macros.md#macros)
+for more information.
+
 ### py
 
 This command invokes a Python command or shell. See
@@ -108,8 +114,8 @@ Execute a command as if at the operating system shell prompt:
 
 ### shortcuts
 
-This command lists available shortcuts. See [Shortcuts](./shortcuts_aliases.md#shortcuts) for more
-information.
+This command lists available shortcuts. See [Shortcuts](./shortcuts_aliases_macros.md#shortcuts) for
+more information.
 
 ## Remove Builtin Commands
 

docs/features/builtin_commands.md

@@ -61,7 +61,7 @@ backwards compatibility.
 - quoted arguments
 - output redirection and piping
 - multi-line commands
-- shortcut and alias expansion
+- shortcut, alias, and macro expansion
 
 In addition to parsing all of these elements from the user input, `cmd2` also has code to make all
 of these items work; it's almost transparent to you and to the commands you write in your own

docs/features/commands.md

@@ -14,8 +14,8 @@ command. The `help` command by itself displays a list of the commands available:
 
 Documented commands (use 'help -v' for verbose/'help <topic>' for details):
 ===========================================================================
-alias  help     ipy  quit          run_script  shell
-edit   history  py   run_pyscript  set         shortcuts
+alias  help     ipy    py    run_pyscript  set    shortcuts
+edit   history  macro  quit  run_script    shell
 ```
 
 The `help` command can also be used to provide detailed help for a specific command:
@@ -53,8 +53,8 @@ By default, the `help` command displays:
 
     Documented commands (use 'help -v' for verbose/'help <topic>' for details):
     ===========================================================================
-    alias  help     ipy  quit          run_script  shell
-    edit   history  py   run_pyscript  set         shortcuts
+    alias  help     ipy    py    run_pyscript  set    shortcuts
+    edit   history  macro  quit  run_script    shell
 
 If you have a large number of commands, you can optionally group your commands into categories.
 Here's the output from the example `help_categories.py`:
@@ -80,8 +80,8 @@ Here's the output from the example `help_categories.py`:
 
     Other
     =====
-    alias   edit  history  run_pyscript  set    shortcuts
-    config  help  quit     run_script    shell  version
+    alias   edit  history  py    run_pyscript  set    shortcuts
+    config  help  macro    quit  run_script    shell  version
 
 There are 2 methods of specifying command categories, using the `@with_category` decorator or with
 the `categorize()` function. Once a single command category is detected, the help output switches to
@@ -143,9 +143,9 @@ categories with per-command Help Messages:
     findleakers           Find Leakers command.
     list                  List command.
     redeploy              Redeploy command.
-    restart               Restart
+    restart               Restart command.
     sessions              Sessions command.
-    start                 Start
+    start                 Start command.
     stop                  Stop command.
     undeploy              Undeploy command.
 
@@ -164,9 +164,9 @@ categories with per-command Help Messages:
     resources             Resources command.
     serverinfo            Server Info command.
     sslconnectorciphers   SSL Connector Ciphers command is an example of a command that contains
-                        multiple lines of help information for the user. Each line of help in a
-                        contiguous set of lines will be printed and aligned in the verbose output
-                        provided with 'help --verbose'.
+                          multiple lines of help information for the user. Each line of help in a
+                          contiguous set of lines will be printed and aligned in the verbose output
+                          provided with 'help --verbose'.
     status                Status command.
     thread_dump           Thread Dump command.
     vminfo                VM Info command.
@@ -178,6 +178,7 @@ categories with per-command Help Messages:
     edit                  Run a text editor and optionally open a file with it.
     help                  List available commands or provide detailed help for a specific command.
     history               View, run, edit, save, or clear previously entered commands.
+    macro                 Manage macros.
     quit                  Exit this application.
     run_pyscript          Run Python script within this application's environment.
     run_script            Run text script.

docs/features/help.md

@@ -198,8 +198,8 @@ without line numbers, so you can copy them to the clipboard:
 
     (Cmd) history -s 1:3
 
-`cmd2` supports aliases which allow you to substitute a short, more convenient input string with a
-longer replacement string. Say we create an alias like this, and then use it:
+`cmd2` supports both aliases and macros, which allow you to substitute a short, more convenient
+input string with a longer replacement string. Say we create an alias like this, and then use it:
 
     (Cmd) alias create ls shell ls -aF
     Alias 'ls' created
@@ -212,7 +212,7 @@ By default, the `history` command shows exactly what we typed:
         1  alias create ls shell ls -aF
         2  ls -d h*
 
-There are two ways to modify the display so you can see what aliases and shortcuts were expanded to.
+There are two ways to modify the display so you can see what aliases and macros were expanded to.
 The first is to use `-x` or `--expanded`. These options show the expanded command instead of the
 entered command:
 
@@ -229,5 +229,5 @@ option:
         2x shell ls -aF -d h*
 
 If the entered command had no expansion, it is displayed as usual. However, if there is some change
-as the result of expanding aliases, then the entered command is displayed with the number, and the
-expanded command is displayed with the number followed by an `x`.
+as the result of expanding macros and aliases, then the entered command is displayed with the
+number, and the expanded command is displayed with the number followed by an `x`.

docs/features/history.md

@@ -24,7 +24,7 @@
 - [Output Redirection and Pipes](redirection.md)
 - [Scripting](scripting.md)
 - [Settings](settings.md)
-- [Shortcuts and Aliases](shortcuts_aliases.md)
+- [Shortcuts, Aliases, and Macros](shortcuts_aliases_macros.md)
 - [Startup Commands](startup_commands.md)
 - [Table Creation](table_creation.md)
 - [Transcripts](transcripts.md)