wez/wezterm
1
1
Fork 0
mirror of https://github.com/wez/wezterm.git synced 2024-08-17 10:10:23 +03:00
Code Issues Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Wez Furlong 2023-01-23 10:50:49 -07:00
parent d8ffbd6b31
commit e725d68f08
No known key found for this signature in database
GPG Key ID: 7A7F66A31EC9B387
4 changed files with 96 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
assets/shell-integration/wezterm.sh
View File

@ -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() {

29
docs/config/lua/pane/get_user_vars.md
View File

@ -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.

27
docs/recipes/passing-data.md
View File

@ -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
function _set_user_var() {
printf "\033]1337;SetUserVar=%s=%s\007" "$1" `echo -n "$2" | 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
}
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

52
docs/shell-integration.md
View File

@ -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 133 Escape sequence to define Input, Output and Prompt zones
* `OSC 7` Escape sequences to advise the terminal of the working directory
* `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
Operating System Command number 7. This is an escape sequence that originated
in the macOS Terminal application that is used to advise the terminal of the
current working directory.
`OSC 7` means Operating System Command number 7. This is an escape sequence
that originated in the macOS Terminal application that is used to advise the
terminal of the 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