Skip to main content

dataport_macros/
lib.rs

1// Copyright © 2025 Stephan Kunz
2//! Macros for port and port collection creation.
3//!
4//! # Known issues
5//! dataport: port creation macros take `String::from(..)`, `x.clone()` and variables only as a `T`
6//!
7//! In the `create_*_entry!` macros (`dataport/macros/src/implementation.rs`) only a literal or a reference
8//! (e.g. `"42"`, `"{pointer}"`, `&String::from(..)`, `&var`) is checked for a port collection pointer
9//! or converted from a `str`/`String`.
10//!
11//! A value given directly as
12//! - a call, e.g. `String::from("{pointer}")`,
13//! - a method call, e.g. `x.clone()`,
14//! - a variable, e.g. `x`,
15//!
16//! falls through to `quote_from_type_value` and is used as the port's `T` as is.
17//! So it compiles only if the expression already has type `T`,
18//! it is neither parsed from a `str`/`String` nor resolved as a collection pointer.
19//!
20//! Workaround: pass a reference, e.g. `&String::from("{pointer}")` or `&x` for an `x` of type `&str` or `String`.
21
22#[doc(hidden)]
23extern crate proc_macro;
24
25mod implementation;
26
27use proc_macro::TokenStream;
28use syn::parse_macro_input;
29
30use crate::implementation::{Params, PortVariant, quote_collection, quote_entry};
31
32/// Creates the collection `kind` from `input`, reporting duplicate literal names as a compile error.
33fn collection(input: TokenStream, kind: &str) -> TokenStream {
34	quote_collection(input.into(), kind)
35		.unwrap_or_else(syn::Error::into_compile_error)
36		.into()
37}
38
39/// Creates a name/port pair of `variant` from `input`, reporting invalid input as a compile error.
40fn entry(input: TokenStream, variant: PortVariant, parseable: bool) -> TokenStream {
41	let params = parse_macro_input!(input as Params);
42	quote_entry(params, variant, parseable)
43		.unwrap_or_else(syn::Error::into_compile_error)
44		.into()
45}
46
47/// Creates a `dataport::PortArray` from a comma separated list of name/port pairs.
48///
49/// The result is a `Result`: the names have to be unique, a name given twice is a `dataport::Error::AlreadyExists`.
50/// A name given twice as a string literal is already a compile error.
51///
52/// # Usage
53/// ```text
54/// create_port_array!(<name/port pair>, ...)
55/// ```
56///
57/// The name/port pairs are best created with the entry macros:
58/// ```text
59/// create_port_array!(
60///     create_out_entry!(<name>, <type>, <value>),
61///     create_inout_entry!(<name>, <type>),
62///     create_in_entry!(<name>, <value>),
63///     create_out_entry_parseable!(<name>, <type>, <value>),
64///     create_inout_entry_parseable!(<name>, <type>),
65///     create_in_entry_parseable!(<name>, <value>),
66/// )
67/// ```
68#[proc_macro]
69pub fn create_port_array(input: TokenStream) -> TokenStream {
70	collection(input, "PortArray")
71}
72
73/// Creates a `dataport::PortVec` from a comma separated list of name/port pairs.
74///
75/// The result is a `Result`: the names have to be unique, a name given twice is a `dataport::Error::AlreadyExists`.
76/// A name given twice as a string literal is already a compile error.
77///
78/// # Usage
79/// ```text
80/// create_port_vec!(<name/port pair>, ...)
81/// ```
82///
83/// The name/port pairs are best created with the entry macros:
84/// ```text
85/// create_port_vec!(
86///     create_out_entry!(<name>, <type>, <value>),
87///     create_inout_entry!(<name>, <type>),
88///     create_in_entry!(<name>, <value>),
89///     create_out_entry_parseable!(<name>, <type>, <value>),
90///     create_inout_entry_parseable!(<name>, <type>),
91///     create_in_entry_parseable!(<name>, <value>),
92/// )
93/// ```
94#[proc_macro]
95pub fn create_port_vec(input: TokenStream) -> TokenStream {
96	collection(input, "PortVec")
97}
98
99/// Creates a `dataport::PortMap` from a comma separated list of name/port pairs.
100///
101/// The result is a `Result`: the names have to be unique, a name given twice is a `dataport::Error::AlreadyExists`.
102/// A name given twice as a string literal is already a compile error.
103///
104/// # Usage
105/// ```text
106/// create_port_map!(<name/port pair>, ...)
107/// ```
108///
109/// The name/port pairs are best created with the entry macros:
110/// ```text
111/// create_port_map!(
112///     create_out_entry!(<name>, <type>, <value>),
113///     create_inout_entry!(<name>, <type>),
114///     create_in_entry!(<name>, <value>),
115///     create_out_entry_parseable!(<name>, <type>, <value>),
116///     create_inout_entry_parseable!(<name>, <type>),
117///     create_in_entry_parseable!(<name>, <value>),
118/// )
119/// ```
120#[proc_macro]
121pub fn create_port_map(input: TokenStream) -> TokenStream {
122	collection(input, "PortMap")
123}
124
125/// Creates a name/port pair of an `In` port.
126///
127/// # Usage
128/// ```text
129/// create_in_entry!(<name>, <type>)
130/// create_in_entry!(<name>, <value>)
131/// create_in_entry!(<name>, <type>, <value>)
132/// create_in_entry!(<name>, <type>, <value>, <collection>)
133/// ```
134#[proc_macro]
135pub fn create_in_entry(input: TokenStream) -> TokenStream {
136	entry(input, PortVariant::In, false)
137}
138
139/// Creates a name/port pair of an `In` port with a `FromStr` setter.
140///
141/// # Usage
142/// ```text
143/// create_in_entry_parseable!(<name>, <type>)
144/// create_in_entry_parseable!(<name>, <value>)
145/// create_in_entry_parseable!(<name>, <type>, <value>)
146/// create_in_entry_parseable!(<name>, <type>, <value>, <collection>)
147/// ```
148#[proc_macro]
149pub fn create_in_entry_parseable(input: TokenStream) -> TokenStream {
150	entry(input, PortVariant::In, true)
151}
152
153/// Creates a name/port pair of an `InOut` port.
154///
155/// # Usage
156/// ```text
157/// create_inout_entry!(<name>, <type>)
158/// create_inout_entry!(<name>, <value>)
159/// create_inout_entry!(<name>, <type>, <value>)
160/// create_inout_entry!(<name>, <type>, <value>, <collection>)
161/// ```
162#[proc_macro]
163pub fn create_inout_entry(input: TokenStream) -> TokenStream {
164	entry(input, PortVariant::InOut, false)
165}
166
167/// Creates a name/port pair of an `InOut` port with a `FromStr` setter.
168///
169/// # Usage
170/// ```text
171/// create_inout_entry_parseable!(<name>, <type>)
172/// create_inout_entry_parseable!(<name>, <value>)
173/// create_inout_entry_parseable!(<name>, <type>, <value>)
174/// create_inout_entry_parseable!(<name>, <type>, <value>, <collection>)
175/// ```
176#[proc_macro]
177pub fn create_inout_entry_parseable(input: TokenStream) -> TokenStream {
178	entry(input, PortVariant::InOut, true)
179}
180
181/// Creates a name/port pair of an `Out` port.
182///
183/// # Usage
184/// ```text
185/// create_out_entry!(<name>, <type>)
186/// create_out_entry!(<name>, <value>)
187/// create_out_entry!(<name>, <type>, <value>)
188/// create_out_entry!(<name>, <type>, <value>, <collection>)
189/// ```
190#[proc_macro]
191pub fn create_out_entry(input: TokenStream) -> TokenStream {
192	entry(input, PortVariant::Out, false)
193}
194
195/// Creates a name/port pair of an `Out` port with a `FromStr` setter.
196///
197/// # Usage
198/// ```text
199/// create_out_entry_parseable!(<name>, <type>)
200/// create_out_entry_parseable!(<name>, <value>)
201/// create_out_entry_parseable!(<name>, <type>, <value>)
202/// create_out_entry_parseable!(<name>, <type>, <value>, <collection>)
203/// ```
204#[proc_macro]
205pub fn create_out_entry_parseable(input: TokenStream) -> TokenStream {
206	entry(input, PortVariant::Out, true)
207}