serde_tokenstream/lib.rs
1// Copyright 2022 Oxide Computer Company
2
3//! This is a [`serde::Deserializer`] implementation for
4//! [`proc_macro2::TokenStream`]. It is intended for proc_macro builders who
5//! want rich configuration in their custom attributes.
6//!
7//! If you'd like the consumers of your macro use it like this:
8//!
9//! ```ignore
10//! #[my_macro {
11//! settings = {
12//! reticulate_splines = true,
13//! normalizing_power = false,
14//! },
15//! disaster = "pandemic",
16//! }]
17//! ```
18//!
19//! Your macro will start like this:
20//!
21//! ```ignore
22//! #[proc_macro_attribute]
23//! pub fn my_macro(
24//! attr: proc_macro::TokenStream,
25//! item: proc_macro::TokenStream,
26//! ) -> proc_macro::TokenStream {
27//! // ...
28//! # }
29//! ```
30//!
31//! Use `serde_tokenstream` to deserialize `attr` into a structure with the
32//! `Deserialize` trait (typically via a `derive` macro):
33//!
34//! ```
35//! # use proc_macro2::TokenStream;
36//! # use serde_tokenstream::from_tokenstream;
37//! # use serde::Deserialize;
38//! # #[derive(Deserialize)]
39//! # struct Config;
40//! # pub fn my_macro(
41//! # attr: proc_macro2::TokenStream,
42//! # item: proc_macro2::TokenStream,
43//! # ) -> proc_macro2::TokenStream {
44//! let config = match from_tokenstream::<Config>(&TokenStream::from(attr)) {
45//! Ok(c) => c,
46//! Err(err) => return err.to_compile_error().into(),
47//! };
48//! # item
49//! # }
50//! ```
51//!
52//! ## Nested attributes
53//!
54//! For attributes that are nested inside a top-level macro, use the
55//! [`from_tokenstream_spanned`] function. See its help for an example.
56
57mod ibidem;
58mod ordered_map;
59mod serde_tokenstream;
60
61pub use crate::ibidem::ParseWrapper;
62pub use crate::ibidem::TokenStreamWrapper;
63pub use crate::ordered_map::OrderedMap;
64pub use crate::serde_tokenstream::from_tokenstream;
65pub use crate::serde_tokenstream::from_tokenstream_spanned;
66pub use crate::serde_tokenstream::Error;
67pub use crate::serde_tokenstream::Result;