tomlmenu

https://docs.rs/tomlmenu/0.1.0/tomlmenu/
Admin
tomlmenu is a reusable ratatui-driven menuconfig TUI library for editing TOML configuration files in...
Tokens:8,177
Snippets:112
Trust Score:9.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Box write example

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Demonstrates writing a value into a box.

```rust
// reuse the box for a second value
let c = Box::write(uninit, 6);
assert_eq!(*c, 6);
```

--------------------------------

### Box Creation Example

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Demonstrates creating a boxed value from a standard variable.

```rust
let x = 5;
let boxed = Box::new(5);

assert_eq!(Box::from(x), boxed);
```

--------------------------------

### Box::from_raw Examples

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Demonstrates constructing a Box from raw pointers, either from a previous into_raw call or via manual allocation.

```rust
let x = Box::new(5);
let ptr = Box::into_raw(x);
let x = unsafe { Box::from_raw(ptr) };
```

```rust
use std::alloc::{alloc, Layout};

unsafe {
    let ptr = alloc(Layout::new::<i32>()) as *mut i32;
    // In general .write is required to avoid attempting to destruct
    // the (uninitialized) previous contents of `ptr`, though for this
    // simple example `*ptr = 5` would have worked as well.
    ptr.write(5);
    let x = Box::from_raw(ptr);
}
```

--------------------------------

### App::run

Source: https://docs.rs/tomlmenu

Starts the TUI application lifecycle and returns the exit reason and the modified document.

```APIDOC
## App::run

### Description
Executes the TUI loop. Returns an ExitReason and the Document state upon completion.

### Signature
`App::run(&mut self) -> (ExitReason, Document)`
```

--------------------------------

### Box::into_non_null usage examples

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Demonstrates converting a Box to a NonNull pointer using the nightly-only API, with examples for cleanup.

```rust
#![feature(box_vec_non_null)]

let x = Box::new(String::from("Hello"));
let non_null = Box::into_non_null(x);
let x = unsafe { Box::from_non_null(non_null) };
```

```rust
#![feature(box_vec_non_null)]

use std::alloc::{dealloc, Layout};

let x = Box::new(String::from("Hello"));
let non_null = Box::into_non_null(x);
unsafe {
    non_null.drop_in_place();
    dealloc(non_null.as_ptr().cast::<u8>(), Layout::new::<String>());
}
```

```rust
#![feature(box_vec_non_null)]

let x = Box::new(String::from("Hello"));
let non_null = Box::into_non_null(x);
unsafe {
    drop(Box::from_non_null(non_null));
}
```

--------------------------------

### Demonstrating ambiguous From implementation

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Example of a discouraged From implementation that causes ambiguity with Pin::from.

```rust
struct Foo; // A type defined in this crate.
impl From<Box<()>> for Pin<Foo> {
    fn from(_: Box<()>) -> Pin<Foo> {
        Pin::new(Foo)
    }
}
```

--------------------------------

### Cloning from reference with allocator

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Examples for cloning a value into a box using a specific allocator, requiring nightly features.

```rust
#![feature(clone_from_ref)]
#![feature(allocator_api)]

use std::alloc::System;

let hello: Box<str, System> = Box::clone_from_ref_in("hello", System);
```

```rust
#![feature(clone_from_ref)]
#![feature(allocator_api)]

use std::alloc::System;

let hello: Box<str, System> = Box::try_clone_from_ref_in("hello", System)?;
```

--------------------------------

### Box::into_raw usage examples

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Demonstrates converting a Box to a raw pointer and performing cleanup via Box::from_raw, manual deallocation, or dropping.

```rust
let x = Box::new(String::from("Hello"));
let ptr = Box::into_raw(x);
let x = unsafe { Box::from_raw(ptr) };
```

```rust
use std::alloc::{dealloc, Layout};
use std::ptr;

let x = Box::new(String::from("Hello"));
let ptr = Box::into_raw(x);
unsafe {
    ptr::drop_in_place(ptr);
    dealloc(ptr as *mut u8, Layout::new::<String>());
}
```

```rust
let x = Box::new(String::from("Hello"));
let ptr = Box::into_raw(x);
unsafe {
    drop(Box::from_raw(ptr));
}
```

--------------------------------

### Box::from_non_null Examples

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Demonstrates constructing a Box from NonNull pointers, requiring the box_vec_non_null feature.

```rust
#![feature(box_vec_non_null)]

let x = Box::new(5);
let non_null = Box::into_non_null(x);
let x = unsafe { Box::from_non_null(non_null) };
```

```rust
#![feature(box_vec_non_null)]

use std::alloc::{alloc, Layout};
use std::ptr::NonNull;

unsafe {
    let non_null = NonNull::new(alloc(Layout::new::<i32>()).cast::<i32>())
        .expect("allocation failed");
    // In general .write is required to avoid attempting to destruct
    // the (uninitialized) previous contents of `non_null`.
    non_null.write(5);
    let x = Box::from_non_null(non_null);
}
```

--------------------------------

### Box::into_raw_with_allocator usage

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Demonstrates consuming a Box into a raw pointer and allocator, with examples for both automatic and manual memory cleanup.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let x = Box::new_in(String::from("Hello"), System);
let (ptr, alloc) = Box::into_raw_with_allocator(x);
let x = unsafe { Box::from_raw_in(ptr, alloc) };
```

```rust
#![feature(allocator_api)]

use std::alloc::{Allocator, Layout, System};
use std::ptr::{self, NonNull};

let x = Box::new_in(String::from("Hello"), System);
let (ptr, alloc) = Box::into_raw_with_allocator(x);
unsafe {
    ptr::drop_in_place(ptr);
    let non_null = NonNull::new_unchecked(ptr);
    alloc.deallocate(non_null.cast(), Layout::new::<String>());
}
```

--------------------------------

### Box::into_non_null_with_allocator usage

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Demonstrates consuming a Box into a NonNull pointer and allocator, with examples for both automatic and manual memory cleanup.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let x = Box::new_in(String::from("Hello"), System);
let (non_null, alloc) = Box::into_non_null_with_allocator(x);
let x = unsafe { Box::from_non_null_in(non_null, alloc) };
```

```rust
#![feature(allocator_api)]

use std::alloc::{Allocator, Layout, System};

let x = Box::new_in(String::from("Hello"), System);
let (non_null, alloc) = Box::into_non_null_with_allocator(x);
unsafe {
    non_null.drop_in_place();
    alloc.deallocate(non_null.cast::<u8>(), Layout::new::<String>());
}
```

--------------------------------

### pub fn require_tty() -> Result<()>

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/fn.require_tty.html

Refuses to start the TUI when stdio is not interactive. Returns an Err, allowing the caller to surface a clear stderr line and exit with code 2.

```APIDOC
## require_tty

### Description
Refuses to start the TUI when stdio is not interactive. Returns an Err, allowing the caller to surface a clear stderr line and exit with code 2.

### Signature
`pub fn require_tty() -> Result<()>`
```

--------------------------------

### App::new

Source: https://docs.rs/tomlmenu

Initializes the top-level menuconfig application with a schema, document, and shadowed state.

```APIDOC
## App::new

### Description
Creates a new instance of the menuconfig application.

### Signature
`App::new(schema: T, document: Document, shadowed: bool) -> App`
```

--------------------------------

### App::new

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/struct.App.html

Constructs a new instance of the App without entering the TUI.

```APIDOC
## pub fn new(schema: &'static MenuNode, document: Document, shadowed: &'static [&'static str]) -> Self

### Description
Constructs a new application instance. This method prepares the application with the provided schema, document, and shadowed keys without starting the TUI.

### Parameters
- **schema** (&'static MenuNode) - Required - The static schema for the menu.
- **document** (Document) - Required - The document representing the on-disk file.
- **shadowed** (&'static [&'static str]) - Required - A slice of dotted keys currently shadowed by external state.
```

--------------------------------

### Basic Box Pinning

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Demonstrates the basic syntax for creating a pinned box.

```rust
let foo = Box::new(());
let bar = Pin::from(foo);
```

--------------------------------

### install_panic_hook

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/fn.install_panic_hook.html

Registers a custom panic hook to execute specific restore actions upon a panic event.

```APIDOC
## install_panic_hook

### Description
Installs a panic hook that invokes each `RestoreAction` in order before re-invoking the previous hook. This function replaces any list of actions previously registered with this function.

### Signature
`pub fn install_panic_hook(actions: Vec<RestoreAction>)`

### Parameters
- **actions** (Vec<RestoreAction>) - Required - A list of restore actions to be executed when a panic occurs.
```

--------------------------------

### Box::try_new_uninit_in

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Constructs a new box with uninitialized contents, returning an error if allocation fails.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let mut five = Box::<u32, _>::try_new_uninit_in(System)?;
// Deferred initialization:
five.write(5);
let five = unsafe { five.assume_init() };

assert_eq!(*five, 5);
```

--------------------------------

### Box::new_uninit

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Constructs a new box with uninitialized contents.

```rust
let mut five = Box::<u32>::new_uninit();
// Deferred initialization:
five.write(5);
let five = unsafe { five.assume_init() };

assert_eq!(*five, 5)
```

--------------------------------

### App::run

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/struct.App.html

Enters the TUI and runs the application until the user exits.

```APIDOC
## pub fn run(self) -> Result<(ExitReason, Document)>

### Description
Starts the TUI and runs the application until the user exits. This method consumes the App instance and returns the exit verdict along with the potentially mutated document.

### Returns
- **Result<(ExitReason, Document)>** - Returns the exit reason and the updated document upon successful completion.
```

--------------------------------

### Box::from_raw_in

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Constructs a box from a raw pointer in the given allocator. This is an unsafe, nightly-only experimental API.

```APIDOC
## pub unsafe fn from_raw_in(raw: *mut T, alloc: A) -> Box<T, A>

### Description
Constructs a box from a raw pointer in the given allocator. After calling this function, the raw pointer is owned by the resulting Box, which will handle memory deallocation and destructor calls.

### Safety
This function is unsafe because improper use may lead to memory problems such as double-frees. The raw pointer must point to a block of memory allocated by the provided allocator.
```

--------------------------------

### Manually create Box from raw pointer

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Allocates memory manually and initializes a Box using the system allocator.

```rust
#![feature(allocator_api, slice_ptr_get)]

use std::alloc::{Allocator, Layout, System};

unsafe {
    let ptr = System.allocate(Layout::new::<i32>())?.as_mut_ptr() as *mut i32;
    // In general .write is required to avoid attempting to destruct
    // the (uninitialized) previous contents of `ptr`, though for this
    // simple example `*ptr = 5` would have worked as well.
    ptr.write(5);
    let x = Box::from_raw_in(ptr, System);
}
```

--------------------------------

### Box::new

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Allocates memory on the heap and places a value into it.

```rust
let five = Box::new(5);
```

--------------------------------

### Box::new_uninit_in

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Constructs a new box with uninitialized contents in the provided allocator.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let mut five = Box::<u32, _>::new_uninit_in(System);
// Deferred initialization:
five.write(5);
let five = unsafe { five.assume_init() };

assert_eq!(*five, 5)
```

--------------------------------

### Document::load

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/struct.Document.html

Loads a TOML document from the specified path. If the file is missing, an empty document is returned.

```APIDOC
## pub fn load(path: &Path) -> Result<Self>

### Description
Load `path` into a `DocumentMut`. A missing file is non-fatal: an empty document is returned so the TUI opens cleanly and a subsequent save creates the file.
```

--------------------------------

### Clone Box contents

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Demonstrates cloning a Box and verifying that the new instance is a unique object with the same value.

```rust
let x = Box::new(5);
let y = x.clone();

// The value is the same
assert_eq!(x, y);

// But they are unique objects
assert_ne!(&*x as *const i32, &*y as *const i32);
```

--------------------------------

### Box::clone_from_ref

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Experimental API to allocate memory on the heap and clone a reference into it.

```rust
#![feature(clone_from_ref)]

let hello: Box<str> = Box::clone_from_ref("hello");
```

--------------------------------

### Box::try_new_uninit

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Experimental API to construct a new box with uninitialized contents on the heap, returning an error if allocation fails.

```rust
#![feature(allocator_api)]

let mut five = Box::<u32>::try_new_uninit()?;
// Deferred initialization:
five.write(5);
let five = unsafe { five.assume_init() };

assert_eq!(*five, 5);
```

--------------------------------

### Using experimental as_non_null

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Requires the box_as_non_null feature gate. Shows how to obtain a NonNull pointer to Box contents.

```rust
#![feature(box_as_non_null)]

unsafe {
    let mut b = Box::new(0);
    let ptr1 = Box::as_non_null(&mut b);
    ptr1.write(1);
    let ptr2 = Box::as_non_null(&mut b);
    ptr2.write(2);
    // Notably, the write to `ptr2` did *not* invalidate `ptr1`:
    ptr1.write(3);
}
```

--------------------------------

### Box::from_non_null_in

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Constructs a box from a NonNull pointer in the given allocator. This is an unsafe, nightly-only experimental API.

```APIDOC
## pub unsafe fn from_non_null_in(raw: NonNull<T>, alloc: A) -> Box<T, A>

### Description
Constructs a box from a NonNull pointer in the given allocator. The Box takes ownership of the pointer and manages its lifecycle.

### Safety
This function is unsafe because improper use may lead to memory problems. The non-null pointer must point to a block of memory allocated by the provided allocator.
```

--------------------------------

### Box::try_clone_from_ref

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Experimental API to allocate memory on the heap and clone a reference into it, returning an error if allocation fails.

```rust
#![feature(clone_from_ref)]
#![feature(allocator_api)]

let hello: Box<str> = Box::try_clone_from_ref("hello")?;
```

--------------------------------

### Box::try_new

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Experimental API to allocate memory on the heap, returning an error if allocation fails.

```rust
#![feature(allocator_api)]

let five = Box::try_new(5)?;
```

--------------------------------

### Manually create Box from NonNull pointer

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Allocates memory manually and initializes a Box using the system allocator with a NonNull pointer.

```rust
#![feature(allocator_api)]

use std::alloc::{Allocator, Layout, System};

unsafe {
    let non_null = System.allocate(Layout::new::<i32>())?.cast::<i32>();
    // In general .write is required to avoid attempting to destruct
    // the (uninitialized) previous contents of `non_null`.
    non_null.write(5);
    let x = Box::from_non_null_in(non_null, System);
}
```

--------------------------------

### Clone Box contents into existing allocation

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Demonstrates using clone_from to copy contents into an existing Box without triggering a new allocation.

```rust
let x = Box::new(5);
let mut y = Box::new(10);
let yp: *const i32 = &*y;

y.clone_from(&x);

// The value is the same
assert_eq!(x, y);

// And no allocation occurred
assert_eq!(yp, &*y);
```

--------------------------------

### Box::into_non_null_with_allocator

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Consumes the Box, returning a wrapped NonNull pointer and the allocator.

```APIDOC
## pub fn into_non_null_with_allocator(b: Box<T, A>) -> (NonNull<T>, A)

### Description
Consumes the `Box`, returning a wrapped `NonNull` pointer and the allocator. The pointer will be properly aligned. The caller is responsible for the memory previously managed by the `Box`.
```

--------------------------------

### Derive Schema Macro Usage

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/derive.Schema.html

Basic syntax for applying the Schema derive macro with available attributes.

```rust
#[derive(Schema)]
{
    // Attributes available to this derive:
    #[tomlmenu]
}
```

--------------------------------

### Document::set

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/struct.Document.html

Sets a value for a dotted key, creating intermediate tables if necessary.

```APIDOC
## pub fn set(&mut self, key: &str, value: Value)

### Description
Set a dotted key, creating any missing intermediate tables. Existing keys are overwritten in place while preserving decor.
```

--------------------------------

### Box::take

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Consumes the box without consuming its allocation, returning the value and the uninitialized box.

```rust
#![feature(box_take)]

let c = Box::new(5);

// take the value out of the box
let (value, uninit) = Box::take(c);
assert_eq!(value, 5);
```

--------------------------------

### Box::into_raw_with_allocator

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Consumes the Box, returning a wrapped raw pointer and the allocator. The caller is responsible for the memory after this call.

```APIDOC
## pub fn into_raw_with_allocator(b: Box<T, A>) -> (*mut T, A)

### Description
Consumes the `Box`, returning a wrapped raw pointer and the allocator. The pointer will be properly aligned and non-null. After calling this function, the caller is responsible for the memory previously managed by the `Box`.
```

--------------------------------

### Box::try_new_zeroed_in

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Constructs a new box with zeroed contents, returning an error if allocation fails.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let zero = Box::<u32, _>::try_new_zeroed_in(System)?;
let zero = unsafe { zero.assume_init() };

assert_eq!(*zero, 0);
```

--------------------------------

### Box::try_new_zeroed

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Experimental API to construct a new box with zeroed uninitialized contents on the heap, returning an error if allocation fails.

```rust
#![feature(allocator_api)]

let zero = Box::<u32>::try_new_zeroed()?;
let zero = unsafe { zero.assume_init() };

assert_eq!(*zero, 0);
```

--------------------------------

### Box::new_zeroed_in

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Constructs a new box with uninitialized contents, filled with zero bytes.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let zero = Box::<u32, _>::new_zeroed_in(System);
let zero = unsafe { zero.assume_init() };

assert_eq!(*zero, 0)
```

--------------------------------

### Document::get

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/struct.Document.html

Retrieves a value from the document using a dotted key.

```APIDOC
## pub fn get(&self, key: &str) -> Option<Value>

### Description
Look up a dotted key and return its `Value` if present.
```

--------------------------------

### Accessing Box contents via raw pointers

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Demonstrates the aliasing guarantees when using as_ptr and as_mut_ptr to access Box contents.

```rust
unsafe {
    let mut v = Box::new(0);
    let ptr1 = Box::as_ptr(&v);
    let ptr2 = Box::as_mut_ptr(&mut v);
    let _val = ptr2.read();
    // No write to this memory has happened yet, so `ptr1` is still valid.
    let _val = ptr1.read();
    // However, once we do a write...
    ptr2.write(1);
    // ... `ptr1` is no longer valid.
    // This would be UB: let _val = ptr1.read();
}
```

--------------------------------

### App struct definition

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/struct.App.html

The definition of the App struct, which contains private fields.

```rust
pub struct App { /* private fields */ }
```

--------------------------------

### Recreate Box from raw pointer

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Restores a Box from a raw pointer and allocator previously obtained via Box::into_raw_with_allocator.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let x = Box::new_in(5, System);
let (ptr, alloc) = Box::into_raw_with_allocator(x);
let x = unsafe { Box::from_raw_in(ptr, alloc) };
```

--------------------------------

### Document::path

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/struct.Document.html

Returns the path of the on-disk file associated with the document.

```APIDOC
## pub fn path(&self) -> &Path

### Description
Path of the on-disk file this document was loaded from (or will be saved to).
```

--------------------------------

### Box::new_zeroed

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Constructs a new box with uninitialized contents, filled with zero bytes.

```rust
let zero = Box::<u32>::new_zeroed();
let zero = unsafe { zero.assume_init() };

assert_eq!(*zero, 0)
```

--------------------------------

### Box::pin_in

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Constructs a new pinned box in the provided allocator.

```rust
#![feature(allocator_api)]
use std::alloc::System;

let x = Box::pin_in(1, System);
```

--------------------------------

### Document::get_str

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/struct.Document.html

Retrieves a string value from the document using a dotted key.

```APIDOC
## pub fn get_str(&self, key: &str) -> Option<&str>

### Description
Convenience: return a `&str` borrowed from the underlying string value, or `None` if the key is absent or not string-typed.
```

--------------------------------

### require_tty

Source: https://docs.rs/tomlmenu

Validates that the application is running in an interactive terminal environment.

```APIDOC
## require_tty

### Description
Refuses to start the TUI when stdio is not interactive. Returns an error if the environment is not a TTY.

### Signature
`require_tty() -> Result<()>`
```

--------------------------------

### Box::as_mut_ptr usage

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Demonstrates obtaining a raw mutable pointer to Box contents while maintaining aliasing guarantees.

```rust
unsafe {
    let mut b = Box::new(0);
    let ptr1 = Box::as_mut_ptr(&mut b);
    ptr1.write(1);
    let ptr2 = Box::as_mut_ptr(&mut b);
    ptr2.write(2);
    // Notably, the write to `ptr2` did *not* invalidate `ptr1`:
    ptr1.write(3);
}
```

--------------------------------

### Recreate Box from NonNull pointer

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Restores a Box from a NonNull pointer and allocator previously obtained via Box::into_non_null_with_allocator.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let x = Box::new_in(5, System);
let (non_null, alloc) = Box::into_non_null_with_allocator(x);
let x = unsafe { Box::from_non_null_in(non_null, alloc) };
```

--------------------------------

### Box::new_in

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Allocates memory in the given allocator and places the value into it.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let five = Box::new_in(5, System);
```

--------------------------------

### Document::save

Source: https://docs.rs/tomlmenu

Persists the current state of the TOML document to disk using atomic-rename writes.

```APIDOC
## Document::save

### Description
Saves the document to the associated on-disk path.

### Signature
`Document::save(&self) -> Result<()>`
```

--------------------------------

### Document::save

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/struct.Document.html

Atomically saves the document to the original file path.

```APIDOC
## pub fn save(&self) -> Result<()>

### Description
Atomically save the document to disk by writing to a temporary file and persisting it over the original path.
```

--------------------------------

### Box::try_map

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Experimental API to attempt to map the value in a box, reusing the allocation if possible.

```rust
#![feature(smart_pointer_try_map)]

let b = Box::new(7);
let new = Box::try_map(b, u32::try_from).unwrap();
assert_eq!(*new, 7);
```

--------------------------------

### Document::clear

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/struct.Document.html

Removes a key from the document.

```APIDOC
## pub fn clear(&mut self, key: &str)

### Description
Remove a key from the target section. The surrounding section’s other keys keep their order and decor.
```

--------------------------------

### Box::try_new_in

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Allocates memory in the given allocator, returning an error if allocation fails.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let five = Box::try_new_in(5, System)?;
```

--------------------------------

### Box::as_mut_ptr

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Returns a raw mutable pointer to the Box’s contents.

```APIDOC
## pub fn as_mut_ptr(b: &mut Box<T, A>) -> *mut T

### Description
Returns a raw mutable pointer to the `Box`’s contents. The caller must ensure that the `Box` outlives the pointer this function returns, or else it will end up dangling.
```

--------------------------------

### Schema Trait Definition

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/trait.Schema.html

The core trait definition requiring a static MenuBody constant and a menu_schema method.

```rust
pub trait Schema {
    const SCHEMA_BODY: &'static MenuBody;

    // Required method
    fn menu_schema() -> MenuNode;
}
```

--------------------------------

### Box::map

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Experimental API to map the value in a box, reusing the allocation if possible.

```rust
#![feature(smart_pointer_try_map)]

let b = Box::new(7);
let new = Box::map(b, |i| i + 7);
assert_eq!(*new, 14);
```

--------------------------------

### Box::into_inner

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Consumes the box and returns the wrapped value.

```rust
#![feature(box_into_inner)]

let c = Box::new(5);

assert_eq!(Box::into_inner(c), 5);
```

--------------------------------

### MenuNode Struct Definition

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/struct.MenuNode.html

The definition of the MenuNode struct, which serves as a node in the menu schema tree.

```rust
pub struct MenuNode {
    pub label: &'static str,
    pub help: &'static str,
    pub key: &'static str,
    pub body: MenuBody,
}
```

--------------------------------

### require_tty function signature

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/fn.require_tty.html

The function signature for require_tty, which returns a Result indicating success or failure.

```rust
pub fn require_tty() -> Result<()>
```

--------------------------------

### RestoreAction Struct Definition

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Internal structure representation of the RestoreAction type.

```rust
pub struct RestoreAction(/* private fields */);
```

--------------------------------

### Define Result Type Alias

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.Result.html

The library-wide error alias for handling results.

```rust
pub type Result<T> = Result<T>;
```

--------------------------------

### ExitReason Enum Definition

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/enum.ExitReason.html

The definition of the ExitReason enum, which provides two variants for handling application exit states.

```rust
pub enum ExitReason {
    Saved,
    Discarded,
}
```

--------------------------------

### RestoreAction Type Definition

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Defines the RestoreAction type as a thread-safe boxed closure.

```rust
pub type RestoreAction = Box<dyn Fn() + Send + Sync + 'static>;
```

--------------------------------

### Leaking Box memory

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.RestoreAction.html

Consumes a Box and returns a mutable reference with a static lifetime.

```rust
let x = Box::new(41);
let static_ref: &'static mut usize = Box::leak(x);
*static_ref += 1;
assert_eq!(*static_ref, 42);
```

```rust
let x = vec![1, 2, 3].into_boxed_slice();
let static_ref = Box::leak(x);
static_ref[0] = 4;
assert_eq!(*static_ref, [4, 2, 3]);
```

--------------------------------

### Result Enum Definition

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/type.Result.html

The structure of the Result enum containing success and error variants.

```rust
pub enum Result<T> {
    Ok(T),
    Err(Error),
}
```

--------------------------------

### Define MenuBody Enum

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/enum.MenuBody.html

The structure of the MenuBody enum, which holds either a static slice of MenuNode or a LeafKind.

```rust
pub enum MenuBody {
    Section(&'static [MenuNode]),
    Leaf(LeafKind),
}
```

--------------------------------

### Define LeafKind Enum

Source: https://docs.rs/tomlmenu/0.1.0/tomlmenu/enum.LeafKind.html

The structure of the LeafKind enum, defining the supported input types for leaf nodes.

```rust
pub enum LeafKind {
    Bool,
    UInt {
        min: u64,
        max: u64,
    },
    Text,
    Choice(&'static [&'static str]),
}
```
Tokens:
Raw