Scope deprecations (#5798)

15 files changed, 82 insertions, 21 deletions

diff --git a/crates/typst-library/src/diag.rs b/crates/typst-library/src/diag.rs
index bd4c90a1..49cbd02c 100644
--- a/crates/typst-library/src/diag.rs
+++ b/crates/typst-library/src/diag.rs
@@ -11,6 +11,7 @@ use ecow::{eco_vec, EcoVec};
 use typst_syntax::package::{PackageSpec, PackageVersion};
 use typst_syntax::{Span, Spanned, SyntaxError};
 
+use crate::engine::Engine;
 use crate::{World, WorldExt};
 
 /// Early-return with a [`StrResult`] or [`SourceResult`].
@@ -228,6 +229,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);
+}
+
+impl DeprecationSink for () {
+    fn emit(self, _: &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));
+    }
+}
+
 /// A part of a diagnostic's [trace](SourceDiagnostic::trace).
 #[derive(Debug, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
 pub enum Tracepoint {
diff --git a/crates/typst-library/src/foundations/func.rs b/crates/typst-library/src/foundations/func.rs
index 741b6633..3ed1562f 100644
--- a/crates/typst-library/src/foundations/func.rs
+++ b/crates/typst-library/src/foundations/func.rs
@@ -9,7 +9,7 @@ use ecow::{eco_format, EcoString};
 use typst_syntax::{ast, Span, SyntaxNode};
 use typst_utils::{singleton, LazyHash, Static};
 
-use crate::diag::{bail, At, SourceResult, StrResult};
+use crate::diag::{bail, At, DeprecationSink, SourceResult, StrResult};
 use crate::engine::Engine;
 use crate::foundations::{
     cast, repr, scope, ty, Args, Bytes, CastInfo, Content, Context, Element, IntoArgs,
@@ -255,11 +255,15 @@ impl Func {
     }
 
     /// Get a field from this function's scope, if possible.
-    pub fn field(&self, field: &str) -> StrResult<&'static Value> {
+    pub fn field(
+        &self,
+        field: &str,
+        sink: impl DeprecationSink,
+    ) -> StrResult<&'static Value> {
         let scope =
             self.scope().ok_or("cannot access fields on user-defined functions")?;
         match scope.get(field) {
-            Some(binding) => Ok(binding.read()),
+            Some(binding) => Ok(binding.read_checked(sink)),
             None => match self.name() {
                 Some(name) => bail!("function `{name}` does not contain field `{field}`"),
                 None => bail!("function does not contain field `{field}`"),
diff --git a/crates/typst-library/src/foundations/module.rs b/crates/typst-library/src/foundations/module.rs
index 3259c17e..8d9626a1 100644
--- a/crates/typst-library/src/foundations/module.rs
+++ b/crates/typst-library/src/foundations/module.rs
@@ -4,7 +4,7 @@ use std::sync::Arc;
 use ecow::{eco_format, EcoString};
 use typst_syntax::FileId;
 
-use crate::diag::{bail, StrResult};
+use crate::diag::{bail, DeprecationSink, StrResult};
 use crate::foundations::{repr, ty, Content, Scope, Value};
 
 /// An module of definitions.
@@ -118,9 +118,9 @@ impl Module {
     }
 
     /// Try to access a definition in the module.
-    pub fn field(&self, field: &str) -> StrResult<&Value> {
+    pub fn field(&self, field: &str, sink: impl DeprecationSink) -> StrResult<&Value> {
         match self.scope().get(field) {
-            Some(binding) => Ok(binding.read()),
+            Some(binding) => Ok(binding.read_checked(sink)),
             None => match &self.name {
                 Some(name) => bail!("module `{name}` does not contain `{field}`"),
                 None => bail!("module does not contain `{field}`"),
diff --git a/crates/typst-library/src/foundations/scope.rs b/crates/typst-library/src/foundations/scope.rs
index e73afeac..d6c5a8d0 100644
--- a/crates/typst-library/src/foundations/scope.rs
+++ b/crates/typst-library/src/foundations/scope.rs
@@ -10,7 +10,7 @@ use indexmap::IndexMap;
 use typst_syntax::Span;
 use typst_utils::Static;
 
-use crate::diag::{bail, HintedStrResult, HintedString, StrResult};
+use crate::diag::{bail, DeprecationSink, HintedStrResult, HintedString, StrResult};
 use crate::foundations::{
     Element, Func, IntoValue, NativeElement, NativeFunc, NativeFuncData, NativeType,
     Type, Value,
@@ -258,6 +258,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 different kinds of slots.
@@ -277,6 +279,7 @@ impl Binding {
             span,
             kind: BindingKind::Normal,
             category: None,
+            deprecation: None,
         }
     }
 
@@ -285,11 +288,29 @@ impl Binding {
         Self::new(value, Span::detached())
     }
 
+    /// Marks this binding as deprecated, with the given `message`.
+    pub fn deprecated(&mut self, message: &'static str) -> &mut Self {
+        self.deprecation = Some(message);
+        self
+    }
+
     /// Read the value.
     pub fn read(&self) -> &Value {
         &self.value
     }
 
+    /// Read the value, checking for deprecation.
+    ///
+    /// As the `sink`
+    /// - 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);
+        }
+        &self.value
+    }
+
     /// Try to write to the value.
     ///
     /// This fails if the value is a read-only closure capture.
@@ -320,6 +341,11 @@ impl Binding {
         self.span
     }
 
+    /// A deprecation message for the value, if any.
+    pub fn deprecation(&self) -> Option<&'static str> {
+        self.deprecation
+    }
+
     /// The category of the value, if any.
     pub fn category(&self) -> Option<Category> {
         self.category
diff --git a/crates/typst-library/src/foundations/ty.rs b/crates/typst-library/src/foundations/ty.rs
index 09f5efa1..40f7003c 100644
--- a/crates/typst-library/src/foundations/ty.rs
+++ b/crates/typst-library/src/foundations/ty.rs
@@ -8,7 +8,7 @@ use std::sync::LazyLock;
 use ecow::{eco_format, EcoString};
 use typst_utils::Static;
 
-use crate::diag::{bail, StrResult};
+use crate::diag::{bail, DeprecationSink, StrResult};
 use crate::foundations::{
     cast, func, AutoValue, Func, NativeFuncData, NoneValue, Repr, Scope, Value,
 };
@@ -94,9 +94,13 @@ impl Type {
     }
 
     /// Get a field from this type's scope, if possible.
-    pub fn field(&self, field: &str) -> StrResult<&'static Value> {
+    pub fn field(
+        &self,
+        field: &str,
+        sink: impl DeprecationSink,
+    ) -> StrResult<&'static Value> {
         match self.scope().get(field) {
-            Some(binding) => Ok(binding.read()),
+            Some(binding) => Ok(binding.read_checked(sink)),
             None => bail!("type {self} does not contain field `{field}`"),
         }
     }
diff --git a/crates/typst-library/src/foundations/value.rs b/crates/typst-library/src/foundations/value.rs
index 4fa380b4..854c2486 100644
--- a/crates/typst-library/src/foundations/value.rs
+++ b/crates/typst-library/src/foundations/value.rs
@@ -11,7 +11,7 @@ use serde::{Deserialize, Deserializer, Serialize, Serializer};
 use typst_syntax::{ast, Span};
 use typst_utils::ArcExt;
 
-use crate::diag::{HintedStrResult, HintedString, StrResult};
+use crate::diag::{DeprecationSink, HintedStrResult, HintedString, StrResult};
 use crate::foundations::{
     fields, ops, repr, Args, Array, AutoValue, Bytes, CastInfo, Content, Datetime,
     Decimal, Dict, Duration, Fold, FromValue, Func, IntoValue, Label, Module,
@@ -155,15 +155,15 @@ impl Value {
     }
 
     /// Try to access a field on the value.
-    pub fn field(&self, field: &str) -> StrResult<Value> {
+    pub fn field(&self, field: &str, sink: impl DeprecationSink) -> StrResult<Value> {
         match self {
             Self::Symbol(symbol) => symbol.clone().modified(field).map(Self::Symbol),
             Self::Version(version) => version.component(field).map(Self::Int),
             Self::Dict(dict) => dict.get(field).cloned(),
             Self::Content(content) => content.field_by_name(field),
-            Self::Type(ty) => ty.field(field).cloned(),
-            Self::Func(func) => func.field(field).cloned(),
-            Self::Module(module) => module.field(field).cloned(),
+            Self::Type(ty) => ty.field(field, sink).cloned(),
+            Self::Func(func) => func.field(field, sink).cloned(),
+            Self::Module(module) => module.field(field, sink).cloned(),
             _ => fields::field(self, field),
         }
     }
diff --git a/crates/typst-library/src/loading/cbor.rs b/crates/typst-library/src/loading/cbor.rs
index 2bdeb80e..bd65e844 100644
--- a/crates/typst-library/src/loading/cbor.rs
+++ b/crates/typst-library/src/loading/cbor.rs
@@ -38,6 +38,7 @@ impl cbor {
     /// This function is deprecated. The [`cbor`] function now accepts bytes
     /// directly.
     #[func(title = "Decode CBOR")]
+    #[deprecated = "`cbor.decode` is deprecated, directly pass bytes to `cbor` instead"]
     pub fn decode(
         engine: &mut Engine,
         /// CBOR data.
diff --git a/crates/typst-library/src/loading/csv.rs b/crates/typst-library/src/loading/csv.rs
index 1cf656ae..d01d687b 100644
--- a/crates/typst-library/src/loading/csv.rs
+++ b/crates/typst-library/src/loading/csv.rs
@@ -100,6 +100,7 @@ impl csv {
     /// This function is deprecated. The [`csv`] function now accepts bytes
     /// directly.
     #[func(title = "Decode CSV")]
+    #[deprecated = "`csv.decode` is deprecated, directly pass bytes to `csv` instead"]
     pub fn decode(
         engine: &mut Engine,
         /// CSV data.
diff --git a/crates/typst-library/src/loading/json.rs b/crates/typst-library/src/loading/json.rs
index 035c5e4a..52c87371 100644
--- a/crates/typst-library/src/loading/json.rs
+++ b/crates/typst-library/src/loading/json.rs
@@ -69,6 +69,7 @@ impl json {
     /// This function is deprecated. The [`json`] function now accepts bytes
     /// directly.
     #[func(title = "Decode JSON")]
+    #[deprecated = "`json.decode` is deprecated, directly pass bytes to `json` instead"]
     pub fn decode(
         engine: &mut Engine,
         /// JSON data.
diff --git a/crates/typst-library/src/loading/toml.rs b/crates/typst-library/src/loading/toml.rs
index 402207b0..45611246 100644
--- a/crates/typst-library/src/loading/toml.rs
+++ b/crates/typst-library/src/loading/toml.rs
@@ -48,6 +48,7 @@ impl toml {
     /// This function is deprecated. The [`toml`] function now accepts bytes
     /// directly.
     #[func(title = "Decode TOML")]
+    #[deprecated = "`toml.decode` is deprecated, directly pass bytes to `toml` instead"]
     pub fn decode(
         engine: &mut Engine,
         /// TOML data.
diff --git a/crates/typst-library/src/loading/xml.rs b/crates/typst-library/src/loading/xml.rs
index ca467c23..0172071b 100644
--- a/crates/typst-library/src/loading/xml.rs
+++ b/crates/typst-library/src/loading/xml.rs
@@ -81,6 +81,7 @@ impl xml {
     /// This function is deprecated. The [`xml`] function now accepts bytes
     /// directly.
     #[func(title = "Decode XML")]
+    #[deprecated = "`xml.decode` is deprecated, directly pass bytes to `xml` instead"]
     pub fn decode(
         engine: &mut Engine,
         /// XML data.
diff --git a/crates/typst-library/src/loading/yaml.rs b/crates/typst-library/src/loading/yaml.rs
index 5767cb64..511c676c 100644
--- a/crates/typst-library/src/loading/yaml.rs
+++ b/crates/typst-library/src/loading/yaml.rs
@@ -59,6 +59,7 @@ impl yaml {
     /// This function is deprecated. The [`yaml`] function now accepts bytes
     /// directly.
     #[func(title = "Decode YAML")]
+    #[deprecated = "`yaml.decode` is deprecated, directly pass bytes to `yaml` instead"]
     pub fn decode(
         engine: &mut Engine,
         /// YAML data.
diff --git a/crates/typst-library/src/visualize/image/mod.rs b/crates/typst-library/src/visualize/image/mod.rs
index 07ebdabe..9306eb6f 100644
--- a/crates/typst-library/src/visualize/image/mod.rs
+++ b/crates/typst-library/src/visualize/image/mod.rs
@@ -171,6 +171,7 @@ impl ImageElem {
     /// #image.decode(changed)
     /// ```
     #[func(title = "Decode Image")]
+    #[deprecated = "`image.decode` is deprecated, directly pass bytes to `image` instead"]
     pub fn decode(
         span: Span,
         /// The data to decode as an image. Can be a string for SVGs.
diff --git a/crates/typst-library/src/visualize/mod.rs b/crates/typst-library/src/visualize/mod.rs
index b0e627af..76849ac8 100644
--- a/crates/typst-library/src/visualize/mod.rs
+++ b/crates/typst-library/src/visualize/mod.rs
@@ -24,7 +24,7 @@ pub use self::shape::*;
 pub use self::stroke::*;
 pub use self::tiling::*;
 
-use crate::foundations::{category, Category, Scope, Type};
+use crate::foundations::{category, Category, Element, Scope, Type};
 
 /// Drawing and data visualization.
 ///
@@ -49,8 +49,10 @@ pub(super) fn define(global: &mut Scope) {
     global.define_elem::<CircleElem>();
     global.define_elem::<PolygonElem>();
     global.define_elem::<CurveElem>();
-    global.define_elem::<PathElem>();
-
-    // Compatibility.
-    global.define("pattern", Type::of::<Tiling>());
+    global
+        .define("path", Element::of::<PathElem>())
+        .deprecated("the `path` function is deprecated, use `curve` instead");
+    global
+        .define("pattern", Type::of::<Tiling>())
+        .deprecated("the name `pattern` is deprecated, use `tiling` instead");
 }
diff --git a/crates/typst-library/src/visualize/path.rs b/crates/typst-library/src/visualize/path.rs
index 6aacb319..5d3439c0 100644
--- a/crates/typst-library/src/visualize/path.rs
+++ b/crates/typst-library/src/visualize/path.rs
@@ -23,7 +23,7 @@ use crate::visualize::{FillRule, Paint, Stroke};
 /// ```
 ///
 /// # Deprecation
-/// This element is deprecated. The [`curve`] element should be used instead.
+/// This function is deprecated. The [`curve`] function should be used instead.
 #[elem(Show)]
 pub struct PathElem {
     /// How to fill the path.