kefta 0.0.1

proc-macro for simplified attribute parsing
Documentation 
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

//! ## `Kefta`
//! a simple attribute parser
//!
//! ### Key Features
//! - derive macros for easily parsing structures
//! - built-in "decent" error messages
//! - build-in attribute parsing
//! - optional `syn` support
//!
//! ### Feature Toggles
//! - `literal` - literal parsing
//! - `util` - pre-made types and utility traits
//! - `syn` - syn support via `Syn<impl syn::Parse>`
//! 
//! ### Examples
//! ```
//! use kefta::{Attr, parse_attr};
//!
//! // derive `Attr` onto your struct
//! #[derive(Attr)]
//! struct MyAttrs {
//!     // a marker field,
//!     alive: bool,
//!
//!     // an optional field
//!     #[attr(optional)]
//!     name: Option<String>,
//!
//!     // a required field
//!     #[attr(required)]
//!     value: i32,
//!
//!     // a default field (defaults to 0)
//!     count: u32,
//!
//!     // a renamed field
//!     #[attr(optional, name="desc")]
//!     description: Option<String>,
//!
//!     // a field with an alias
//!     #[attr(alias="color")]
//!     colour: Option<String>,
//!
//!     // a field with multiple values
//!     #[attr(multiple)]
//!     jobs: Vec<String>,
//!
//!     // an optional, aliased field, with multiple values
//!     #[attr(multiple, optional, alias="chores")]
//!     tasks: Option<Vec<String>>,
//!     /* you get the point */
//! }
//!
//! // parse in your derive-macro
//! // * this uses the syn crate and `syn` feature
//! #[proc_macro_derive(Human, attributes(human))]
//! pub fn test_macro(item: TokenStream) -> TokenStream {
//!     // parse with `syn`
//!     let input = syn::parse_macro_input!(item as DeriveInput);
//!
//!     // parse the attributes with the `parse_attr!` macro
//!     // it contains a `return TokenStream`, so you don't have to handle errors.
//!     let attrs = parse_attr!(input.attrs => MyAttrs);
//!
//!     // print out one of our fields
//!     println!("Name:  {:?}", attrs.name);
//!
//!     TokenStream::new()
//! }
//!
//! ```
//!
//! You can use attributes like so
//! ```no_compile
//! #[derive(Human)]
//! #[human(name="Jimmy", value=10, alive)]
//! #[human(jobs="foo", jobs="bar", jobs="baz")]
//! pub struct Jimmy;
//! ```


mod parse;

pub use kefta_core::error;
pub use kefta_core::token;
pub use kefta_core::parse::{AttrValue};
pub use kefta_core::node::{AttrNode, AttrTree};
pub use kefta_core::structs::{AttrMap, AttrStruct, AttrParse};
#[cfg(any(feature = "syn", feature = "util"))]
pub use kefta_core::util;

/// attribute for creating attribute structures
///
/// - fields must implement (`AttrValue`)
/// - by default, fields are parsed as single nodes using `Default` if not present.
/// - a number of attributes can be used to change this behaviour
///
/// ```text
/// #[attr(required)]               a required marker or value (errors if not present)
/// #[attr(optional)]               explicit use of an optional value (`Option<T>`)
/// #[attr(multiple)]               parse multiple nodes (`Vec<T>`)
/// #[attr(container)]              parse an inner structure (`impl AttrStruct`)
///
/// #[attr(name="name")]            rename the field
/// #[attr(alias="b", alias="b")]   add an alias for the field
///
/// #[attr(with="path_to_func")]    parse the value with a function
/// ```
///
pub use kefta_macro::Attr;