Abscissa Core

https://docs.rs/abscissa_core
Admin
Abscissa Core is the main framework library for building Rust CLI tools and network services with...
Tokens:508,936
Snippets:4,179
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Path Operations Example

Source: https://docs.rs/abscissa_core/latest/abscissa_core/path/struct.Path.html

Demonstrates common operations on a Path, such as getting the parent directory, file stem, and extension. This example works on Unix-like systems.

```rust
use std::path::Path;
use std::ffi::OsStr;

// Note: this example does work on Windows
let path = Path::new("./foo/bar.txt");

let parent = path.parent();
assert_eq!(parent, Some(Path::new("./foo")));

let file_stem = path.file_stem();
assert_eq!(file_stem, Some(OsStr::new("bar")));

let extension = path.extension();
assert_eq!(extension, Some(OsStr::new("txt")));
```

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

### BTreeMap Entry API Examples

Source: https://docs.rs/abscissa_core/latest/abscissa_core/map/struct.BTreeMap.html

Demonstrates the Entry API for complex methods of getting, setting, updating, and removing keys and their values in a BTreeMap.

```rust
use std::collections::BTreeMap;

// type inference lets us omit an explicit type signature (
// which would be `BTreeMap<&str, u8>` in this example).
let mut player_stats = BTreeMap::new();

fn random_stat_buff() -> u8 {
    // could actually return some random value here - let's just return
    // some fixed value for now
    42
}

// insert a key only if it doesn't already exist
player_stats.entry("health").or_insert(100);

// insert a key using a function that provides a new value only if it
// doesn't already exist
player_stats.entry("defence").or_insert_with(random_stat_buff);

// update a key, guarding against the key possibly not being set
let stat = player_stats.entry("attack").or_insert(100);
*stat += random_stat_buff();

// modify an entry before an insert with in-place mutation
player_stats.entry("mana").and_modify(|mana| *mana += 200).or_insert(100);
```

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

### Install Abscissa CLI

Source: https://docs.rs/abscissa_core/latest/abscissa_core/index.html

Install the Abscissa CLI utility to generate new applications. This is the first step in creating an Abscissa project.

```bash
cargo install abscissa
```

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

### Run Abscissa Application Command

Source: https://docs.rs/abscissa_core/latest/abscissa_core/index.html

Execute a subcommand of your Abscissa application. This example shows how to run the 'start' subcommand with an argument.

```bash
cargo run -- start world
```

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

### Install Abscissa CLI Utility

Source: https://docs.rs/abscissa_core

Install the Abscissa CLI utility to generate new Abscissa applications. This is a prerequisite for creating new projects.

```bash
$ cargo install abscissa
```

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

### Regex splitn examples

Source: https://docs.rs/abscissa_core/latest/abscissa_core/testing/struct.Regex.html

Demonstrates various uses of the `splitn` method with different delimiters and split counts.

```rust
use regex::Regex;

let re = Regex::new(r" ").unwrap();
let hay = "Mary had a little lamb";
let got: Vec<&str> = re.splitn(hay, 3).collect();
assert_eq!(got, vec!["Mary", "had", "a little lamb"]);
```

```rust
let re = Regex::new(r"X").unwrap();
let hay = "";
let got: Vec<&str> = re.splitn(hay, 3).collect();
assert_eq!(got, vec![""]);
```

```rust
let re = Regex::new(r"X").unwrap();
let hay = "lionXXtigerXleopard";
let got: Vec<&str> = re.splitn(hay, 3).collect();
assert_eq!(got, vec!["lion", "", "tigerXleopard"]);
```

```rust
let re = Regex::new(r"::").unwrap();
let hay = "lion::tiger::leopard";
let got: Vec<&str> = re.splitn(hay, 2).collect();
assert_eq!(got, vec!["lion", "tiger::leopard"]);
```

```rust
let re = Regex::new(r"X").unwrap();
let hay = "abcXdef";
let got: Vec<&str> = re.splitn(hay, 1).collect();
assert_eq!(got, vec!["abcXdef"]);
```

```rust
let re = Regex::new(r"X").unwrap();
let hay = "abcdef";
let got: Vec<&str> = re.splitn(hay, 2).collect();
assert_eq!(got, vec!["abcdef"]);
```

```rust
let re = Regex::new(r"X").unwrap();
let hay = "abcXdef";
let got: Vec<&str> = re.splitn(hay, 0).collect();
assert!(got.is_empty());
```

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

### step_by

Source: https://docs.rs/abscissa_core/latest/abscissa_core/component/registry/type.Iter.html

Creates an iterator starting at the same point, but stepping by the given amount at each iteration.

```APIDOC
## step_by(self, step: usize) -> StepBy<Self>

### Description
Creates an iterator starting at the same point, but stepping by the given amount at each iteration.

### Parameters
#### Path Parameters
- **step** (usize) - Description: The number of elements to step by.
```

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

### BTreeSet Union Example

Source: https://docs.rs/abscissa_core/latest/abscissa_core/set/struct.BTreeSet.html

Demonstrates how to compute the union of two BTreeSets. The result is collected into a Vec.

```rust
use std::collections::BTreeSet;

let mut a = BTreeSet::new();
a.insert(1);

let mut b = BTreeSet::new();
b.insert(2);

let union: Vec<_> = a.union(&b).cloned().collect();
assert_eq!(union, [1, 2]);
```

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

### boot_with_args Function

Source: https://docs.rs/abscissa_core/latest/abscissa_core/application/index.html

Boots the given application, parsing subcommand and options from the provided iterator, and terminating when complete.

```APIDOC
## Function boot_with_args

Boot the given application, parsing subcommand and options from the provided iterator, and terminating when complete.
```

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

### BTreeSet Get Example

Source: https://docs.rs/abscissa_core/latest/abscissa_core/set/struct.BTreeSet.html

Retrieves a reference to an element in the BTreeSet if it exists. The value can be borrowed.

```rust
use std::collections::BTreeSet;

let set = BTreeSet::from([1, 2, 3]);
assert_eq!(set.get(&2), Some(&2));
assert_eq!(set.get(&4), None);
```

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

### boot_with_args

Source: https://docs.rs/abscissa_core/latest/abscissa_core/application/fn.boot_with_args.html

Boots the given application, parsing subcommand and options from the provided iterator, and terminating when complete. This is useful if you want to pre-process the arguments, e.g. perform glob expansion on Windows. Otherwise use boot.

```APIDOC
## Function boot_with_args

abscissa_core::application

### Summary
```
pub fn boot_with_args<A, I, T>(app_cell: &'static AppCell<A>, args: I) -> !
where
    A: Application,
    I: IntoIterator<Item = T>,
    T: Into<OsString> + Clone,
```

### Description
Boot the given application, parsing subcommand and options from the provided iterator, and terminating when complete.
This is useful if you want to pre-process the arguments, e.g. perform glob expansion on Windows. Otherwise use boot.
```

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

### Boot Application with Default Arguments

Source: https://docs.rs/abscissa_core/latest/src/abscissa_core/application.rs.html

Boots the application by parsing command-line arguments from the environment. This is the primary entry point for most applications.

```rust
pub fn boot<A: Application>(app_cell: &'static AppCell<A>) -> !
{
    let args = env::args_os();
    boot_with_args(app_cell, args)
}
```

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

### Run Abscissa Application Subcommand

Source: https://docs.rs/abscissa_core

Execute a subcommand within a generated Abscissa application. This example shows how to run the 'start' subcommand.

```bash
$ cargo run -- start world
```

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

### boot Function

Source: https://docs.rs/abscissa_core/latest/abscissa_core/application/index.html

Boots the given application, parsing subcommand and options from command-line arguments, and terminating when complete.

```APIDOC
## Function boot

Boot the given application, parsing subcommand and options from command-line arguments, and terminating when complete.
```

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

### BTreeSet lower_bound cursor example

Source: https://docs.rs/abscissa_core/latest/abscissa_core/set/struct.BTreeSet.html

Demonstrates using `lower_bound` with different `Bound` types to get a cursor. The cursor can peek at adjacent elements.

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

use std::collections::BTreeSet;
use std::ops::Bound;

let set = BTreeSet::from([1, 2, 3, 4]);

let cursor = set.lower_bound(Bound::Included(&2));
assert_eq!(cursor.peek_prev(), Some(&1));
assert_eq!(cursor.peek_next(), Some(&2));

let cursor = set.lower_bound(Bound::Excluded(&2));
assert_eq!(cursor.peek_prev(), Some(&2));
assert_eq!(cursor.peek_next(), Some(&3));

let cursor = set.lower_bound(Bound::Unbounded);
assert_eq!(cursor.peek_prev(), None);
assert_eq!(cursor.peek_next(), Some(&1));
```

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

### boot Function

Source: https://docs.rs/abscissa_core/latest/abscissa_core/application/fn.boot.html

Boots the application by parsing command-line arguments and terminating when complete.

```APIDOC
## boot<A: Application>

### Description
Boot the given application, parsing subcommand and options from command-line arguments, and terminating when complete.

### Signature
```rust
pub fn boot<A: Application>(app_cell: &'static AppCell<A>) -> !
```
```

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

### BTreeMap Initialization and Usage

Source: https://docs.rs/abscissa_core/latest/abscissa_core/map/struct.BTreeMap.html

Demonstrates how to create, insert elements into, check for keys, remove elements, and iterate over a BTreeMap.

```APIDOC
## BTreeMap::new()

### Description
Creates a new, empty `BTreeMap`.

### Method
`new()`

### Endpoint
N/A (Method Call)

### Parameters
None

### Request Example
```rust
use std::collections::BTreeMap;
let mut map: BTreeMap<String, i32> = BTreeMap::new();
```

### Response
#### Success Response (200)
An empty `BTreeMap`.

#### Response Example
```rust
// Returns an empty BTreeMap
```

## BTreeMap::insert()

### Description
Inserts a key-value pair into the map. If the map did not have this key present, `None` is returned. If the map did have this key present, the value is updated, and the old value is returned.

### Method
`insert(key: K, value: V)`

### Endpoint
N/A (Method Call)

### Parameters
- **key** (K) - The key to insert.
- **value** (V) - The value to insert.

### Request Example
```rust
use std::collections::BTreeMap;
let mut map = BTreeMap::new();
map.insert("apple", 1);
```

### Response
#### Success Response (200)
- **Option<V>** - `None` if the key was not present, `Some(old_value)` if the key was present.

#### Response Example
```rust
// Returns None or Some(old_value)
```

## BTreeMap::contains_key()

### Description
Returns `true` if the map contains a value for the specified key.

### Method
`contains_key(key: &Q)` where Q: ?Sized + Ord

### Endpoint
N/A (Method Call)

### Parameters
- **key** (&Q) - The key to check for.

### Request Example
```rust
use std::collections::BTreeMap;
let mut map = BTreeMap::new();
map.insert("apple", 1);
let has_apple = map.contains_key("apple"); // true
```

### Response
#### Success Response (200)
- **bool** - `true` if the key exists, `false` otherwise.

#### Response Example
```rust
// Returns true or false
```

## BTreeMap::remove()

### Description
Removes a key from the map, returning the value at the key if the key was previously in the map.

### Method
`remove(key: &Q)` where Q: ?Sized + Ord

### Endpoint
N/A (Method Call)

### Parameters
- **key** (&Q) - The key to remove.

### Request Example
```rust
use std::collections::BTreeMap;
let mut map = BTreeMap::new();
map.insert("apple", 1);
let removed_value = map.remove("apple"); // Some(1)
```

### Response
#### Success Response (200)
- **Option<V>** - `Some(value)` if the key was present, `None` otherwise.

#### Response Example
```rust
// Returns Some(value) or None
```

## BTreeMap::iter()

### Description
Returns an iterator visiting all key-value pairs in the map in ascending key order.

### Method
`iter()`

### Endpoint
N/A (Method Call)

### Parameters
None

### Request Example
```rust
use std::collections::BTreeMap;
let mut map = BTreeMap::new();
map.insert("apple", 1);
map.insert("banana", 2);

for (key, value) in map.iter() {
    println!("{}: {}", key, value);
}
```

### Response
#### Success Response (200)
- **Iter<'_, K, V>** - An iterator over key-value pairs.

#### Response Example
```rust
// Iterator yielding (&K, &V) tuples
```

## BTreeMap::from()

### Description
Creates a `BTreeMap` from an array of key-value tuples.

### Method
`from(values: [(K, V); N])`

### Endpoint
N/A (Method Call)

### Parameters
- **values** ([(K, V); N]) - An array of key-value tuples.

### Request Example
```rust
use std::collections::BTreeMap;
let map = BTreeMap::from([
    ("Mercury", 0.4),
    ("Venus", 0.7),
]);
```

### Response
#### Success Response (200)
- **BTreeMap<K, V>** - A `BTreeMap` initialized with the provided key-value pairs.

#### Response Example
```rust
// Returns a BTreeMap populated with the array elements
```
```

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

### BTreeMap Upper Bound Cursor Examples

Source: https://docs.rs/abscissa_core/latest/abscissa_core/map/struct.BTreeMap.html

Illustrates how to use `upper_bound` to get a cursor pointing to the gap after the greatest key smaller than the given bound. This API is nightly-only and requires the `btree_cursors` feature.

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

use std::collections::BTreeMap;
use std::ops::Bound;

let map = BTreeMap::from([
    (1, "a"),
    (2, "b"),
    (3, "c"),
    (4, "d"),
]);

let cursor = map.upper_bound(Bound::Included(&3));
assert_eq!(cursor.peek_prev(), Some((&3, &"c")));
assert_eq!(cursor.peek_next(), Some((&4, &"d")));

let cursor = map.upper_bound(Bound::Excluded(&3));
assert_eq!(cursor.peek_prev(), Some((&2, &"b")));
assert_eq!(cursor.peek_next(), Some((&3, &"c")));

let cursor = map.upper_bound(Bound::Unbounded);
assert_eq!(cursor.peek_prev(), Some((&4, &"d")));
assert_eq!(cursor.peek_next(), None);

```

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

### Find captures at specific start with Regex

Source: https://docs.rs/abscissa_core/latest/abscissa_core/testing/struct.Regex.html

Use `captures_at` to find captures starting at a given offset. This considers surrounding context, unlike `captures` on a substring. Panics if `start` is out of bounds.

```rust
use regex::Regex;

let re = Regex::new(r"\bchew\b").unwrap();
let hay = "eschew";
// We get a match here, but it's probably not intended.
assert_eq!(&re.captures(&hay[2..]).unwrap()[0], "chew");
// No match because the  assertions take the context into account.
assert!(re.captures_at(hay, 2).is_none());
```

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

### Application Bootstrapping

Source: https://docs.rs/abscissa_core/latest/src/abscissa_core/application.rs.html

Functions to boot the application, either with command-line arguments or a custom iterator.

```APIDOC
## Application Bootstrapping

### Description
Provides functions to initialize and run the application by parsing command-line arguments and executing the main application logic.

### Functions

- **boot<A: Application>(app_cell: &'static AppCell<A>) -> !**
  Boots the application using command-line arguments obtained from `env::args_os()`.

- **boot_with_args<A, I, T>(app_cell: &'static AppCell<A>, args: I) -> !**
  Boots the application with a custom iterator of arguments. This is useful for pre-processing arguments before they are parsed by the application.
```

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

### Check if match exists at specific start with Regex

Source: https://docs.rs/abscissa_core/latest/abscissa_core/testing/struct.Regex.html

Use `is_match_at` to check for a match starting at a given offset. This considers surrounding context, unlike `is_match` on a substring. Panics if `start` is out of bounds.

```rust
use regex::Regex;

let re = Regex::new(r"\bchew\b").unwrap();
let hay = "eschew";
// We get a match here, but it's probably not intended.
assert!(re.is_match(&hay[2..]));
// No match because the  assertions take the context into account.
assert!(!re.is_match_at(hay, 2));
```

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

### Find match at specific start with Regex

Source: https://docs.rs/abscissa_core/latest/abscissa_core/testing/struct.Regex.html

Use `find_at` to find the first match starting at a given offset. The returned `Match`'s range is relative to the haystack's beginning. Panics if `start` is out of bounds.

```rust
use regex::Regex;

let re = Regex::new(r"\bchew\b").unwrap();
let hay = "eschew";
// We get a match here, but it's probably not intended.
assert_eq!(re.find(&hay[2..]).map(|m| m.range()), Some(0..4));
// No match because the  assertions take the context into account.
assert_eq!(re.find_at(hay, 2), None);
```

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

### Find shortest match offset at specific start with Regex

Source: https://docs.rs/abscissa_core/latest/abscissa_core/testing/struct.Regex.html

Use `shortest_match_at` to find the shortest match starting at a given offset. The returned offset is relative to the haystack's beginning. Panics if `start` is out of bounds.

```rust
use regex::Regex;

let re = Regex::new(r"\bchew\b").unwrap();
let hay = "eschew";
// We get a match here, but it's probably not intended.
assert_eq!(re.shortest_match(&hay[2..]), Some(4));
// No match because the  assertions take the context into account.
assert_eq!(re.shortest_match_at(hay, 2), None);
```

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

### Initialize and Use BTreeMap

Source: https://docs.rs/abscissa_core/latest/abscissa_core/struct.Map.html

Demonstrates initializing a `BTreeMap` with entries, checking for keys, removing entries, and iterating over the map. Panics if a key is not found when using index access.

```rust
use std::collections::BTreeMap;

// type inference lets us omit an explicit type signature (which
// would be `BTreeMap<&str, &str>` in this example).
let mut movie_reviews = BTreeMap::new();

// review some movies.
movie_reviews.insert("Office Space",       "Deals with real issues in the workplace.");
movie_reviews.insert("Pulp Fiction",       "Masterpiece.");
movie_reviews.insert("The Godfather",      "Very enjoyable.");
movie_reviews.insert("The Blues Brothers", "Eye lyked it a lot.");

// check for a specific one.
if !movie_reviews.contains_key("Les Misérables") {
    println!("We've got {} reviews, but Les Misérables ain't one.",
             movie_reviews.len());
}

// oops, this review has a lot of spelling mistakes, let's delete it.
movie_reviews.remove("The Blues Brothers");

// look up the values associated with some keys.
let to_find = ["Up!", "Office Space"];
for movie in &to_find {
    match movie_reviews.get(movie) {
       Some(review) => println!("{movie}: {review}"),
       None => println!("{movie} is unreviewed.")
    }
}

// Look up the value for a key (will panic if the key is not found).
println!("Movie review: {}", movie_reviews["Office Space"]);

// iterate over everything.
for (movie, review) in &movie_reviews {
    println!( $"{movie}: \"{review}\""");
}
```

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

### Get value from VacantEntry

Source: https://docs.rs/abscissa_core/latest/abscissa_core/set/struct.VacantEntry.html

Shows how to get a reference to the value that would be inserted using a VacantEntry. This is an experimental API.

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

use std::collections::BTreeSet;

let mut set = BTreeSet::new();
assert_eq!(set.entry("poneyland").get(), &"poneyland");

```

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

### Constructing Trace Events

Source: https://docs.rs/abscissa_core/latest/abscissa_core/prelude/macro.event.html

Examples demonstrating how to use the `event` macro with different levels, targets, and field formats. Ensure `tracing` is imported.

```rust
use tracing::{event, Level};

let data = (42, "forty-two");
let private_data = "private";
let error = "a bad error";

event!(Level::ERROR, %error, "Received error");
event!(
    target: "app_events",
    Level::WARN,
    private_data,
    ?data,
    "App warning: {}",
    error
);
event!(name: "answer", Level::INFO, the_answer = data.0);
event!(Level::INFO, the_answer = data.0);
```

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

### Get component reference by ID

Source: https://docs.rs/abscissa_core/latest/src/abscissa_core/component/registry.rs.html

Retrieves a reference to a component using its ID. This involves first getting the handle and then the component.

```rust
pub fn get_by_id(&self, id: Id) -> Option<&dyn Component<A>> {
        self.get(self.get_handle_by_id(id)?)
    }
```

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

### Get Error Cause for FrameworkErrorKind (Deprecated)

Source: https://docs.rs/abscissa_core/latest/abscissa_core/error/framework/enum.FrameworkErrorKind.html

Deprecated method to get the underlying cause of the error. Replaced by `Error::source`.

```rust
fn cause(&self) -> Option<&dyn Error>
```

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

### Boot Application with Custom Arguments

Source: https://docs.rs/abscissa_core/latest/src/abscissa_core/application.rs.html

Boots the application by parsing arguments from a provided iterator. This is useful for pre-processing arguments, such as performing glob expansion.

```rust
pub fn boot_with_args<A, I, T>(app_cell: &'static AppCell<A>, args: I) -> !
where
    A: Application,
    I: IntoIterator<Item = T>,
    T: Into<OsString> + Clone,
{
    A::run(app_cell, args);
    process::exit(0);
}
```

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

### Initialize and Use BTreeMap

Source: https://docs.rs/abscissa_core/latest/abscissa_core/map/struct.BTreeMap.html

Demonstrates basic usage of BTreeMap, including initialization, insertion, checking for keys, removal, retrieval, and iteration. Ensure keys implement `Ord` and avoid modifying keys after insertion.

```rust
use std::collections::BTreeMap;

// type inference lets us omit an explicit type signature (which
// would be `BTreeMap<&str, &str>` in this example).
let mut movie_reviews = BTreeMap::new();

// review some movies.
movie_reviews.insert("Office Space",       "Deals with real issues in the workplace.");
movie_reviews.insert("Pulp Fiction",       "Masterpiece.");
movie_reviews.insert("The Godfather",      "Very enjoyable.");
movie_reviews.insert("The Blues Brothers", "Eye lyked it a lot.");

// check for a specific one.
if !movie_reviews.contains_key("Les Misérables") {
    println!("We've got {} reviews, but Les Misérables ain\'t one.",
             movie_reviews.len());
}

// oops, this review has a lot of spelling mistakes, let's delete it.
movie_reviews.remove("The Blues Brothers");

// look up the values associated with some keys.
let to_find = ["Up!", "Office Space"];
for movie in &to_find {
    match movie_reviews.get(movie) {
       Some(review) => println!("{movie}: {review}"),
       None => println!("{movie} is unreviewed.")
    }
}

// Look up the value for a key (will panic if the key is not found).
println!("Movie review: {}", movie_reviews["Office Space"]);

// iterate over everything.
for (movie, review) in &movie_reviews {
    println!("{movie}: \"{review}\" ");
}
```

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

### Regex::shortest_match_at

Source: https://docs.rs/abscissa_core/latest/abscissa_core/testing/struct.Regex.html

Returns the same as `Regex::shortest_match`, but starts the search at the given offset. The significance of the starting point is that it takes the surrounding context into consideration.

```APIDOC
## Regex::shortest_match_at

### Description
Returns the same as `Regex::shortest_match`, but starts the search at the given offset. The significance of the starting point is that it takes the surrounding context into consideration. For example, the `\A` anchor can only match when `start == 0`.

If a match is found, the offset returned is relative to the beginning of the haystack, not the beginning of the search.

### Method
`shortest_match_at`

### Parameters
#### Path Parameters
- **haystack** (str) - Required - The string to search within.
- **start** (usize) - Required - The byte offset at which to start the search.

### Panics
This panics when `start >= haystack.len() + 1`.

### Response
- **Option<usize>** - The end byte offset of the first match relative to the beginning of the haystack, or None if no match is found.

### Example
```rust
use regex::Regex;

let re = Regex::new(r"\bchew\b").unwrap();
let hay = "eschew";
// We get a match here, but it's probably not intended.
assert_eq!(re.shortest_match(&hay[2..]), Some(4));
// No match because the assertions take the context into account.
assert_eq!(re.shortest_match_at(hay, 2), None);
```
```

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

### Version::new

Source: https://docs.rs/abscissa_core/latest/abscissa_core/struct.Version.html

Constructs a new Version instance with specified major, minor, and patch numbers, initializing pre-release and build metadata to empty.

```APIDOC
### impl Version

#### pub const fn new(major: u64, minor: u64, patch: u64) -> Version

Create `Version` with an empty pre-release and build metadata.
Equivalent to:
```
Version {
    major,
    minor,
    patch,
    pre: Prerelease::EMPTY,
    build: BuildMetadata::EMPTY,
}
```
```

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

### Get mutable component reference by ID

Source: https://docs.rs/abscissa_core/latest/src/abscissa_core/component/registry.rs.html

Retrieves a mutable reference to a component using its ID. This involves first getting the handle and then the component.

```rust
pub fn get_mut_by_id(&mut self, id: Id) -> Option<&mut (dyn Component<A> + 'static)> {
        self.get_mut(self.get_handle_by_id(id)?)
    }
```

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

### Run Tests and Checks on Generated App

Source: https://docs.rs/abscissa_core

After generating a test application, navigate to its directory and run tests, rustfmt, and clippy to ensure everything is working correctly. These checks are part of the CI process.

```bash
cd /tmp/example_app # or 'pushd /tmp/example_app' and 'popd' to return
cargo test
cargo fmt -- --check # generated app is expected to pass rustfmt
cargo clippy
```

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

### Create a ConfigFile

Source: https://docs.rs/abscissa_core/latest/abscissa_core/testing/struct.ConfigFile.html

Creates a configuration file by serializing the provided configuration object to the specified application name. This is useful for managing application settings.

```rust
pub fn create<C>(app_name: &OsStr, config: &C) -> Self
where C: Serialize
```

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

### Get Error Description for FrameworkErrorKind (Deprecated)

Source: https://docs.rs/abscissa_core/latest/abscissa_core/error/framework/enum.FrameworkErrorKind.html

Deprecated method to get a string description of the error. Use the Display implementation or `to_string()` instead.

```rust
fn description(&self) -> &str
```

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

### Getting a reference to the value in OccupiedEntry

Source: https://docs.rs/abscissa_core/latest/abscissa_core/set/struct.OccupiedEntry.html

Shows how to use the `get` method on an `OccupiedEntry` to retrieve a reference to the stored value. This requires the 'btree_set_entry' nightly feature.

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

use std::collections::btree_set::{Entry, BTreeSet};

let mut set = BTreeSet::new();
set.entry("poneyland").or_insert();

match set.entry("poneyland") {
    Entry::Vacant(_) => panic!(),
    Entry::Occupied(entry) => assert_eq!(entry.get(), &"poneyland"),
}

```

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

### starts_with

Source: https://docs.rs/abscissa_core/latest/abscissa_core/path/struct.PathBuf.html

Checks if the path begins with a specified prefix, considering whole path components.

```APIDOC
## starts_with

### Description
Determines whether `base` is a prefix of `self`.
Only considers whole path components to match.

### Method
`pub fn starts_with<P>(&self, base: P) -> bool`
where P: AsRef<Path>,

### Examples
```rust
use std::path::Path;

let path = Path::new("/etc/passwd");

assert!(path.starts_with("/etc"));
assert!(path.starts_with("/etc/"));
assert!(path.starts_with("/etc/passwd"));
assert!(path.starts_with("/etc/passwd/")); // extra slash is okay
assert!(path.starts_with("/etc/passwd///")); // multiple extra slashes are okay

assert!(!path.starts_with("/e"));
assert!(!path.starts_with("/etc/passwd.txt"));

assert!(!Path::new("/etc/foo.rs").starts_with("/etc/foo"));
```
```

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

### streams

Source: https://docs.rs/abscissa_core/latest/abscissa_core/terminal/fn.streams.html

Get the terminal `Streams`.

```APIDOC
## streams

abscissa_core::terminal

# Function streams

```
pub fn streams() -> &'static Streams
```

### Description
Get the terminal `Streams`.

### Returns
- `&'static Streams`: A static reference to the terminal streams.
```

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

### Command Description Method

Source: https://docs.rs/abscissa_core/latest/abscissa_core/command/trait.Command.html

Implement this method to provide a brief description of the subcommand.

```rust
fn description() -> &'static str;
```

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

### type_id

Source: https://docs.rs/abscissa_core/latest/abscissa_core/set/struct.BTreeSet.html

Gets the TypeId of the BTreeSet.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`.

### Returns
The `TypeId` of the `BTreeSet`.
```

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

### Tracing::new

Source: https://docs.rs/abscissa_core/latest/src/abscissa_core/trace/component.rs.html

Initializes the `tracing` subsystem with a given configuration and color choice. It sets up log/tracing interoperability and configures the subscriber with an environment filter and reload capabilities.

```APIDOC
## Tracing::new

### Description
Initializes the `tracing` subsystem with a given configuration and color choice. It sets up log/tracing interoperability and configures the subscriber with an environment filter and reload capabilities.

### Signature
```rust
pub fn new(config: Config, color_choice: ColorChoice) -> Result<Self, FrameworkError>
```

### Parameters

#### `config`
- **type**: `Config`
- **description**: The tracing configuration, including the initial filter.

#### `color_choice`
- **type**: `ColorChoice`
- **description**: Determines whether ANSI colors are used in the output.

### Returns
- **type**: `Result<Self, FrameworkError>`
- **description**: Returns the initialized `Tracing` component on success, or a `FrameworkError` if initialization fails.
```

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

### Type ID

Source: https://docs.rs/abscissa_core/latest/abscissa_core/set/struct.Intersection.html

Gets the TypeId of the iterator.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`.

### Method
`type_id`

### Parameters
None

### Response
- `TypeId`: The unique identifier for the type of the iterator.
```

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

### Path TypeId

Source: https://docs.rs/abscissa_core/latest/abscissa_core/path/struct.Path.html

Gets the `TypeId` of the Path.

```APIDOC
#### fn type_id(&self) -> TypeId
Gets the `TypeId` of `self`. Read more
```

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

### Create Verbose Tracing Configuration

Source: https://docs.rs/abscissa_core/latest/src/abscissa_core/trace/config.rs.html

Provides a constructor for creating a `Config` with verbose output (debug level). Use this when detailed logging is required.

```rust
/// Create a config for verbose output.
pub fn verbose() -> Self {
    "debug".to_owned().into()
}
```

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

### type_id

Source: https://docs.rs/abscissa_core/latest/abscissa_core/path/struct.AbsPath.html

Gets the TypeId of the AbsPath instance.

```APIDOC
## type_id

### Description
Gets the `TypeId` of `self`.

### Signature
`fn type_id(&self) -> TypeId`
```

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

### Into Implementation

Source: https://docs.rs/abscissa_core/latest/abscissa_core/map/struct.RangeMut.html

Provides a generic conversion capability.

```APIDOC
### impl<T, U> Into<U> for T

#### fn into(self) -> U

### Description
Calls `U::from(self)`. This conversion is determined by the `From<T> for U` implementation. It allows converting between types that have a defined `From` relationship.

### Method
`into`

### Parameters
None

### Response
- `U`: The converted value.
```

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

### Open a new unique config file for writing

Source: https://docs.rs/abscissa_core/latest/src/abscissa_core/testing/config.rs.html

The `open` function attempts to create a new file in the system's temporary directory with a unique name based on the application name. It retries up to `FILE_CREATE_ATTEMPTS` times to ensure a new file is created.

```rust
use abscissa_core::fs::{self, File, OpenOptions};
use std::{env, ffi::OsStr, io::{self, Write}, path::{Path, PathBuf}};

// This is an internal helper function, shown for context.
// In practice, you would use `ConfigFile::create`.
fn open(app_name: &OsStr) -> (PathBuf, File) {
    // TODO: fully `OsString`-based path building
    let filename_prefix = app_name.to_string_lossy().to_string();

    for n in 0..1024 {
        let filename = format!("{}-{}.toml", &filename_prefix, n);
        let path = env::temp_dir().join(filename);

        match OpenOptions::new().write(true).create_new(true).open(&path) {
            Ok(file) => return (path, file),
            Err(e) => {
                if e.kind() == io::ErrorKind::AlreadyExists {
                    continue;
                } else {
                    panic!("couldn't create {}: {}", path.display(), e);
                }
            }
        }
    }

    panic!(
        "couldn't create {}.toml after {} attempts!",
        filename_prefix,
        1024
    )
}
```

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

### msg

Source: https://docs.rs/abscissa_core/latest/abscissa_core/error/framework/enum.FrameworkErrorKind.html

Gets a message to display for this error.

```APIDOC
## impl FrameworkErrorKind

### pub fn msg(&self) -> &'static str

Get a message to display for this error.
```

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

### get_key_value

Source: https://docs.rs/abscissa_core/latest/abscissa_core/struct.Map.html

Retrieves the key-value pair corresponding to the supplied key. This is useful for key types where non-identical keys can be considered equal, for getting the stored key value from a borrowed lookup key, or for getting a reference to a key with the same lifetime as the collection.

```APIDOC
## get_key_value

### Description
Retrieves the key-value pair corresponding to the supplied key. This is potentially useful:
  * for key types where non-identical keys can be considered equal;
  * for getting the `&K` stored key value from a borrowed `&Q` lookup key; or
  * for getting a reference to a key with the same lifetime as the collection.

The supplied key may be any borrowed form of the map’s key type, but the ordering on the borrowed form _must_ match the ordering on the key type.

### Method
`get_key_value(&self, k: &Q) -> Option<(&K, &V)>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use std::cmp::Ordering;
use std::collections::BTreeMap;

#[derive(Clone, Copy, Debug)]
struct S {
    id: u32,
    name: &'static str, // ignored by equality and ordering operations
}

impl PartialEq for S {
    fn eq(&self, other: &S) -> bool {
        self.id == other.id
    }
}

impl Eq for S {}

impl PartialOrd for S {
    fn partial_cmp(&self, other: &S) -> Option<Ordering> {
        self.id.partial_cmp(&other.id)
    }
}

impl Ord for S {
    fn cmp(&self, other: &S) -> Ordering {
        self.id.cmp(&other.id)
    }
}

let j_a = S { id: 1, name: "Jessica" };
let j_b = S { id: 1, name: "Jess" };
let p = S { id: 2, name: "Paul" };
assert_eq!(j_a, j_b);

let mut map = BTreeMap::new();
map.insert(j_a, "Paris");
assert_eq!(map.get_key_value(&j_a), Some((&j_a, &"Paris")));
assert_eq!(map.get_key_value(&j_b), Some((&j_a, &"Paris"))); // the notable case
assert_eq!(map.get_key_value(&p), None);
```

```

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

### Try Convert From

Source: https://docs.rs/abscissa_core/latest/abscissa_core/error/framework/struct.FrameworkError.html

Performs a conversion from one type to another, returning a `Result`.

```APIDOC
## fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

### Description
Performs the conversion.

### Parameters
- **value** (U) - The value to convert.
```
Tokens:
Raw