rbx_tree/lib.rs
1//! rbx_tree is a common representation of the Roblox DOM for Rust. It's
2//! designed to play nicely with the borrow checker and allows accessing
3//! instances by ID in constant time.
4//!
5//! rbx_tree's APIs are not completely stable, but most of the design is locked
6//! in. It is definitely a 0.x.y quality library.
7//!
8//! Constructing a new tree of instances is accomplished by first creating an
9//! [`RbxInstanceProperties`] object that describes the root instance of the
10//! tree, and then wrapping it with an [`RbxTree`]:
11//!
12//! ```
13//! use std::collections::HashMap;
14//! use rbx_tree::{RbxInstanceProperties, RbxTree};
15//!
16//! let props = RbxInstanceProperties {
17//! name: "My Cool Game".to_owned(),
18//! class_name: "DataModel".to_owned(),
19//! properties: HashMap::new(),
20//! };
21//!
22//! let mut tree = RbxTree::new(props);
23//! println!("ID of instance we just inserted is {}", tree.get_root_id());
24//! ```
25//!
26//! Note that the [maplit] crate is incredibly useful for defining properties
27//! inline.
28//!
29//! Once we have a tree, we can use [`RbxTree::insert_instance`] and
30//! [`RbxTree::get_instance`] to add instances to the tree and retrieve them.
31//!
32//! ```
33//! # use std::collections::HashMap;
34//! # use rbx_tree::{RbxInstanceProperties, RbxTree};
35//! use rbx_tree::RbxValue;
36//! use maplit::hashmap;
37//! #
38//! # let props = RbxInstanceProperties {
39//! # name: "My Cool Game".to_owned(),
40//! # class_name: "DataModel".to_owned(),
41//! # properties: HashMap::new(),
42//! # };
43//! #
44//! # let mut tree = RbxTree::new(props);
45//! #
46//! let http_service = RbxInstanceProperties {
47//! name: "HttpService".to_owned(),
48//! class_name: "HttpService".to_owned(),
49//! properties: hashmap! {
50// // Properties are represented via the RbxValue enum
51//! "HttpEnabled".to_owned() => RbxValue::Bool {
52//! value: true,
53//! },
54//! },
55//! };
56//!
57//! let datamodel_id = tree.get_root_id();
58//! let http_service_id = tree.insert_instance(http_service, datamodel_id);
59//!
60//! println!("HttpService has ID {}", http_service_id);
61//! ```
62//!
63//! To change properties on an instance that's already present in the tree, use
64//! [`RbxTree::get_instance_mut`]. Note that it isn't possible to add or remove
65//! children through this method, use [`RbxTree::insert_instance`] instead.
66//!
67//! [`RbxTree`]: struct.RbxTree.html
68//! [`RbxTree::insert_instance`]: struct.RbxTree.html#method.insert_instance
69//! [`RbxTree::get_instance`]: struct.RbxTree.html#method.get_instance
70//! [`RbxTree::get_instance_mut`]: struct.RbxTree.html#method.get_instance_mut
71//! [`RbxInstanceProperties`]: struct.RbxInstanceProperties.html
72//! [maplit]: https://crates.io/crates/maplit
73
74mod id;
75mod instance;
76mod tree;
77mod value;
78
79pub use crate::{
80 id::RbxId,
81 instance::{RbxInstanceProperties, RbxInstance},
82 tree::{RbxTree, Descendants},
83 value::{RbxValue, PhysicalProperties},
84};