1use heck::{ToSnakeCase as _, ToTitleCase as _};
2use proc_macro2::TokenStream;
3use quote::{ToTokens, quote};
4use syn::{Data, DeriveInput, LitStr, Token, parse_macro_input};
5
6/// Derive macro for the `SettingsUi` marker trait.
7///
8/// This macro automatically implements the `SettingsUi` trait for the annotated type.
9/// The `SettingsUi` trait is a marker trait used to indicate that a type can be
10/// displayed in the settings UI.
11///
12/// # Example
13///
14/// ```
15/// use settings_ui_macros::SettingsUi;
16///
17/// #[derive(SettingsUi)]
18/// #[settings_ui(group = "Standard")]
19/// struct MySettings {
20/// enabled: bool,
21/// count: usize,
22/// }
23/// ```
24#[proc_macro_derive(SettingsUi, attributes(settings_ui))]
25pub fn derive_settings_ui(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
26 let input = parse_macro_input!(input as DeriveInput);
27 let name = &input.ident;
28
29 // Handle generic parameters if present
30 let (impl_generics, ty_generics, where_clause) = input.generics.split_for_impl();
31
32 let mut group_name = Option::<String>::None;
33 let mut path_name = Option::<String>::None;
34
35 for attr in &input.attrs {
36 if attr.path().is_ident("settings_ui") {
37 attr.parse_nested_meta(|meta| {
38 if meta.path.is_ident("group") {
39 if group_name.is_some() {
40 return Err(meta.error("Only one 'group' path can be specified"));
41 }
42 meta.input.parse::<Token![=]>()?;
43 let lit: LitStr = meta.input.parse()?;
44 group_name = Some(lit.value());
45 } else if meta.path.is_ident("path") {
46 // todo(settings_ui) rely entirely on settings_key, remove path attribute
47 if path_name.is_some() {
48 return Err(meta.error("Only one 'path' can be specified, either with `path` in `settings_ui` or with `settings_key`"));
49 }
50 meta.input.parse::<Token![=]>()?;
51 let lit: LitStr = meta.input.parse()?;
52 path_name = Some(lit.value());
53 } else if meta.path.is_ident("render") {
54 // Just consume the tokens even if we don't use them here
55 meta.input.parse::<Token![=]>()?;
56 let _lit: LitStr = meta.input.parse()?;
57 }
58 Ok(())
59 })
60 .unwrap_or_else(|e| panic!("in #[settings_ui] attribute: {}", e));
61 } else if let Some(settings_key) = parse_setting_key_attr(attr) {
62 // todo(settings_ui) either remove fallback key or handle it here
63 if path_name.is_some() && settings_key.key.is_some() {
64 panic!("Both 'path' and 'settings_key' are specified. Must specify only one");
65 }
66 path_name = settings_key.key;
67 }
68 }
69
70 let doc_str = parse_documentation_from_attrs(&input.attrs);
71
72 let ui_item_fn_body = generate_ui_item_body(group_name.as_ref(), &input);
73
74 // todo(settings_ui): make group name optional, repurpose group as tag indicating item is group, and have "title" tag for custom title
75 let title = group_name.unwrap_or(input.ident.to_string().to_title_case());
76
77 let ui_entry_fn_body = map_ui_item_to_entry(
78 path_name.as_deref(),
79 &title,
80 doc_str.as_deref(),
81 quote! { Self },
82 );
83
84 let expanded = quote! {
85 impl #impl_generics settings::SettingsUi for #name #ty_generics #where_clause {
86 fn settings_ui_item() -> settings::SettingsUiItem {
87 #ui_item_fn_body
88 }
89
90 fn settings_ui_entry() -> settings::SettingsUiEntry {
91 #ui_entry_fn_body
92 }
93 }
94 };
95
96 proc_macro::TokenStream::from(expanded)
97}
98
99fn extract_type_from_option(ty: TokenStream) -> TokenStream {
100 match option_inner_type(ty.clone()) {
101 Some(inner_type) => inner_type,
102 None => ty,
103 }
104}
105
106fn option_inner_type(ty: TokenStream) -> Option<TokenStream> {
107 let ty = syn::parse2::<syn::Type>(ty).ok()?;
108 let syn::Type::Path(path) = ty else {
109 return None;
110 };
111 let segment = path.path.segments.last()?;
112 if segment.ident != "Option" {
113 return None;
114 }
115 let syn::PathArguments::AngleBracketed(args) = &segment.arguments else {
116 return None;
117 };
118 let arg = args.args.first()?;
119 let syn::GenericArgument::Type(ty) = arg else {
120 return None;
121 };
122 return Some(ty.to_token_stream());
123}
124
125fn map_ui_item_to_entry(
126 path: Option<&str>,
127 title: &str,
128 doc_str: Option<&str>,
129 ty: TokenStream,
130) -> TokenStream {
131 // todo(settings_ui): does quote! just work with options?
132 let path = token_stream_from_option(path);
133 let doc_str = token_stream_from_option(doc_str);
134 let item = ui_item_from_type(ty);
135 quote! {
136 settings::SettingsUiEntry {
137 title: #title,
138 path: #path,
139 item: #item,
140 documentation: #doc_str,
141 }
142 }
143}
144
145fn ui_item_from_type(ty: TokenStream) -> TokenStream {
146 let ty = extract_type_from_option(ty);
147 return trait_method_call(ty, quote! {settings::SettingsUi}, quote! {settings_ui_item});
148}
149
150fn trait_method_call(
151 ty: TokenStream,
152 trait_name: TokenStream,
153 method_name: TokenStream,
154) -> TokenStream {
155 // doing the <ty as settings::SettingsUi> makes the error message better:
156 // -> "#ty Doesn't implement settings::SettingsUi" instead of "no item "settings_ui_item" for #ty"
157 // it also ensures safety against name conflicts with the method name, and works for parameterized types such as `Vec<T>`,
158 // as the syntax for calling methods directly on parameterized types is `Vec::<T>::method_name()`,
159 // but `<Vec<T> as MyTrait>::method_name()` is valid so we don't have to worry about inserting the extra
160 // colons as appropriate
161 quote! {
162 <#ty as #trait_name>::#method_name()
163 }
164}
165
166// the default impl for `Option<T: ToTokens>` in quote!{} is to include T if it is Some, and include nothing if it is None
167// This function actually results in a `Some(T)` if the option is Some, and a `None` if the option is None
168fn token_stream_from_option<T: ToTokens>(option: Option<T>) -> TokenStream {
169 match option {
170 Some(value) => quote! { Some(#value) },
171 None => quote! { None },
172 }
173}
174
175fn generate_ui_item_body(group_name: Option<&String>, input: &syn::DeriveInput) -> TokenStream {
176 match (group_name, &input.data) {
177 (_, Data::Union(_)) => unimplemented!("Derive SettingsUi for Unions"),
178 (None, Data::Struct(_)) => quote! {
179 settings::SettingsUiItem::None
180 },
181 (Some(_), Data::Struct(data_struct)) => {
182 let parent_serde_attrs = parse_serde_attributes(&input.attrs);
183 item_group_from_fields(&data_struct.fields, &parent_serde_attrs)
184 }
185 (None, Data::Enum(data_enum)) => {
186 let serde_attrs = parse_serde_attributes(&input.attrs);
187 let render_as = parse_render_as(&input.attrs);
188 let length = data_enum.variants.len();
189
190 let mut variants = Vec::with_capacity(length);
191 let mut labels = Vec::with_capacity(length);
192
193 for variant in &data_enum.variants {
194 // todo(settings_ui): Can #[serde(rename = )] be on enum variants?
195 let ident = variant.ident.clone().to_string();
196 let variant_name = serde_attrs.rename_all.apply(&ident);
197 let title = variant_name.to_title_case();
198
199 variants.push(variant_name);
200 labels.push(title);
201 }
202
203 let is_not_union = data_enum.variants.iter().all(|v| v.fields.is_empty());
204 if is_not_union {
205 return match render_as {
206 RenderAs::ToggleGroup if length > 6 => {
207 panic!("Can't set toggle group with more than six entries");
208 }
209 RenderAs::ToggleGroup => {
210 quote! {
211 settings::SettingsUiItem::Single(settings::SettingsUiItemSingle::ToggleGroup{ variants: &[#(#variants),*], labels: &[#(#labels),*] })
212 }
213 }
214 RenderAs::Default => {
215 quote! {
216 settings::SettingsUiItem::Single(settings::SettingsUiItemSingle::DropDown{ variants: &[#(#variants),*], labels: &[#(#labels),*] })
217 }
218 }
219 };
220 }
221 // else: Union!
222 let enum_name = &input.ident;
223
224 let options = data_enum.variants.iter().map(|variant| {
225 if variant.fields.is_empty() {
226 return quote! {None};
227 }
228 let name = &variant.ident;
229 let item = item_group_from_fields(&variant.fields, &serde_attrs);
230 let documentation =
231 token_stream_from_option(parse_documentation_from_attrs(&variant.attrs));
232 return quote! {
233 Some(settings::SettingsUiEntry {
234 path: None,
235 title: stringify!(#name),
236 documentation: #documentation,
237 item: #item,
238 })
239 };
240 });
241 let defaults = data_enum.variants.iter().map(|variant| {
242 let variant_name = &variant.ident;
243 if variant.fields.is_empty() {
244 quote! {
245 serde_json::to_value(#enum_name::#variant_name).expect("Failed to serialize default value for #enum_name::#variant_name")
246 }
247 } else {
248 let fields = variant.fields.iter().enumerate().map(|(index, field)| {
249 let field_name = field.ident.as_ref().map_or_else(|| syn::Index::from(index).into_token_stream(), |ident| ident.to_token_stream());
250 let field_type = &field.ty;
251 let field_type_is_option = option_inner_type(field_type.to_token_stream()).is_some();
252 let field_default = if field_type_is_option {
253 quote! {
254 None
255 }
256 } else {
257 quote! {
258 ::std::default::Default::default()
259 }
260 };
261
262 quote!{
263 #field_name: #field_default
264 }
265 });
266 quote! {
267 serde_json::to_value(#enum_name::#variant_name {
268 #(#fields),*
269 }).expect("Failed to serialize default value for #enum_name::#variant_name")
270 }
271 }
272 });
273 // todo(settings_ui): Identify #[default] attr and use it for index, defaulting to 0
274 let default_variant_index: usize = 0;
275 let determine_option_fn = {
276 let match_arms = data_enum
277 .variants
278 .iter()
279 .enumerate()
280 .map(|(index, variant)| {
281 let variant_name = &variant.ident;
282 quote! {
283 Ok(#variant_name {..}) => #index
284 }
285 });
286 quote! {
287 |value: &serde_json::Value, _cx: &gpui::App| -> usize {
288 use #enum_name::*;
289 match serde_json::from_value::<#enum_name>(value.clone()) {
290 #(#match_arms),*,
291 Err(_) => #default_variant_index,
292 }
293 }
294 }
295 };
296 // todo(settings_ui) should probably always use toggle group for unions, dropdown makes less sense
297 return quote! {
298 settings::SettingsUiItem::Union(settings::SettingsUiItemUnion {
299 defaults: Box::new([#(#defaults),*]),
300 labels: &[#(#labels),*],
301 options: Box::new([#(#options),*]),
302 determine_option: #determine_option_fn,
303 })
304 };
305 }
306 (_, Data::Enum(_)) => quote! {
307 settings::SettingsUiItem::None
308 },
309 }
310}
311
312fn item_group_from_fields(fields: &syn::Fields, parent_serde_attrs: &SerdeOptions) -> TokenStream {
313 let group_items = fields
314 .iter()
315 .filter(|field| {
316 let mut has_skip = false;
317 for attr in &field.attrs {
318 if attr.path().is_ident("settings_ui") {
319 let _ = attr.parse_nested_meta(|meta| {
320 if meta.path.is_ident("skip") {
321 has_skip = true;
322 }
323 Ok(())
324 });
325 }
326 }
327
328 !has_skip
329 })
330 .map(|field| {
331 let field_serde_attrs = parse_serde_attributes(&field.attrs);
332 let name = field.ident.as_ref().map(ToString::to_string);
333 let title = name.as_ref().map_or_else(
334 || "todo(settings_ui): Titles for tuple fields".to_string(),
335 |name| name.to_title_case(),
336 );
337 let doc_str = parse_documentation_from_attrs(&field.attrs);
338
339 (
340 title,
341 doc_str,
342 // todo(settings_ui): Have apply_rename_to_field take flatten into account
343 name.filter(|_| !field_serde_attrs.flatten).map(|name| {
344 parent_serde_attrs.apply_rename_to_field(&field_serde_attrs, &name)
345 }),
346 field.ty.to_token_stream(),
347 )
348 })
349 // todo(settings_ui): Re-format field name as nice title, and support setting different title with attr
350 .map(|(title, doc_str, path, ty)| {
351 map_ui_item_to_entry(path.as_deref(), &title, doc_str.as_deref(), ty)
352 });
353
354 quote! {
355 settings::SettingsUiItem::Group(settings::SettingsUiItemGroup{ items: Box::new([#(#group_items),*]) })
356 }
357}
358
359struct SerdeOptions {
360 rename_all: SerdeRenameAll,
361 rename: Option<String>,
362 flatten: bool,
363 untagged: bool,
364 _alias: Option<String>, // todo(settings_ui)
365}
366
367#[derive(PartialEq)]
368enum SerdeRenameAll {
369 Lowercase,
370 SnakeCase,
371 None,
372}
373
374impl SerdeRenameAll {
375 fn apply(&self, name: &str) -> String {
376 match self {
377 SerdeRenameAll::Lowercase => name.to_lowercase(),
378 SerdeRenameAll::SnakeCase => name.to_snake_case(),
379 SerdeRenameAll::None => name.to_string(),
380 }
381 }
382}
383
384impl SerdeOptions {
385 fn apply_rename_to_field(&self, field_options: &Self, name: &str) -> String {
386 // field renames take precedence over struct rename all cases
387 if let Some(rename) = &field_options.rename {
388 return rename.clone();
389 }
390 return self.rename_all.apply(name);
391 }
392}
393
394enum RenderAs {
395 ToggleGroup,
396 Default,
397}
398
399fn parse_render_as(attrs: &[syn::Attribute]) -> RenderAs {
400 let mut render_as = RenderAs::Default;
401
402 for attr in attrs {
403 if !attr.path().is_ident("settings_ui") {
404 continue;
405 }
406
407 attr.parse_nested_meta(|meta| {
408 if meta.path.is_ident("render") {
409 meta.input.parse::<Token![=]>()?;
410 let lit = meta.input.parse::<LitStr>()?.value();
411
412 if lit == "toggle_group" {
413 render_as = RenderAs::ToggleGroup;
414 } else {
415 return Err(meta.error(format!("invalid `render` attribute: {}", lit)));
416 }
417 }
418 Ok(())
419 })
420 .unwrap();
421 }
422
423 render_as
424}
425
426fn parse_serde_attributes(attrs: &[syn::Attribute]) -> SerdeOptions {
427 let mut options = SerdeOptions {
428 rename_all: SerdeRenameAll::None,
429 rename: None,
430 flatten: false,
431 untagged: false,
432 _alias: None,
433 };
434
435 for attr in attrs {
436 if !attr.path().is_ident("serde") {
437 continue;
438 }
439 attr.parse_nested_meta(|meta| {
440 if meta.path.is_ident("rename_all") {
441 meta.input.parse::<Token![=]>()?;
442 let lit = meta.input.parse::<LitStr>()?.value();
443
444 if options.rename_all != SerdeRenameAll::None {
445 return Err(meta.error("duplicate `rename_all` attribute"));
446 } else if lit == "lowercase" {
447 options.rename_all = SerdeRenameAll::Lowercase;
448 } else if lit == "snake_case" {
449 options.rename_all = SerdeRenameAll::SnakeCase;
450 } else {
451 return Err(meta.error(format!("invalid `rename_all` attribute: {}", lit)));
452 }
453 // todo(settings_ui): Other options?
454 } else if meta.path.is_ident("flatten") {
455 options.flatten = true;
456 } else if meta.path.is_ident("rename") {
457 if options.rename.is_some() {
458 return Err(meta.error("Can only have one rename attribute"));
459 }
460
461 meta.input.parse::<Token![=]>()?;
462 let lit = meta.input.parse::<LitStr>()?.value();
463 options.rename = Some(lit);
464 } else if meta.path.is_ident("untagged") {
465 options.untagged = true;
466 }
467 Ok(())
468 })
469 .unwrap();
470 }
471
472 return options;
473}
474
475fn parse_documentation_from_attrs(attrs: &[syn::Attribute]) -> Option<String> {
476 let mut doc_str = Option::<String>::None;
477 for attr in attrs {
478 if attr.path().is_ident("doc") {
479 // /// ...
480 // becomes
481 // #[doc = "..."]
482 use syn::{Expr::Lit, ExprLit, Lit::Str, Meta, MetaNameValue};
483 if let Meta::NameValue(MetaNameValue {
484 value:
485 Lit(ExprLit {
486 lit: Str(ref lit_str),
487 ..
488 }),
489 ..
490 }) = attr.meta
491 {
492 let doc = lit_str.value();
493 let doc_str = doc_str.get_or_insert_default();
494 doc_str.push_str(doc.trim());
495 doc_str.push('\n');
496 }
497 }
498 }
499 return doc_str;
500}
501
502struct SettingsKey {
503 key: Option<String>,
504 fallback_key: Option<String>,
505}
506
507fn parse_setting_key_attr(attr: &syn::Attribute) -> Option<SettingsKey> {
508 if !attr.path().is_ident("settings_key") {
509 return None;
510 }
511
512 let mut settings_key = SettingsKey {
513 key: None,
514 fallback_key: None,
515 };
516
517 let mut found_none = false;
518
519 attr.parse_nested_meta(|meta| {
520 if meta.path.is_ident("None") {
521 found_none = true;
522 } else if meta.path.is_ident("key") {
523 if settings_key.key.is_some() {
524 return Err(meta.error("Only one 'group' path can be specified"));
525 }
526 meta.input.parse::<Token![=]>()?;
527 let lit: LitStr = meta.input.parse()?;
528 settings_key.key = Some(lit.value());
529 } else if meta.path.is_ident("fallback_key") {
530 if found_none {
531 return Err(meta.error("Cannot specify 'fallback_key' and 'None'"));
532 }
533
534 if settings_key.fallback_key.is_some() {
535 return Err(meta.error("Only one 'fallback_key' can be specified"));
536 }
537
538 meta.input.parse::<Token![=]>()?;
539 let lit: LitStr = meta.input.parse()?;
540 settings_key.fallback_key = Some(lit.value());
541 }
542 Ok(())
543 })
544 .unwrap_or_else(|e| panic!("in #[settings_key] attribute: {}", e));
545
546 if found_none && settings_key.fallback_key.is_some() {
547 panic!("in #[settings_key] attribute: Cannot specify 'None' and 'fallback_key'");
548 }
549 if found_none && settings_key.key.is_some() {
550 panic!("in #[settings_key] attribute: Cannot specify 'None' and 'key'");
551 }
552 if !found_none && settings_key.key.is_none() {
553 panic!("in #[settings_key] attribute: 'key' must be specified");
554 }
555
556 return Some(settings_key);
557}
558
559#[proc_macro_derive(SettingsKey, attributes(settings_key))]
560pub fn derive_settings_key(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
561 let input = parse_macro_input!(input as DeriveInput);
562 let name = &input.ident;
563
564 // Handle generic parameters if present
565 let (impl_generics, ty_generics, where_clause) = input.generics.split_for_impl();
566
567 let mut settings_key = Option::<SettingsKey>::None;
568
569 for attr in &input.attrs {
570 let parsed_settings_key = parse_setting_key_attr(attr);
571 if parsed_settings_key.is_some() && settings_key.is_some() {
572 panic!("Duplicate #[settings_key] attribute");
573 }
574 settings_key = settings_key.or(parsed_settings_key);
575 }
576
577 let Some(SettingsKey { key, fallback_key }) = settings_key else {
578 panic!("Missing #[settings_key] attribute");
579 };
580
581 let key = token_stream_from_option(key);
582 let fallback_key = token_stream_from_option(fallback_key);
583
584 let expanded = quote! {
585 impl #impl_generics settings::SettingsKey for #name #ty_generics #where_clause {
586 const KEY: Option<&'static str> = #key;
587
588 const FALLBACK_KEY: Option<&'static str> = #fallback_key;
589 };
590 };
591
592 proc_macro::TokenStream::from(expanded)
593}
594
595#[cfg(test)]
596mod tests {
597 use syn::{Attribute, parse_quote};
598
599 use super::*;
600
601 #[test]
602 fn test_extract_key() {
603 let input: Attribute = parse_quote!(
604 #[settings_key(key = "my_key")]
605 );
606 let settings_key = parse_setting_key_attr(&input).unwrap();
607 assert_eq!(settings_key.key, Some("my_key".to_string()));
608 assert_eq!(settings_key.fallback_key, None);
609 }
610
611 #[test]
612 fn test_empty_key() {
613 let input: Attribute = parse_quote!(
614 #[settings_key(None)]
615 );
616 let settings_key = parse_setting_key_attr(&input).unwrap();
617 assert_eq!(settings_key.key, None);
618 assert_eq!(settings_key.fallback_key, None);
619 }
620}