#s-expr #serialization #kicad

serde_kicad_sexpr

KiCAD v6 S-Expression Format

1 unstable release

0.1.0 Jan 15, 2022

#1046 in Encoding

Apache-2.0 OR LGPL-3.0

59KB
2K SLoC

serde_kicad_sexpr License Apache-2.0 License LGPL-3.0 GitHub

This crate provides a serde Serializer and Deserializer implementation for the S-Expression data format used by KiCAD. Since this format differs in some central aspects from other formats like JSON, there are some limitations and special cases you should be aware of:

  • The name of your struct matters. For a simple struct like

    #[derive(Deserialize, Serialize)]
    struct Point(i32, i32);
    

    and an example value Point(1, 2) you will get a JSON representation of [1, 2] whereas this crate will output (Point 1 2).

  • The name of the fields also matters if the field’s type is either a boolean, a tuple or a sequence. These fields cannot appear in unnamed containers (i.e. tuple structs).

  • Deserializing Option is not supported, because we need to know the type inside the option to determine if it is present or missing. To deserialize optional values, use the custom deserializing logic from this crate:

    #[derive(Deserialize, Serialize)]
    struct Position {
        x: i32,
        y: i32,
        #[serde(with = "serde_kicad_sexpr::Option")]
        rotation: Option<i32>
    }
    
  • If you need to deserialize some sort of container with an unknown number of children, use a special field with an empty name, like so:

    #[derive(Deserialize, Serialize)]
    struct Point(i32, i32);
    
    #[derive(Deserialize, Serialize)]
    struct Polygon {
        #[serde(default, rename = "")]
        points: Vec<Point>
    }
    

    Note that this has to be the last field of the struct. There must not be any fields after a field with an empty name, and there must only be one field with an empty name.

  • Untagged enums are not supported. If you need to parse one from a number of types, use the untagged! macro:

    serde_kicad_sexpr::untagged! {
        enum TextOrNumber {
            Text(String),
            Int(i32),
            Float(f32)
        }
    }
    

License

Licensed under either of Apache License, Version 2.0 or Lesser GNU General Public License, Version 3.0 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.

Dependencies

~0.5–1.6MB
~35K SLoC