caisin/typst
1
0
Fork 0
mirror of https://github.com/typst/typst synced 2025-07-27 06:17:53 +08:00
Code Issues Packages Projects Releases Wiki Activity

Use by-value builder API for Deprecation

Browse Source 
This makes the API for `Binding` more consistent without requiring any
intermediate bindings for the `Deprecation`.
This commit is contained in:
tinger 2025-07-23 20:11:12 +02:00
parent 6eced92e7c
commit 1a8797e6cc
5 changed files with 35 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
crates/typst-library/src/foundations/scope.rs
View File

@ -254,7 +254,7 @@ pub struct Binding {
/// The category of the binding. /// The category of the binding.
category: Option<Category>, category: Option<Category>,
/// The deprecation information if this item is deprecated. /// The deprecation information if this item is deprecated.
deprecation: Option<Box<DeprecationInfo>>, deprecation: Option<Box<Deprecation>>,
} }
/// The different kinds of slots. /// The different kinds of slots.
@ -284,20 +284,8 @@ impl Binding {
} }
/// Marks this binding as deprecated, with the given `message`. /// Marks this binding as deprecated, with the given `message`.
pub fn deprecated(&mut self, message: &'static str) -> &mut Self { pub fn deprecated(&mut self, deprecation: Deprecation) -> &mut Self {
self.deprecation self.deprecation = Some(Box::new(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);
self self
} }
@ -349,7 +337,7 @@ impl Binding {
} }
/// A deprecation message for the value, if any. /// A deprecation message for the value, if any.
pub fn deprecation(&self) -> Option<&DeprecationInfo> { pub fn deprecation(&self) -> Option<&Deprecation> {
self.deprecation.as_deref() self.deprecation.as_deref()
} }
@ -370,14 +358,14 @@ pub enum Capturer {
/// Information about a deprecated binding. /// Information about a deprecated binding.
#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)] #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
pub struct DeprecationInfo { pub struct Deprecation {
/// A deprecation message for the definition. /// A deprecation message for the definition.
message: &'static str, message: &'static str,
/// A version in which the deprecated binding is planned to be removed. /// A version in which the deprecated binding is planned to be removed.
until: Option<&'static str>, until: Option<&'static str>,
} }
impl DeprecationInfo { impl Deprecation {
/// Creates new deprecation info with a default message to display when /// Creates new deprecation info with a default message to display when
/// emitting the deprecation warning. /// emitting the deprecation warning.
pub fn new() -> Self { pub fn new() -> Self {
@ -385,13 +373,13 @@ impl DeprecationInfo {
} }
/// Set the message to display when emitting the deprecation warning. /// 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.message = message;
self self
} }
/// Set the version in which the binding is planned to be removed. /// 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.until = Some(version);
self self
} }
@ -407,7 +395,7 @@ impl DeprecationInfo {
} }
} }
impl Default for DeprecationInfo { impl Default for Deprecation {
fn default() -> Self { fn default() -> Self {
Self::new() Self::new()
} }

4
crates/typst-library/src/symbols.rs
View File

@ -1,6 +1,6 @@
//! Modifiable symbols. //! Modifiable symbols.
use crate::foundations::{Module, Scope, Symbol, Value}; use crate::foundations::{Deprecation, Module, Scope, Symbol, Value};
/// Hook up all `symbol` definitions. /// Hook up all `symbol` definitions.
pub(super) fn define(global: &mut Scope) { 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); let scope_binding = scope.define(name, value);
if let Some(message) = binding.deprecation { if let Some(message) = binding.deprecation {
scope_binding.deprecated(message); scope_binding.deprecated(Deprecation::new().with_message(message));
} }
} }
} }

17
crates/typst-library/src/visualize/mod.rs
View File

@ -24,6 +24,7 @@ pub use self::shape::*;
pub use self::stroke::*; pub use self::stroke::*;
pub use self::tiling::*; pub use self::tiling::*;
use crate::foundations::Deprecation;
use crate::foundations::{Element, Scope, Type}; use crate::foundations::{Element, Scope, Type};
/// Hook up all visualize definitions. /// Hook up all visualize definitions.
@ -41,12 +42,14 @@ pub(super) fn define(global: &mut Scope) {
global.define_elem::<CircleElem>(); global.define_elem::<CircleElem>();
global.define_elem::<PolygonElem>(); global.define_elem::<PolygonElem>();
global.define_elem::<CurveElem>(); global.define_elem::<CurveElem>();
global global.define("path", Element::of::<PathElem>()).deprecated(
.define("path", Element::of::<PathElem>()) Deprecation::new()
.deprecated("the `path` function is deprecated, use `curve` instead"); .with_message("the `path` function is deprecated, use `curve` instead"),
global );
.define("pattern", Type::of::<Tiling>()) global.define("pattern", Type::of::<Tiling>()).deprecated(
.deprecated("the name `pattern` is deprecated, use `tiling` instead") Deprecation::new()
.deprecated_until("0.15.0"); .with_message("the name `pattern` is deprecated, use `tiling` instead")
.with_until("0.15.0"),
);
global.reset_category(); global.reset_category();
} }

9
crates/typst-macros/src/scope.rs
View File

@ -64,17 +64,22 @@ pub fn scope(_: TokenStream, item: syn::Item) -> Result<TokenStream> {
Punctuated::<MetaNameValue, Token![,]>::parse_separated_nonempty, Punctuated::<MetaNameValue, Token![,]>::parse_separated_nonempty,
)?; )?;
let mut deprecation =
quote! { crate::foundations::Deprecation::new() };
if let Some(message) = args.iter().find_map(|pair| { if let Some(message) = args.iter().find_map(|pair| {
pair.path.is_ident("message").then_some(&pair.value) 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| { if let Some(version) = args.iter().find_map(|pair| {
pair.path.is_ident("until").then_some(&pair.value) 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) }
} }
_ => {} _ => {}
} }

14
docs/src/lib.rs
View File

@ -17,7 +17,7 @@ use serde::Deserialize;
use serde_yaml as yaml; use serde_yaml as yaml;
use std::sync::LazyLock; use std::sync::LazyLock;
use typst::diag::{StrResult, bail}; use typst::diag::{StrResult, bail};
use typst::foundations::DeprecationInfo; use typst::foundations::Deprecation;
use typst::foundations::{ use typst::foundations::{
AutoValue, Binding, Bytes, CastInfo, Func, Module, NoneValue, ParamInfo, Repr, Scope, AutoValue, Binding, Bytes, CastInfo, Func, Module, NoneValue, ParamInfo, Repr, Scope,
Smart, Type, Value, Smart, Type, Value,
@ -382,7 +382,7 @@ fn func_page(
parent: &str, parent: &str,
func: &Func, func: &Func,
path: &[&str], path: &[&str],
deprecation: Option<&DeprecationInfo>, deprecation: Option<&Deprecation>,
) -> PageModel { ) -> PageModel {
let model = func_model(resolver, func, path, false, deprecation); let model = func_model(resolver, func, path, false, deprecation);
let name = func.name().unwrap(); let name = func.name().unwrap();
@ -403,7 +403,7 @@ fn func_model(
func: &Func, func: &Func,
path: &[&str], path: &[&str],
nested: bool, nested: bool,
deprecation: Option<&DeprecationInfo>, deprecation: Option<&Deprecation>,
) -> FuncModel { ) -> FuncModel {
let name = func.name().unwrap(); let name = func.name().unwrap();
let scope = func.scope().unwrap(); let scope = func.scope().unwrap();
@ -439,8 +439,8 @@ fn func_model(
oneliner: oneliner(details), oneliner: oneliner(details),
element: func.element().is_some(), element: func.element().is_some(),
contextual: func.contextual().unwrap_or(false), contextual: func.contextual().unwrap_or(false),
deprecation_message: deprecation.map(DeprecationInfo::message), deprecation_message: deprecation.map(Deprecation::message),
deprecation_until: deprecation.and_then(DeprecationInfo::until), deprecation_until: deprecation.and_then(Deprecation::until),
details: Html::markdown(resolver, details, nesting), details: Html::markdown(resolver, details, nesting),
example: example.map(|md| Html::markdown(resolver, md, None)), example: example.map(|md| Html::markdown(resolver, md, None)),
self_, self_,
@ -740,8 +740,8 @@ fn symbols_model(resolver: &dyn Resolver, group: &GroupData) -> SymbolsModel {
.map(|(other, _, _)| complete(other)) .map(|(other, _, _)| complete(other))
.collect(), .collect(),
deprecation_message: deprecation_message deprecation_message: deprecation_message
.or_else(|| binding.deprecation().map(DeprecationInfo::message)), .or_else(|| binding.deprecation().map(Deprecation::message)),
deprecation_until: binding.deprecation().and_then(DeprecationInfo::until), deprecation_until: binding.deprecation().and_then(Deprecation::until),
}); });
} }
} }