# options.OptionValue

- **Module:** options
- **Package:** libtmux
- **Language:** Rust
- **Kind:** enum
- **Source:** https://github.com/libtmux/libtmux-rs/blob/f0e37052c232636b61d095817046e6bfc8f2ca40/crates/libtmux/src/options.rs#L458
- **Page:** https://libtmux.org/en/rs/latest/reference/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`](crate::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.

## Example

```rust
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.