Skip to main content

tmux_client/
advanced.rs

1//! Typed builders for advanced tmux command families.
2
3use std::collections::BTreeMap;
4use std::ffi::OsString;
5use std::path::PathBuf;
6use std::time::Duration;
7
8use crate::{
9    ClientName, Command, Error, OptionValue, Pane, PaneId, ReleaseVersion, Result, Server,
10    SparseOptionMap, TmuxText, Window,
11};
12
13const V33: ReleaseVersion = ReleaseVersion::new(3, 3, None);
14const V34: ReleaseVersion = ReleaseVersion::new(3, 4, None);
15const V35: ReleaseVersion = ReleaseVersion::new(3, 5, None);
16const V36: ReleaseVersion = ReleaseVersion::new(3, 6, None);
17const V37: ReleaseVersion = ReleaseVersion::new(3, 7, None);
18
19/// Typed arguments for `run-shell`.
20#[derive(Clone, Debug)]
21pub struct RunShell {
22    command: OsString,
23    background: bool,
24    delay: Option<Duration>,
25    as_tmux_command: bool,
26    target: Option<PaneId>,
27    cwd: Option<PathBuf>,
28    show_stderr: bool,
29    arguments: Vec<OsString>,
30}
31
32impl RunShell {
33    /// Creates a shell job.
34    #[must_use]
35    pub fn new(command: impl Into<OsString>) -> Self {
36        Self {
37            command: command.into(),
38            background: false,
39            delay: None,
40            as_tmux_command: false,
41            target: None,
42            cwd: None,
43            show_stderr: false,
44            arguments: Vec::new(),
45        }
46    }
47
48    /// Runs the job without waiting for output.
49    #[must_use]
50    pub const fn background(mut self, enabled: bool) -> Self {
51        self.background = enabled;
52        self
53    }
54
55    /// Delays execution by a non-zero duration.
56    pub fn delay(mut self, delay: Duration) -> Result<Self> {
57        if delay.is_zero() {
58            return Err(Error::InvalidArgument {
59                argument: "run-shell delay",
60                message: "must be non-zero".to_owned(),
61            });
62        }
63        self.delay = Some(delay);
64        Ok(self)
65    }
66
67    /// Parses the command as tmux commands instead of a shell command.
68    #[must_use]
69    pub const fn as_tmux_command(mut self, enabled: bool) -> Self {
70        self.as_tmux_command = enabled;
71        self
72    }
73
74    /// Selects a pane for formats and output.
75    #[must_use]
76    pub const fn target(mut self, target: PaneId) -> Self {
77        self.target = Some(target);
78        self
79    }
80
81    /// Sets the starting directory. Requires tmux 3.4+.
82    #[must_use]
83    pub fn cwd(mut self, cwd: impl Into<PathBuf>) -> Self {
84        self.cwd = Some(cwd.into());
85        self
86    }
87
88    /// Includes job standard error. Requires tmux 3.6+.
89    #[must_use]
90    pub const fn show_stderr(mut self, enabled: bool) -> Self {
91        self.show_stderr = enabled;
92        self
93    }
94
95    /// Adds positional template arguments. Requires tmux 3.7+.
96    #[must_use]
97    pub fn arguments<I, S>(mut self, arguments: I) -> Self
98    where
99        I: IntoIterator<Item = S>,
100        S: Into<OsString>,
101    {
102        self.arguments.extend(arguments.into_iter().map(Into::into));
103        self
104    }
105}
106
107/// An operation supported by `wait-for`.
108#[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)]
109pub enum WaitAction {
110    /// Wait until another command signals the channel.
111    #[default]
112    Wait,
113    /// Signal the channel (`-S`).
114    Signal,
115    /// Lock the channel (`-L`).
116    Lock,
117    /// Unlock the channel (`-U`).
118    Unlock,
119}
120
121impl WaitAction {
122    fn flag(self) -> Option<&'static str> {
123        match self {
124            Self::Wait => None,
125            Self::Signal => Some("-S"),
126            Self::Lock => Some("-L"),
127            Self::Unlock => Some("-U"),
128        }
129    }
130}
131
132/// Typed arguments for `bind-key`.
133#[derive(Clone, Debug)]
134pub struct KeyBinding {
135    key: OsString,
136    command: OsString,
137    table: Option<OsString>,
138    note: Option<OsString>,
139    repeat: bool,
140    root: bool,
141}
142
143impl KeyBinding {
144    /// Creates a key binding.
145    #[must_use]
146    pub fn new(key: impl Into<OsString>, command: impl Into<OsString>) -> Self {
147        Self {
148            key: key.into(),
149            command: command.into(),
150            table: None,
151            note: None,
152            repeat: false,
153            root: false,
154        }
155    }
156
157    /// Selects a key table.
158    #[must_use]
159    pub fn table(mut self, table: impl Into<OsString>) -> Self {
160        self.table = Some(table.into());
161        self
162    }
163
164    /// Adds a user-facing binding note.
165    #[must_use]
166    pub fn note(mut self, note: impl Into<OsString>) -> Self {
167        self.note = Some(note.into());
168        self
169    }
170
171    /// Makes the binding repeatable.
172    #[must_use]
173    pub const fn repeat(mut self, enabled: bool) -> Self {
174        self.repeat = enabled;
175        self
176    }
177
178    /// Binds without the prefix key (`-n`).
179    #[must_use]
180    pub const fn root(mut self, enabled: bool) -> Self {
181        self.root = enabled;
182        self
183    }
184}
185
186/// Typed arguments for `unbind-key`.
187#[derive(Clone, Debug, Default)]
188pub struct UnbindKey {
189    key: Option<OsString>,
190    table: Option<OsString>,
191    all: bool,
192    quiet: bool,
193}
194
195impl UnbindKey {
196    /// Creates an empty unbind request.
197    #[must_use]
198    pub fn new() -> Self {
199        Self::default()
200    }
201
202    /// Selects a key.
203    #[must_use]
204    pub fn key(mut self, key: impl Into<OsString>) -> Self {
205        self.key = Some(key.into());
206        self
207    }
208
209    /// Selects a key table.
210    #[must_use]
211    pub fn table(mut self, table: impl Into<OsString>) -> Self {
212        self.table = Some(table.into());
213        self
214    }
215
216    /// Removes all bindings in the selected table.
217    #[must_use]
218    pub const fn all(mut self, enabled: bool) -> Self {
219        self.all = enabled;
220        self
221    }
222
223    /// Suppresses errors for missing keys.
224    #[must_use]
225    pub const fn quiet(mut self, enabled: bool) -> Self {
226        self.quiet = enabled;
227        self
228    }
229}
230
231/// A server ACL permission.
232#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
233pub enum ClientPermission {
234    /// Force read-only attachment.
235    ReadOnly,
236    /// Permit read-write attachment.
237    ReadWrite,
238}
239
240/// A typed `server-access` action.
241#[derive(Clone, Debug, Eq, PartialEq)]
242pub enum ServerAccess {
243    /// Allow a user with an explicit permission.
244    Allow {
245        /// Operating-system username.
246        user: String,
247        /// Attachment permission.
248        permission: ClientPermission,
249    },
250    /// Deny a user.
251    Deny {
252        /// Operating-system username.
253        user: String,
254    },
255    /// List access rules.
256    List,
257}
258
259/// Typed arguments for `confirm-before`.
260#[derive(Clone, Debug)]
261pub struct ConfirmBefore {
262    command: OsString,
263    prompt: Option<OsString>,
264    confirm_key: Option<OsString>,
265    default_yes: bool,
266    target_client: Option<ClientName>,
267}
268
269impl ConfirmBefore {
270    /// Creates a background confirmation request.
271    #[must_use]
272    pub fn new(command: impl Into<OsString>) -> Self {
273        Self {
274            command: command.into(),
275            prompt: None,
276            confirm_key: None,
277            default_yes: false,
278            target_client: None,
279        }
280    }
281
282    /// Sets prompt text.
283    #[must_use]
284    pub fn prompt(mut self, prompt: impl Into<OsString>) -> Self {
285        self.prompt = Some(prompt.into());
286        self
287    }
288
289    /// Sets the acceptance key. Requires tmux 3.4+.
290    #[must_use]
291    pub fn confirm_key(mut self, key: impl Into<OsString>) -> Self {
292        self.confirm_key = Some(key.into());
293        self
294    }
295
296    /// Makes Enter confirm by default. Requires tmux 3.4+.
297    #[must_use]
298    pub const fn default_yes(mut self, enabled: bool) -> Self {
299        self.default_yes = enabled;
300        self
301    }
302
303    /// Targets an attached client.
304    #[must_use]
305    pub fn target_client(mut self, client: ClientName) -> Self {
306        self.target_client = Some(client);
307        self
308    }
309}
310
311/// A tmux prompt-history and completion namespace.
312#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
313pub enum PromptType {
314    /// Command history.
315    Command,
316    /// Search history.
317    Search,
318    /// General target history.
319    Target,
320    /// Window-target history.
321    WindowTarget,
322}
323
324impl PromptType {
325    fn as_str(self) -> &'static str {
326        match self {
327            Self::Command => "command",
328            Self::Search => "search",
329            Self::Target => "target",
330            Self::WindowTarget => "window-target",
331        }
332    }
333}
334
335/// Typed arguments for `command-prompt`.
336#[derive(Clone, Debug)]
337pub struct CommandPrompt {
338    template: OsString,
339    prompt: Option<OsString>,
340    inputs: Option<OsString>,
341    target_client: Option<ClientName>,
342    one_key: bool,
343    key_only: bool,
344    on_input_change: bool,
345    numeric: bool,
346    prompt_type: Option<PromptType>,
347    expand_format: bool,
348    literal: bool,
349    backspace_exit: bool,
350    no_freeze: bool,
351}
352
353impl CommandPrompt {
354    /// Creates a background prompt with a tmux command template.
355    #[must_use]
356    pub fn new(template: impl Into<OsString>) -> Self {
357        Self {
358            template: template.into(),
359            prompt: None,
360            inputs: None,
361            target_client: None,
362            one_key: false,
363            key_only: false,
364            on_input_change: false,
365            numeric: false,
366            prompt_type: None,
367            expand_format: false,
368            literal: false,
369            backspace_exit: false,
370            no_freeze: false,
371        }
372    }
373
374    /// Sets prompt text.
375    #[must_use]
376    pub fn prompt(mut self, prompt: impl Into<OsString>) -> Self {
377        self.prompt = Some(prompt.into());
378        self
379    }
380
381    /// Sets prefilled inputs.
382    #[must_use]
383    pub fn inputs(mut self, inputs: impl Into<OsString>) -> Self {
384        self.inputs = Some(inputs.into());
385        self
386    }
387
388    /// Targets an attached client.
389    #[must_use]
390    pub fn target_client(mut self, client: ClientName) -> Self {
391        self.target_client = Some(client);
392        self
393    }
394
395    /// Accepts one key press.
396    #[must_use]
397    pub const fn one_key(mut self, enabled: bool) -> Self {
398        self.one_key = enabled;
399        self
400    }
401
402    /// Accepts keys but no text input.
403    #[must_use]
404    pub const fn key_only(mut self, enabled: bool) -> Self {
405        self.key_only = enabled;
406        self
407    }
408
409    /// Runs the template after every input change.
410    #[must_use]
411    pub const fn on_input_change(mut self, enabled: bool) -> Self {
412        self.on_input_change = enabled;
413        self
414    }
415
416    /// Restricts input to numbers.
417    #[must_use]
418    pub const fn numeric(mut self, enabled: bool) -> Self {
419        self.numeric = enabled;
420        self
421    }
422
423    /// Selects the history namespace.
424    #[must_use]
425    pub const fn prompt_type(mut self, prompt_type: PromptType) -> Self {
426        self.prompt_type = Some(prompt_type);
427        self
428    }
429
430    /// Expands formats in the command template.
431    #[must_use]
432    pub const fn expand_format(mut self, enabled: bool) -> Self {
433        self.expand_format = enabled;
434        self
435    }
436
437    /// Treats a comma-containing prompt literally. Requires tmux 3.6+.
438    #[must_use]
439    pub const fn literal(mut self, enabled: bool) -> Self {
440        self.literal = enabled;
441        self
442    }
443
444    /// Exits when backspace empties input. Requires tmux 3.7+.
445    #[must_use]
446    pub const fn backspace_exit(mut self, enabled: bool) -> Self {
447        self.backspace_exit = enabled;
448        self
449    }
450
451    /// Keeps panes unfrozen. Requires tmux 3.7+.
452    #[must_use]
453    pub const fn no_freeze(mut self, enabled: bool) -> Self {
454        self.no_freeze = enabled;
455        self
456    }
457}
458
459/// One entry in a popup menu.
460#[derive(Clone, Debug, Eq, PartialEq)]
461pub enum MenuItem {
462    /// A selectable name/key/command triple.
463    Entry {
464        /// Displayed label.
465        label: OsString,
466        /// Shortcut key.
467        key: OsString,
468        /// tmux command executed on selection.
469        command: OsString,
470    },
471    /// A visual separator.
472    Separator,
473}
474
475impl MenuItem {
476    /// Creates a selectable entry.
477    #[must_use]
478    pub fn entry(
479        label: impl Into<OsString>,
480        key: impl Into<OsString>,
481        command: impl Into<OsString>,
482    ) -> Self {
483        Self::Entry {
484            label: label.into(),
485            key: key.into(),
486            command: command.into(),
487        }
488    }
489}
490
491/// Typed arguments for `display-menu`.
492#[derive(Clone, Debug, Default)]
493pub struct Menu {
494    items: Vec<MenuItem>,
495    title: Option<OsString>,
496    target_pane: Option<PaneId>,
497    target_client: Option<ClientName>,
498    x: Option<OsString>,
499    y: Option<OsString>,
500    starting_choice: Option<OsString>,
501    border_lines: Option<OsString>,
502    style: Option<OsString>,
503    border_style: Option<OsString>,
504    selected_style: Option<OsString>,
505    mouse: bool,
506    stay_open: bool,
507}
508
509impl Menu {
510    /// Creates an empty menu.
511    #[must_use]
512    pub fn new() -> Self {
513        Self::default()
514    }
515
516    /// Adds a menu item.
517    #[must_use]
518    pub fn item(mut self, item: MenuItem) -> Self {
519        self.items.push(item);
520        self
521    }
522
523    /// Sets the menu title.
524    #[must_use]
525    pub fn title(mut self, title: impl Into<OsString>) -> Self {
526        self.title = Some(title.into());
527        self
528    }
529
530    /// Targets a pane.
531    #[must_use]
532    pub const fn target_pane(mut self, pane: PaneId) -> Self {
533        self.target_pane = Some(pane);
534        self
535    }
536
537    /// Targets a client.
538    #[must_use]
539    pub fn target_client(mut self, client: ClientName) -> Self {
540        self.target_client = Some(client);
541        self
542    }
543
544    /// Sets an x position or tmux position expression.
545    #[must_use]
546    pub fn x(mut self, value: impl Into<OsString>) -> Self {
547        self.x = Some(value.into());
548        self
549    }
550
551    /// Sets a y position or tmux position expression.
552    #[must_use]
553    pub fn y(mut self, value: impl Into<OsString>) -> Self {
554        self.y = Some(value.into());
555        self
556    }
557
558    /// Sets the initially selected row. Requires tmux 3.4+.
559    #[must_use]
560    pub fn starting_choice(mut self, value: impl Into<OsString>) -> Self {
561        self.starting_choice = Some(value.into());
562        self
563    }
564
565    /// Sets the border line style. Requires tmux 3.4+.
566    #[must_use]
567    pub fn border_lines(mut self, value: impl Into<OsString>) -> Self {
568        self.border_lines = Some(value.into());
569        self
570    }
571
572    /// Sets menu style. Requires tmux 3.4+.
573    #[must_use]
574    pub fn style(mut self, value: impl Into<OsString>) -> Self {
575        self.style = Some(value.into());
576        self
577    }
578
579    /// Sets border style. Requires tmux 3.4+.
580    #[must_use]
581    pub fn border_style(mut self, value: impl Into<OsString>) -> Self {
582        self.border_style = Some(value.into());
583        self
584    }
585
586    /// Sets selected-entry style. Requires tmux 3.4+.
587    #[must_use]
588    pub fn selected_style(mut self, value: impl Into<OsString>) -> Self {
589        self.selected_style = Some(value.into());
590        self
591    }
592
593    /// Enables mouse handling. Requires tmux 3.5+.
594    #[must_use]
595    pub const fn mouse(mut self, enabled: bool) -> Self {
596        self.mouse = enabled;
597        self
598    }
599
600    /// Keeps the menu open after mouse release.
601    #[must_use]
602    pub const fn stay_open(mut self, enabled: bool) -> Self {
603        self.stay_open = enabled;
604        self
605    }
606}
607
608/// Typed arguments for `display-popup`.
609#[derive(Clone, Debug, Default)]
610pub struct Popup {
611    command: Option<OsString>,
612    close_on_exit: bool,
613    close_on_success: bool,
614    close_existing: bool,
615    target_client: Option<ClientName>,
616    width: Option<OsString>,
617    height: Option<OsString>,
618    x: Option<OsString>,
619    y: Option<OsString>,
620    cwd: Option<PathBuf>,
621    title: Option<OsString>,
622    border_lines: Option<OsString>,
623    style: Option<OsString>,
624    border_style: Option<OsString>,
625    environment: BTreeMap<String, OsString>,
626    no_border: bool,
627    close_on_any_key: bool,
628    no_keys: bool,
629}
630
631impl Popup {
632    /// Creates popup arguments.
633    #[must_use]
634    pub fn new() -> Self {
635        Self::default()
636    }
637
638    /// Sets the popup shell command.
639    #[must_use]
640    pub fn command(mut self, command: impl Into<OsString>) -> Self {
641        self.command = Some(command.into());
642        self
643    }
644
645    /// Closes after any exit status.
646    #[must_use]
647    pub const fn close_on_exit(mut self, enabled: bool) -> Self {
648        self.close_on_exit = enabled;
649        self
650    }
651
652    /// Closes only after success.
653    #[must_use]
654    pub const fn close_on_success(mut self, enabled: bool) -> Self {
655        self.close_on_success = enabled;
656        self
657    }
658
659    /// Closes an existing popup.
660    #[must_use]
661    pub const fn close_existing(mut self, enabled: bool) -> Self {
662        self.close_existing = enabled;
663        self
664    }
665
666    /// Targets a client.
667    #[must_use]
668    pub fn target_client(mut self, client: ClientName) -> Self {
669        self.target_client = Some(client);
670        self
671    }
672
673    /// Sets width in cells, percent, or a tmux expression.
674    #[must_use]
675    pub fn width(mut self, value: impl Into<OsString>) -> Self {
676        self.width = Some(value.into());
677        self
678    }
679
680    /// Sets height in cells, percent, or a tmux expression.
681    #[must_use]
682    pub fn height(mut self, value: impl Into<OsString>) -> Self {
683        self.height = Some(value.into());
684        self
685    }
686
687    /// Sets x position.
688    #[must_use]
689    pub fn x(mut self, value: impl Into<OsString>) -> Self {
690        self.x = Some(value.into());
691        self
692    }
693
694    /// Sets y position.
695    #[must_use]
696    pub fn y(mut self, value: impl Into<OsString>) -> Self {
697        self.y = Some(value.into());
698        self
699    }
700
701    /// Sets the starting directory.
702    #[must_use]
703    pub fn cwd(mut self, value: impl Into<PathBuf>) -> Self {
704        self.cwd = Some(value.into());
705        self
706    }
707
708    /// Sets the title. Requires tmux 3.3+.
709    #[must_use]
710    pub fn title(mut self, value: impl Into<OsString>) -> Self {
711        self.title = Some(value.into());
712        self
713    }
714
715    /// Sets border line style. Requires tmux 3.3+.
716    #[must_use]
717    pub fn border_lines(mut self, value: impl Into<OsString>) -> Self {
718        self.border_lines = Some(value.into());
719        self
720    }
721
722    /// Sets popup style. Requires tmux 3.3+.
723    #[must_use]
724    pub fn style(mut self, value: impl Into<OsString>) -> Self {
725        self.style = Some(value.into());
726        self
727    }
728
729    /// Sets border style. Requires tmux 3.3+.
730    #[must_use]
731    pub fn border_style(mut self, value: impl Into<OsString>) -> Self {
732        self.border_style = Some(value.into());
733        self
734    }
735
736    /// Adds an environment entry. Requires tmux 3.3+.
737    pub fn environment(
738        mut self,
739        name: impl Into<String>,
740        value: impl Into<OsString>,
741    ) -> Result<Self> {
742        let name = name.into();
743        crate::server::validate_name("environment name", &name)?;
744        self.environment.insert(name, value.into());
745        Ok(self)
746    }
747
748    /// Removes the popup border. Requires tmux 3.3+.
749    #[must_use]
750    pub const fn no_border(mut self, enabled: bool) -> Self {
751        self.no_border = enabled;
752        self
753    }
754
755    /// Closes on any key after process exit. Requires tmux 3.6+.
756    #[must_use]
757    pub const fn close_on_any_key(mut self, enabled: bool) -> Self {
758        self.close_on_any_key = enabled;
759        self
760    }
761
762    /// Disables automatic close keys. Requires tmux 3.6+.
763    #[must_use]
764    pub const fn no_keys(mut self, enabled: bool) -> Self {
765        self.no_keys = enabled;
766        self
767    }
768}
769
770/// Typed arguments for the broad `display-message` flag family.
771#[derive(Clone, Debug, Default)]
772pub struct DisplayMessage {
773    message: Option<OsString>,
774    print: bool,
775    all_formats: bool,
776    verbose: bool,
777    literal: bool,
778    notify: bool,
779    client: Option<ClientName>,
780    delay_millis: Option<u32>,
781    format: Option<OsString>,
782}
783
784/// Typed arguments for conditional tmux command execution.
785#[derive(Clone, Debug)]
786pub struct IfShell {
787    condition: OsString,
788    if_command: OsString,
789    else_command: Option<OsString>,
790    background: bool,
791    format: bool,
792    target: Option<PaneId>,
793}
794
795impl IfShell {
796    /// Creates a shell condition and success command.
797    #[must_use]
798    pub fn new(condition: impl Into<OsString>, if_command: impl Into<OsString>) -> Self {
799        Self {
800            condition: condition.into(),
801            if_command: if_command.into(),
802            else_command: None,
803            background: false,
804            format: false,
805            target: None,
806        }
807    }
808
809    /// Sets the command run when the condition is false.
810    #[must_use]
811    pub fn else_command(mut self, command: impl Into<OsString>) -> Self {
812        self.else_command = Some(command.into());
813        self
814    }
815
816    /// Runs without blocking the tmux command queue.
817    #[must_use]
818    pub const fn background(mut self, enabled: bool) -> Self {
819        self.background = enabled;
820        self
821    }
822
823    /// Treats the condition as a tmux format expression.
824    #[must_use]
825    pub const fn format(mut self, enabled: bool) -> Self {
826        self.format = enabled;
827        self
828    }
829
830    /// Selects a target pane.
831    #[must_use]
832    pub const fn target(mut self, target: PaneId) -> Self {
833        self.target = Some(target);
834        self
835    }
836}
837
838impl DisplayMessage {
839    /// Creates empty display arguments.
840    #[must_use]
841    pub fn new() -> Self {
842        Self::default()
843    }
844
845    /// Sets the message or format expression.
846    #[must_use]
847    pub fn message(mut self, message: impl Into<OsString>) -> Self {
848        self.message = Some(message.into());
849        self
850    }
851
852    /// Prints expanded output rather than rendering to the status line.
853    #[must_use]
854    pub const fn print(mut self, enabled: bool) -> Self {
855        self.print = enabled;
856        self
857    }
858
859    /// Lists all format variables.
860    #[must_use]
861    pub const fn all_formats(mut self, enabled: bool) -> Self {
862        self.all_formats = enabled;
863        self
864    }
865
866    /// Includes verbose format type details.
867    #[must_use]
868    pub const fn verbose(mut self, enabled: bool) -> Self {
869        self.verbose = enabled;
870        self
871    }
872
873    /// Prevents format expansion. Requires tmux 3.4+.
874    #[must_use]
875    pub const fn literal(mut self, enabled: bool) -> Self {
876        self.literal = enabled;
877        self
878    }
879
880    /// Does not wait for input.
881    #[must_use]
882    pub const fn notify(mut self, enabled: bool) -> Self {
883        self.notify = enabled;
884        self
885    }
886
887    /// Targets a client.
888    #[must_use]
889    pub fn client(mut self, client: ClientName) -> Self {
890        self.client = Some(client);
891        self
892    }
893
894    /// Sets the status-line display duration.
895    #[must_use]
896    pub const fn delay_millis(mut self, delay: u32) -> Self {
897        self.delay_millis = Some(delay);
898        self
899    }
900
901    /// Sets an alternative output format.
902    #[must_use]
903    pub fn format(mut self, format: impl Into<OsString>) -> Self {
904        self.format = Some(format.into());
905        self
906    }
907}
908
909/// Scope for hook commands.
910#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
911pub enum HookScope {
912    /// Global hooks (`-g`).
913    Global,
914    /// Session hooks (no scope flag).
915    Session,
916    /// Window hooks (`-w`).
917    Window,
918    /// Pane hooks (`-p`).
919    Pane,
920}
921
922impl HookScope {
923    fn flag(self) -> Option<&'static str> {
924        match self {
925            Self::Global => Some("-g"),
926            Self::Session => None,
927            Self::Window => Some("-w"),
928            Self::Pane => Some("-p"),
929        }
930    }
931}
932
933impl Server {
934    /// Runs a shell or tmux command job.
935    pub async fn run_shell(&self, options: RunShell) -> Result<Option<TmuxText>> {
936        let version = self.version().await?;
937        if options.cwd.is_some() {
938            version.require("run-shell working directory", V34)?;
939        }
940        if options.show_stderr {
941            version.require("run-shell stderr forwarding", V36)?;
942        }
943        if !options.arguments.is_empty() {
944            version.require("run-shell positional arguments", V37)?;
945        }
946        let mut command = Command::new("run-shell");
947        if options.background {
948            command = command.arg("-b");
949        }
950        if let Some(delay) = options.delay {
951            command = command.arg("-d").arg(format_duration(delay));
952        }
953        if options.as_tmux_command {
954            command = command.arg("-C");
955        }
956        if let Some(target) = options.target {
957            command = command.target(target);
958        }
959        if let Some(cwd) = options.cwd {
960            command = command.arg("-c").arg(cwd);
961        }
962        if options.show_stderr {
963            command = command.arg("-E");
964        }
965        command = command
966            .sensitive_arg(options.command)
967            .args(options.arguments);
968        let result = self.checked("run shell", command).await?;
969        Ok((!options.background).then(|| result.stdout().clone()))
970    }
971
972    /// Waits, signals, locks, or unlocks a named channel.
973    pub async fn wait_for(&self, channel: &str, action: WaitAction) -> Result<()> {
974        crate::server::validate_name("wait channel", channel)?;
975        let mut command = Command::new("wait-for");
976        if let Some(flag) = action.flag() {
977            command = command.arg(flag);
978        }
979        self.checked("wait for channel", command.arg(channel))
980            .await
981            .map(|_| ())
982    }
983
984    /// Creates or replaces a key binding.
985    pub async fn bind_key(&self, binding: KeyBinding) -> Result<()> {
986        let mut command = Command::new("bind-key");
987        if binding.repeat {
988            command = command.arg("-r");
989        }
990        if binding.root {
991            command = command.arg("-n");
992        }
993        if let Some(note) = binding.note {
994            command = command.arg("-N").arg(note);
995        }
996        if let Some(table) = binding.table {
997            command = command.arg("-T").arg(table);
998        }
999        self.checked("bind key", command.arg(binding.key).arg(binding.command))
1000            .await
1001            .map(|_| ())
1002    }
1003
1004    /// Removes one or more key bindings.
1005    pub async fn unbind_key(&self, options: UnbindKey) -> Result<()> {
1006        if options.key.is_none() && !options.all {
1007            return Err(Error::InvalidArgument {
1008                argument: "unbind key",
1009                message: "a key or all=true is required".to_owned(),
1010            });
1011        }
1012        let mut command = Command::new("unbind-key");
1013        if options.all {
1014            command = command.arg("-a");
1015        }
1016        if options.quiet {
1017            command = command.arg("-q");
1018        }
1019        if let Some(table) = options.table {
1020            command = command.arg("-T").arg(table);
1021        }
1022        if let Some(key) = options.key {
1023            command = command.arg(key);
1024        }
1025        self.checked("unbind key", command).await.map(|_| ())
1026    }
1027
1028    /// Lists key bindings as byte-preserving lines.
1029    pub async fn list_keys(
1030        &self,
1031        table: Option<&str>,
1032        format: Option<&str>,
1033    ) -> Result<Vec<TmuxText>> {
1034        let mut command = Command::new("list-keys");
1035        if let Some(table) = table {
1036            command = command.arg("-T").arg(table);
1037        }
1038        if let Some(format) = format {
1039            command = command.arg("-F").arg(format);
1040        }
1041        Ok(self
1042            .checked("list keys", command)
1043            .await?
1044            .stdout_lines()
1045            .collect())
1046    }
1047
1048    /// Lists tmux commands, optionally narrowed by name.
1049    pub async fn list_commands(&self, name: Option<&str>) -> Result<Vec<TmuxText>> {
1050        let mut command = Command::new("list-commands");
1051        if let Some(name) = name {
1052            command = command.arg(name);
1053        }
1054        Ok(self
1055            .checked("list commands", command)
1056            .await?
1057            .stdout_lines()
1058            .collect())
1059    }
1060
1061    /// Locks every attached client.
1062    pub async fn lock_server(&self) -> Result<()> {
1063        self.checked("lock server", Command::new("lock-server"))
1064            .await
1065            .map(|_| ())
1066    }
1067
1068    /// Applies or lists server ACL rules. Requires tmux 3.3+.
1069    pub async fn server_access(&self, action: ServerAccess) -> Result<Option<Vec<TmuxText>>> {
1070        self.version()
1071            .await?
1072            .require("server access control", V33)?;
1073        let mut command = Command::new("server-access");
1074        let listing = matches!(action, ServerAccess::List);
1075        match action {
1076            ServerAccess::Allow { user, permission } => {
1077                command = command.arg("-a").arg(user).arg(match permission {
1078                    ClientPermission::ReadOnly => "-r",
1079                    ClientPermission::ReadWrite => "-w",
1080                });
1081            }
1082            ServerAccess::Deny { user } => {
1083                command = command.arg("-d").arg(user);
1084            }
1085            ServerAccess::List => {
1086                command = command.arg("-l");
1087            }
1088        }
1089        let result = self.checked("server access", command).await?;
1090        Ok(listing.then(|| result.stdout_lines().collect()))
1091    }
1092
1093    /// Opens a background confirmation prompt.
1094    pub async fn confirm_before(&self, options: ConfirmBefore) -> Result<()> {
1095        let version = self.version().await?;
1096        version.require("background confirmation", V33)?;
1097        if options.confirm_key.is_some() || options.default_yes {
1098            version.require("confirmation key/default", V34)?;
1099        }
1100        let mut command = Command::new("confirm-before").arg("-b");
1101        if let Some(prompt) = options.prompt {
1102            command = command.arg("-p").arg(prompt);
1103        }
1104        if let Some(key) = options.confirm_key {
1105            command = command.arg("-c").arg(key);
1106        }
1107        if options.default_yes {
1108            command = command.arg("-y");
1109        }
1110        if let Some(client) = options.target_client {
1111            command = command.arg("-t").arg(client.to_os_string());
1112        }
1113        self.checked("confirm before", command.arg(options.command))
1114            .await
1115            .map(|_| ())
1116    }
1117
1118    /// Opens a background command prompt.
1119    pub async fn command_prompt(&self, options: CommandPrompt) -> Result<()> {
1120        let version = self.version().await?;
1121        version.require("background command prompt", V33)?;
1122        if options.literal {
1123            version.require("literal prompt", V36)?;
1124        }
1125        if options.backspace_exit || options.no_freeze {
1126            version.require("prompt backspace/no-freeze flags", V37)?;
1127        }
1128        let mut command = Command::new("command-prompt").arg("-b");
1129        for (enabled, flag) in [
1130            (options.one_key, "-1"),
1131            (options.key_only, "-k"),
1132            (options.on_input_change, "-i"),
1133            (options.numeric, "-N"),
1134            (options.expand_format, "-F"),
1135            (options.literal, "-l"),
1136            (options.backspace_exit, "-e"),
1137            (options.no_freeze, "-C"),
1138        ] {
1139            if enabled {
1140                command = command.arg(flag);
1141            }
1142        }
1143        if let Some(prompt) = options.prompt {
1144            command = command.arg("-p").arg(prompt);
1145        }
1146        if let Some(inputs) = options.inputs {
1147            command = command.arg("-I").arg(inputs);
1148        }
1149        if let Some(prompt_type) = options.prompt_type {
1150            command = command.arg("-T").arg(prompt_type.as_str());
1151        }
1152        if let Some(client) = options.target_client {
1153            command = command.arg("-t").arg(client.to_os_string());
1154        }
1155        self.checked("command prompt", command.arg(options.template))
1156            .await
1157            .map(|_| ())
1158    }
1159
1160    /// Displays an attached-client menu.
1161    pub async fn display_menu(&self, options: Menu) -> Result<()> {
1162        let version = self.version().await?;
1163        if options.starting_choice.is_some()
1164            || options.border_lines.is_some()
1165            || options.style.is_some()
1166            || options.border_style.is_some()
1167            || options.selected_style.is_some()
1168        {
1169            version.require("advanced menu styling", V34)?;
1170        }
1171        if options.mouse {
1172            version.require("menu mouse mode", V35)?;
1173        }
1174        let mut command = Command::new("display-menu");
1175        push_optional(&mut command, "-T", options.title);
1176        if let Some(client) = options.target_client {
1177            command = command.arg("-c").arg(client.to_os_string());
1178        }
1179        if let Some(pane) = options.target_pane {
1180            command = command.target(pane);
1181        }
1182        push_optional(&mut command, "-x", options.x);
1183        push_optional(&mut command, "-y", options.y);
1184        push_optional(&mut command, "-C", options.starting_choice);
1185        push_optional(&mut command, "-b", options.border_lines);
1186        push_optional(&mut command, "-s", options.style);
1187        push_optional(&mut command, "-S", options.border_style);
1188        push_optional(&mut command, "-H", options.selected_style);
1189        if options.mouse {
1190            command = command.arg("-M");
1191        }
1192        if options.stay_open {
1193            command = command.arg("-O");
1194        }
1195        for item in options.items {
1196            match item {
1197                MenuItem::Entry {
1198                    label,
1199                    key,
1200                    command: item_command,
1201                } => {
1202                    command = command.arg(label).arg(key).arg(item_command);
1203                }
1204                MenuItem::Separator => {
1205                    command = command.arg("");
1206                }
1207            }
1208        }
1209        self.checked("display menu", command).await.map(|_| ())
1210    }
1211
1212    /// Runs the broad server-scoped display-message operation.
1213    pub async fn display(&self, options: DisplayMessage) -> Result<Option<TmuxText>> {
1214        if options.literal {
1215            self.version()
1216                .await?
1217                .require("literal display message", V34)?;
1218        }
1219        let print = options.print;
1220        let command = display_command(options, None);
1221        let result = self.checked("display message", command).await?;
1222        Ok(print.then(|| result.stdout().clone()))
1223    }
1224
1225    /// Starts the tmux daemon without creating a session.
1226    pub async fn start_server(&self) -> Result<()> {
1227        self.checked("start server", Command::new("start-server"))
1228            .await
1229            .map(|_| ())
1230    }
1231
1232    /// Shows server messages, terminal capabilities, or jobs.
1233    pub async fn show_messages(
1234        &self,
1235        client: Option<&ClientName>,
1236        terminals: bool,
1237        jobs: bool,
1238    ) -> Result<Vec<TmuxText>> {
1239        if terminals && jobs {
1240            return Err(Error::InvalidArgument {
1241                argument: "show-messages mode",
1242                message: "terminals and jobs are mutually exclusive".to_owned(),
1243            });
1244        }
1245        let mut command = Command::new("show-messages");
1246        if terminals {
1247            command = command.arg("-T");
1248        }
1249        if jobs {
1250            command = command.arg("-J");
1251        }
1252        if let Some(client) = client {
1253            command = command.arg("-t").arg(client.to_os_string());
1254        }
1255        Ok(self
1256            .checked("show messages", command)
1257            .await?
1258            .stdout_lines()
1259            .collect())
1260    }
1261
1262    /// Refreshes a client display and optionally requests the clipboard.
1263    pub async fn refresh_client(
1264        &self,
1265        client: Option<&ClientName>,
1266        request_clipboard: bool,
1267    ) -> Result<()> {
1268        if request_clipboard {
1269            self.version()
1270                .await?
1271                .require("client clipboard request", V37)?;
1272        }
1273        let mut command = Command::new("refresh-client");
1274        if request_clipboard {
1275            command = command.arg("-l");
1276        }
1277        if let Some(client) = client {
1278            command = command.arg("-t").arg(client.to_os_string());
1279        }
1280        self.checked("refresh client", command).await.map(|_| ())
1281    }
1282
1283    /// Sends one key to an attached client's key handling state. Requires tmux 3.4+.
1284    pub async fn send_client_key(
1285        &self,
1286        client: &ClientName,
1287        key: impl Into<OsString>,
1288    ) -> Result<()> {
1289        self.version().await?.require("client-targeted keys", V34)?;
1290        self.checked(
1291            "send client key",
1292            Command::new("send-keys")
1293                .arg("-K")
1294                .arg("-c")
1295                .arg(client.to_os_string())
1296                .arg(key),
1297        )
1298        .await
1299        .map(|_| ())
1300    }
1301
1302    /// Suspends an explicit or current client.
1303    pub async fn suspend_client(&self, client: Option<&ClientName>) -> Result<()> {
1304        let mut command = Command::new("suspend-client");
1305        if let Some(client) = client {
1306            command = command.arg("-t").arg(client.to_os_string());
1307        }
1308        self.checked("suspend client", command).await.map(|_| ())
1309    }
1310
1311    /// Locks an explicit or current client.
1312    pub async fn lock_client(&self, client: Option<&ClientName>) -> Result<()> {
1313        let mut command = Command::new("lock-client");
1314        if let Some(client) = client {
1315            command = command.arg("-t").arg(client.to_os_string());
1316        }
1317        self.checked("lock client", command).await.map(|_| ())
1318    }
1319
1320    /// Detaches an explicit or current client, optionally running a shell command afterward.
1321    pub async fn detach_client(
1322        &self,
1323        client: Option<&ClientName>,
1324        shell_command: Option<OsString>,
1325    ) -> Result<()> {
1326        let mut command = Command::new("detach-client");
1327        if let Some(shell_command) = shell_command {
1328            command = command.arg("-E").sensitive_arg(shell_command);
1329        }
1330        if let Some(client) = client {
1331            command = command.arg("-t").arg(client.to_os_string());
1332        }
1333        self.checked("detach client", command).await.map(|_| ())
1334    }
1335
1336    /// Detaches all clients except an optional retained client.
1337    pub async fn detach_all_clients(
1338        &self,
1339        keep: Option<&ClientName>,
1340        shell_command: Option<OsString>,
1341    ) -> Result<()> {
1342        let mut command = Command::new("detach-client").arg("-a");
1343        if let Some(shell_command) = shell_command {
1344            command = command.arg("-E").sensitive_arg(shell_command);
1345        }
1346        if let Some(client) = keep {
1347            command = command.arg("-t").arg(client.to_os_string());
1348        }
1349        self.checked("detach all clients", command)
1350            .await
1351            .map(|_| ())
1352    }
1353
1354    /// Executes one of two tmux commands based on a shell or format condition.
1355    pub async fn if_shell(&self, options: IfShell) -> Result<()> {
1356        let mut command = Command::new("if-shell");
1357        if options.background {
1358            command = command.arg("-b");
1359        }
1360        if options.format {
1361            command = command.arg("-F");
1362        }
1363        if let Some(target) = options.target {
1364            command = command.target(target);
1365        }
1366        command = command
1367            .sensitive_arg(options.condition)
1368            .sensitive_arg(options.if_command);
1369        if let Some(else_command) = options.else_command {
1370            command = command.sensitive_arg(else_command);
1371        }
1372        self.checked("if shell", command).await.map(|_| ())
1373    }
1374
1375    /// Shows prompt history. Requires tmux 3.3+.
1376    pub async fn prompt_history(&self, prompt_type: Option<PromptType>) -> Result<Vec<TmuxText>> {
1377        self.version().await?.require("prompt history", V33)?;
1378        let mut command = Command::new("show-prompt-history");
1379        if let Some(prompt_type) = prompt_type {
1380            command = command.arg("-T").arg(prompt_type.as_str());
1381        }
1382        Ok(self
1383            .checked("show prompt history", command)
1384            .await?
1385            .stdout_lines()
1386            .collect())
1387    }
1388
1389    /// Clears prompt history. Requires tmux 3.3+.
1390    pub async fn clear_prompt_history(&self, prompt_type: Option<PromptType>) -> Result<()> {
1391        self.version().await?.require("clear prompt history", V33)?;
1392        let mut command = Command::new("clear-prompt-history");
1393        if let Some(prompt_type) = prompt_type {
1394            command = command.arg("-T").arg(prompt_type.as_str());
1395        }
1396        self.checked("clear prompt history", command)
1397            .await
1398            .map(|_| ())
1399    }
1400
1401    /// Runs a named hook immediately.
1402    pub async fn run_hook(&self, name: &str, target: Option<&str>) -> Result<()> {
1403        crate::server::validate_name("hook name", name)?;
1404        let mut command = Command::new("run-hook");
1405        if let Some(target) = target {
1406            command = command.arg("-t").arg(target);
1407        }
1408        self.checked("run hook", command.arg(name))
1409            .await
1410            .map(|_| ())
1411    }
1412
1413    /// Sets one hook command, optionally at a sparse index.
1414    pub async fn set_hook(
1415        &self,
1416        scope: HookScope,
1417        target: Option<&str>,
1418        name: &str,
1419        index: Option<u32>,
1420        value: &OptionValue,
1421        append: bool,
1422    ) -> Result<()> {
1423        crate::server::validate_name("hook name", name)?;
1424        let mut command = Command::new("set-hook");
1425        if let Some(flag) = scope.flag() {
1426            command = command.arg(flag);
1427        }
1428        if append {
1429            command = command.arg("-a");
1430        }
1431        if let Some(target) = target {
1432            command = command.arg("-t").arg(target);
1433        }
1434        let name = index.map_or_else(|| name.to_owned(), |index| format!("{name}[{index}]"));
1435        self.checked("set hook", command.arg(name).arg(value.to_os_string()))
1436            .await
1437            .map(|_| ())
1438    }
1439
1440    /// Unsets one hook or sparse hook index.
1441    pub async fn unset_hook(
1442        &self,
1443        scope: HookScope,
1444        target: Option<&str>,
1445        name: &str,
1446        index: Option<u32>,
1447    ) -> Result<()> {
1448        crate::server::validate_name("hook name", name)?;
1449        let mut command = Command::new("set-hook").arg("-u");
1450        if let Some(flag) = scope.flag() {
1451            command = command.arg(flag);
1452        }
1453        if let Some(target) = target {
1454            command = command.arg("-t").arg(target);
1455        }
1456        let name = index.map_or_else(|| name.to_owned(), |index| format!("{name}[{index}]"));
1457        self.checked("unset hook", command.arg(name))
1458            .await
1459            .map(|_| ())
1460    }
1461
1462    /// Shows hooks as sparse option arrays.
1463    pub async fn show_hooks(
1464        &self,
1465        scope: HookScope,
1466        target: Option<&str>,
1467    ) -> Result<SparseOptionMap> {
1468        let mut command = Command::new("show-hooks");
1469        if let Some(flag) = scope.flag() {
1470            command = command.arg(flag);
1471        }
1472        if let Some(target) = target {
1473            command = command.arg("-t").arg(target);
1474        }
1475        let result = self.checked("show hooks", command).await?;
1476        SparseOptionMap::parse(result.stdout().as_bytes())
1477    }
1478}
1479
1480impl Pane {
1481    /// Displays a popup associated with this pane.
1482    pub async fn display_popup(&self, options: Popup) -> Result<()> {
1483        if options.close_on_exit && options.close_on_success {
1484            return Err(Error::InvalidArgument {
1485                argument: "popup close behavior",
1486                message: "close_on_exit and close_on_success are mutually exclusive".to_owned(),
1487            });
1488        }
1489        let version = self.server().version().await?;
1490        if options.title.is_some()
1491            || options.border_lines.is_some()
1492            || options.style.is_some()
1493            || options.border_style.is_some()
1494            || !options.environment.is_empty()
1495            || options.no_border
1496        {
1497            version.require("popup styling and environment", V33)?;
1498        }
1499        if options.close_on_any_key || options.no_keys {
1500            version.require("popup close-key flags", V36)?;
1501        }
1502        let mut command = Command::new("display-popup").target(self.id());
1503        if options.close_existing {
1504            command = command.arg("-C");
1505        }
1506        if let Some(client) = options.target_client {
1507            command = command.arg("-c").arg(client.to_os_string());
1508        }
1509        if options.close_on_exit {
1510            command = command.arg("-E");
1511        }
1512        if options.close_on_success {
1513            command = command.arg("-E").arg("-E");
1514        }
1515        push_optional(&mut command, "-w", options.width);
1516        push_optional(&mut command, "-h", options.height);
1517        push_optional(&mut command, "-x", options.x);
1518        push_optional(&mut command, "-y", options.y);
1519        if let Some(cwd) = options.cwd {
1520            command = command.arg("-d").arg(cwd);
1521        }
1522        push_optional(&mut command, "-T", options.title);
1523        push_optional(&mut command, "-b", options.border_lines);
1524        push_optional(&mut command, "-s", options.style);
1525        push_optional(&mut command, "-S", options.border_style);
1526        for (name, value) in options.environment {
1527            command =
1528                command
1529                    .arg("-e")
1530                    .sensitive_arg(format!("{}={}", name, value.to_string_lossy()));
1531        }
1532        if options.no_border {
1533            command = command.arg("-B");
1534        }
1535        if options.close_on_any_key {
1536            command = command.arg("-k");
1537        }
1538        if options.no_keys {
1539            command = command.arg("-N");
1540        }
1541        if let Some(popup_command) = options.command {
1542            command = command.sensitive_arg(popup_command);
1543        }
1544        self.server()
1545            .checked("display popup", command)
1546            .await
1547            .map(|_| ())
1548    }
1549
1550    /// Displays or evaluates a message in this pane's context.
1551    pub async fn display(&self, options: DisplayMessage) -> Result<Option<TmuxText>> {
1552        if options.literal {
1553            self.server()
1554                .version()
1555                .await?
1556                .require("literal display message", V34)?;
1557        }
1558        let print = options.print;
1559        let command = display_command(options, Some(self.id().to_string()));
1560        let result = self
1561            .server()
1562            .checked("display pane message", command)
1563            .await?;
1564        Ok(print.then(|| result.stdout().clone()))
1565    }
1566}
1567
1568impl Window {
1569    /// Displays or evaluates a message in this window's context.
1570    pub async fn display(&self, options: DisplayMessage) -> Result<Option<TmuxText>> {
1571        if options.literal {
1572            self.server()
1573                .version()
1574                .await?
1575                .require("literal display message", V34)?;
1576        }
1577        let print = options.print;
1578        let command = display_command(options, Some(self.id().to_string()));
1579        let result = self
1580            .server()
1581            .checked("display window message", command)
1582            .await?;
1583        Ok(print.then(|| result.stdout().clone()))
1584    }
1585}
1586
1587fn display_command(options: DisplayMessage, target: Option<String>) -> Command {
1588    let mut command = Command::new("display-message");
1589    for (enabled, flag) in [
1590        (options.print, "-p"),
1591        (options.all_formats, "-a"),
1592        (options.verbose, "-v"),
1593        (options.literal, "-l"),
1594        (options.notify, "-N"),
1595    ] {
1596        if enabled {
1597            command = command.arg(flag);
1598        }
1599    }
1600    if let Some(client) = options.client {
1601        command = command.arg("-c").arg(client.to_os_string());
1602    }
1603    if let Some(target) = target {
1604        command = command.arg("-t").arg(target);
1605    }
1606    if let Some(delay) = options.delay_millis {
1607        command = command.arg("-d").arg(delay.to_string());
1608    }
1609    push_optional(&mut command, "-F", options.format);
1610    if let Some(message) = options.message {
1611        command = command.arg(message);
1612    }
1613    command
1614}
1615
1616fn push_optional(command: &mut Command, flag: &'static str, value: Option<OsString>) {
1617    if let Some(value) = value {
1618        *command = command.clone().arg(flag).arg(value);
1619    }
1620}
1621
1622fn format_duration(duration: Duration) -> String {
1623    let seconds = duration.as_secs_f64();
1624    format!("{seconds:.6}")
1625        .trim_end_matches('0')
1626        .trim_end_matches('.')
1627        .to_owned()
1628}