Method span

cmd2/history.py:226–273

Return a slice of the History list. :param span: string containing an index or a slice :param include_persisted: if True, then retrieve full results including from persisted history :return: a dictionary of history items keyed by their 1-based index in ascending order,

(self, span: str, include_persisted: bool = False)

    spanpattern = re.compile(r"^\s*(?P<start>-?[1-9]\d*)?(?P<separator>:|(\.{2,}))(?P<end>-?[1-9]\d*)?\s*$")

    def span(self, span: str, include_persisted: bool = False) -> dict[int, "HistoryItem"]:
        """Return a slice of the History list.

        :param span: string containing an index or a slice
        :param include_persisted: if True, then retrieve full results including from persisted history
        :return: a dictionary of history items keyed by their 1-based index in ascending order,
                 or an empty dictionary if no results were found

        This method can accommodate input in any of these forms:

            a..b or a:b
            a.. or a:
            ..a or :a
            -a.. or -a:
            ..-a or :-a

        Different from native python indexing and slicing of arrays, this method
        uses 1-based array numbering. Users who are not programmers can&#x27;t grok
        zero based numbering. Programmers can sometimes grok zero based numbering.
        Which reminds me, there are only two hard problems in programming:

        - naming
        - cache invalidation
        - off by one errors

        """
        results = self.spanpattern.search(span)
        if not results:
            # our regex doesn't match the input, bail out
            raise ValueError("History indices must be positive or negative integers, and may not be zero.")

        start_token = results.group("start")
        if start_token:
            start = min(self._zero_based_index(start_token), len(self) - 1)
            if start < 0:
                start = max(0, len(self) + start)
        else:
            start = 0 if include_persisted else self.session_start_index

        end_token = results.group("end")
        if end_token:
            end = min(int(end_token), len(self))
            if end < 0:
                end = max(0, len(self) + end + 1)
        else:
            end = len(self)

        return self._build_result_dictionary(start, end)

    def str_search(self, search: str, include_persisted: bool = False) -> dict[int, "HistoryItem"]:
        """Find history items which contain a given string.