[][src]Crate sml

SML

SML is a simple markup language. It is designed to convert human readable information into Rust data-structures.

Data Format

  1. Each line can either be just a key, for example
    key:

or it can be a key/value pair, for example

    key: "value"
  1. Indentation has meaning and is 4 spaces. The first key on the first line determines the alignment of indentation.

  2. All values must be double quoted.

  3. Every key/value pair must be nested in a key. For example

    hobbit: "Frodo"

by itself is invalid. It can be written:

    hobbit:
        name: "Frodo"

Thinking in terms of Rust data-structures, a key without a value represents a struct or an enum while a key/value pair represents a struct field or enum variant.

  1. Separation of lines has meaning.

  2. Keys may not include :.

  3. Double quotes in values must be escaped using \".

  4. There can be an arbitary amount of whitespace and returns before the first key and after the last key.

  5. Characters after the second double-quote in the value are ignored (so this space can be used for comments).

Example

Create a data-structure from a small-formatted string,

use sml::{Small, FromSmall, SmallError};

#[derive(Debug)]
struct Hobbit {
    name:    String,
    age:     u32,
    friends: Vec<Hobbit>,
    bicycle: Option<String>,
}
 
impl FromSmall for Hobbit {
    fn from_small(small: Small) -> Result<Self, SmallError> {
        Ok(Self {
            name:    String::sml(&small, "hobbit::name")?,
            age:     u32::sml(&small, "hobbit::age")?,
            friends: Vec::<Hobbit>::sml(&small, "hobbit::friends::hobbit")?,
            bicycle: Option::<String>::sml(&small, "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);
}

and create a small-formatted string from a data-structure,

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) -> Small {
        Small::key("hobbit")
            .append(self.name)
            .append(self.age)
            .append(self.friends)
            .append(self.bicycle);
    }
}

println!("{}", frodo::<ToSmall>::to_string());

// hobbit:
//     name:         "Frodo Baggins"
//     age:          "98"
//     friends:
//         hobbit:
//             name: "Bilbo Baggins"
//             age:  "176"
//         hobbit:
//             name: "Samwise Gamgee"
//             age:  "66"

Structs

Small

Small is an internal representation of the original input string, or part of the original string.

Token

The Token struct contains implementation details of a parsed line of the input String. Its not really part of the API, but gets passed around by SmallError and as such is public.

Tokens

Enums

SmallError

Traits

FromSmall

Data-structures that implement the FromSmall trait can be constructed from a small-formatted string.

ToSmall