lua: add pane:get_logical_lines_as_text

refs: #1468

docs/changelog.md

@@ -26,6 +26,7 @@ As features stabilize some brief notes about them will accumulate here.
 * [wezterm.open_wth](config/lua/wezterm/open_with.md) function for opening URLs/documents with the default or a specific application [#1362](https://github.com/wez/wezterm/issues/1362)
 * [pane:get_foreground_process_name()](config/lua/pane/get_foreground_process_name.md) method, [PaneInformation](config/lua/PaneInformation.md) now has `foreground_process_name` and `current_working_dir` fields. [#1421](https://github.com/wez/wezterm/discussions/1421) [#915](https://github.com/wez/wezterm/issues/915) [#876](https://github.com/wez/wezterm/issues/876)
 * [ActivatePaneDirection](config/lua/keyassignment/ActivatePaneDirection.md) now also supports `"Next"` and `"Prev"` to cycle through panes [#976](https://github.com/wez/wezterm/issues/976)
+* [pane:get_logical_lines_as_text](config/lua/pane/get_logical_lines_as_text.md) to retrieve unwrapped logical lines from a pane [#1468](https://github.com/wez/wezterm/issues/1468)
 
 #### Changed
 

docs/config/lua/pane/get_lines_as_text.md

@@ -3,7 +3,11 @@
 *Since: 20201031-154415-9614e117*
 
 Returns the textual representation (not including color or other attributes) of
-the lines of text in the viewport as a string.
+the *physical* lines of text in the viewport as a string.
+
+A *physical* line is a possibly-wrapped line that composes a row in the terminal
+display matrix.  If you'd rather operate on *logical* lines, see
+[pane:get_logical_lines_as_text](get_logical_lines_as_text.md).
 
 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)

docs/config/lua/pane/get_logical_lines_as_text.md

@@ -0,0 +1,27 @@
+# `pane:get_logical_lines_as_text([nlines])`
+
+*Since: nightly builds only*
+
+Returns the textual representation (not including color or other attributes) of
+the *logical* lines of text in the viewport as a string.
+
+A *logical* line is an original input line prior to being wrapped into *physical*
+lines to composes rows in the terminal display matrix.  WezTerm doesn't store
+logical lines, but can recompute them from metadata stored in physical lines.
+Excessively long logical lines are force-wrapped to constrain the cost of
+rewrapping on resize and selection operations.
+
+If you'd rather operate on physical lines, see
+[pane:get_lines_as_text](get_lines_as_text.md).
+
+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.
+
+

wezterm-gui/src/scripting/pane.rs

@@ -80,5 +80,26 @@ impl UserData for PaneObject {
             text.truncate(trimmed);
             Ok(text)
         });
+
+        methods.add_method("get_logical_lines_as_text", |_, this, nlines: Option<usize>| {
+            let pane = this.pane()?;
+            let dims = pane.get_dimensions();
+            let nlines = nlines.unwrap_or(dims.viewport_rows);
+            let bottom_row = dims.physical_top + dims.viewport_rows as isize;
+            let top_row = bottom_row.saturating_sub(nlines as isize);
+            let lines = pane.get_logical_lines(top_row..bottom_row);
+            let mut text = String::new();
+            for line in lines {
+                for (_, cell) in line.logical.visible_cells() {
+                    text.push_str(cell.str());
+                }
+                let trimmed = text.trim_end().len();
+                text.truncate(trimmed);
+                text.push('\n');
+            }
+            let trimmed = text.trim_end().len();
+            text.truncate(trimmed);
+            Ok(text)
+        });
     }
 }