feat(pane): add capability to use [-SE] flags to capture_pane (#465)

In re: #458

Author: tony

src/libtmux/pane.py

@@ -155,13 +155,42 @@ def resize_pane(self, *args: t.Any, **kwargs: t.Any) -> "Pane":
         self.refresh()
         return self
 
-    def capture_pane(self) -> t.Union[str, t.List[str]]:
+    def capture_pane(
+        self,
+        start: t.Union["Literal['-']", t.Optional[int]] = None,
+        end: t.Union["Literal['-']", t.Optional[int]] = None,
+    ) -> t.Union[str, t.List[str]]:
         """
         Capture text from pane.
 
         ``$ tmux capture-pane`` to pane.
+        ``$ tmux capture-pane -S -10`` to pane.
+        ``$ tmux capture-pane`-E 3` to pane.
+        ``$ tmux capture-pane`-S - -E -` to pane.
+
+        Parameters
+        ----------
+        start: [str,int]
+            Specify the starting line number.
+            Zero is the first line of the visible pane.
+            Positive numbers are lines in the visible pane.
+            Negative numbers are lines in the history.
+            ‘-’ is the start of the history.
+            Default: None
+        end: [str,int]
+            Specify the ending line number.
+            Zero is the first line of the visible pane.
+            Positive numbers are lines in the visible pane.
+            Negative numbers are lines in the history.
+            ‘-’ is the end of the visible pane
+            Default: None
         """
-        return self.cmd("capture-pane", "-p").stdout
+        cmd = ["capture-pane", "-p"]
+        if start is not None:
+            cmd.extend(["-S", str(start)])
+        if end is not None:
+            cmd.extend(["-E", str(end)])
+        return self.cmd(*cmd).stdout
 
     def send_keys(
         self,

tests/test_pane.py

@@ -90,3 +90,52 @@ def test_capture_pane(session: Session) -> None:
     assert pane_contents == r'$ printf "\n%s\n" "Hello World !"{}'.format(
         "\n\nHello World !\n$"
     )
+
+
+def test_capture_pane_start(session: Session) -> None:
+    env = shutil.which("env")
+    assert env is not None, "Cannot find usable `env` in PATH."
+
+    session.new_window(
+        attach=True,
+        window_name="capture_pane_start",
+        window_shell=f"{env} PS1='$ ' sh",
+    )
+    pane = session.attached_window.attached_pane
+    assert pane is not None
+    pane_contents = "\n".join(pane.capture_pane())
+    assert pane_contents == "$"
+    pane.send_keys(r'printf "%s"', literal=True, suppress_history=False)
+    pane_contents = "\n".join(pane.capture_pane())
+    assert pane_contents == '$ printf "%s"\n$'
+    pane.send_keys("clear -x", literal=True, suppress_history=False)
+    pane_contents = "\n".join(pane.capture_pane())
+    assert pane_contents == "$"
+    pane_contents_start = pane.capture_pane(start=-2)
+    assert pane_contents_start[0] == '$ printf "%s"'
+    assert pane_contents_start[1] == "$ clear -x"
+    assert pane_contents_start[-1] == "$"
+    pane_contents_start = pane.capture_pane(start="-")
+    assert pane_contents == "$"
+
+
+def test_capture_pane_end(session: Session) -> None:
+    env = shutil.which("env")
+    assert env is not None, "Cannot find usable `env` in PATH."
+
+    session.new_window(
+        attach=True,
+        window_name="capture_pane_end",
+        window_shell=f"{env} PS1='$ ' sh",
+    )
+    pane = session.attached_window.attached_pane
+    assert pane is not None
+    pane_contents = "\n".join(pane.capture_pane())
+    assert pane_contents == "$"
+    pane.send_keys(r'printf "%s"', literal=True, suppress_history=False)
+    pane_contents = "\n".join(pane.capture_pane())
+    assert pane_contents == '$ printf "%s"\n$'
+    pane_contents = "\n".join(pane.capture_pane(end=0))
+    assert pane_contents == '$ printf "%s"'
+    pane_contents = "\n".join(pane.capture_pane(end="-"))
+    assert pane_contents == '$ printf "%s"\n$'