docs: shell-integration: cover the new built-in user-vars

assets/shell-integration/wezterm.sh

@@ -391,7 +391,7 @@ if [[ ! -n "$BLE_VERSION" ]]; then
   __wezterm_install_bash_prexec
 fi
 
-# This functions emits an OSC 1337 sequencne to set a user var
+# This function emits an OSC 1337 sequence to set a user var
 # associated with the current terminal pane.
 # It requires the `base64` utility to be available in the path.
 __wezterm_set_user_var() {

docs/config/lua/pane/get_user_vars.md

@@ -10,7 +10,24 @@ also recognized by wezterm; this example sets the `foo` user variable
 to the value `bar`:
 
 ```bash
-printf "\033]1337;SetUserVar=%s=%s\007" foo `echo -n bar | base64`
+# This function emits an OSC 1337 sequence to set a user var
+# associated with the current terminal pane.
+# It requires the `base64` utility to be available in the path.
+# This function is included in the wezterm shell integration script, but
+# is reproduced here for clarity
+__wezterm_set_user_var() {
+  if hash base64 2>/dev/null ; then
+    if [[ -z "${TMUX}" ]] ; then
+      printf "\033]1337;SetUserVar=%s=%s\007" "$1" `echo -n "$2" | base64`
+    else
+      # <https://github.com/tmux/tmux/wiki/FAQ#what-is-the-passthrough-escape-sequence-and-how-do-i-use-it>
+      # Note that you ALSO need to add "set -g allow-passthrough on" to your tmux.conf
+      printf "\033Ptmux;\033\033]1337;SetUserVar=%s=%s\007\033\\" "$1" `echo -n "$2" | base64`
+    fi
+  fi
+}
+
+__wezterm_set_user_var "foo" "bar"
 ```
 
 you're then able to access this in your wezterm config:
@@ -19,3 +36,13 @@ you're then able to access this in your wezterm config:
 wezterm.log_info('foo var is ' .. pane:get_user_vars().foo)
 ```
 
+Setting a user var will generate events in the window that contains
+the corresponding pane:
+
+* [user-var-changed](../window-events/user-var-changed.md), which
+  allows you to directly take action when a var is set/changed.
+* [update-status](../window-events/update-status.md) which allows you to update left/right status items
+* the title and tab bar area will then update and trigger any associated events as part of that update
+
+The user var change event will propagate to all connected multiplexer clients.
+

docs/recipes/passing-data.md

@@ -29,7 +29,7 @@ printf "\033]1337;SetUserVar=%s=%s\007" foo `echo -n bar | base64`
 
 Note that the value must be base64 encoded.
 
-Setting a user var will generate two events in the window that contains
+Setting a user var will generate events in the window that contains
 the corresponding pane:
 
 * [user-var-changed](../config/lua/window-events/user-var-changed.md), which
@@ -48,17 +48,29 @@ In this example, an alias is used to set a user var named PROG to something
 when running various commands:
 
 ```bash
-# This function sets a user var
+# This function emits an OSC 1337 sequence to set a user var
-function _set_user_var() {
+# associated with the current terminal pane.
-    printf "\033]1337;SetUserVar=%s=%s\007" "$1" `echo -n "$2" | base64`
+# It requires the `base64` utility to be available in the path.
+# This function is included in the wezterm shell integration script, but
+# is reproduced here for clarity
+__wezterm_set_user_var() {
+  if hash base64 2>/dev/null ; then
+    if [[ -z "${TMUX}" ]] ; then
+      printf "\033]1337;SetUserVar=%s=%s\007" "$1" `echo -n "$2" | base64`
+    else
+      # <https://github.com/tmux/tmux/wiki/FAQ#what-is-the-passthrough-escape-sequence-and-how-do-i-use-it>
+      # Note that you ALSO need to add "set -g allow-passthrough on" to your tmux.conf
+      printf "\033Ptmux;\033\033]1337;SetUserVar=%s=%s\007\033\\" "$1" `echo -n "$2" | base64`
+    fi
+  fi
 }
 
 function _run_prog() {
     # set PROG to the program being run
-    _set_user_var "PROG" "$1"
+    __wezterm_set_user_var "PROG" "$1"
 
     # arrange to clear it when it is done
-    trap '_set_user_var PROG ""' EXIT
+    trap '__wezterm_set_user_var PROG ""' EXIT
 
     # and now run the corresponding command, taking care to avoid looping
     # with the alias definition
@@ -83,6 +95,9 @@ end)
 return {}
 ```
 
+If you install the [wezterm shell integration](../shell-integration.md) you
+will get a more comprehensive set of user vars set for you automatically.
+
 User vars enable you to very deliberately signal information from your pane to
 your wezterm config, and will work across multiplexer connections and even
 through tmux (provided that you use the [tmux passthrough escape

docs/shell-integration.md

@@ -2,8 +2,11 @@
 
 wezterm supports integrating with the shell through the following means:
 
-* OSC 7 Escape sequences to advise the terminal of the working directory
+* `OSC 7` Escape sequences to advise the terminal of the working directory
-* OSC 133 Escape sequence to define Input, Output and Prompt zones
+* `OSC 133` Escape sequence to define Input, Output and Prompt zones
+* `OSC 1337` Escape sequences to set user vars for tracking additional shell state
+
+`OSC` is escape sequence jargon for *Operating System Command*.
 
 These sequences enable some improved user experiences, such as being able
 to spawn new panes, tabs and windows with the same current working directory
@@ -24,12 +27,49 @@ can be found below.
 
 [Learn more about OSC 133 Semantic Prompt Escapes](https://gitlab.freedesktop.org/Per_Bothner/specifications/blob/master/proposals/semantic-prompts.md).
 
+### User Vars
+
+`OSC 1337` provides a means for setting *user vars*, which are somewhat similar
+to environment variables, except that they are variables associated with a
+given pane rather than a process.
+
+Installing the wezterm shell integration will define the following user vars
+by default:
+
+* `WEZTERM_PROG` - the command line being executed by the shell
+* `WEZTERM_USER` - holds the output from `id -un`; the current user name
+* `WEZTERM_HOST` - holds the output from `hostname`; the hostname that the shell is running on
+* `WEZTERM_IN_TMUX` - holds `1` if the shell is running inside tmux, `0` otherwise
+
+If you are a tmux user, you must ensure that you have `set -g allow-passthrough on` set
+in your tmux.conf for user vars to work.
+
+Those vars will be updated each time the prompt is shown and just prior to executing a command.
+
+The shell integration provides a shell function named `__wezterm_set_user_var` which can be
+used to set your own user vars.
+
+Setting a user var will generate events in the window that contains
+the corresponding pane:
+
+* [user-var-changed](config/lua/window-events/user-var-changed.md), which
+  allows you to directly take action when a var is set/changed.
+* [update-status](config/lua/window-events/update-status.md) which allows you to update left/right status items
+* the title and tab bar area will then update and trigger any associated events as part of that update
+
+You can access the complete set of user vars in a given pane by calling
+[pane:get_user_vars()](config/lua/pane/get_user_vars.md), or by accessing
+the `user_vars` field in a [PaneInformation](config/lua/PaneInformation.md)
+struct.
+
+You may wish to use this information to adjust what is shown in your tab titles
+or in the status area.
+
 ### OSC 7 Escape sequence to set the working directory
 
-`OSC` is escape sequence jargon for *Operating System Command*; `OSC 7` means
+`OSC 7` means Operating System Command number 7.  This is an escape sequence
-Operating System Command number 7.  This is an escape sequence that originated
+that originated in the macOS Terminal application that is used to advise the
-in the macOS Terminal application that is used to advise the terminal of the
+terminal of the current working directory.
-current working directory.
 
 An application (usually your shell) can be configured to emit this escape
 sequence when the current directory changes, or just to emit it each time