OptionValue
One option's value, typed by what tmux's own option table declares.
Source and package
- Qualified name
-
libtmux::options:: Option Value - Module
- options
- Package
- libtmux
- Source
- crates/libtmux/src/options.rs
-
Description#
Every handle reads and writes options the same way:
To Call read one value typed_option, and onServeralsotyped_global_option()andtyped_global_window_option()read every value set at one scope optionslist the names set at one scope option_nameswrite a value checked against the table set_typed_option, and onServeralsoset_typed_global_option()andset_typed_global_window_option()write text unchecked set_option,append_option, and onServerset_global_option(),set_global_window_option(), and the array writesReads decode by declared kind: a flag arrives as
Self::Flag, a number asSelf::Number, and everything else asSelf::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::OptionValueRefusedand leave the option unchanged.statusreadsonand is a choice, not a flag, so it takes"on", nottrue.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 --trueason,3as3-- and reads back asSelf::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_optionsends 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?; - A user option, whose name begins with