Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/dtolnay/serde-yaml

Strongly typed YAML library for Rust
https://github.com/dtolnay/serde-yaml

rust serde yaml

Last synced: 2 months ago
JSON representation

Strongly typed YAML library for Rust

Awesome Lists containing this project

README 

        
Serde YAML

==========



[github](https://github.com/dtolnay/serde-yaml)

[crates.io](https://crates.io/crates/serde_yaml)

[docs.rs](https://docs.rs/serde_yaml)

[build status](https://github.com/dtolnay/serde-yaml/actions?query=branch%3Amaster)



Rust library for using the [Serde] serialization framework with data in [YAML]

file format. _(This project is no longer maintained.)_



[Serde]: https://github.com/serde-rs/serde

[YAML]: https://yaml.org/



## Dependency



```toml

[dependencies]

serde = "1.0"

serde_yaml = "0.9"

```



Release notes are available under [GitHub releases].



[GitHub releases]: https://github.com/dtolnay/serde-yaml/releases



## Using Serde YAML



[API documentation is available in rustdoc form][docs.rs] but the general idea

is:



[docs.rs]: https://docs.rs/serde_yaml



```rust

use std::collections::BTreeMap;



fn main() -> Result<(), serde_yaml::Error> {

    // You have some type.

    let mut map = BTreeMap::new();

    map.insert("x".to_string(), 1.0);

    map.insert("y".to_string(), 2.0);



    // Serialize it to a YAML string.

    let yaml = serde_yaml::to_string(&map)?;

    assert_eq!(yaml, "x: 1.0\ny: 2.0\n");



    // Deserialize it back to a Rust type.

    let deserialized_map: BTreeMap = serde_yaml::from_str(&yaml)?;

    assert_eq!(map, deserialized_map);

    Ok(())

}

```



It can also be used with Serde's derive macros to handle structs and enums

defined in your program.



```toml

[dependencies]

serde = { version = "1.0", features = ["derive"] }

serde_yaml = "0.9"

```



Structs serialize in the obvious way:



```rust

use serde::{Serialize, Deserialize};



#[derive(Debug, PartialEq, Serialize, Deserialize)]

struct Point {

    x: f64,

    y: f64,

}



fn main() -> Result<(), serde_yaml::Error> {

    let point = Point { x: 1.0, y: 2.0 };



    let yaml = serde_yaml::to_string(&point)?;

    assert_eq!(yaml, "x: 1.0\ny: 2.0\n");



    let deserialized_point: Point = serde_yaml::from_str(&yaml)?;

    assert_eq!(point, deserialized_point);

    Ok(())

}

```



Enums serialize using YAML's `!tag` syntax to identify the variant name.



```rust

use serde::{Serialize, Deserialize};



#[derive(Serialize, Deserialize, PartialEq, Debug)]

enum Enum {

    Unit,

    Newtype(usize),

    Tuple(usize, usize, usize),

    Struct { x: f64, y: f64 },

}



fn main() -> Result<(), serde_yaml::Error> {

    let yaml = "

        - !Newtype 1

        - !Tuple [0, 0, 0]

        - !Struct {x: 1.0, y: 2.0}

    ";

    let values: Vec = serde_yaml::from_str(yaml).unwrap();

    assert_eq!(values[0], Enum::Newtype(1));

    assert_eq!(values[1], Enum::Tuple(0, 0, 0));

    assert_eq!(values[2], Enum::Struct { x: 1.0, y: 2.0 });



    // The last two in YAML's block style instead:

    let yaml = "

        - !Tuple

          - 0

          - 0

          - 0

        - !Struct

          x: 1.0

          y: 2.0

    ";

    let values: Vec = serde_yaml::from_str(yaml).unwrap();

    assert_eq!(values[0], Enum::Tuple(0, 0, 0));

    assert_eq!(values[1], Enum::Struct { x: 1.0, y: 2.0 });



    // Variants with no data can be written using !Tag or just the string name.

    let yaml = "

        - Unit  # serialization produces this one

        - !Unit

    ";

    let values: Vec = serde_yaml::from_str(yaml).unwrap();

    assert_eq!(values[0], Enum::Unit);

    assert_eq!(values[1], Enum::Unit);



    Ok(())

}

```







#### License





Licensed under either of Apache License, Version

2.0 or MIT license at your option.










Unless you explicitly state otherwise, any contribution intentionally submitted

for inclusion in this crate by you, as defined in the Apache-2.0 license, shall

be dual licensed as above, without any additional terms or conditions.