diet_xml/

lib.rs

//! # diet-xml
//!
//! A schema-driven, ergonomic XML builder for Rust.
//!

//! ## Example
//! ```rust
//! use diet_xml::XmlBuilder;
//!
//! fn main() {
//!
//!     // example data
//!     let employees = vec![
//!         Employee { id: 1, first: "John", last: "Doe", dob: "1900-01-01" },
//!         Employee { id: 2, first: "Jane", last: "Doe", dob: "1800-12-31" },
//!         Employee { id: 3, first: "John", last: "Dough", dob: "1700-01-01" },
//!     ];
//!
//!     // create an XmlBuilder struct
//!
//!     // this is a struct that allows you build an xml output in memory
//!     let mut xb = XmlBuilder::new();
//!
//!     // define the schema you wish to populate in plain text
//!     xb.set_schema("
//!     <root>
//!         <employee>
//!             <name>
//!                 <first></first>
//!                 <last></last>
//!             </name>
//!             <info>
//!                 <dob></dob>
//!             </info>
//!         </employee>
//!         <passing_str_ok></passing_str_ok>
//!         <passing_i32_ok></passing_i32_ok>
//!         <name!2></name!2>   
//!     </root>");
//!
//!     // default header is <?xml version="1.0" encoding="UTF-8"?>
//!     // to remove all headers use xb.clear_header();
//!     // to set customer header use xb.set_header("your customer header, < > will be applied the the star/end automatically");
//!
//!     for e in employees{
//!
//!         // we want each id to relate to it's own employee element
//!         // so use the id as the key 
//!         // we can also chain into attributes to have the id display as an element attribute
//!       
//!         // these arguments can be anything that implments .to_string()
//!         // eg String, usize, &str, int
//!         // (element_the_key_is_on, key_value) 
//!         // this is to allow the other to quickly add values to elements
//!         // without needing boiler plate to convert to text where possible
//!
//!         xb.set_key("employee", e.id)
//!             .attribute("id", e.id);
//!
//!         // you can chain either an add_element or set_key into .attribute
//!         // this takes two arguments
//!         // these arguments can be anything that implments .to_string()
//!         // eg String, usize, &str, int
//!         // (attribute_name, attribute_value)
//!         // the .attributes() method can be used to add multiple attributes
//!         // this should be passed in the form
//!         // &[(&str,&str),(&str,&str),(&str,&str),(&str,&str)]
//!         // tuples pairs of &str with attribute name and value
//!         // attribute and attributes can be chained from add_element also
//!
//!         // now we simply add the element values we want populated
//!         // there is no need to build the entire structure
//!         // unlike other libraries the parent elements are implicitly built
//!         xb.add_element("first", e.first);
//!         xb.add_element("last", e.last);
//!
//!         // you can chain into the cdata() method to enclose an element in cdata tags
//!         xb.add_element("dob", e.dob).cdata();
//!
//!         // clears keys resets all context to a default value
//!         // this isn't necessary in this sample program
//!         // as keys are all overwritten on each iteration
//!         // keys retain their state until either overwritten or cleared
//!         xb.clear_keys();       
//!    }
//!
//!
//!     // passing any type that implements to_string as a value for
//!     // add_element, attribute(), set_key is ok
//!     xb.add_element("passing_str_ok", "some str");
//!     xb.add_element("passing_i32_ok", 111222333);
//!
//!     // duplicate element names should be distinguised by !AnyAlphaNumtext in the schema definition
//!     // the suffix will be remove when the XML is produced
//!     xb.add_element("name!2", "suffix !2 has been removed, this enables use of duplicate element names");
//!
//!    // builds the xml in the background
//!    xb.build_xml();
//!
//!
//!     // function .xml_out() returns string of the xml output
//!     println!("{}", xb.xml_out());
//! }
//!
//! struct Employee {
//!     id: usize,
//!     first: &'static str,
//!     last: &'static str,
//!     dob: &'static str,
//! }
//! ```

mod builder;
mod schema;

// Public facing API
pub struct XmlBuilder {
    builder: builder::Builder,
}

impl XmlBuilder {
    /// Overwrite the XML header (e.g., with a custom processing instruction)
    pub fn set_header(&mut self, header: &str) {
        self.builder.custom_header(header);
    }

    /// Clear all XML headers
    pub fn clear_header(&mut self) {
        self.builder.clear_headers();
    }
    pub fn new() -> Self {
        XmlBuilder {
            builder: builder::Builder::new(),
        }
    }

    pub fn set_schema(&mut self, txt_schema: &str) {
        self.builder.set_schema(txt_schema);
    }

    pub fn set_key<K: ToString>(&mut self, nm_element: &str, txt_key: K) -> ChainFromAdd {
        let key_string = txt_key.to_string();
        self.builder.set_key(nm_element, &key_string)
    }

    pub fn clear_keys(&mut self)  {
        self.builder.clear_key()
    }

    pub fn add_element<V: ToString>(&mut self, nm_element: &str, value_element: V) -> ChainFromAdd {
        let value_string = value_element.to_string();
        self.builder.add_element(nm_element, &value_string)
    }

    pub fn build_xml(&mut self) {
        self.builder.build_xml();
    }

    pub fn xml_out(&self) -> &str {
        &self.builder.xml_output
    }

    
    pub fn attributes(&mut self, attributes: &[(&str, &str)]) {

        self.attributes(attributes);   
    }

}

// Re-export ChainFromAdd so users can call .attributes()
pub use builder::ChainFromAdd;