ion

ion is a Rust crate for parsing section-based *.ion documents into strongly typed data structures.

Why Use `ion`?

Parse mixed documents containing section dictionaries and table rows.
Work with typed values (String, i64, f64, bool, arrays, dictionaries).
Keep stable output formatting and choose dictionary ordering backend.
Filter parsing by section when you only need part of a large file.

Installation

Default dictionary backend (BTreeMap):

[dependencies]
ion = "0.10.0"

Insertion-ordered dictionaries with IndexMap:

[dependencies]
ion = { version = "0.10.0", features = ["dictionary-indexmap"] }

Rust Quick Start

use ion::Ion;

let raw = r#"
    [HOTEL]
    name = "HOTEL"
    markets = ["PL", "DE"]

    [ROOMS]
    | code | capacity |
    |------|----------|
    | DBL  | 2        |
"#;

let ion: Ion = raw.parse().unwrap();

let hotel = ion.get("HOTEL").unwrap();
assert_eq!(
    Some("HOTEL"),
    hotel.get("name").and_then(|value| value.as_str())
);

let rooms = ion.get("ROOMS").unwrap();
assert_eq!(1, rooms.rows_without_header().len());

Parse only selected sections:

use ion::Ion;

let raw = r#"
    [IGNORED]
    key = "value"

    [KEPT]
    key = "kept"
"#;

let ion = Ion::from_str_filtered(raw, vec!["KEPT"]).unwrap();
assert!(ion.get("IGNORED").is_none());
assert!(ion.get("KEPT").is_some());

Backend Choice

Dictionary uses:

BTreeMap by default.
IndexMap with dictionary-indexmap.

This affects ordering in Value::Dictionary, section field serialization, and Ion::to_string().

Example Usage

The following examples demonstrate the flexibility and structure of *.ion files:

Basic Section

[CONTRACT]
id = "HOTEL001"
name = "Hotel001"
currency = "EUR"
active = true
markets = ["DE", "PL"]

Table Format

[DEF.MEAL]
| code | description |
|------|-------------|
| RO   | Room Only   |

[DEF.ROOM]
| code | description |      occ       |
|------|-------------|----------------|
| SGL  | Single      | P1:2 A1:1 C0:1 |
| DBL  | Double      | P2:3 A2:2 C0:1 |

Basic section with possible field types

[CONTRACT]
country = "Poland"                  // String
markets = ["PL", "DE", "UK"]        // Array
75042 = {                           // Dictionary
    view = "SV"                     // String
    loc  = ["M", "B"]               // Array
    dist = { beach_km = 4.1 }       // Dictionary
}

Complex document built from few sections

[CONTRACT]
country = "Poland"
markets = ["PL", "DE", "UK"]
75042 = {
    view = "SV"
    loc  = ["M", "B"]
    dist = { beach_km = 4.1 }
}

[RATE.PLAN]
|       dates       | code |  description   |    rooms    | rules |
|-------------------|------|----------------|-------------|-------|
| 20200512:20200514 | BAR  | Best available | SGL,DBL,APP |       |
| 20200601:20200614 | BBV  | Best Bar View  | DBL,APP     |       |

# A `key-value` and `table` section
[RATE.BASE]
enable = true
legend = {
    UN = "unit night"
    RO = "room only"
}
|       dates       | charge | room | occ | meal |  amt   |
|-------------------|--------|------|-----|------|--------|
| 20161122:20170131 | UN     | APP  | A2  | RO   | 250.00 |
| 20161122:20170131 | UN     | APP  | A4  | RO   | 450.00 |
| 20161122:20170131 | UN     | APP  | A6  | RO   | 650.00 |

Related Crates

ion-fmt: formatter library and CLI for Ion documents.

License

Licensed under the MIT license.

ion 0.10.0

ion

Why Use ion?