Hint that deprecated items will be removed in 0.15.0 (typst#6617)

Author: tingerrr

crates/typst-library/src/diag.rs

@@ -234,18 +234,23 @@ impl From<SyntaxError> for SourceDiagnostic {
 
 /// Destination for a deprecation message when accessing a deprecated value.
 pub trait DeprecationSink {
-    /// Emits the given deprecation message into this sink.
-    fn emit(self, message: &str);
+    /// Emits the given deprecation message into this sink alongside a version
+    /// in which the deprecated item is planned to be removed.
+    fn emit(self, message: &str, until: Option<&str>);
 }
 
 impl DeprecationSink for () {
-    fn emit(self, _: &str) {}
+    fn emit(self, _: &str, _: Option<&str>) {}
 }
 
 impl DeprecationSink for (&mut Engine<'_>, Span) {
     /// Emits the deprecation message as a warning.
-    fn emit(self, message: &str) {
-        self.0.sink.warn(SourceDiagnostic::warning(self.1, message));
+    fn emit(self, message: &str, version: Option<&str>) {
+        self.0
+            .sink
+            .warn(SourceDiagnostic::warning(self.1, message).with_hints(
+                version.map(|v| eco_format!("it will be removed in Typst {}", v)),
+            ));
     }
 }
 

crates/typst-library/src/foundations/scope.rs

@@ -253,8 +253,8 @@ pub struct Binding {
     span: Span,
     /// The category of the binding.
     category: Option<Category>,
-    /// A deprecation message for the definition.
-    deprecation: Option<&'static str>,
+    /// The deprecation information if this item is deprecated.
+    deprecation: Option<Box<Deprecation>>,
 }
 
 /// The different kinds of slots.
@@ -284,8 +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 = Some(message);
+    pub fn deprecated(&mut self, deprecation: Deprecation) -> &mut Self {
+        self.deprecation = Some(Box::new(deprecation));
         self
     }
 
@@ -300,8 +300,8 @@ impl Binding {
     /// - pass `()` to ignore the message.
     /// - pass `(&mut engine, span)` to emit a warning into the engine.
     pub fn read_checked(&self, sink: impl DeprecationSink) -> &Value {
-        if let Some(message) = self.deprecation {
-            sink.emit(message);
+        if let Some(info) = &self.deprecation {
+            sink.emit(info.message, info.until);
         }
         &self.value
     }
@@ -337,8 +337,8 @@ impl Binding {
     }
 
     /// A deprecation message for the value, if any.
-    pub fn deprecation(&self) -> Option<&'static str> {
-        self.deprecation
+    pub fn deprecation(&self) -> Option<&Deprecation> {
+        self.deprecation.as_deref()
     }
 
     /// The category of the value, if any.
@@ -356,6 +356,51 @@ pub enum Capturer {
     Context,
 }
 
+/// Information about a deprecated binding.
+#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
+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 Deprecation {
+    /// Creates new deprecation info with a default message to display when
+    /// emitting the deprecation warning.
+    pub fn new() -> Self {
+        Self { message: "item is deprecated", until: None }
+    }
+
+    /// Set the message to display when emitting the deprecation warning.
+    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 with_until(mut self, version: &'static str) -> Self {
+        self.until = Some(version);
+        self
+    }
+
+    /// The message to display when emitting the deprecation warning.
+    pub fn message(&self) -> &'static str {
+        self.message
+    }
+
+    /// The version in which the binding is planned to be removed.
+    pub fn until(&self) -> Option<&'static str> {
+        self.until
+    }
+}
+
+impl Default for Deprecation {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
 /// The error message when trying to mutate a variable from the standard
 /// library.
 #[cold]

crates/typst-library/src/foundations/symbol.rs

@@ -151,7 +151,7 @@ impl Symbol {
                 modifiers.best_match_in(list.variants().map(|(m, _, d)| (m, d)))
             {
                 if let Some(message) = deprecation {
-                    sink.emit(message)
+                    sink.emit(message, None)
                 }
                 return Ok(self);
             }

crates/typst-library/src/loading/cbor.rs

@@ -33,7 +33,10 @@ pub fn cbor(
 impl cbor {
     /// Reads structured data from CBOR bytes.
     #[func(title = "Decode CBOR")]
-    #[deprecated = "`cbor.decode` is deprecated, directly pass bytes to `cbor` instead"]
+    #[deprecated(
+        message = "`cbor.decode` is deprecated, directly pass bytes to `cbor` instead",
+        until = "0.15.0"
+    )]
     pub fn decode(
         engine: &mut Engine,
         /// CBOR data.

crates/typst-library/src/loading/csv.rs

@@ -95,7 +95,10 @@ pub fn csv(
 impl csv {
     /// Reads structured data from a CSV string/bytes.
     #[func(title = "Decode CSV")]
-    #[deprecated = "`csv.decode` is deprecated, directly pass bytes to `csv` instead"]
+    #[deprecated(
+        message = "`csv.decode` is deprecated, directly pass bytes to `csv` instead",
+        until = "0.15.0"
+    )]
     pub fn decode(
         engine: &mut Engine,
         /// CSV data.

crates/typst-library/src/loading/json.rs

@@ -67,7 +67,10 @@ pub fn json(
 impl json {
     /// Reads structured data from a JSON string/bytes.
     #[func(title = "Decode JSON")]
-    #[deprecated = "`json.decode` is deprecated, directly pass bytes to `json` instead"]
+    #[deprecated(
+        message = "`json.decode` is deprecated, directly pass bytes to `json` instead",
+        until = "0.15.0"
+    )]
     pub fn decode(
         engine: &mut Engine,
         /// JSON data.

crates/typst-library/src/loading/toml.rs

@@ -41,7 +41,10 @@ pub fn toml(
 impl toml {
     /// Reads structured data from a TOML string/bytes.
     #[func(title = "Decode TOML")]
-    #[deprecated = "`toml.decode` is deprecated, directly pass bytes to `toml` instead"]
+    #[deprecated(
+        message = "`toml.decode` is deprecated, directly pass bytes to `toml` instead",
+        until = "0.15.0"
+    )]
     pub fn decode(
         engine: &mut Engine,
         /// TOML data.

crates/typst-library/src/loading/xml.rs

@@ -75,7 +75,10 @@ pub fn xml(
 impl xml {
     /// Reads structured data from an XML string/bytes.
     #[func(title = "Decode XML")]
-    #[deprecated = "`xml.decode` is deprecated, directly pass bytes to `xml` instead"]
+    #[deprecated(
+        message = "`xml.decode` is deprecated, directly pass bytes to `xml` instead",
+        until = "0.15.0"
+    )]
     pub fn decode(
         engine: &mut Engine,
         /// XML data.

crates/typst-library/src/loading/yaml.rs

@@ -54,7 +54,10 @@ pub fn yaml(
 impl yaml {
     /// Reads structured data from a YAML string/bytes.
     #[func(title = "Decode YAML")]
-    #[deprecated = "`yaml.decode` is deprecated, directly pass bytes to `yaml` instead"]
+    #[deprecated(
+        message = "`yaml.decode` is deprecated, directly pass bytes to `yaml` instead",
+        until = "0.15.0"
+    )]
     pub fn decode(
         engine: &mut Engine,
         /// YAML data.

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));
         }
     }
 }