add pane:get_foreground_process_info()

Returns all known information about the foreground process in the pane.

refs: #1987

ci/generate-docs.py

@@ -219,6 +219,7 @@ clear and convenient.
 
 """,
                     ),
+                    Page("object: LocalProcessInfo", "config/lua/LocalProcessInfo.md"),
                     Page("object: PaneInformation", "config/lua/PaneInformation.md"),
                     Page("object: TabInformation", "config/lua/TabInformation.md"),
                     Page("object: SshDomain", "config/lua/SshDomain.md"),

docs/config/lua/LocalProcessInfo.md

@@ -0,0 +1,18 @@
+# `LocalProcessInfo`
+
+*Since: 20220101-133340-7edc5b5a*
+
+`LocalProcessInfo` represents a process running on the local machine.
+
+It has the following fields:
+
+* `pid` - the process id
+* `ppid` - the parent process id
+* `name` - a short name for the process. You probably should prefer to look at the `executable` or `argv` fields instead of this one
+* `status` - a string holding the status of the process; it can be `Idle`, `Run`, `Sleep`, `Stop`, `Zombie`, `Tracing`, `Dead`, `Wakekill`, `Waking`, `Parked`, `LockBlocked`, `Unknown`.
+* `argv` - a table holding the argument array for the process
+* `executable` - the full path to the executable image for the process (may be empty)
+* `cwd` - the current working directory for the process (may be empty)
+* `children` - a table keyed by child process id and whose values are themselves `LocalProcessInfo` objects that describe the child processes
+
+See [mux-is-process-stateful](mux-events/mux-is-process-stateful.md) and [pane:get_foreground_process_info()](pane/get_foreground_process_info.md)

docs/config/lua/mux-events/mux-is-process-stateful.md

@@ -8,17 +8,8 @@ to determine whether a given Pane can be closed without prompting the user.
 This event is *synchronous* and must return as quickly as possible in order
 to avoid blocking the multiplexer.
 
-The event is passed a `LocalProcessInfo` object representing the process that
-corresponds to the pane. `LocalProcessInfo` has the following fields:
-
-* `pid` - the process id
-* `ppid` - the parent process id
-* `name` - a short name for the process. You probably should prefer to look at the `executable` or `argv` fields instead of this one
-* `status` - a string holding the status of the process; it can be `Idle`, `Run`, `Sleep`, `Stop`, `Zombie`, `Tracing`, `Dead`, `Wakekill`, `Waking`, `Parked`, `LockBlocked`, `Unknown`.
-* `argv` - a table holding the argument array for the process
-* `executable` - the full path to the executable image for the process (may be empty)
-* `cwd` - the current working directory for the process (may be empty)
-* `children` - a table keyed by child process id and whose values are themselves `LocalProcessInfo` objects that describe the child processes
+The event is passed a [LocalProcessInfo](../LocalProcessInfo.md) object
+representing the process that corresponds to the pane.
 
 The hook can return one of the following values:
 

docs/config/lua/pane/get_foreground_process_info.md

@@ -0,0 +1,41 @@
+# `pane:get_foreground_process_info()`
+
+*Since: nightly builds only*
+
+Returns a [LocalProcessInfo](../LocalProcessInfo.md) object corresponding to the current foreground process that is running in the pane.
+
+This method has some restrictions and caveats:
+
+* This information is only available for local panes.  Multiplexer panes do not report this information.  Similarly, if you are using eg: `ssh` to connect to a remote host, you won't be able to access the name of the remote process that is running.
+* On unix systems, the *process group leader* (the foreground process) will be queried, but that concept doesn't exist on Windows, so instead, the process tree of the originally spawned program is examined, and the most recently spawned descendant is assumed to be the foreground process
+* On Linux, macOS and Windows, the process can be queried to determine this path. Other operating systems (notably, FreeBSD and other unix systems) are not currently supported
+* Querying the path may fail for a variety of reasons outside of the control of WezTerm
+* Querying process information has some runtime overhead, which may cause wezterm to slow down if over-used.
+
+If the process cannot be determined then this method returns `nil`.
+
+This example sets the right status to show the process id and executable path:
+
+```lua
+local wezterm = require 'wezterm'
+
+-- Equivalent to POSIX basename(3)
+-- Given "/foo/bar" returns "bar"
+-- Given "c:\\foo\\bar" returns "bar"
+function basename(s)
+  return string.gsub(s, "(.*[/\\])(.*)", "%2")
+end
+
+wezterm.on("update-right-status", function(window, pane)
+  local info = pane:get_foreground_process_info()
+  if info then
+    window:set_right_status(tostring(info.pid) .. " " .. basename(info.executable))
+  else
+    window:set_right_status("")
+  end
+end)
+
+return {
+}
+```
+

docs/config/lua/pane/get_foreground_process_name.md

@@ -14,7 +14,7 @@ This method has some restrictions and caveats:
 
 If the path is not known then this method returns `nil`.
 
-This example sets the right status are to the executable path:
+This example sets the right status to the executable path:
 
 ```lua
 local wezterm = require 'wezterm'
@@ -33,3 +33,5 @@ end)
 return {
 }
 ```
+
+See also: [get_foreground_process_info](get_foreground_process_info.md)

mux/src/localpane.rs

@@ -371,6 +371,15 @@ impl Pane for LocalPane {
             .or_else(|| self.divine_current_working_dir())
     }
 
+    fn get_foreground_process_info(&self) -> Option<LocalProcessInfo> {
+        #[cfg(unix)]
+        if let Some(pid) = self.pty.borrow().process_group_leader() {
+            return LocalProcessInfo::with_root_pid(pid as u32);
+        }
+
+        self.divine_foreground_process()
+    }
+
     fn get_foreground_process_name(&self) -> Option<String> {
         #[cfg(unix)]
         if let Some(pid) = self.pty.borrow().process_group_leader() {

mux/src/pane.rs

@@ -390,6 +390,9 @@ pub trait Pane: Downcast {
     fn get_foreground_process_name(&self) -> Option<String> {
         None
     }
+    fn get_foreground_process_info(&self) -> Option<procinfo::LocalProcessInfo> {
+        None
+    }
 
     fn trickle_paste(&self, text: String) -> anyhow::Result<()> {
         if text.len() <= PASTE_CHUNK_SIZE {

wezterm-gui/src/scripting/pane.rs

@@ -41,6 +41,9 @@ impl UserData for PaneObject {
         methods.add_method("get_foreground_process_name", |_, this, _: ()| {
             Ok(this.pane()?.get_foreground_process_name())
         });
+        methods.add_method("get_foreground_process_info", |_, this, _: ()| {
+            Ok(this.pane()?.get_foreground_process_info())
+        });
         methods.add_method("paste", |_, this, text: String| {
             this.pane()?.send_paste(&text).map_err(luaerr)?;
             Ok(())