Removed macros.

Author: kmvanbrunt

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 3.0.0 (TBD)
+* Breaking Change
+  * Removed macros
+
 ## 2.5.0 (October 23, 2024)
 * Breaking Change
   * `cmd2` 2.5 supports Python 3.8+ (removed support for Python 3.6 and 3.7)

README.md

@@ -62,9 +62,9 @@ Deep extensive tab completion and help text generation based on the argparse lib
 
 <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
 - Transcripts for use with built-in regression can be automatically generated from `history -t` or `run_script -t`

cmd2/cmd2.py

@@ -38,56 +38,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]
     """String subclass with additional attributes to store the results of parsing.
@@ -210,10 +160,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

@@ -9,7 +9,7 @@ cmd2.Cmd
     .. attribute:: default_error
 
       The error message displayed when a non-existent command is run.
-      Default: ``{} is not a recognized command, alias, or macro.``
+      Default: ``{} is not a recognized command or alias.``
 
     .. attribute:: help_error
 

docs/api/cmd.rst

@@ -15,7 +15,7 @@ Classes for parsing and storing user input.
 
     .. attribute:: command
 
-      The name of the command after shortcuts and macros have been expanded
+      The name of the command after shortcuts have been expanded
 
     .. attribute:: args
 

docs/api/parsing.rst

@@ -11,7 +11,7 @@ features of ``cmd2``:
 * :ref:`features/argument_processing:Argument Processing`
 * :ref:`features/generating_output:Generating Output`
 * :ref:`features/help:Help`
-* :ref:`features/shortcuts_aliases_macros:Shortcuts`
+* :ref:`features/shortcuts_aliases:Shortcuts`
 * :ref:`features/multiline_commands:Multiline Commands`
 * :ref:`features/history:History`
 
@@ -178,8 +178,8 @@ Shortcuts
 ---------
 
 ``cmd2`` has several capabilities to simplify repetitive user input:
-:ref:`Shortcuts, Aliases, and Macros
-<features/shortcuts_aliases_macros:Shortcuts, Aliases, and Macros>`. Let's add
+:ref:`Shortcuts and Aliases
+<features/shortcuts_aliases:Shortcuts and Aliases>`. 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.rst

@@ -13,7 +13,7 @@ alias
 ~~~~~
 
 This command manages aliases via subcommands ``create``, ``delete``, and
-``list``.  See :ref:`features/shortcuts_aliases_macros:Aliases` for more
+``list``.  See :ref:`features/shortcuts_aliases:Aliases` for more
 information.
 
 edit
@@ -50,14 +50,6 @@ ipy
 This optional opt-in command enters an interactive IPython shell.  See
 :ref:`features/embedded_python_shells: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 :ref:`features/shortcuts_aliases_macros:Macros` for more
-information.
-
 py
 ~~
 
@@ -143,7 +135,7 @@ shortcuts
 ~~~~~~~~~
 
 This command lists available shortcuts.  See
-:ref:`features/shortcuts_aliases_macros:Shortcuts` for more information.
+:ref:`features/shortcuts_aliases:Shortcuts` for more information.
 
 
 Remove Builtin Commands

docs/features/builtin_commands.rst

@@ -67,7 +67,7 @@ the cmd_ module. This parsing handles:
 - 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

docs/features/commands.rst

@@ -19,8 +19,8 @@ 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:
@@ -63,8 +63,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``::
@@ -90,8 +90,8 @@ into categories. 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
@@ -142,51 +142,49 @@ The ``help`` command also has a verbose option (``help -v`` or ``help
     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 command
+    sessions              Sessions command
+    start                 Start command
+    stop                  Stop command
+    undeploy              Undeploy command
 
     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

docs/features/help.rst

@@ -232,9 +232,9 @@ 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
@@ -248,7 +248,7 @@ By default, the ``history`` command shows exactly what we typed::
         2  ls -d h*
 
 There are two ways to modify that display so you can see what aliases and
-macros were expanded to. The first is to use ``-x`` or ``--expanded``. These
+shortcuts were expanded to. The first is to use ``-x`` or ``--expanded``. These
 options show the expanded command instead of the entered command::
 
     (Cmd) history -x
@@ -264,6 +264,6 @@ If you want to see both the entered command and the expanded command, use the
         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``.
+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``.

docs/features/history.rst

@@ -26,7 +26,7 @@ Features
    redirection
    scripting
    settings
-   shortcuts_aliases_macros
+   shortcuts_aliases
    startup_commands
    table_creation
    transcripts

docs/features/index.rst

@@ -141,7 +141,6 @@ override:
   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

docs/features/initialization.rst

@@ -14,7 +14,7 @@ operating system shell::
 
     (Cmd) shell ls -al
 
-If you use the default :ref:`features/shortcuts_aliases_macros:Shortcuts`
+If you use the default :ref:`features/shortcuts_aliases:Shortcuts`
 defined in ``cmd2`` you'll get a ``!`` shortcut for ``shell``, which allows you
 to type::
 
@@ -107,8 +107,8 @@ 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)