refactor!: use run-shell -C to execute hooks (#60)

BREAKING CHANGE:
1. Hooks are now directly forwarded to tmux using `run-shell -C <hook>`.
2. Escape sequences are handled by tmux.

Author: loichyan

CHANGELOG.md

@@ -45,14 +45,20 @@ follows <https://www.conventionalcommits.org/en/v1.0.0/> to track changes.
 - Add `@popup-proxy` to run tmux commands in the caller session ([#59])
 - Add `@popup-sync-buffer` to sync tmux buffers before pasting ([#59])
 
+### Changed
+
+- (**breaking**) Use `run-shell -C` to execute hooks. Escape sequences are now
+  handled by tmux, so `\;` can be used directly ([#60])
+
 ### Removed
 
 - (**breaking**) Remove placeholder `{popup_caller_path}` and
   `{popup_caller_pane_path}`. Use `##{session_path}` and `##{pane_current_path}`
   instead ([#58])
 
 [#58]: https://github.com/loichyan/tmux-toggle-popup/pull/58
-[#{59}]: https://github.com/loichyan/tmux-toggle-popup/pull/59
+[#59]: https://github.com/loichyan/tmux-toggle-popup/pull/59
+[#60]: https://github.com/loichyan/tmux-toggle-popup/pull/60
 
 ## [0.4.4] - 2025-08-30
 

README.md

@@ -13,7 +13,7 @@ A handy plugin to create toggleable popups.
 - tmux >= **3.4** (not tested on earlier versions)
 - Bash >= **3.2.57**
 
-> [!NOTE]
+> [!Note]
 >
 > This plugin has been tested on macOS's built-in Bash through GitHub Actions.
 > However, if you are experiencing issues on macOS, please try upgrading your
@@ -60,8 +60,8 @@ config.programs.tmux = {
   extraConfig = ''
     ...
     # popups
-    bind C-t run "#{@popup-toggle} -Ed'#{pane_current_path}' -w75% -h75%"
-    bind C-g run "#{@popup-toggle} -Ed'#{pane_current_path}' -w90% -h90% --name=lazygit lazygit"
+    bind C-t run "#{@popup-toggle} -Ed'##{pane_current_path}' -w75% -h75%"
+    bind C-g run "#{@popup-toggle} -Ed'##{pane_current_path}' -w90% -h90% --name=lazygit lazygit"
     ...
   '';
 };
@@ -92,7 +92,7 @@ set -g @plugin "tmux-plugins/tmux-continuum"
 set -g @plugin "loichyan/tmux-toggle-popup"
 ```
 
-> [!TIP]
+> [!Tip]
 >
 > Whenever you update the *.tmux.conf*, remember to reload it in both your
 > working session and the popup session; otherwise, keybinding or style changes

USAGE.md

@@ -111,7 +111,7 @@ intended as a workaround for [tmux/tmux#3991], which has been fixed in
 [tmux/tmux#3991]: https://github.com/tmux/tmux/issues/3991
 [tmux/tmux@a869693]: https://github.com/tmux/tmux/commit/a869693405f99c8ca8e2da32a08534489ce165f2
 
-> [!NOTE]
+> [!Note]
 >
 > The fix has been included in tmux v3.6, so this command is no longer
 > necessary.
@@ -216,38 +216,29 @@ affect subsequent calls.
 
 ## 🪝 Hooks
 
-A hook is used to run tmux commands on certain events. Each hook is preprocessed
-by *xargs(1)*, which splits it into a token stream. The token stream is
-collected and passed to tmux when the corresponding event fires. When writing
-hooks, keep the following rules in mind:
-
-1. Two commands must be delimited by a semicolon (`;`).
-2. Line breaks are replaced with spaces, therefore, as rule *(1)* states,
-   remember to put a semicolon after each command.
-3. Tokens can be protected by quotes (either `'` or `"`) from being split.
-4. Any character preceded by a backslash (`\`) is treated as a literal escape.
-   For instance, `\n` is interpreted as `n` rather than a line break.
-5. For commands that take a command sequence as an argument, each command in
-   that sequence must be delimited by `\;`, just as you would do in
-   *.tmux.conf*. You can use either `\\;` or `'\;'` to input a `\;`.
-   Additionally, you may also put the entire sequence in a pair of quotes, as
-   the following example shows.
-
-To disable a hook, you should set it to `nop` instead of an empty string.
+A hook is used to run tmux commands on certain events. Each hook is sent to tmux
+using `run-shell -C <hook>`. Here are some general tips for writing hooks:
+
+1. Separate two commands with a semicolon (`;`).
+2. For commands that accept a command sequence as an argument, like `bind-key`,
+   separate each command in the sequence with `\;`.
+3. To disable a hook, set it to `nop` or an empty string.
 
 **Example**:
 
 ```tmux
-# Hide the statusline and setup additional key bindings
-set -g  @popup-on-init 'set status off'
-# In single quotes, no escape sequence will be recognized.
-set -ga @popup-on-init '
-  ; bind -n M-1 confirm -p"inside a popup?" "run true" \\; display -d3000 "of course!"
+# tmux transforms everything inside braces into a single string that it can
+# parse. This string is then sent to tmux through `run-shell -C` right after we
+# we enter the popup session.
+set -g @popup-on-init {
+    set status off
+    bind -n M-t confirm -p "inside a popup?" "run true" \; display -d3000 "of course!"
+}
+# Outside tmux.conf, we need to manually escape and separate each command.
+set -g @popup-on-init '
+    set status off;
+    bind -n M-t confirm -p "inside a popup?" "run true" \; display -d3000 "of course!";
 '
-# While in double quotes, escape sequences work as usual.
-set -ga @popup-on-init "
-  ; bind -n M-2 \"confirm -p'inside a popup?' 'run true' ; display -d3000 'of course!'\"
-"
 ```
 
 ### `@popup-on-init`
@@ -331,7 +322,7 @@ if -F "#{!:#{@popup_did_init}}" {
 }
 ```
 
-> [!NOTE]
+> [!Note]
 >
 > Whenever you need to interact with the popup session, do it through the
 > `on-init` hook rather than `#{@popup-toggle} some_script.sh`. This is because,

src/helpers.sh

@@ -78,16 +78,11 @@ escape_session_name() {
 	print "${1//[.:]/_}"
 }
 
-# Parses tmux commands, assigning the tokens to an array named `cmds`.
-#
-# It returns 1 if the given string does not contain any valid tmux commands.
-declare cmds
-parse_cmds() {
+# Returns whether a hook is enabled.
+check_hook() {
 	if [[ -z $1 || $1 == "nop" ]]; then
 		return 1
 	fi
-	# shellcheck disable=SC2034
-	IFS=$'\n' read -d '' -ra cmds < <(print "$1" | xargs printf "%s\n") || true
 }
 
 # Expands the provided tmux FORMAT string.

src/helpers_tests.sh

@@ -9,61 +9,6 @@ CURRENT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 # shellcheck source=./helpers.sh
 source "$CURRENT_DIR/helpers.sh"
 
-#-- test:parse_cmds ------------------------------------------------------------
-
-test_parse_commands() {
-	parse_cmds "$1"
-	shift
-
-	if [[ $# -ne ${#cmds[@]} ]]; then
-		failf "expected $# tokens to be parsed, got ${#cmds[@]}:%s" "$(printf "\n\t%s" "${cmds[@]}")"
-	fi
-
-	local i=0
-	while [[ $# -gt 0 ]]; do
-		if [[ $1 != "${cmds[$i]}" ]]; then
-			git diff <(print "${cmds[i]}") <(print "$1")
-			failf "unexpected token at $((i + 1))"
-		fi
-		shift
-		i=$((i + 1))
-	done
-}
-
-(
-	begin_test "delimited_by_semis" || exit 0
-	test_parse_commands \
-		'set status off ; set exit-empty off' \
-		'set' 'status' 'off' ';' \
-		'set' 'exit-empty' 'off'
-) || exit 1 || exit 1
-
-(
-	begin_test "delimited_by_line_breaks" || exit 0
-	test_parse_commands \
-		'set status off
-	 set exit-empty off' \
-		'set' 'status' 'off' \
-		'set' 'exit-empty' 'off'
-) || exit 1 || exit 1
-
-(
-	begin_test "escaped_multiple_commands" || exit 0
-	test_parse_commands \
-		'bind -n M-1 display random\ text \\; display and\ more' \
-		'bind' '-n' 'M-1' \
-		'display' 'random text' '\;' \
-		'display' 'and more'
-) || exit 1
-
-(
-	begin_test "quoted_multiple_commands" || exit 0
-	test_parse_commands \
-		"bind -n M-2 \"display 'random text' ; display 'and more'\"" \
-		'bind' '-n' 'M-2' \
-		"display 'random text' ; display 'and more'"
-) || exit 1
-
 #-- test:interpolate -----------------------------------------------------------
 
 declare expected input

src/toggle.sh

@@ -76,9 +76,8 @@ prepare_init() {
 		on_cleanup+=(unbind $k \;)
 	done
 
-	if parse_cmds "$on_init"; then
-		init_cmds+=("${cmds[@]}")
-	fi
+	# Handle hook: on-init
+	if check_hook "$on_init"; then init_cmds+=(run -C "$on_init" \;); fi
 }
 
 declare name id id_format toggle_keys=() init_args=() display_args=()
@@ -197,26 +196,27 @@ main() {
 	open_script=""
 
 	# Handle hook: before-open
-	if parse_cmds "$before_open"; then open_cmds+=("${cmds[@]}" \;); fi
+	if check_hook "$before_open"; then open_cmds+=(run -C "$before_open" \;); fi
 
 	# Starting from version 3.5, tmux uses the user's `default-shell` to execute
 	# shell commands. However, our scripts require sh(1) and may not be parsed
 	# correctly by some incompatible shells. In this case, we change the default
 	# shell to `/bin/sh` and then revert it immediately.
-	open_script+="tmux set default-shell '$default_shell' ;"
+	open_script+="tmux set default-shell '$default_shell';"
 	open_cmds+=(set default-shell "/bin/sh" \;)
 
 	# Set $TMUX_POPUP_SERVER to identify the popup server.
-	open_script+="export TMUX_POPUP_SERVER='$popup_server' SHELL='$default_shell' ;"
+	open_script+="export TMUX_POPUP_SERVER='$popup_server' SHELL='$default_shell';"
 
 	# Suppress stdout to hide the `[detached] ...` message
-	open_script+="exec tmux $(escape "${popup_socket[@]}" "${init_cmds[@]}") >/dev/null ;"
+	open_script+="exec $(escape tmux "${popup_socket[@]}" "${init_cmds[@]}")>/dev/null;"
 	open_cmds+=(display-popup "${display_args[@]}" "$open_script" \;)
 
 	# Handle hook: after-close
-	if parse_cmds "$after_close"; then open_cmds+=("${cmds[@]}" \;); fi
+	if check_hook "$after_close"; then open_cmds+=(run -C "$after_close" \;); fi
 
 	# Do open the popup window
+	# printf '%s\n'
 	tmux "${open_cmds[@]}"
 
 	# Undo temporary changes on the popup server

src/toggle_tests/escape_session_name.stdout

@@ -4,7 +4,8 @@ TMUX:BEGIN[1] {
 	SHELL=/system/shell
 }
 	run
-	#{@popup_before_open}
+	-C
+	run '#{@popup_before_open}'
 	;
 	set
 	default-shell
@@ -38,10 +39,13 @@ TMUX:BEGIN[1] {
 		%current_pane_id:tmux-test
 		;
 		run
-		#{@popup_on_init}
+		-C
+		run '#{@popup_on_init}'
+		;
 	TMUX:END[3]
 	;
 	run
-	#{@popup_after_close}
+	-C
+	run '#{@popup_after_close}'
 	;
 TMUX:END[1]

src/toggle_tests/open_nested_popup.stdout

@@ -4,7 +4,8 @@ TMUX:BEGIN[1] {
 	SHELL=/system/shell
 }
 	run
-	#{@popup_before_open}
+	-C
+	run '#{@popup_before_open}'
 	;
 	set
 	default-shell
@@ -30,6 +31,7 @@ TMUX:BEGIN[1] {
 	TMUX:END[3]
 	;
 	run
-	#{@popup_after_close}
+	-C
+	run '#{@popup_after_close}'
 	;
 TMUX:END[1]

src/toggle_tests/open_nested_with_id.stdout

@@ -4,7 +4,8 @@ TMUX:BEGIN[1] {
 	SHELL=/system/shell
 }
 	run
-	#{@popup_before_open}
+	-C
+	run '#{@popup_before_open}'
 	;
 	set
 	default-shell
@@ -30,6 +31,7 @@ TMUX:BEGIN[1] {
 	TMUX:END[3]
 	;
 	run
-	#{@popup_after_close}
+	-C
+	run '#{@popup_after_close}'
 	;
 TMUX:END[1]

src/toggle_tests/open_nested_with_toggle_key.stdout

@@ -4,7 +4,8 @@ TMUX:BEGIN[1] {
 	SHELL=/system/shell
 }
 	run
-	#{@popup_before_open}
+	-C
+	run '#{@popup_before_open}'
 	;
 	set
 	default-shell
@@ -30,6 +31,7 @@ TMUX:BEGIN[1] {
 	TMUX:END[3]
 	;
 	run
-	#{@popup_after_close}
+	-C
+	run '#{@popup_after_close}'
 	;
 TMUX:END[1]