syntax_parser_generator/handles/
mod.rs

1//! Manage lightweight handles to arbitrary objects.
2//!
3//! This module provides an API for managing lightweight identifiers, called _handles_, that may
4//! be associated with object of arbitrary types. This is used to make the objects' manipulation
5//! more efficient (juggling lightweight identifiers instead of whole objects), and allows the crate
6//! to operate on a more abstract level - using these generic handles, instead of ground instances.
7//!
8//! # Usage
9//!
10//! A [Handle] is defined by a single field known as its _core_. The core identifies the handled
11//! object, and is an instance of a lightweight type that implements [HandleCore]. The module comes
12//! with 2 built-in implementations of this trait: [u8] and [u16].
13//!
14//! In order to associate handles with instances of some arbitrary type `T`, we must first define
15//! the corresponding [HandleCore] type that `T`'s handles will constitute of. This is done by
16//! implementing the [Handled] trait for this `T`. The more instances of `T` we expect to keep
17//! track of, the more bits we might want to use for `T`'s handles (i.e. the wider its [HandleCore]
18//! should be).
19//!
20//! ```rust
21//! # use syntax_parser_generator::handles::Handled;
22//! struct MyStruct {
23//!     data: Vec<u32>,
24//!     name: String,
25//! }
26//! impl Handled for MyStruct {
27//!     type HandleCoreType = u16;
28//! }
29//! ```
30//!
31//! We can now use [Handled::new_handle] to create handles to instances of `T`, identified by serial
32//! numbers.
33//!
34//! ```rust
35//! # use syntax_parser_generator::handles::Handled;
36//! # struct NamedList {
37//! #     data: Vec<u32>,
38//! #     name: String,
39//! # }
40//! # impl Handled for NamedList {
41//! #     type HandleCoreType = u16;
42//! # }
43//! let handle_of_first_named_list = NamedList::new_handle(0);
44//! ```
45//!
46//! In practice, you won't need to manually create handles with [Handled::new_handle]. Instead, you
47//! may use an existing API for doing so systematically. Check out [collections::HandledVec],
48//! [collections::HandledHashMap], and [specials::AutomaticallyHandled] for that purpose.
49
50pub use handle::{Handle, HandleCore, Handled};
51
52mod handle;
53mod known_cores;
54
55pub mod collections;
56
57pub mod specials;