From 850fdf40decea684550977d88fd97be75abb5f41 Mon Sep 17 00:00:00 2001 From: Wez Furlong Date: Fri, 9 Oct 2020 23:22:52 -0700 Subject: [PATCH] docs: add docs for the Pane object refs: #225 --- .gitignore | 1 + ci/generate-docs.py | 5 ++++- .../lua/pane/get_current_working_dir.md | 14 ++++++++++++++ docs/config/lua/pane/get_cursor_position.md | 15 +++++++++++++++ docs/config/lua/pane/get_dimensions.md | 19 +++++++++++++++++++ docs/config/lua/pane/get_lines_as_text.md | 17 +++++++++++++++++ docs/config/lua/pane/get_title.md | 16 ++++++++++++++++ docs/config/lua/pane/pane_id.md | 8 ++++++++ docs/config/lua/pane/paste.md | 12 ++++++++++++ wezterm/src/scripting/pane.rs | 2 ++ 10 files changed, 108 insertions(+), 1 deletion(-) create mode 100644 docs/config/lua/pane/get_current_working_dir.md create mode 100644 docs/config/lua/pane/get_cursor_position.md create mode 100644 docs/config/lua/pane/get_dimensions.md create mode 100644 docs/config/lua/pane/get_lines_as_text.md create mode 100644 docs/config/lua/pane/get_title.md create mode 100644 docs/config/lua/pane/pane_id.md create mode 100644 docs/config/lua/pane/paste.md diff --git a/.gitignore b/.gitignore index f8896a887..1cbab5b46 100644 --- a/.gitignore +++ b/.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 diff --git a/ci/generate-docs.py b/ci/generate-docs.py index da9394467..fb31ca942 100644 --- a/ci/generate-docs.py +++ b/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"), diff --git a/docs/config/lua/pane/get_current_working_dir.md b/docs/config/lua/pane/get_current_working_dir.md new file mode 100644 index 000000000..6b66d220e --- /dev/null +++ b/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. diff --git a/docs/config/lua/pane/get_cursor_position.md b/docs/config/lua/pane/get_cursor_position.md new file mode 100644 index 000000000..49d2ef62f --- /dev/null +++ b/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 + + diff --git a/docs/config/lua/pane/get_dimensions.md b/docs/config/lua/pane/get_dimensions.md new file mode 100644 index 000000000..4c9f01570 --- /dev/null +++ b/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. + diff --git a/docs/config/lua/pane/get_lines_as_text.md b/docs/config/lua/pane/get_lines_as_text.md new file mode 100644 index 000000000..3e4db0c40 --- /dev/null +++ b/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. + diff --git a/docs/config/lua/pane/get_title.md b/docs/config/lua/pane/get_title.md new file mode 100644 index 000000000..ab6418166 --- /dev/null +++ b/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. diff --git a/docs/config/lua/pane/pane_id.md b/docs/config/lua/pane/pane_id.md new file mode 100644 index 000000000..e80dbf089 --- /dev/null +++ b/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. + diff --git a/docs/config/lua/pane/paste.md b/docs/config/lua/pane/paste.md new file mode 100644 index 000000000..19259f15d --- /dev/null +++ b/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. diff --git a/wezterm/src/scripting/pane.rs b/wezterm/src/scripting/pane.rs index b804fb4a9..896ab84b2 100644 --- a/wezterm/src/scripting/pane.rs +++ b/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) }); }