jupiter_rs/infograph/

builder.rs

//! Provides `DocBuilder` which used to create a `Doc` programmatically.
//!
//! Many of the performance optimizations of `Infograph` are based on the fact
//! that a `Doc` is created once and then never modified. (Of course a new Doc can be created
//! to replace a current version, but the data itself is immutable).
//!
//! Therefore a `DocBuilder` along with the helpers provided here is used to setup the data and
//! then converted into a `Doc` as a final step.
//!
//! Note that there are also helpers like [yaml::hash_to_doc](crate::infograph::yaml::hash_to_doc)
//! or [yaml::list_to_doc](crate::infograph::yaml::list_to_doc) which directly transform a given
//! `Yaml` hash or list into a `Doc`.
use crate::infograph::docs::Doc;
use crate::infograph::node::Node;
use crate::infograph::symbols::{Symbol, SymbolMap, SymbolTable};

/// Provides a builder to generate a `Doc`.
///
/// A doc an internally have either a list or a map as its root node. Therefore either
/// `root_object_builder()`or `root_list_builder()` has to be called the retrieve the
/// appropriate builder after which `build()` must be called to create the resulting `Doc`.
///
/// # Examples
///
/// Creating a list based `Doc`:
/// ```
/// # use jupiter::infograph::builder::DocBuilder;
/// let mut builder = DocBuilder::new();
/// let mut list_builder = builder.root_list_builder();
/// list_builder.append_int(1);
/// list_builder.append_int(2);
/// list_builder.append_int(3);
///
/// let doc = builder.build();
/// assert_eq!(doc.root().at(1).as_int().unwrap(), 2);
/// ```
///
/// Creating a map based `Doc`:
/// ```
/// # use jupiter::infograph::builder::DocBuilder;
/// let mut builder = DocBuilder::new();
/// let mut obj_builder = builder.root_object_builder();
/// obj_builder.put_int("Test", 1);
/// obj_builder.put_int("Foo", 2);
///
/// let doc = builder.build();
/// assert_eq!(doc.root().query("Test").as_int().unwrap(), 1);
/// assert_eq!(doc.root().query("Foo").as_int().unwrap(), 2);
/// ```
pub struct DocBuilder {
    symbols: SymbolTable,
    root: Node,
}

impl DocBuilder {
    /// Creates a new builder instance.
    pub fn new() -> Self {
        DocBuilder {
            symbols: SymbolTable::new(),
            root: Node::Empty,
        }
    }

    /// Resolves the given name into a `Symbol` for repeated insertions.
    ///
    /// # Errors
    /// If the internal symbol table overflows, an error is returned.
    pub fn resolve(&mut self, symbol: impl AsRef<str>) -> anyhow::Result<Symbol> {
        self.symbols.find_or_create(symbol)
    }

    /// Makes the root node of the `Doc` a map and returns a builder for it.
    ///
    /// Note that for each `DocBuilder` either `root_object_builder` or `root_list_builder`
    /// has to called exactly once.  
    pub fn root_object_builder(&mut self) -> ObjectBuilder {
        self.root = Node::Object(SymbolMap::new());
        if let Node::Object(ref mut map) = self.root {
            ObjectBuilder {
                symbols: &mut self.symbols,
                map,
            }
        } else {
            unreachable!("Concurrent modification or corruption a DocBuilder")
        }
    }

    /// Makes the root node of the `Doc` a list and returns a builder for it.
    ///
    /// Note that for each `DocBuilder` either `root_object_builder` or `root_list_builder`
    /// has to called exactly once.  
    pub fn root_list_builder(&mut self) -> ListBuilder {
        self.root = Node::List(Vec::new());

        if let Node::List(ref mut list) = self.root {
            ListBuilder {
                symbols: &mut self.symbols,
                list,
            }
        } else {
            unreachable!("Concurrent modification or corruption a DocBuilder")
        }
    }

    /// Turns the builder into a `Doc`.
    pub fn build(self) -> Doc {
        Doc::new(self.symbols, self.root)
    }
}

/// Builds an inner object or map within a `Doc` or another element.
///
/// A builder can either be obtained via [DocBuilder::root_object_builder](DocBuilder::root_object_builder)
/// or using either [ObjectBuilder::put_object](ObjectBuilder::put_object) - to place an inner
/// object in another or via [ListBuilder::append_object](ListBuilder::append_object) to add an
/// object to a list.
pub struct ObjectBuilder<'a> {
    symbols: &'a mut SymbolTable,
    map: &'a mut SymbolMap<Node>,
}

impl<'a> ObjectBuilder<'a> {
    /// Places an integer value within the object being built.
    ///
    /// # Errors
    /// If the internal symbol table overflows, an error is returned.
    ///
    /// # Example
    /// ```
    /// # use jupiter::infograph::builder::DocBuilder;
    /// let mut builder = DocBuilder::new();
    /// let mut obj_builder = builder.root_object_builder();
    ///
    /// obj_builder.put_int("Test", 42).unwrap();
    ///
    /// let doc = builder.build();
    /// assert_eq!(doc.root().query("Test").as_int().unwrap(), 42);
    /// ```
    pub fn put_int(&mut self, key: impl AsRef<str>, value: i64) -> anyhow::Result<()> {
        let symbol = self.symbols.find_or_create(key)?;
        self.insert_int(symbol, value);
        Ok(())
    }

    /// Places an integer value within the object being built using a `Symbol`which has been looked
    /// up previously.
    ///
    /// # Example
    /// ```
    /// # use jupiter::infograph::builder::DocBuilder;
    /// let mut builder = DocBuilder::new();
    /// let key = builder.resolve("Test").unwrap();
    /// let mut obj_builder = builder.root_object_builder();
    ///
    /// obj_builder.insert_int(key, 42);
    ///
    /// let doc = builder.build();
    /// assert_eq!(doc.root().query("Test").as_int().unwrap(), 42);
    /// ```
    pub fn insert_int(&mut self, key: Symbol, value: i64) {
        self.map.put(key, Node::Integer(value));
    }

    /// Places a string value within the object being built.
    ///
    /// # Errors
    /// If the internal symbol table overflows, an error is returned.
    ///
    /// # Example
    /// ```
    /// # use jupiter::infograph::builder::DocBuilder;
    /// let mut builder = DocBuilder::new();
    /// let mut obj_builder = builder.root_object_builder();
    ///
    /// obj_builder.put_string("Test", "Foo").unwrap();
    ///
    /// let doc = builder.build();
    /// assert_eq!(doc.root().query("Test").as_str().unwrap(), "Foo");
    /// ```
    pub fn put_string(
        &mut self,
        key: impl AsRef<str>,
        value: impl AsRef<str>,
    ) -> anyhow::Result<()> {
        let symbol = self.symbols.find_or_create(key)?;
        self.insert_string(symbol, value);

        Ok(())
    }

    /// Places a string value within the object being built using a `Symbol`which has been looked
    /// up previously.
    ///
    /// # Example
    /// ```
    /// # use jupiter::infograph::builder::DocBuilder;
    /// let mut builder = DocBuilder::new();
    /// let key = builder.resolve("Test").unwrap();
    /// let mut obj_builder = builder.root_object_builder();
    ///
    /// obj_builder.insert_string(key, "Foo");
    ///
    /// let doc = builder.build();
    /// assert_eq!(doc.root().query("Test").as_str().unwrap(), "Foo");
    /// ```
    pub fn insert_string(&mut self, key: Symbol, value: impl AsRef<str>) {
        self.map.put(key, Node::from(value.as_ref()));
    }

    /// Places a bool value within the object being built.
    ///
    /// # Errors
    /// If the internal symbol table overflows, an error is returned.
    ///
    /// # Example
    /// ```
    /// # use jupiter::infograph::builder::DocBuilder;
    /// let mut builder = DocBuilder::new();
    /// let mut obj_builder = builder.root_object_builder();
    ///
    /// obj_builder.put_bool("Test", true).unwrap();
    ///
    /// let doc = builder.build();
    /// assert_eq!(doc.root().query("Test").as_bool(), true);
    /// ```
    pub fn put_bool(&mut self, key: impl AsRef<str>, value: bool) -> anyhow::Result<()> {
        let symbol = self.symbols.find_or_create(key)?;
        self.insert_bool(symbol, value);

        Ok(())
    }

    /// Places bool value within the object being built using a `Symbol`which has been looked
    /// up previously.
    ///
    /// # Example
    /// ```
    /// # use jupiter::infograph::builder::DocBuilder;
    /// let mut builder = DocBuilder::new();
    /// let key = builder.resolve("Test").unwrap();
    /// let mut obj_builder = builder.root_object_builder();
    ///
    /// obj_builder.insert_bool(key, true);
    ///
    /// let doc = builder.build();
    /// assert_eq!(doc.root().query("Test").as_bool(), true);
    /// ```
    pub fn insert_bool(&mut self, key: Symbol, value: bool) {
        self.map.put(key, Node::Boolean(value));
    }

    /// Places a list value within the object being built. Returns the builder used to populate
    /// the list.
    ///
    /// # Errors
    /// If the internal symbol table overflows, an error is returned.
    ///
    /// # Example
    /// ```
    /// # use jupiter::infograph::builder::DocBuilder;
    /// let mut builder = DocBuilder::new();
    /// let mut obj_builder = builder.root_object_builder();
    ///
    /// let mut list_builder = obj_builder.put_list("Test").unwrap();
    /// list_builder.append_int(1);
    ///
    /// let doc = builder.build();
    /// assert_eq!(doc.root().query("Test").at(0).as_int().unwrap(), 1);
    /// ```
    pub fn put_list(&mut self, key: impl AsRef<str>) -> anyhow::Result<ListBuilder> {
        let symbol = self.symbols.find_or_create(key)?;
        Ok(self.insert_list(symbol))
    }

    /// Places a list value within the object being built using a `Symbol`which has been looked
    /// up previously. Returns the builder used to populate the list.   
    ///
    /// # Example
    /// ```
    /// # use jupiter::infograph::builder::DocBuilder;
    /// let mut builder = DocBuilder::new();
    /// let key = builder.resolve("Test").unwrap();
    /// let mut obj_builder = builder.root_object_builder();
    ///
    /// let mut list_builder = obj_builder.insert_list(key);
    /// list_builder.append_int(1);
    ///
    /// let doc = builder.build();
    /// assert_eq!(doc.root().query("Test").at(0).as_int().unwrap(), 1);
    /// ```
    pub fn insert_list(&mut self, key: Symbol) -> ListBuilder {
        self.map.put(key, Node::List(Vec::new()));
        if let Node::List(ref mut list) = self.map.get_mut(key).unwrap() {
            ListBuilder {
                symbols: self.symbols,
                list,
            }
        } else {
            unreachable!("Concurrent modification or corruption of the underlying map!")
        }
    }

    /// Places an inner object within the object being built. Returns the builder used to populate
    /// the list.
    ///
    /// # Errors
    /// If the internal symbol table overflows, an error is returned.
    ///
    /// # Example
    /// ```
    /// # use jupiter::infograph::builder::DocBuilder;
    /// let mut builder = DocBuilder::new();
    /// let mut obj_builder = builder.root_object_builder();
    ///
    /// let mut inner_obj_builder = obj_builder.put_object("Test").unwrap();
    /// inner_obj_builder.put_string("Foo", "Bar").unwrap();
    ///
    /// let doc = builder.build();
    /// assert_eq!(doc.root().query("Test.Foo").as_str().unwrap(), "Bar");
    /// ```
    pub fn put_object(&mut self, key: impl AsRef<str>) -> anyhow::Result<ObjectBuilder> {
        let symbol = self.symbols.find_or_create(key)?;
        Ok(self.insert_object(symbol))
    }

    /// Places an inner object within the object being built using a `Symbol`which has been looked
    /// up previously. Returns the builder used to populate the list.
    ///
    /// # Example
    /// ```
    /// # use jupiter::infograph::builder::DocBuilder;
    /// let mut builder = DocBuilder::new();
    /// let key = builder.resolve("Test").unwrap();
    /// let mut obj_builder = builder.root_object_builder();
    ///
    /// let mut inner_obj_builder = obj_builder.insert_object(key);
    /// inner_obj_builder.put_string("Foo", "Bar").unwrap();
    ///
    /// let doc = builder.build();
    /// assert_eq!(doc.root().query("Test.Foo").as_str().unwrap(), "Bar");
    /// ```
    pub fn insert_object(&mut self, key: Symbol) -> ObjectBuilder {
        self.map.put(key, Node::Object(SymbolMap::new()));
        if let Node::Object(ref mut map) = self.map.get_mut(key).unwrap() {
            ObjectBuilder {
                symbols: self.symbols,
                map,
            }
        } else {
            unreachable!("Concurrent modification or corruption of the underlying map!")
        }
    }
}

/// Builds an inner list within a `Doc` or another element.
///
/// A builder can either be obtained via [DocBuilder::root_list_builder](DocBuilder::root_list_builder)
/// or using either [ObjectBuilder::put_list](ObjectBuilder::put_list) - to place an inner
/// list in another or via [ListBuilder::append_list](ListBuilder::append_list) to add a
/// list as child element to a list.
pub struct ListBuilder<'a> {
    symbols: &'a mut SymbolTable,
    list: &'a mut Vec<Node>,
}

impl<'a> ListBuilder<'a> {
    /// Appends an integer value to the list being built.
    ///
    /// # Example
    /// ```
    /// # use jupiter::infograph::builder::DocBuilder;
    /// let mut builder = DocBuilder::new();
    /// let mut list_builder = builder.root_list_builder();
    ///
    /// list_builder.append_int(42);
    ///
    /// let doc = builder.build();
    /// assert_eq!(doc.root().at(0).as_int().unwrap(), 42);
    /// ```
    pub fn append_int(&mut self, value: i64) {
        self.list.push(Node::Integer(value));
    }

    /// Appends a string to the list being built.
    ///
    /// # Example
    /// ```
    /// # use jupiter::infograph::builder::DocBuilder;
    /// let mut builder = DocBuilder::new();
    /// let mut list_builder = builder.root_list_builder();
    ///
    /// list_builder.append_string("Test");
    ///
    /// let doc = builder.build();
    /// assert_eq!(doc.root().at(0).as_str().unwrap(), "Test");
    /// ```
    pub fn append_string(&mut self, value: impl AsRef<str>) {
        self.list.push(Node::from(value.as_ref()));
    }

    /// Appends a bool value to the list being built.
    ///
    /// # Example
    /// ```
    /// # use jupiter::infograph::builder::DocBuilder;
    /// let mut builder = DocBuilder::new();
    /// let mut list_builder = builder.root_list_builder();
    ///
    /// list_builder.append_bool(true);
    ///
    /// let doc = builder.build();
    /// assert_eq!(doc.root().at(0).as_bool(), true);    
    /// ```
    pub fn append_bool(&mut self, value: bool) {
        self.list.push(Node::Boolean(value));
    }

    /// Appends a child-list to the list being built. Returns the builder used to populate the list.
    ///
    /// Note that this will not join two lists but rather construct a list as child element and
    /// append further items to this child list.
    ///
    /// # Example
    /// ```
    /// # use jupiter::infograph::builder::DocBuilder;
    /// let mut builder = DocBuilder::new();
    /// let mut list_builder = builder.root_list_builder();
    ///
    /// let mut child_list_builder = list_builder.append_list();
    /// child_list_builder.append_int(42);
    ///
    /// let doc = builder.build();
    /// assert_eq!(doc.root().len(), 1);    
    /// assert_eq!(doc.root().at(0).len(), 1);    
    /// assert_eq!(doc.root().at(0).at(0).as_int().unwrap(), 42);
    /// ```
    pub fn append_list(&mut self) -> ListBuilder {
        self.list.push(Node::List(Vec::new()));
        if let Node::List(ref mut list) = self.list.last_mut().unwrap() {
            ListBuilder {
                symbols: self.symbols,
                list,
            }
        } else {
            unreachable!("Concurrent modification or corruption of the underlying list!")
        }
    }

    /// Appends a child object to the list being built. Returns the builder used to populate the
    /// object.
    ///
    /// # Example
    /// ```
    /// # use jupiter::infograph::builder::DocBuilder;
    /// let mut builder = DocBuilder::new();
    /// let mut list_builder = builder.root_list_builder();
    ///
    /// let mut obj_builder = list_builder.append_object();
    /// obj_builder.put_string("Foo", "Bar").unwrap();
    ///
    /// let doc = builder.build();
    /// assert_eq!(doc.root().len(), 1);    
    /// assert_eq!(doc.root().at(0).query("Foo").as_str().unwrap(), "Bar");
    /// ```
    pub fn append_object(&mut self) -> ObjectBuilder {
        self.list.push(Node::Object(SymbolMap::new()));
        if let Node::Object(ref mut map) = self.list.last_mut().unwrap() {
            ObjectBuilder {
                symbols: self.symbols,
                map,
            }
        } else {
            unreachable!("Concurrent modification or corruption of the underlying list!")
        }
    }
}