♻️ (config): Ajustes con #[settings] al arrancar

- Nuevo atributo `#[settings]`: valores por defecto en los campos (tipos
  comprobados al compilar y documentados); claves desconocidas y valores
  no válidos rechazados. Sustituye a `include_config!`, que se elimina.
- `LazySettings<T>::new()` declara los ajustes de una sección, y
  `Extension::settings()` los carga al arrancar, en orden; un error de
  configuración o una sección reclamada dos veces detiene el arranque.
- Aviso de secciones que no corresponden a ninguna extensión.
- Bootsier: [dev] bootsier_static_dir pasa a [bootsier] static_dir.
This commit is contained in:
Manuel Cillero 2026-10-12 21:41:01 +02:00
parent 8a7a827259
commit 728a5c83dc
32 changed files with 918 additions and 488 deletions

View file

@ -36,6 +36,7 @@ cada proyecto PageTop.
mod builder;
mod maud;
mod settings;
mod smart_default;
use proc_macro::TokenStream;
@ -114,6 +115,49 @@ pub fn derive_auto_default(input: TokenStream) -> TokenStream {
}
}
/// Macro (*attribute*) que convierte una estructura en ajustes de configuración.
///
/// Los valores por defecto se declaran en los propios campos, con `#[default = valor]` o
/// `#[default(expresión)]`, igual que en [`AutoDefault`](macro@AutoDefault). Los campos sin valor
/// por defecto toman el de su tipo (`None` en un `Option<T>`, o los de otra estructura de ajustes
/// anidada).
///
/// La macro añade a la estructura:
///
/// - `#[derive(AutoDefault, Debug, Deserialize)]`, por lo que no hay que derivarlos de nuevo
/// (hacerlo daría un error de implementación duplicada).
/// - `#[serde(default, deny_unknown_fields)]`: las claves ausentes toman su valor por defecto y una
/// clave desconocida (p. ej. una errata) es un error al cargar la configuración.
/// - Una línea con el valor por defecto en la documentación de cada campo que lo declare.
///
/// Con `section = "nombre"` la estructura corresponde a esa sección del archivo de configuración y
/// sus ajustes se declaran con `pagetop::config::LazySettings`. Sin ella, es una subsección que
/// forma parte de otra estructura de ajustes.
///
/// # Ejemplo
///
/// ```rust,ignore
/// #[settings(section = "blog")]
/// pub struct BlogSettings {
/// /// Título del blog.
/// #[default = "Mi Blog"]
/// pub title: String,
/// /// Comentarios, en la subsección `[blog.comments]`.
/// pub comments: CommentsSettings,
/// }
///
/// #[settings]
/// pub struct CommentsSettings {
/// /// Si se admiten comentarios.
/// #[default = true]
/// pub enabled: bool,
/// }
/// ```
#[proc_macro_attribute]
pub fn settings(attr: TokenStream, item: TokenStream) -> TokenStream {
settings::expand(attr.into(), item.into()).into()
}
/// Macro (*attribute*) que asocia un método *builder* `with_` con un método `alter_`.
///
/// La macro añade automáticamente un método `alter_` que permite modificar la instancia actual

View file

@ -0,0 +1,114 @@
use proc_macro2::TokenStream;
use quote::{ToTokens, quote};
use syn::{Attribute, Expr, Fields, ItemStruct, LitStr, Meta};
pub fn expand(attr: TokenStream, item: TokenStream) -> TokenStream {
match try_expand(attr, item) {
Ok(output) => output,
Err(error) => error.to_compile_error(),
}
}
fn try_expand(attr: TokenStream, item: TokenStream) -> syn::Result<TokenStream> {
let mut section: Option<LitStr> = None;
let parser = syn::meta::parser(|meta| {
if meta.path.is_ident("section") {
let name: LitStr = meta.value()?.parse()?;
if name.value().trim().is_empty() {
return Err(syn::Error::new_spanned(
&name,
"the section name cannot be empty",
));
}
section = Some(name);
Ok(())
} else {
Err(meta.error("expected `section = \"...\"`"))
}
});
syn::parse::Parser::parse2(parser, attr)?;
let mut item: ItemStruct = syn::parse2(item)?;
if !item.generics.params.is_empty() {
return Err(syn::Error::new_spanned(
&item.generics,
"`#[settings]` does not support generic structs",
));
}
let Fields::Named(fields) = &mut item.fields else {
return Err(syn::Error::new_spanned(
&item.ident,
"`#[settings]` requires a struct with named fields",
));
};
for field in &mut fields.named {
if let Some(shown) = default_value_doc(&field.attrs)? {
let has_doc = field.attrs.iter().any(|a| a.path().is_ident("doc"));
let line = format!(" Por defecto: `{shown}`.");
if has_doc {
field.attrs.push(syn::parse_quote!(#[doc = ""]));
}
field.attrs.push(syn::parse_quote!(#[doc = #line]));
}
}
let ident = &item.ident;
let section_impl = section.map(|section| {
quote! {
impl ::pagetop::config::SettingsSection for #ident {
const SECTION: &'static str = #section;
}
}
});
Ok(quote! {
#[derive(::pagetop::AutoDefault, ::core::fmt::Debug, ::pagetop::serde::Deserialize)]
#[serde(crate = "::pagetop::serde", default, deny_unknown_fields)]
#item
#section_impl
})
}
// Texto con el valor por defecto de un campo para su documentación, si tiene `#[default = ...]` o
// `#[default(...)]`. De una ruta (p. ej. `LogRolling::Stdout`) se muestra sólo el último segmento,
// que es el valor que se escribe en el archivo de configuración.
fn default_value_doc(attrs: &[Attribute]) -> syn::Result<Option<String>> {
let Some(attr) = attrs.iter().find(|a| a.path().is_ident("default")) else {
return Ok(None);
};
let expr: Expr = match &attr.meta {
Meta::NameValue(name_value) => name_value.value.clone(),
Meta::List(list) => match list.parse_args::<Expr>() {
Ok(expr) => expr,
// Formas que `AutoDefault` admite pero que no son una expresión (p. ej. `_code = ...`).
Err(_) => return Ok(None),
},
Meta::Path(_) => return Ok(None),
};
let shown = match &expr {
Expr::Path(path) => path
.path
.segments
.last()
.map(|segment| segment.ident.to_string())
.unwrap_or_default(),
other => compact(&other.to_token_stream().to_string()),
};
Ok(Some(shown))
}
// Quita los espacios que `quote` deja entre los elementos de una expresión (p. ej.
// `UnitValue :: Px (1440)` -> `UnitValue::Px(1440)`, o `- 1` -> `-1`).
fn compact(tokens: &str) -> String {
let compacted = tokens
.replace(" :: ", "::")
.replace(" (", "(")
.replace("( ", "(")
.replace(" )", ")")
.replace(" ,", ",");
match compacted.strip_prefix("- ") {
Some(rest) => format!("-{rest}"),
None => compacted,
}
}

View file

@ -52,12 +52,12 @@ pub use pastey::paste;
// La documentación anterior se copia en `pagetop::util::paste!` porque el *crate* original no la
// define y `pagetop` no la hereda automáticamente.
/// Concatena varios fragmentos en un [`String`] reservando una sola vez la memoria del resultado.
/// Concatena varios fragmentos en un [`String`].
///
/// Acepta uno o más fragmentos que implementen [`AsRef<str>`] (literales, `&str`, [`String`],
/// `Cow<str>`...) y construye el resultado con la capacidad exacta, sin pasar por el formateo. Es
/// la forma preferida de componer texto a partir de fragmentos, y suele ser más rápida que
/// `format!`.
/// `Cow<str>`...) y construye el resultado reservando la memoria una sola vez, con la capacidad
/// exacta, sin pasar por el formateo. Es la forma preferida de componer texto a partir de
/// fragmentos, y suele ser más rápida que `format!`.
///
/// Cada expresión se evalúa **una sola vez**, por lo que admite llamadas como `n.to_string()` o
/// cierres con efectos secundarios. Los valores que no son cadenas (números, tipos `Display`) se