//! # SML //! //! SML is a simple markup language. It is designed to convert human readable information into //! Rust data-structures. The focus is on simplicity, usability and hands-on control (no magic). //! The format looks this, //! //! text //! hobbit: //! name: "Frodo Baggins" //! age: "98" //! friends: //! hobbit: //! name: "Bilbo Baggins" //! age: "176" //! hobbit: //! name: "Samwise Gamgee" //! age: "66" //! //! ## State of Progress //! //! Small was created for processing schemas and loading config files, where its better to //! manually specify conversion types. This becomes overly verbose when used for serializing and //! deserializing structs and enums, where data-structures tend to be nested within each other. //! The goal is to reduce this verbosity by using procedural macros, but no deadlines are set for //! this. //! //! ## Data Format Rules //! //! 1. Indentation has meaning and is 4 spaces, relative to the top key. //! //! 2. All values must be double quoted. //! //! 3. Every key/value combination must be nested in a key. For example //! rust //! hobbit: "Frodo" //! //! by itself is invalid. It can be written: //! rust //! hobbit: //! name: "Frodo" //! //! The motivation behind this is for the data format to distinguish clearly //! between whole data structures, which are headed by a key only, and parts of a //! data structure which are either key/value pairs, representing fields or //! variants, or other data-structures, which again are headed by a key only. //! //! 4. Separation of lines has meaning. //! //! 5. Keys may not include :. //! //! 6. Double quotes in values must be escaped using \". //! //! 7. Everything after the second double quote is ignored (and can be used for commenting). //! //! 8. Empty lines or lines with whitespace only are ignored. //! //! ## Basic Organization //! //! text //! --------------------------from_str()---------------------------- //! | | //! | --------path()-------- | //! | | | | //! | | FromSmall trait | | //! | | --from_small()-- | -----to_ref()---- --from_str()--- | //! | | | | | | | | | | //! v v v | | v | v | | //! ---------- ------------ --------- ---------- //! | Hobbit | | SmallRef |-ref into->| Small | | String | //! ---------- ------------ --------- ---------- //! ^ ^ | ^ //! | | | | //! ------------ to_small()----------------- --to_string()-- //! ToSmall trait //! //! //! ## Example 1: From Small-formatted string to your data-structure. //! //! The following two examples should cover 90 percent of use cases. //! data-structure. //! //! rust //! use small::{Small, FromSmall, SmallError}; //! //! #[derive(Debug)] //! struct Hobbit { //! name: String, //! age: u32, //! friends: Vec<Hobbit>, //! bicycle: Option<String>, //! } //! //! impl FromSmall for Hobbit { //! fn from_small(s: SmallRef) -> Result<Self, SmallError> { //! Ok(Self { //! name: String::path(&s, "hobbit::name")?, //! age: u32::path(&s, "hobbit::age")?, //! friends: Vec::<Hobbit>::path(&s, "hobbit::friends::hobbit")?, //! bicycle: Option::<String>::path(&s, "hobbit::bicycle")?, //! }) //! } //! } //! //! fn main() { //! let s = r#" //! hobbit: //! name: "Frodo Baggins" //! age: "98" //! friends: //! hobbit: //! name: "Bilbo Baggins" //! age: "176" //! hobbit: //! name: "Samwise Gamgee" //! age: "66""#; //! //! let frodo = Hobbit::from_str_debug(s); //! } //! //! //! Most standard-library types are implemented for FromSmall. To custom convert strings from //! Small values to your data-type, use from_val(s: &SmallRef, key_path: &str) which returns a //! Vec of Strings or from_unique_val(s: &SmallRef, key_path: &str) which provides a single //! String value. These can then be used in the FromSmall implementation for your //! data-structure. //! //! ## Example 2: From your data-structure to a Small-formatted string. //! //! To convert from a data-structure to a string, //! //! rust //! use sml::{Small, ToSmall, SmallError}; //! //! #[derive(Debug)] //! struct Hobbit { //! name: String, //! age: u32, //! friends: Vec<Hobbit>, //! bicycle: Option<String>, //! } //! //! impl ToSmall for Hobbit { //! fn to_small(&self, key: &str) -> Result<Small, SmallError> { //! Small::join("hobbit", &vec!( //! self.name.to_small("name")?, //! self.age.to_small("age")?, //! self.friends.to_small("friends")?, //! self.bicycle.to_small("bicycle")?, //! )) //! } //! } //! //! println!("{}", frodo::key("hobbit")); //! //! // hobbit: //! // name: "Frodo Baggins" //! // age: "98" //! // friends: //! // hobbit: //! // name: "Bilbo Baggins" //! // age: "176" //! // hobbit: //! // name: "Samwise Gamgee" //! // age: "66" //! //! ## Functions on Small //! //! rust //! join(key: &str, subs: &Vec<Small>) -> Result<Small, SmallError> //! //! //! Returns a Small type given a key and a Vec of Smalls. The Vec of Smalls are //! indented below the key. See example 2. //! //! rust //! key_value(key: &str, value: String) -> Result<Small, SmallError> //! //! //! Returns a Small type that consists of one key-value pair. //! //! rust //! to_ref(&self) -> SmallRef //! //! //! Converts self into a SmallRef. //! //! ## FromSmall Trait //! Types that implement the FromSmall trait can be constructed from a Small-formatted string. //! //! Required function: //! rust //! from_small(slice: &SmallRef) -> Result<Self, SmallError> //! //! The from_small() function describes how to create a data-structure from the parts of //! SmallRef. See example 1 for canonical usage. //! //! rust //! path(small: &SmallRef, key_path: &str) -> Result<Self, SmallError> //! //! Reduces SmallRef to the key_path and then uses the FromSmall trait to convert to the //! receiver type. //! //! rust //! from_str(s: &str) -> Result<Self, SmallError> //! //! Top level function that convert a Small-formatted string into the receiver. //! //! rust //! from_str_debug(s: &str) -> Self //! //! Top level function that converts a Small-formatted string into the receiver giving helpful //! error messages for debugging. //! //! ## ToSmall Trait //! The ToSmall trait is implemented for Strings, Vec<T>, Option<T>, bool and all the //! standard library integer and float types. //! //! Required function: //! rust //! fn to_small(&self, key: &str) -> Result<Small, SmallError>; //! //! Converts a receiver that implements ToSmall into a Small-formatted string. key can be //! overridden in the implementation, depending on whether you want to data-structure itself to //! set the key name or whether you want to context of the Small-formatted string to set the //! key name.