1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87

#![warn(rust_2018_idioms, unreachable_pub)]
#![deny(elided_lifetimes_in_paths)]
#![forbid(unsafe_code)]

//! 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
//!
//!    ```rust
//!    # use serde::{Deserialize, Serialize};
//!    #[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:
//!
//!    ```rust
//!    # use serde::{Deserialize, Serialize};
//!    #[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:
//!
//!    ```rust
//!    # use serde::{Deserialize, Serialize};
//!    #[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:
//!
//!    ```rust
//!    serde_kicad_sexpr::untagged! {
//!        enum TextOrNumber {
//!            Text(String),
//!            Int(i32),
//!            Float(f32)
//!        }
//!    }
//!    ```
//!
//!  [`Serializer`]: serde::ser::Serializer
//!  [`Deserializer`]: serde::de::Deserializer
//!  [`untagged!`]: serde_kicad_sexpr::untagged

mod option;
#[macro_use]
mod untagged;

pub mod de;
#[doc(hidden)]
pub mod private;
pub mod ser;

pub use de::from_str;
pub use option::{deserialize_option, OptionDef as Option};
pub use ser::{to_string, to_string_pretty};