diff options
| -rw-r--r-- | cmd2/history.py | 42 | ||||
| -rw-r--r-- | docs/api/cmd.rst | 10 | ||||
| -rw-r--r-- | docs/api/history.rst | 16 | ||||
| -rw-r--r-- | docs/api/index.rst | 1 |
4 files changed, 52 insertions, 17 deletions
diff --git a/cmd2/history.py b/cmd2/history.py index 3b18fbeb..7b52aa16 100644 --- a/cmd2/history.py +++ b/cmd2/history.py @@ -15,7 +15,7 @@ from .parsing import Statement @attr.s(frozen=True) class HistoryItem(): - """Class used to represent one command in the History list""" + """Class used to represent one command in the history list""" _listformat = ' {:>4} {}' _ex_listformat = ' {:>4}x {}' @@ -28,16 +28,23 @@ class HistoryItem(): @property def raw(self) -> str: - """Return the raw input from the user for this item""" + """The raw input from the user for this item. + + Proxy property for ``self.statement.raw`` + """ return self.statement.raw @property def expanded(self) -> str: - """Return the command as run which includes shortcuts and aliases resolved plus any changes made in hooks""" + """Return the command as run which includes shortcuts and aliases resolved + plus any changes made in hooks + + Proxy property for ``self.statement.expanded_command_line`` + """ return self.statement.expanded_command_line def pr(self, script=False, expanded=False, verbose=False) -> str: - """Represent a HistoryItem in a pretty fashion suitable for printing. + """Represent this item in a pretty fashion suitable for printing. If you pass verbose=True, script and expanded will be ignored @@ -72,15 +79,17 @@ class HistoryItem(): class History(list): - """A list of HistoryItems that knows how to respond to user requests. + """A list of :class:`~cmd2.history.HistoryItem` objects with additional methods + for searching and managing the list. + + :class:`~cmd2.Cmd` instantiates this class into the :data:`~cmd2.Cmd.history` + attribute, and adds commands to it as a user enters them. - Here are some key methods: + See :ref:`features/history:History` for information about the built-in command + which allows users to view, search, run, and save previously entered commands. - select() - parse user input and return a list of relevant history items - str_search() - return a list of history items which contain the given string - regex_search() - return a list of history items which match a given regex - get() - return a single element of the list, using 1 based indexing - span() - given a 1-based slice, return the appropriate list of history items + Developers interested in accessing previously entered commands can use this + class to gain access to the historical record. """ def __init__(self, seq=()) -> None: super().__init__(seq) @@ -99,9 +108,10 @@ class History(list): return result def append(self, new: Statement) -> None: - """Append a HistoryItem to end of the History list. + """Append a new statement to the end of the History list. - :param new: command line to convert to HistoryItem and add to the end of the History list + :param new: Statement object which will be composed into a HistoryItem + and added to the end of the list """ history_item = HistoryItem(new, len(self) + 1) super().append(history_item) @@ -115,7 +125,7 @@ class History(list): """Get item from the History list using 1-based indexing. :param index: optional item to get (index as either integer or string) - :return: a single HistoryItem + :return: a single :class:`~cmd2.history.HistoryItem` """ index = int(index) if index == 0: @@ -171,8 +181,8 @@ class History(list): Different from native python indexing and slicing of arrays, this method uses 1-based array numbering. Users who are not programmers can't grok - 0 based numbering. Programmers can usually grok either. Which reminds me, - there are only two hard problems in programming: + zero based numbering. Programmers can sometimes grok zero based numbering. + Which reminds me, there are only two hard problems in programming: - naming - cache invalidation diff --git a/docs/api/cmd.rst b/docs/api/cmd.rst index 213a14ec..345e6219 100644 --- a/docs/api/cmd.rst +++ b/docs/api/cmd.rst @@ -29,8 +29,16 @@ cmd2.Cmd .. attribute:: settable - This dictionary contains the name and description of all settings available to users. + This dictionary contains the name and description of all settings + available to users. Users use the :ref:`features/builtin_commands:set` command to view and modify settings. Settings are stored in instance attributes with the same name as the setting. + + .. attribute:: history + + A record of previously entered commands. + + This attribute is an instance of :class:`cmd2.history.History`, and + each command is an instance of :class:`cmd2.history.HistoryItem`. diff --git a/docs/api/history.rst b/docs/api/history.rst new file mode 100644 index 00000000..a685db7a --- /dev/null +++ b/docs/api/history.rst @@ -0,0 +1,16 @@ +cmd2.history +=============== + +.. autoclass:: cmd2.history.History + :members: + +.. autoclass:: cmd2.history.HistoryItem + :members: + + .. attribute:: statement + + The statement object resulting from parsing + + .. attribute:: idx + + The 1-based index of this statement in the history list diff --git a/docs/api/index.rst b/docs/api/index.rst index fea39f72..43b36c7a 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -7,6 +7,7 @@ API Reference cmd parsing decorators + history ansi utils constants |