Struct TreeBuilder

pub struct TreeBuilder<'a, 's> { /* private fields */ }

A builder struct for formatting AST nodes.

Implementations

impl<'a, 's> TreeBuilder<'a, 's>

pub fn new<S: Into<Cow<'a, str>>>(name: S, symbols: &'s dyn Symbols) -> Self

Creates a new TreeBuilder instance with the given node name and Symbols.

pub fn with_default_symbols<S: Into<Cow<'a, str>>>(name: S) -> Self

Creates a new TreeBuilder configured to use DefaultSymbols.

pub fn field<A: AstToStr>(self, name: &str, value: &A) -> Self

Adds a new child with the given name to the tree, recursively calling AstToStr::ast_to_str_impl on the value.

Example

use ast2str::{builder::TreeBuilder};

let mut tree = TreeBuilder::with_default_symbols("Expr");
tree = tree.field("kind", &"ExprKind::Literal");
tree = tree.field("span", &(3..10));
assert_eq!(
    tree.build(),
    r#"
Expr
├─kind: "ExprKind::Literal"
╰─span: 3..10
"#.trim());

pub fn quoted<S: Display>(self, name: &str, value: S) -> Self

Adds a new child with the given name to the tree, formatting its value as Display surrounded with backticks.

Example

use ast2str::{builder::TreeBuilder};

let mut tree = TreeBuilder::with_default_symbols("Token");
tree = tree.quoted("lexeme", "\"a string\"");
tree = tree.field("span", &(0..8));
assert_eq!(
    tree.build(),
    r#"
Token
├─lexeme: `"a string"`
╰─span: 0..8
"#.trim());

pub fn display<S: Display>(self, name: &str, value: S) -> Self

Adds a new child with the given name to the tree, formatting its value as Display.

Example

use ast2str::{builder::TreeBuilder};

let mut tree = TreeBuilder::with_default_symbols("Variable");
tree = tree.display("name", "x");
assert_eq!(
    tree.build(),
    r#"
Variable
╰─name: x
"#.trim());

pub fn debug<S: Debug>(self, name: &str, value: S) -> Self

Adds a new child with the given name to the tree, formatting its value as Debug.

Example

use ast2str::{builder::TreeBuilder};

let mut tree = TreeBuilder::with_default_symbols("Binary");
tree = tree.field("left", &1);
tree = tree.debug("operator", &std::cmp::Ordering::Less);
tree = tree.field("right", &3);
assert_eq!(
    tree.build(),
    r#"
Binary
├─left: 1
├─operator: Less
╰─right: 3
"#.trim());

pub fn option<A: AstToStr>( self, field: &str, default: &str, option: &Option<A>, ) -> Self

Attempts to add a new child to the tree with field if the option is Some, recursively calling AstToStr::ast_to_str_impl on its value. If the option is None, falls back to display with the given default as its value.

Example

use ast2str::{builder::TreeBuilder};

let mut tree = TreeBuilder::with_default_symbols("VarDecl");
tree = tree.quoted("name", "x");
tree = tree.option("initializer", "<None>", &None::<i32>);
assert_eq!(
    tree.build(),
    r#"
VarDecl
├─name: `x`
╰─initializer: <None>
"#.trim());

let mut tree = TreeBuilder::with_default_symbols("VarDecl");
tree = tree.quoted("name", "x");
tree = tree.option("initializer", "<None>", &Some(7));
assert_eq!(
    tree.build(),
    r#"
VarDecl
├─name: `x`
╰─initializer: 7
"#.trim());

pub fn list<'b, S: AstToStr + 'static>( self, name: &str, collection: impl IntoIterator<Item = &'b S>, ) -> Self

Adds the given collection of items to the tree as a child, recursively calling AstToStr::ast_to_str_impl on each item. If the collection is empty, Symbols::missing_items_symbol will be displayed; otherwise, Symbols::item_list_symbol.

Example

use ast2str::{builder::TreeBuilder};

let mut tree = TreeBuilder::with_default_symbols("List");
tree = tree.list("non_empty", &[1usize, 2, 3]);
tree = tree.list("empty", &Vec::<usize>::new());
assert_eq!(
    tree.build(),
    r#"
List
├─non_empty=↓
│ ├─1
│ ├─2
│ ╰─3
╰─empty=✕
"#.trim());

pub fn list_map<T, A: AstToStr>( self, name: &str, collection: impl IntoIterator<Item = T>, f: impl Fn(T) -> A, ) -> Self

Just like list, but allows the user to pass a function, applying it to every item.

Example

use ast2str::{builder::TreeBuilder};

let mut tree = TreeBuilder::with_default_symbols("List");
tree = tree.list_map("values", &[1, 2, 3], |x| x * x);
assert_eq!(
    tree.build(),
    r#"
List
╰─values=↓
  ├─1
  ├─4
  ╰─9
"#.trim());

pub fn add_child<S: ToString>(self, child: S) -> Self

Adds the given value to the tree as a child.

Example

use ast2str::{builder::TreeBuilder};

let mut tree = TreeBuilder::with_default_symbols("root");
tree = tree.add_child(std::f64::consts::PI);
tree = tree.add_child("any ToString value works");
assert_eq!(
    tree.build(),
    r#"
root
├─3.141592653589793
╰─any ToString value works
"#.trim());

pub fn build(self) -> String

Consumes the builder, formatting the node and its children as a tree. See the other methods for examples.

Trait Implementations

impl<'a, 's> Debug for TreeBuilder<'a, 's>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.