tmux_interface/options/mod.rs
1// doc note parts/modules commands builders and parsers
2//
3//!
4//! Command builders and output parsers
5//!
6//! # Table Of Contents
7//! * 1. Quick Start
8//! * 2. Developer Information
9//! * 2.1. Tmux Manual
10//! * 2.2. Structure
11//! * 2.3. Implementation
12//! * 2.4. Modules Hierarchy
13//!
14//! # 1. Quick Start
15//!
16//! ## Examples
17//!
18//!
19//! # 2. Developer Information
20//!
21//! ## 2.1. Tmux Manual
22//!
23//! Get command
24//! ```text
25//! show-options [-AgHpqsvw] [-t target-pane] [option]
26//! (alias: show)
27//! Show the pane options (or a single option if option is
28//! provided) with -p, the window options with -w, the server
29//! options with -s, otherwise the session options. If the
30//! option is not a user option, -w or -s may be unnecessary -
31//! tmux will infer the type from the option name, assuming -w
32//! for pane options. Global session or window options are
33//! listed if -g is used. -v shows only the option value, not
34//! the name. If -q is set, no error will be returned if
35//! option is unset. -H includes hooks (omitted by default).
36//! -A includes options inherited from a parent set of options,
37//! such options are marked with an asterisk.
38//! ```
39//!
40//! Set command
41//! ```text
42//! set-option [-aFgopqsuUw] [-t target-pane] option value
43//! (alias: set)
44//! Set a pane option with -p, a window option with -w, a
45//! server option with -s, otherwise a session option. If the
46//! option is not a user option, -w or -s may be unnecessary -
47//! tmux will infer the type from the option name, assuming -w
48//! for pane options. If -g is given, the global session or
49//! window option is set.
50//!
51//! -F expands formats in the option value. The -u flag unsets
52//! an option, so a session inherits the option from the global
53//! options (or with -g, restores a global option to the
54//! default). -U unsets an option (like -u) but if the option
55//! is a pane option also unsets the option on any panes in the
56//! window. value depends on the option and may be a number, a
57//! string, or a flag (on, off, or omitted to toggle).
58//!
59//! The -o flag prevents setting an option that is already set
60//! and the -q flag suppresses errors about unknown or
61//! ambiguous options.
62//!
63//! With -a, and if the option expects a string or a style,
64//! value is appended to the existing setting. For example:
65//!
66//! set -g status-left "foo"
67//! set -ag status-left "bar"
68//!
69//! Will result in ‘foobar’. And:
70//!
71//! set -g status-style "bg=red"
72//! set -ag status-style "fg=blue"
73//!
74//! Will result in a red background and blue foreground.
75//! Without -a, the result would be the default background and
76//! a blue foreground.
77//! ```
78//!
79//! # 2.2. Structure
80//!
81//! Briefly, abstractions for working procedures with Tmux options can be done using following principles:
82//!
83//! * by [Scope](#scope) (`-g` flag)
84//! * Global (`-g` flag)
85//! * Local (`` flag omitted)
86//!
87//! * by access type (`[option]` parameter)
88//! * All (`[option]` parameter omitted)
89//! * Value only (`-v` flag)
90//! * Single (`[option]` parameter)
91//! * Multiple Selective (multiple `show-options`, `set-option` commands)
92//!
93//! * by object type (`-s`, ` `, `-w`, `-p` flags)
94//! * [`Server`](self::server) (`-s` flag)
95//! * [`Session`](self::session) (` ` flag omitted)
96//! * [`Window`](self::window) (`-w` flag)
97//! * [`Pane`](self::pane) (`-p` flag)
98//!
99//! * by modifiying methods (`[value]` parameter and `-u` flag)
100//! * Set (`[value]` parameter is set)
101//! * Unset (`-u` flag)
102//! * Toggle (for `on | off | ...` options) (`[value] parameter omitted`)
103//!
104//! **Table**: Tmux Options
105//! <table>
106//! <thead>
107//! <tr>
108//! <th>Tmux Options</th>
109//! <th colspan="2">Scope</th>
110//! </tr>
111//! </thead>
112//! <tbody>
113//! <tr>
114//! <td></td>
115//! <td>Global (`show/set -g`)</td>
116//! <td>Local</td>
117//! </tr>
118//! <tr>
119//! <td>ServerOptions</td>
120//! <td></td>
121//! <td>x (`show/set -s`)</td>
122//! </tr>
123//! <tr>
124//! <td>SessionOptions</td>
125//! <td>x (`show/set -g`) </td>
126//! <td>x (`show/set`)</td>
127//! </tr>
128//! <tr>
129//! <td>WindowOptions</td>
130//! <td>x (`show/set -wg`)</td>
131//! <td>x (`show/set -w`)</td>
132//! </tr>
133//! <tr>
134//! <td>PaneOptions</td>
135//! <td></td>
136//! <td>x (`show/set -p`)</td>
137//! </tr>
138//! </tbody>
139//! </table>
140//!
141//! # 2.3. XXX
142//!
143//! XXX: examples
144//!
145//! # 2.3. Control
146//!
147//! * [`ServerOptionsCtl`]
148//! * [`SessionOptionsCtl`]
149//! * [`GlobalSessionOptionsCtl`]
150//! * [`LocalSessionOptionsCtl`]
151//! * [`WindowOptionsCtl`]
152//! * [`GlobalWindowOptionsCtl`]
153//! * [`LocalWindowOptionsCtl`]
154//! * [`PaneOptionsCtl`]
155//!
156//! # 2.3. Implementation
157//!
158//! implementations derived using previous prinnciples
159//!
160//! * Common
161//! * [`UserOptions`](self::common::user_option)
162//! * [`GetUserOption`] getter method for user option (`@user-option-name value`)
163//! * [`GetUserOptions`] getter method for user options (`@user-option-name value`)
164//! * [`SetUserOption`] setter method for user option (`@user-option-name value`)
165//! * [`SetUserOptions`] setter method for user options (`@user-option-name value`)
166//! * [`GetOptionTr`] common getter method for all options
167//! * [`SetOptionTr`] common setter method for all options
168//! * [`Server`](self::server)
169//! * [`GetServerOption`]
170//! * [`GetServerOptionValue`]
171//! * [`SetServerOption`]
172//! * [`Ctl`](self::server::ctl)
173//! * [`Session`](self::session)
174//! * [`Builder`](self::session::builder)
175//! * [`global`]
176//! * [`GetGlobalSessionOption`]
177//! * [`GetGlobalSessionOptionValue`]
178//! * [`SetGlobalSessionOption`]
179//! * [`local`](self::session::builder::local)
180//! * [`GetLocalSessionOption`]
181//! * [`GetLocalSessionOptionValue`]
182//! * [`SetLocalSessionOption`]
183//! * [`Ctl`](self::session::ctl)
184//! * [`SessionOptionsCtl`](self::session::ctl::session_options_ctl)
185//! * [`GlobalSessionOptionsCtl`](self::session::ctl::global_session_options_ctl)
186//! * [`LocalSessionOptionsCtl`](self::session::ctl::local_session_options_ctl)
187//! * [`Window`](self::window)
188//! * [`Builder`](self::window::builder)
189//! * [`global`](self::window::builder::global)
190//! * [`GetGlobalWindowOption`]
191//! * [`GetGlobalWindowOptionValue`]
192//! * [`SetGlobalWindowOption`]
193//! * [`local`](self::window::builder::local)
194//! * [`GetLocalWindowOption`]
195//! * [`GetLocalWindowOptionValue`]
196//! * [`SetLocalWindowOption`]
197//! * [`Ctl`](self::window::ctl)
198//! * [`WindowOptionsCtl`](self::window::ctl::window_options_ctl)
199//! * [`LocalWindowOptionsCtl`](self::window::ctl::local_window_options_ctl)
200//! * [`GlobalWindowOptionsCtl`](self::window::ctl::global_window_options_ctl)
201//! * [`Pane`](self::pane)
202//! * [`GetPaneOption`]
203//! * [`GetPaneOptionValue`]
204//! * [`SetPaneOption`]
205//! * [`Ctl`](self::pane::ctl)
206//!
207//!
208//! ## 2.4. Modules Hierarchy
209//!
210//! Options submodules, traits and structures schematic hierarchy
211//! ```text
212//! Get/Set options control traits
213//! Global
214//! +-------------------------+ +------------------------+
215//! | GlobalSessionOptionsCtl | | GlobalWindowOptionsCtl |
216//! +-------------------------+ +------------------------+
217//! * .get_<OPTION>() ...
218//! * .set_<OPTION>()
219//! * ...
220//! * .get_all()
221//! * .set_all()
222//! Local
223//! +------------------------+ +-----------------------+
224//! | LocalSessionOptionsCtl | | LocalWindowOptionsCtl |
225//! +------------------------+ +-----------------------+
226//! ... ...
227//!
228//! +------------------+ +-------------------+ +------------------+ +----------------+
229//! | ServerOptionsCtl | | SessionOptionsCtl | | WindowOptionsCtl | | PaneOptionsCtl |
230//! +------------------+ +-------------------+ +------------------+ +----------------+
231//! ... ... ... ...
232//!
233//! Get/Set options command builder traits (by target, by scope, by access)
234//!
235//! Global
236//! single option
237//! +------------------------+ +-----------------------+
238//! | GetGlobalSessionOption | | GetGlobalWindowOption |
239//! +------------------------+ +-----------------------+
240//! ... ...
241//! single value only
242//! +-----------------------------+ +----------------------------+
243//! | GetGlobalSessionOptionValue | | GetGlobalWindowOptionValue |
244//! +-----------------------------+ +----------------------------+
245//! ... ...
246//! multiple options
247//! +-------------------------+ +------------------------+
248//! | GetGlobalSessionOptions | | GetGlobalWindowOptions |
249//! +-------------------------+ +------------------------+
250//! ... ...
251//! single option
252//! +------------------------+ +-----------------------+
253//! | SetGlobalSessionOption | | SetGlobalWindowOption |
254//! +------------------------+ +-----------------------+
255//! ... ...
256//! multiple options
257//! +-------------------------+ +------------------------+
258//! | SetGlobalSessionOptions | | SetGlobalWindowOptions |
259//! +-------------------------+ +------------------------+
260//! ... ...
261//! Local
262//! single option
263//! +----------------+ +-----------------------+ +----------------------+ +---------------+
264//! | GetServerOpton | | GetLocalSessionOption | | GetLocalWindowOption | | GetPaneOption |
265//! +----------------+ +-----------------------+ +----------------------+ +---------------+
266//! ... ... ... ...
267//! single value only
268//! +---------------------+ +----------------------------+ +---------------------------+ +--------------------+
269//! | GetServerOptonValue | | GetLocalSessionOptionValue | | GetLocalWindowOptionValue | | GetPaneOptionValue |
270//! +---------------------+ +----------------------------+ +---------------------------+ +--------------------+
271//! ... ... ... ...
272//! multiple options
273//! +-----------------+ +------------------------+ +-----------------------+ +----------------+
274//! | GetServerOptons | | GetLocalSessionOptions | | GetLocalWindowOptions | | GetPaneOptions |
275//! +-----------------+ +------------------------+ +-----------------------+ +----------------+
276//! ... ... ... ...
277//! single option
278//! +----------------+ +-----------------------+ +----------------------+ +---------------+
279//! | SetServerOpton | | SetLocalSessionOption | | SetLocalWindowOption | | SetPaneOption |
280//! +----------------+ +-----------------------+ +----------------------+ +---------------+
281//! ... ... ... ...
282//! multiple options
283//! +-----------------+ +------------------------+ +-----------------------+ +----------------+
284//! | SetServerOptons | | SetLocalSessionOptions | | SetLocalWindowOptions | | SetPaneOptions |
285//! +-----------------+ +------------------------+ +-----------------------+ +----------------+
286//! ... ... ... ...
287//! Options Structures
288//! +---------------+ +----------------+ +---------------+ +-------------+
289//! | ServerOptions | | SessionOptions | | WindowOptions | | PaneOptions |
290//! +---------------+ +----------------+ +---------------+ +-------------+
291//! ... ... ... ...
292//! Get/Set user options command builder traits (custom get/set implementations for user options `@name value`)
293//! +---------------+ +---------------+
294//! | GetUserOption | | SetUserOption |
295//! +---------------+ +---------------+
296//! ... ...
297//! +----------------+ +----------------+
298//! | GetUserOptions | | SetUserOptions |
299//! +----------------+ +----------------+
300//! ... ...
301//! Get/Set options command builder traits (custom get/set implementations for server/session/window/pane)
302//! +-------------+ +-------------+
303//! | GetOptionTr | | SetOptionTr |
304//! +-------------+ +-------------+
305//! ... ...
306//!
307//! Get/Set options commands builder structures (named methods for server/session/window/pane and other)
308//! +------------+ +-----------+
309//! | ShowOption | | SetOption |
310//! +------------+ +-----------+
311//! ... ...
312//!
313//! Tmux interface command structures (command, flags, options, parameters)
314//! +-------------+
315//! | TmuxCommand |
316//! +-------------+
317//! ...
318//! +--------------+
319//! | TmuxCommands |
320//! +--------------+
321//! ...
322//! Tmux command (resulting command as `std::process::Command` or `String`)
323//! +--------------------------+ +---------------------------------+
324//! | `show [-FLAGS] <OPTION>` | | `set [-FLAGS] <OPTION> <VALUE>` |
325//! +--------------------------+ +---------------------------------+
326//! ```
327//
328// Tmux boundary conditions
329//
330// * Tmux Option:
331// * Server Options (`-s`)
332// > server options which do not apply to any particular window or session or pane
333// * absolute (no global/local differentiation)
334// * get
335// * single
336// * name value
337// * value
338// * all
339// * name value
340// * value
341// * set
342// * toggle (on/off {default}/off) if no value specified
343// * Session Options (otherwise ``)
344// > Sessions which do not have a particular option configured inherit the value from the global session options
345// * local (``)
346// * get
347// * single
348// * name value
349// * value
350// * all
351// * name value
352// * value
353// * set
354// * name value
355// * global (`-g`)
356// * get
357// * single
358// * name value
359// * value
360// * all
361// * name value
362// * value
363// * set
364// * name value
365// * Window Options (`-w`)
366// > There is also a set of global window options from which any unset window or pane options are inherited
367// * local (``)
368// * get
369// * single
370// * name value
371// * value
372// * all
373// * name value
374// * value
375// * set
376// * name value
377// * global (`-g`)
378// * get
379// * single
380// * name value
381// * value
382// * all
383// * name value
384// * value
385// * set
386// * name value
387// * Pane Options (`-p`)
388// > Pane options inherit from window options
389// * absolute (no global/local differentiation)
390// * get
391// * single
392// * name value
393// * value
394// * all
395// * name value
396// * value
397// * set
398// * name value
399//
400// * User Option (`@name`)
401//
402// Get:
403// * inherited from parent (`*`)
404//
405// Set:
406// * single one with name and value
407//
408// 1. need subclassing global / local options -> custom Deref trait
409// 2. need user methods abstraction (so user can't access options of wrong object) -> newtype wrapper type
410// 3. need builder / parser for single option
411// mb separated crate later, and tmux_commands as underlying layer
412//
413pub mod common;
414pub mod get_option_tr;
415pub mod set_option_tr;
416
417pub use common::*;
418
419pub use get_option_tr::GetOptionTr;
420pub use set_option_tr::SetOptionTr;
421
422#[cfg(feature = "tmux_3_1")]
423pub mod pane;
424#[cfg(feature = "tmux_1_2")]
425pub mod server;
426#[cfg(feature = "tmux_1_0")]
427pub mod session;
428#[cfg(feature = "tmux_1_2")]
429pub mod window;
430
431#[cfg(feature = "tmux_3_1")]
432pub use pane::*;
433#[cfg(feature = "tmux_1_2")]
434pub use server::*;
435#[cfg(feature = "tmux_1_0")]
436pub use session::*;
437#[cfg(feature = "tmux_1_2")]
438pub use window::*;
439
440#[cfg(test)]
441#[path = "."]
442mod options_tests {
443 pub mod get_option_tr_tests;
444
445 pub mod set_option_tr_tests;
446}