From 1a8797e6cc123b1bd9928347ac95901947e42686 Mon Sep 17 00:00:00 2001 From: tinger Date: Wed, 23 Jul 2025 20:11:12 +0200 Subject: [PATCH] Use by-value builder API for `Deprecation` This makes the API for `Binding` more consistent without requiring any intermediate bindings for the `Deprecation`. --- crates/typst-library/src/foundations/scope.rs | 30 ++++++------------- crates/typst-library/src/symbols.rs | 4 +-- crates/typst-library/src/visualize/mod.rs | 17 ++++++----- crates/typst-macros/src/scope.rs | 9 ++++-- docs/src/lib.rs | 14 ++++----- 5 files changed, 35 insertions(+), 39 deletions(-) diff --git a/crates/typst-library/src/foundations/scope.rs b/crates/typst-library/src/foundations/scope.rs index 22691869d..18d972d33 100644 --- a/crates/typst-library/src/foundations/scope.rs +++ b/crates/typst-library/src/foundations/scope.rs @@ -254,7 +254,7 @@ pub struct Binding { /// The category of the binding. category: Option, /// The deprecation information if this item is deprecated. - deprecation: Option>, + deprecation: Option>, } /// The different kinds of slots. @@ -284,20 +284,8 @@ impl Binding { } /// Marks this binding as deprecated, with the given `message`. - pub fn deprecated(&mut self, message: &'static str) -> &mut Self { - self.deprecation - .get_or_insert_with(|| Box::new(DeprecationInfo::new())) - .deprecated_message(message); - self - } - - /// Set the version in which the binding is planned to be removed. - /// - /// This is ignored if [`Binding::deprecated`] isn't also set. - pub fn deprecated_until(&mut self, version: &'static str) -> &mut Self { - self.deprecation - .get_or_insert_with(|| Box::new(DeprecationInfo::new())) - .deprecated_until(version); + pub fn deprecated(&mut self, deprecation: Deprecation) -> &mut Self { + self.deprecation = Some(Box::new(deprecation)); self } @@ -349,7 +337,7 @@ impl Binding { } /// A deprecation message for the value, if any. - pub fn deprecation(&self) -> Option<&DeprecationInfo> { + pub fn deprecation(&self) -> Option<&Deprecation> { self.deprecation.as_deref() } @@ -370,14 +358,14 @@ pub enum Capturer { /// Information about a deprecated binding. #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)] -pub struct DeprecationInfo { +pub struct Deprecation { /// A deprecation message for the definition. message: &'static str, /// A version in which the deprecated binding is planned to be removed. until: Option<&'static str>, } -impl DeprecationInfo { +impl Deprecation { /// Creates new deprecation info with a default message to display when /// emitting the deprecation warning. pub fn new() -> Self { @@ -385,13 +373,13 @@ impl DeprecationInfo { } /// Set the message to display when emitting the deprecation warning. - pub fn deprecated_message(&mut self, message: &'static str) -> &mut Self { + pub fn with_message(mut self, message: &'static str) -> Self { self.message = message; self } /// Set the version in which the binding is planned to be removed. - pub fn deprecated_until(&mut self, version: &'static str) -> &mut Self { + pub fn with_until(mut self, version: &'static str) -> Self { self.until = Some(version); self } @@ -407,7 +395,7 @@ impl DeprecationInfo { } } -impl Default for DeprecationInfo { +impl Default for Deprecation { fn default() -> Self { Self::new() } diff --git a/crates/typst-library/src/symbols.rs b/crates/typst-library/src/symbols.rs index 0588ace95..8f26d74ad 100644 --- a/crates/typst-library/src/symbols.rs +++ b/crates/typst-library/src/symbols.rs @@ -1,6 +1,6 @@ //! Modifiable symbols. -use crate::foundations::{Module, Scope, Symbol, Value}; +use crate::foundations::{Deprecation, Module, Scope, Symbol, Value}; /// Hook up all `symbol` definitions. pub(super) fn define(global: &mut Scope) { @@ -23,7 +23,7 @@ fn extend_scope_from_codex_module(scope: &mut Scope, module: codex::Module) { let scope_binding = scope.define(name, value); if let Some(message) = binding.deprecation { - scope_binding.deprecated(message); + scope_binding.deprecated(Deprecation::new().with_message(message)); } } } diff --git a/crates/typst-library/src/visualize/mod.rs b/crates/typst-library/src/visualize/mod.rs index d116db73b..06977c891 100644 --- a/crates/typst-library/src/visualize/mod.rs +++ b/crates/typst-library/src/visualize/mod.rs @@ -24,6 +24,7 @@ pub use self::shape::*; pub use self::stroke::*; pub use self::tiling::*; +use crate::foundations::Deprecation; use crate::foundations::{Element, Scope, Type}; /// Hook up all visualize definitions. @@ -41,12 +42,14 @@ pub(super) fn define(global: &mut Scope) { global.define_elem::(); global.define_elem::(); global.define_elem::(); - global - .define("path", Element::of::()) - .deprecated("the `path` function is deprecated, use `curve` instead"); - global - .define("pattern", Type::of::()) - .deprecated("the name `pattern` is deprecated, use `tiling` instead") - .deprecated_until("0.15.0"); + global.define("path", Element::of::()).deprecated( + Deprecation::new() + .with_message("the `path` function is deprecated, use `curve` instead"), + ); + global.define("pattern", Type::of::()).deprecated( + Deprecation::new() + .with_message("the name `pattern` is deprecated, use `tiling` instead") + .with_until("0.15.0"), + ); global.reset_category(); } diff --git a/crates/typst-macros/src/scope.rs b/crates/typst-macros/src/scope.rs index ece5bbf3b..e0a0eca7d 100644 --- a/crates/typst-macros/src/scope.rs +++ b/crates/typst-macros/src/scope.rs @@ -64,17 +64,22 @@ pub fn scope(_: TokenStream, item: syn::Item) -> Result { Punctuated::::parse_separated_nonempty, )?; + let mut deprecation = + quote! { crate::foundations::Deprecation::new() }; + if let Some(message) = args.iter().find_map(|pair| { pair.path.is_ident("message").then_some(&pair.value) }) { - def = quote! { #def.deprecated(#message) } + deprecation = quote! { #deprecation.with_message(#message) } } if let Some(version) = args.iter().find_map(|pair| { pair.path.is_ident("until").then_some(&pair.value) }) { - def = quote! { #def.deprecated_until(#version) } + deprecation = quote! { #deprecation.with_until(#version) } } + + def = quote! { #def.deprecated(#deprecation) } } _ => {} } diff --git a/docs/src/lib.rs b/docs/src/lib.rs index 4844619af..2d9e9bdbc 100644 --- a/docs/src/lib.rs +++ b/docs/src/lib.rs @@ -17,7 +17,7 @@ use serde::Deserialize; use serde_yaml as yaml; use std::sync::LazyLock; use typst::diag::{StrResult, bail}; -use typst::foundations::DeprecationInfo; +use typst::foundations::Deprecation; use typst::foundations::{ AutoValue, Binding, Bytes, CastInfo, Func, Module, NoneValue, ParamInfo, Repr, Scope, Smart, Type, Value, @@ -382,7 +382,7 @@ fn func_page( parent: &str, func: &Func, path: &[&str], - deprecation: Option<&DeprecationInfo>, + deprecation: Option<&Deprecation>, ) -> PageModel { let model = func_model(resolver, func, path, false, deprecation); let name = func.name().unwrap(); @@ -403,7 +403,7 @@ fn func_model( func: &Func, path: &[&str], nested: bool, - deprecation: Option<&DeprecationInfo>, + deprecation: Option<&Deprecation>, ) -> FuncModel { let name = func.name().unwrap(); let scope = func.scope().unwrap(); @@ -439,8 +439,8 @@ fn func_model( oneliner: oneliner(details), element: func.element().is_some(), contextual: func.contextual().unwrap_or(false), - deprecation_message: deprecation.map(DeprecationInfo::message), - deprecation_until: deprecation.and_then(DeprecationInfo::until), + deprecation_message: deprecation.map(Deprecation::message), + deprecation_until: deprecation.and_then(Deprecation::until), details: Html::markdown(resolver, details, nesting), example: example.map(|md| Html::markdown(resolver, md, None)), self_, @@ -740,8 +740,8 @@ fn symbols_model(resolver: &dyn Resolver, group: &GroupData) -> SymbolsModel { .map(|(other, _, _)| complete(other)) .collect(), deprecation_message: deprecation_message - .or_else(|| binding.deprecation().map(DeprecationInfo::message)), - deprecation_until: binding.deprecation().and_then(DeprecationInfo::until), + .or_else(|| binding.deprecation().map(Deprecation::message)), + deprecation_until: binding.deprecation().and_then(Deprecation::until), }); } }