options.OptionValue

enum options.OptionValue

enumoverload [source] ¶

enumoverload [source] ¶

enum options.OptionValue

One option's value, typed by what tmux's own option table declares.

Every handle reads and writes options the same way:

| To | Call | | --- | --- | | read one value | typed_option, and on Server also typed_global_option and typed_global_window_option | | read every value set at one scope | options | | list the names set at one scope | option_names | | write a value checked against the table | set_typed_option, and on Server also set_typed_global_option and set_typed_global_window_option | | write text unchecked | set_option, append_option, and on Server set_global_option , set_global_window_option , and the array writes |

Reads decode by declared kind: a flag arrives as Self::Flag , a number as Self::Number , and everything else as Self::Text . Nothing is lost in decoding: TmuxText::from(value) gives back the bytes tmux stored.

A typed write takes the variant a read returns, and checks it against the table before anything is sent. The wrong variant, a word outside a choice's set, and a number outside its range each fail with Error::OptionValueRefused and leave the option unchanged. status reads on and is a choice, not a flag, so it takes "on", not true.

Two writes are not checked, because there is nothing to check against:

• A user option, whose name begins with @. tmux keeps no type for one, so the value is stored as the text a read would show for it -- true as on, 3 as 3 -- and reads back as Self::Text .
• A name the table does not declare. It is sent as written, and tmux answers for it.

Appending and the array writes have no typed form: tmux appends to text, and every array option holds text or commands.

The table is generated from the newest tmux release this crate supports. An older release refuses what it lacks on its own. A newer one may accept a word the table does not list; set_option sends that unchecked.

Examples

use libtmux::{Error, OptionValue, OptionValueRefusal};

let guard = libtmux::test::TestServer::new().await?;
let server = guard.server();
server.new_session("typed").await?;

// `mouse` is a flag, so it is written and read back as one.
server.set_typed_global_option("mouse", true).await?;
assert_eq!(server.typed_global_option("mouse").await?, Some(OptionValue::Flag(true)));

// `status` also reads `on`, and is *not* a flag: tmux accepts `on`, `off`,
// and `2` through `5`. Inferring the type from the value would call this a
// boolean and then fail on a value that is not one, which is why the
// schema is generated from tmux's own option table instead.
let status = server.typed_global_option("status").await?.expect("status is set");
assert!(matches!(status, OptionValue::Text(_)));

// A word tmux's table does not list for a choice is refused unsent.
let refused = server
    .set_typed_global_option("status-position", "sideways")
    .await
    .expect_err("not a position tmux has");
assert!(matches!(
    refused,
    Error::OptionValueRefused { reason: OptionValueRefusal::NotAChoice { .. }, .. },
));

guard.shutdown().await?;

Members

• Flag constant A flag tmux wrote as on or off.
• Number constant A number.
• Text constant Text, which covers choices, colours, keys, commands, and user options.