Removed macros.

Author: kmvanbrunt

CHANGELOG.md

@@ -1,3 +1,8 @@
+## 3.0.0 (TBD)
+
+- Breaking Change
+    - Removed macros
+
 ## 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/macro creation,
-command line argument parsing and execution of cmd2 scripting.
+cmd2 creates the second pillar of 'ease of transition to automation' through alias creation, command
+line argument parsing and execution of cmd2 scripting.
 
-- Flexible alias and macro creation for quick abstraction of commands.
+- Flexible alias 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,56 +35,6 @@ 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.
@@ -205,10 +155,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 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()``.
+        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()``.
 
         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_macros.md#shortcuts)
+- [Shortcuts](../features/shortcuts_aliases.md#shortcuts)
 - [Multiline Commands](../features/multiline_commands.md)
 - [History](../features/history.md)
 
@@ -166,7 +166,7 @@ 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, Aliases, and Macros](../features/shortcuts_aliases_macros.md). Let's add a shortcut to
+[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:

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_macros.md#aliases) for more information.
+[Aliases](shortcuts_aliases.md#aliases) for more information.
 
 ### edit
 
@@ -38,12 +38,6 @@ 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
@@ -114,8 +108,8 @@ Execute a command as if at the operating system shell prompt:
 
 ### shortcuts
 
-This command lists available shortcuts. See [Shortcuts](./shortcuts_aliases_macros.md#shortcuts) for
-more information.
+This command lists available shortcuts. See [Shortcuts](./shortcuts_aliases.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, macro, and alias expansion
+- shortcut and alias 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    py    run_pyscript  set    shortcuts
-edit   history  macro  quit  run_script    shell
+alias  help     ipy  quit          run_script  shell
+edit   history  py   run_pyscript  set         shortcuts
 ```
 
 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    py    run_pyscript  set    shortcuts
-    edit   history  macro  quit  run_script    shell
+    alias  help     ipy  quit          run_script  shell
+    edit   history  py   run_pyscript  set         shortcuts
 
 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  py    run_pyscript  set    shortcuts
-    config  help  macro    quit  run_script    shell  version
+    alias   edit  history  run_pyscript  set    shortcuts
+    config  help  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
@@ -137,51 +137,54 @@ categories with per-command Help Messages:
     Documented commands (use 'help -v' for verbose/'help <topic>' for details):
 
     Application Management
-    ================================================================================
-    deploy              Deploy command
-    expire              Expire command
-    findleakers         Find Leakers command
-    list                List command
-    redeploy            Redeploy command
-    restart             usage: restart [-h] {now,later,sometime,whenever}
-    sessions            Sessions command
-    start               Start command
-    stop                Stop command
-    undeploy            Undeploy command
+    ======================================================================================================
+    deploy                Deploy command.
+    expire                Expire command.
+    findleakers           Find Leakers command.
+    list                  List command.
+    redeploy              Redeploy command.
+    restart               Restart
+    sessions              Sessions command.
+    start                 Start
+    stop                  Stop command.
+    undeploy              Undeploy command.
+
+    Command Management
+    ======================================================================================================
+    disable_commands      Disable the Application Management commands.
+    enable_commands       Enable the Application Management commands.
 
     Connecting
-    ================================================================================
-    connect             Connect command
-    which               Which command
+    ======================================================================================================
+    connect               Connect command.
+    which                 Which command.
 
     Server Information
-    ================================================================================
-    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'
-    status                 Status command
-    thread_dump            Thread Dump command
-    vminfo                 VM Info command
+    ======================================================================================================
+    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'.
+    status                Status command.
+    thread_dump           Thread Dump command.
+    vminfo                VM Info command.
 
     Other
-    ================================================================================
-    alias               Manage aliases
-    config              Config command
-    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
-    py                  Invoke Python command or shell
-    quit                Exits this application
-    run_pyscript        Runs a python script file inside the console
-    run_script          Runs commands in script file that is encoded as either ASCII or UTF-8 text
-    set                 Set a settable parameter or show current settings of parameters
-    shell               Execute a command as if at the OS prompt
-    shortcuts           List available shortcuts
-    version             Version command
+    ======================================================================================================
+    alias                 Manage aliases
+    config                Config command.
+    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
+    quit                  Exit this application
+    run_pyscript          Run a Python script file inside the console
+    run_script            Run commands in script file that is encoded as either ASCII or UTF-8 text
+    set                   Set a settable parameter or show current settings of parameters.
+    shell                 Execute a command as if at the OS prompt
+    shortcuts             List available shortcuts
+    version               Version command.
 
 When called with the `-v` flag for verbose help, the one-line description for each command is
 provided by the first line of the docstring for that command's associated `do_*` method.

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 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:
+`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:
 
     (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 that display so you can see what aliases and macros were expanded to.
+There are two ways to modify the display so you can see what aliases and shortcuts 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 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`.
+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`.

docs/features/history.md

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

docs/features/index.md

@@ -92,7 +92,7 @@ The `cmd2.Cmd` class provides a large number of public instance attributes which
 
 ### Public instance attributes
 
-Here are instance attributes of `cmd2.Cmd` which developers might wish override:
+Here are instance attributes of `cmd2.Cmd` which developers might wish to override:
 
 - **always_show_hint**: if `True`, display tab completion hint even when completion suggestions print (Default: `False`)
 - **broken_pipe_warning**: if non-empty, this string will be displayed if a broken pipe error occurs
@@ -112,7 +112,6 @@ Here are instance attributes of `cmd2.Cmd` which developers might wish override:
 - **help_error**: the error that prints when no help information can be found
 - **hidden_commands**: commands to exclude from the help menu and tab completion
 - **last_result**: stores results from the last command run to enable usage of results in a Python script or interactive console. Built-in commands don't make use of this. It is purely there for user-defined commands and convenience.
-- **macros**: dictionary of macro names and their values
 - **max_completion_items**: max number of CompletionItems to display during tab completion (Default: 50)
 - **pager**: sets the pager command used by the `Cmd.ppaged()` method for displaying wrapped output using a pager
 - **pager_chop**: sets the pager command used by the `Cmd.ppaged()` method for displaying chopped/truncated output using a pager

docs/features/initialization.md

@@ -10,8 +10,8 @@ See [Output Redirection and Pipes](./redirection.md#output-redirection-and-pipes
 
     (Cmd) shell ls -al
 
-If you use the default [Shortcuts](./shortcuts_aliases_macros.md#shortcuts) defined in `cmd2` you'll
-get a `!` shortcut for `shell`, which allows you to type:
+If you use the default [Shortcuts](./shortcuts_aliases.md#shortcuts) defined in `cmd2` you'll get a
+`!` shortcut for `shell`, which allows you to type:
 
     (Cmd) !ls -al
 
@@ -89,8 +89,8 @@ shell, and execute those commands before entering the command loop:
 
     Documented commands (use 'help -v' for verbose/'help <topic>' for details):
     ===========================================================================
-    alias  help     macro   orate  quit          run_script  set    shortcuts
-    edit   history  mumble  py     run_pyscript  say         shell  speak
+    alias  help     ipy  quit          run_script  shell
+    edit   history  py   run_pyscript  set         shortcuts
 
     (Cmd)