mirror of
https://github.com/wez/wezterm.git
synced 2024-08-17 10:10:23 +03:00
docs: shell-integration: cover the new built-in user-vars
This commit is contained in:
parent
d8ffbd6b31
commit
e725d68f08
@ -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() {
|
||||
|
@ -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.
|
||||
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
Loading…
Reference in New Issue
Block a user