Crate sml

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,

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

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

    hobbit: "Frodo"

by itself is invalid. It can be written:

    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

  ------------------------from_str()-------------------------
  | -------------path()--------------------                 |
  | |                                     |                 |
  | |  FromSmall trait                    |                 |
  | | --from_small()--  -- apply_path()-- | --from_str()--- |
  | | |              |  |               | | |             | |
  v v v              |  v               | | v             | |
--------          ----------           -------         ----------
|Hobbit|          |SmallRef|-ref into->|Small|         | String |
--------          ----------           -------         ----------
      ^                                 ^   |             ^
      |                                 |   |             |
      ------------to_small()-------------   --to_string()--
                 ToSmall trait

But most of the time, you can go directly from string to data-structure and back to string, ignoring the Small type in the middle. For example,

Example 1: From Small-formatted String to Your Data-structure.

The following two examples should cover 90 percent of use cases. data-structure.

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,

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"

Structs

Small	Small represents a string in Small data format.
SmallRef	SmallRef is a selection of Small.
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.

Enums

SmallError

Traits

FromSmall	Types that implement the FromSmall trait can be constructed from a Small-formatted string.
ToSmall	Types that implement the ToSmall trait can be converted to the Small.