muon_rs/lib.rs
1// lib.rs muon crate.
2//
3// Copyright (c) 2019 Douglas Lau
4//
5#![forbid(unsafe_code)]
6#![deny(missing_docs)]
7//! # muon-rs
8//!
9//! A Rust library for the [MuON](https://github.com/muon-data/muon) data
10//! format, using [serde](https://serde.rs).
11//!
12//! ## Deserializing
13//!
14//! The easiest way to deserialize data is to derive [`serde::Deserialize`] on
15//! a struct. Then use one of the [`from_`](index.html#functions) functions.
16//!
17//! [`serde::Deserialize`]: https://docs.serde.rs/serde/trait.Deserialize.html
18//!
19//! ### Example
20//!
21//! MuON file:
22//! ```muon
23//! book: Pale Fire
24//! author: Vladimir Nabokov
25//! year: 1962
26//! character: John Shade
27//! location: New Wye
28//! character: Charles Kinbote
29//! location: Zembla
30//! book: The Curious Incident of the Dog in the Night-Time
31//! author: Mark Haddon
32//! year: 2003
33//! character: Christopher Boone
34//! location: Swindon
35//! character: Siobhan
36//! ```
37//!
38//! Rust code:
39//! ```rust
40//! # use serde::{Deserialize, Serialize};
41//! # use std::fs::File;
42//! #[derive(Debug, Deserialize, Serialize)]
43//! struct BookList {
44//! book: Vec<Book>,
45//! }
46//!
47//! #[derive(Debug, Deserialize, Serialize)]
48//! struct Book {
49//! title: String,
50//! author: String,
51//! year: Option<i16>,
52//! character: Vec<Character>,
53//! }
54//!
55//! #[derive(Debug, Deserialize, Serialize)]
56//! struct Character {
57//! name: String,
58//! location: Option<String>,
59//! }
60//!
61//! # fn main() -> Result<(), muon_rs::Error> {
62//! let muon = File::open("tests/books.muon")?;
63//! let books: BookList = muon_rs::from_reader(muon)?;
64//! println!("{:?}", books);
65//! # Ok(())
66//! # }
67//! ```
68//!
69//! ## Serializing
70//!
71//! Deriving [`serde::Serialize`] on a struct is just as easy. The
72//! [`to_`](index.html#functions) functions are used to serialize MuON data.
73//!
74//! [`serde::Serialize`]: https://docs.serde.rs/serde/trait.Serialize.html
75//!
76//! ### Example
77//!
78//! ```rust
79//! # use serde::Serialize;
80//! # use std::fs::File;
81//! # #[derive(Debug, Serialize)]
82//! # struct BookList {
83//! # book: Vec<Book>,
84//! # }
85//! # #[derive(Debug, Serialize)]
86//! # struct Book {
87//! # title: String,
88//! # author: String,
89//! # year: Option<i16>,
90//! # character: Vec<Character>,
91//! # }
92//! # #[derive(Debug, Serialize)]
93//! # struct Character {
94//! # name: String,
95//! # location: Option<String>,
96//! # }
97//! # fn main() -> Result<(), muon_rs::Error> {
98//! let books = BookList {
99//! book: vec![
100//! Book {
101//! title: "Flight".to_string(),
102//! author: "Sherman Alexie".to_string(),
103//! year: Some(2007),
104//! character: vec![
105//! Character {
106//! name: "Zits".to_string(),
107//! location: Some("Seattle".to_string()),
108//! },
109//! Character {
110//! name: "Justice".to_string(),
111//! location: None,
112//! },
113//! ],
114//! },
115//! ],
116//! };
117//! let muon = muon_rs::to_string(&books)?;
118//! println!("{:?}", muon);
119//! # Ok(())
120//! # }
121//! ```
122//!
123//! ## Types
124//!
125//! MuON types can be mapped to different Rust types.
126//!
127//! <table>
128//! <tr>
129//! <th>MuON Type</th>
130//! <th>Rust Types</th>
131//! </tr>
132//! <tr>
133//! <td>text</td>
134//! <td><a href="https://doc.rust-lang.org/std/string/struct.String.html">
135//! String</a>
136//! </td>
137//! </tr>
138//! <tr>
139//! <td>bool</td>
140//! <td><a href="https://doc.rust-lang.org/std/primitive.bool.html">bool</a>
141//! </td>
142//! </tr>
143//! <tr>
144//! <td>int</td>
145//! <td><a href="https://doc.rust-lang.org/std/primitive.i8.html">i8</a>
146//! <a href="https://doc.rust-lang.org/std/primitive.i16.html">i16</a>
147//! <a href="https://doc.rust-lang.org/std/primitive.i32.html">i32</a>
148//! <a href="https://doc.rust-lang.org/std/primitive.i64.html">i64</a>
149//! <a href="https://doc.rust-lang.org/std/primitive.i128.html">i128</a>
150//! <a href="https://doc.rust-lang.org/std/primitive.isize.html">isize</a>
151//! <a href="https://doc.rust-lang.org/std/primitive.u8.html">u8</a>
152//! <a href="https://doc.rust-lang.org/std/primitive.u16.html">u16</a>
153//! <a href="https://doc.rust-lang.org/std/primitive.u32.html">u32</a>
154//! <a href="https://doc.rust-lang.org/std/primitive.u64.html">u64</a>
155//! <a href="https://doc.rust-lang.org/std/primitive.u128.html">u128</a>
156//! <a href="https://doc.rust-lang.org/std/primitive.usize.html">usize</a>
157//! </td>
158//! </tr>
159//! <tr>
160//! <td>number</td>
161//! <td><a href="https://doc.rust-lang.org/std/primitive.f32.html">f32</a>
162//! <a href="https://doc.rust-lang.org/std/primitive.f64.html">f64</a>
163//! </td>
164//! </tr>
165//! <tr>
166//! <td>datetime</td>
167//! <td><a href="struct.DateTime.html">DateTime</a></td>
168//! </tr>
169//! <tr>
170//! <td>date</td>
171//! <td><a href="struct.Date.html">Date</a></td>
172//! </tr>
173//! <tr>
174//! <td>time</td>
175//! <td><a href="struct.Time.html">Time</a></td>
176//! </tr>
177//! <tr>
178//! <td>record</td>
179//! <td>struct implementing
180//! <a href="https://docs.serde.rs/serde/trait.Deserialize.html">
181//! Deserialize</a>
182//! </td>
183//! </tr>
184//! <tr>
185//! <td>dictionary</td>
186//! <td><a href="https://doc.rust-lang.org/std/collections/struct.HashMap.html">
187//! HashMap</a>
188//! </td>
189//! </tr>
190//! <tr>
191//! <td>any</td>
192//! <td><a href="enum.Value.html">Value</a></td>
193//! </tr>
194//! </table>
195//!
196mod common;
197mod datetime;
198mod de;
199mod error;
200mod lines;
201mod parse;
202mod schema;
203mod ser;
204
205pub use datetime::{Date, DateTime, Time, TimeOffset};
206pub use de::{from_reader, from_slice, from_str, Deserializer};
207pub use error::{Error, Result};
208pub use schema::Value;
209pub use ser::{to_string, to_vec, to_writer, Serializer};