docs: add docs for the Pane object

refs: #225

.gitignore

@@ -12,6 +12,7 @@
 /docs/installation.md
 /docs/install/*.md
 /docs/config/lua/wezterm/index.md
+/docs/config/lua/pane/index.md
 **/*.rs.bk
 .*.sw*
 /esctest.log

ci/generate-docs.py

@@ -75,7 +75,10 @@ TOC = [
             Page(
                 "Lua Reference",
                 "config/lua/general.md",
-                children=[Gen("module: wezterm", "config/lua/wezterm"),],
+                children=[
+                    Gen("module: wezterm", "config/lua/wezterm"),
+                    Gen("object: Pane", "config/lua/pane"),
+                ],
             ),
             Page("Scrollback", "scrollback.markdown"),
             Page("Copy Mode", "copymode.markdown"),

docs/config/lua/pane/get_current_working_dir.md

@@ -0,0 +1,14 @@
+# `pane:get_current_working_dir()`
+
+*Since: nightly builds only*
+
+Returns the current working directory of the pane, if known.
+The current directory can be specified by an application sending
+[OSC 7](../../../shell-integration.md).
+
+On Linux and macOS, if OSC 7 was never sent to the pane, wezterm will attempt
+to inspect the cwd of the process group leader attached to the pty and use
+that.
+
+If the current working directory is not known then this method returns `nil`.
+Otherwise, it returns the current working directory as a URI string.

docs/config/lua/pane/get_cursor_position.md

@@ -0,0 +1,15 @@
+# `pane:get_cursor_position()`
+
+*Since: nightly builds only*
+
+Returns a lua representation of the `StableCursorPosition` struct
+that identifies the cursor position, visibility and shape.
+
+It has the following fields:
+
+ * `x` the horizontal cell index
+ * `y` the vertical stable row index
+ * `shape` the `CursorShape` enum value
+ * `visibility` the `CursorVisibility` enum value
+
+

docs/config/lua/pane/get_dimensions.md

@@ -0,0 +1,19 @@
+# `pane:get_dimensions()`
+
+*Since: nightly builds only*
+
+Returns a lua representation of the `RenderableDimensions` struct
+that identifies the dimensions and position of the viewport as
+well as the scrollback for the pane.
+
+It has the following fields:
+
+ * `cols` the number of columns
+ * `viewport_rows` the number of vertical cells in the visible portion
+   of the window
+ * `scrollback_rows` the total number of lines in the scrollback and viewport
+ * `physical_top` the top of the physical non-scrollback screen expressed as
+   a stable index.
+ * `scrollback_top` the top of the scrollback; the earliest row remembered
+   by wezterm.
+

docs/config/lua/pane/get_lines_as_text.md

@@ -0,0 +1,17 @@
+# `pane:get_lines_as_text([nlines])`
+
+*Since: nightly builds only*
+
+Returns the textual representation (not including color or other attributes) of
+the lines of text in the viewport as a string.
+
+If the optional `nlines` argument is specified then it is used to determine how
+many lines of text should be retrieved.  The default (if `nlines` is not specified)
+is to retrieve the number of lines in the viewport (the height of the pane).
+
+The lines have trailing space removed from each line.  The lines will be
+joined together in the returned string separated by a `\n` character.
+Trailing blank lines are stripped, which may result in fewer lines being
+returned than you might expect if the pane only had a couple of lines
+of output.
+

docs/config/lua/pane/get_title.md

@@ -0,0 +1,16 @@
+# `pane:get_title()`
+
+*Since: nightly builds only*
+
+Returns the title of the pane.  This will typically be `wezterm` by default but
+can be modified by applications that send `OSC 1` (Icon/Tab title changing)
+and/or `OSC 2` (Window title changing) escape sequences.
+
+The value returned by this method is the same as that used to display the
+tab title if this pane were the only pane in the tab; if `OSC 1` was used
+to set a non-empty string then that string will be returned.  Otherwise the
+value for `OSC 2` will be returned.
+
+Note that on Microsoft Windows the default behavior of the OS level PTY is to
+implicitly send `OSC 2` sequences to the terminal as new programs attach to the
+console.

docs/config/lua/pane/pane_id.md

@@ -0,0 +1,8 @@
+# `pane:pane_id()`
+
+*Since: nightly builds only*
+
+Returns the id number for the pane.  The Id is used to identify the pane
+within the internal multiplexer and can be used when making API calls
+via `wezterm cli` to indicate the subject of manipulation.
+

docs/config/lua/pane/paste.md

@@ -0,0 +1,12 @@
+# `pane:paste(text)`
+
+*Since: nightly builds only*
+
+Sends the supplied `text` string to the input of the pane as if it
+were pasted from the clipboard, except that the clipboard is not involved.
+
+If the terminal attached to the pane is set to bracketed paste mode then
+the text will be sent as a bracketed paste.
+
+Otherwise the string will be streamed into the input in chunks of
+approximately 1KB each.

wezterm/src/scripting/pane.rs

@@ -71,6 +71,8 @@ impl UserData for PaneObject {
                 text.truncate(trimmed);
                 text.push('\n');
             }
+            let trimmed = text.trim_end().len();
+            text.truncate(trimmed);
             Ok(text)
         });
     }