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 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179
#![warn(missing_docs)] #![doc(html_root_url = "https://docs.rs/serde_any/0.5.0")] //! # Serde Any //! //! Dynamic serialization and deserialization with the format chosen at runtime //! //! ## Reading from and writing to files //! //! ``` //! # use std::collections::HashMap; //! # use serde_any::{Format, Error}; //! # fn main() -> Result<(), Error> { //! let mut m = HashMap::new(); //! m.insert("a", "alpha"); //! m.insert("b", "beta"); //! //! // Serialize to a file, the format is inferred from the file extension //! serde_any::to_file("greek.toml", &m)?; //! //! // Deserialize from a file, the format is also inferred from the file extension //! let m2: HashMap<String, String> = serde_any::from_file("greek.toml")?; //! //! # std::fs::remove_file("greek.toml").unwrap(); //! # Ok(()) //! # } //! ``` //! //! ## Deserialization with a known format //! //! ``` //! # use std::collections::HashMap; //! # use serde_any::{Format, Error}; //! # fn main() -> Result<(), Error> { //! let d = r#"{"a": "alpha", "b": "beta"}"#; //! let m: HashMap<String, String> = serde_any::from_str(d, Format::Json)?; //! # assert_eq!(m.get("a"), Some(&"alpha".to_string())); //! # assert_eq!(m.get("b"), Some(&"beta".to_string())); //! # Ok(()) //! # } //! ``` //! //! If the deserialization format is known in advance, `serde_any` mirrors the API of //! [`serde_json`](https://docs.rs/serde_json) and [`serde_yaml`](https://docs.rs/serde_yaml). //! Namely, functions [`from_reader`], [`from_slice`] and //! [`from_str`] work in the same way as those in format-specific crates, except that they take an //! additional [`Format`] paramater specifying the deserialization format. The //! [`from_file`] function is provided as a convenience wrapper around //! [`from_reader`] for the common case of reading from a file. //! //! ## Deserialization by guessing //! //! ``` //! # use std::collections::HashMap; //! # fn main() -> Result<(), serde_any::Error> { //! let d = r#"{"a": "alpha", "b": "beta"}"#; //! let m: HashMap<String, String> = serde_any::from_str_any(d)?; //! # assert_eq!(m.get("a"), Some(&"alpha".to_string())); //! # assert_eq!(m.get("b"), Some(&"beta".to_string())); //! # Ok(()) //! # } //! ``` //! //! This crate also supports deserialization where the data format is not known in advance. //! There are three different ways of inferring the data format: //! * with [`from_file`], the format is deduced from the file extension. //! This is useful if a user can load a data file of any format. //! * with [`from_file_stem`], each filename with the given stem and a supported extension //! is checked. If any such file exists, its data is deserialized and returned. //! This is useful for configuration files with a known set of filenames. //! * with [`from_slice_any`] and [`from_str_any`], deserialization //! using each supported format is tried until one succeeds. //! This is useful when you receive data from an unknown source and don't know what format it is in. //! //! Note there is no corresponding `from_reader_any` function, as attempting to deserialize from a reader would //! consume its data. In order to deserialize from a [`io::Read`], read the data into a [`Vec<u8>`] or [`String`] and //! call [`from_slice_any`] or [`from_str_any`]. //! //! ## Serialization //! //! ``` //! # use std::collections::HashMap; //! # use serde_any::{Format, Error}; //! # fn main() -> Result<(), Error> { //! let mut m = HashMap::new(); //! m.insert("a", "alpha"); //! m.insert("b", "beta"); //! let s = serde_any::to_string(&m, Format::Yaml)?; //! # Ok(()) //! # } //! ``` //! //! For serialization, the data format must always be provided. //! Consistent with the format-specific crates, data may be serialized to a [`String`] with //! [`to_string`], to a [`Vec<u8>`] with [`to_vec`], or to a [`io::Write`] with //! [`to_writer`]. //! //! Alternatively, when writing to a file, the format can be inferred from the file name by the //! [`to_file`] function. Similarly to [`from_file`], this is most useful when //! saving to a user-selected file. //! //! All serialization functions have pretty printing variants with a `_pretty` suffix, such as //! [`to_string_pretty`]. However, not all formats support pretty printing. //! In such cases, the output from pretty printing functions will be identical to the output //! from serialization functions without pretty printing. //! //! ## Known limitations //! //! * Serialization to TOML requires that all non-table values come before any tables. //! See the [`toml::ser`] module documentation for details and workarounds. //! * The XML format cannot serialize sequences. //! //! [`Format`]: format/enum.Format.html //! [`from_reader`]: de/fn.from_reader.html //! [`from_slice`]: de/fn.from_slice.html //! [`from_str`]: de/fn.from_str.html //! [`from_file`]: de/fn.from_file.html //! [`from_file_stem`]: de/fn.from_file_stem.html //! [`from_slice_any`]: de/fn.from_slice_any.html //! [`from_str_any`]: de/fn.from_str_any.html //! [`to_string`]: ser/fn.to_string.html //! [`to_vec`]: ser/fn.to_vec.html //! [`to_writer`]: ser/fn.to_writer.html //! [`to_file`]: ser/fn.to_file.html //! [`String`]: https://doc.rust-lang.org/std/string/struct.String.html //! [`Vec<u8>`]: https://doc.rust-lang.org/std/vec/struct.Vec.html //! [`io::Read`]: https://doc.rust-lang.org/std/io/trait.Read.html //! [`io::Write`]: https://doc.rust-lang.org/std/io/trait.Write.html //! [`to_string_pretty`]: ser/fn.to_string_pretty.html //! [`toml::ser`]: https://docs.rs/toml/0.4.6/toml/ser/index.html //! #[macro_use] extern crate failure; extern crate serde; #[cfg(feature = "toml")] extern crate toml; #[cfg(feature = "json")] extern crate serde_json; #[cfg(feature = "yaml")] extern crate serde_yaml; #[cfg(feature = "ron")] extern crate ron; #[cfg(feature = "xml")] extern crate serde_xml_any; #[cfg(feature = "url")] extern crate serde_urlencoded; #[cfg(test)] #[macro_use] extern crate serde_derive; #[cfg(test)] #[macro_use] extern crate matches; mod backend; /// Contains the common error type pub mod error; pub use error::Error; /// Types and functions for specifying or determining serialization formats pub mod format; pub use format::*; /// Deserialize data to a Rust structure pub mod de; pub use de::*; /// Serialize a Rust structure to any data format pub mod ser; pub use ser::*;