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};