From 46ef8e1dfa39d2ee953e7af722b3b6ff20907443 Mon Sep 17 00:00:00 2001
From: Laurenz <laurmaedje@gmail.com>
Date: Sat, 20 Jul 2024 14:52:17 +0200
Subject: [PATCH] Deprecate some things (#4562)

---
 crates/typst/src/foundations/styles.rs    |  9 ++++++++-
 crates/typst/src/introspection/counter.rs | 17 ++++++++++++++---
 crates/typst/src/introspection/locate.rs  | 18 ++++++++++++------
 crates/typst/src/introspection/query.rs   | 14 +++++++++++---
 crates/typst/src/introspection/state.rs   | 19 ++++++++++++++++---
 crates/typst/src/layout/measure.rs        | 14 ++++++++++----
 tests/suite/foundations/context.typ       | 13 +++++++++++++
 tests/suite/introspection/counter.typ     |  2 +-
 tests/suite/layout/grid/footers.typ       |  6 +++---
 tests/suite/layout/grid/headers.typ       |  4 ++--
 tests/suite/layout/grid/rowspan.typ       |  2 +-
 tests/suite/layout/spacing.typ            |  2 +-
 tests/suite/styling/fold.typ              |  5 +++++
 13 files changed, 97 insertions(+), 28 deletions(-)

diff --git a/crates/typst/src/foundations/styles.rs b/crates/typst/src/foundations/styles.rs
index 42be89229..48009c8c3 100644
--- a/crates/typst/src/foundations/styles.rs
+++ b/crates/typst/src/foundations/styles.rs
@@ -7,7 +7,7 @@ use comemo::{Track, Tracked};
 use ecow::{eco_vec, EcoString, EcoVec};
 use smallvec::SmallVec;
 
-use crate::diag::{SourceResult, Trace, Tracepoint};
+use crate::diag::{warning, SourceResult, Trace, Tracepoint};
 use crate::engine::Engine;
 use crate::foundations::{
     cast, elem, func, ty, Content, Context, Element, Func, NativeElement, Packed, Repr,
@@ -33,6 +33,8 @@ use crate::utils::LazyHash;
 /// ```
 #[func]
 pub fn style(
+    /// The engine.
+    engine: &mut Engine,
     /// The call site span.
     span: Span,
     /// A function to call with the styles. Its return value is displayed
@@ -43,6 +45,11 @@ pub fn style(
     /// content that depends on the style context it appears in.
     func: Func,
 ) -> Content {
+    engine.sink.warn(warning!(
+        span, "`style` is deprecated";
+        hint: "use a `context` expression instead"
+    ));
+
     StyleElem::new(func).pack().spanned(span)
 }
 
diff --git a/crates/typst/src/introspection/counter.rs b/crates/typst/src/introspection/counter.rs
index 13ea4d142..2aefb68ec 100644
--- a/crates/typst/src/introspection/counter.rs
+++ b/crates/typst/src/introspection/counter.rs
@@ -5,7 +5,7 @@ use comemo::{Track, Tracked, TrackedMut};
 use ecow::{eco_format, eco_vec, EcoString, EcoVec};
 use smallvec::{smallvec, SmallVec};
 
-use crate::diag::{bail, At, HintedStrResult, SourceResult};
+use crate::diag::{bail, warning, At, HintedStrResult, SourceResult};
 use crate::engine::{Engine, Route, Sink, Traced};
 use crate::foundations::{
     cast, elem, func, scope, select_where, ty, Args, Array, Construct, Content, Context,
@@ -464,6 +464,11 @@ impl Counter {
         if let Ok(loc) = context.location() {
             self.display_impl(engine, loc, numbering, both, context.styles().ok())
         } else {
+            engine.sink.warn(warning!(
+                span, "`counter.display` without context is deprecated";
+                hint: "use it in a `context` expression instead"
+            ));
+
             Ok(CounterDisplayElem::new(self, numbering, both)
                 .pack()
                 .spanned(span)
@@ -508,13 +513,19 @@ impl Counter {
         context: Tracked<Context>,
         /// The callsite span.
         span: Span,
-        /// _Compatibility:_ This argument only exists for compatibility with
-        /// Typst 0.10 and lower and shouldn't be used anymore.
+        /// _Compatibility:_ This argument is deprecated. It only exists for
+        /// compatibility with Typst 0.10 and lower and shouldn't be used
+        /// anymore.
         #[default]
         location: Option<Location>,
     ) -> SourceResult<CounterState> {
         if location.is_none() {
             context.location().at(span)?;
+        } else {
+            engine.sink.warn(warning!(
+                span, "calling `counter.final` with a location is deprecated";
+                hint: "try removing the location argument"
+            ));
         }
 
         let sequence = self.sequence(engine)?;
diff --git a/crates/typst/src/introspection/locate.rs b/crates/typst/src/introspection/locate.rs
index 373b1fe27..8991ae9be 100644
--- a/crates/typst/src/introspection/locate.rs
+++ b/crates/typst/src/introspection/locate.rs
@@ -1,6 +1,6 @@
 use comemo::{Track, Tracked};
 
-use crate::diag::{HintedStrResult, SourceResult};
+use crate::diag::{warning, HintedStrResult, SourceResult};
 use crate::engine::Engine;
 use crate::foundations::{
     cast, elem, func, Content, Context, Func, LocatableSelector, NativeElement, Packed,
@@ -29,11 +29,12 @@ use crate::syntax::Span;
 ///
 /// # Compatibility
 /// In Typst 0.10 and lower, the `locate` function took a closure that made the
-/// current location in the document available (like [`here`] does now).
-/// Compatibility with the old way will remain for a while to give package
-/// authors time to upgrade. To that effect, `locate` detects whether it
-/// received a selector or a user-defined function and adjusts its semantics
-/// accordingly. This behaviour will be removed in the future.
+/// current location in the document available (like [`here`] does now). This
+/// usage pattern is deprecated. Compatibility with the old way will remain for
+/// a while to give package authors time to upgrade. To that effect, `locate`
+/// detects whether it received a selector or a user-defined function and
+/// adjusts its semantics accordingly. This behaviour will be removed in the
+/// future.
 #[func(contextual)]
 pub fn locate(
     /// The engine.
@@ -56,6 +57,11 @@ pub fn locate(
             LocateOutput::Location(selector.resolve_unique(engine.introspector, context)?)
         }
         LocateInput::Func(func) => {
+            engine.sink.warn(warning!(
+                span, "`locate` with callback function is deprecated";
+                hint: "use a `context` expression instead"
+            ));
+
             LocateOutput::Content(LocateElem::new(func).pack().spanned(span))
         }
     })
diff --git a/crates/typst/src/introspection/query.rs b/crates/typst/src/introspection/query.rs
index e416bfc9d..07f761a8d 100644
--- a/crates/typst/src/introspection/query.rs
+++ b/crates/typst/src/introspection/query.rs
@@ -1,9 +1,10 @@
 use comemo::Tracked;
 
-use crate::diag::HintedStrResult;
+use crate::diag::{warning, HintedStrResult};
 use crate::engine::Engine;
 use crate::foundations::{func, Array, Context, LocatableSelector, Value};
 use crate::introspection::Location;
+use crate::syntax::Span;
 
 /// Finds elements in the document.
 ///
@@ -141,6 +142,8 @@ pub fn query(
     engine: &mut Engine,
     /// The callsite context.
     context: Tracked<Context>,
+    /// The span of the `query` call.
+    span: Span,
     /// Can be
     /// - an element function like a `heading` or `figure`,
     /// - a `{<label>}`,
@@ -149,13 +152,18 @@ pub fn query(
     ///
     /// Only [locatable]($location/#locatable) element functions are supported.
     target: LocatableSelector,
-    /// _Compatibility:_ This argument only exists for compatibility with
-    /// Typst 0.10 and lower and shouldn't be used anymore.
+    /// _Compatibility:_ This argument is deprecated. It only exists for
+    /// compatibility with Typst 0.10 and lower and shouldn't be used anymore.
     #[default]
     location: Option<Location>,
 ) -> HintedStrResult<Array> {
     if location.is_none() {
         context.introspect()?;
+    } else {
+        engine.sink.warn(warning!(
+            span, "calling `query` with a location is deprecated";
+            hint: "try removing the location argument"
+        ));
     }
 
     let vec = engine.introspector.query(&target.0);
diff --git a/crates/typst/src/introspection/state.rs b/crates/typst/src/introspection/state.rs
index be114c86f..a88ed526a 100644
--- a/crates/typst/src/introspection/state.rs
+++ b/crates/typst/src/introspection/state.rs
@@ -1,7 +1,7 @@
 use comemo::{Track, Tracked, TrackedMut};
 use ecow::{eco_format, eco_vec, EcoString, EcoVec};
 
-use crate::diag::{bail, At, SourceResult};
+use crate::diag::{bail, warning, At, SourceResult};
 use crate::engine::{Engine, Route, Sink, Traced};
 use crate::foundations::{
     cast, elem, func, scope, select_where, ty, Args, Construct, Content, Context, Func,
@@ -325,13 +325,19 @@ impl State {
         context: Tracked<Context>,
         /// The callsite span.
         span: Span,
-        /// _Compatibility:_ This argument only exists for compatibility with
-        /// Typst 0.10 and lower and shouldn't be used anymore.
+        /// _Compatibility:_ This argument is deprecated. It only exists for
+        /// compatibility with Typst 0.10 and lower and shouldn't be used
+        /// anymore.
         #[default]
         location: Option<Location>,
     ) -> SourceResult<Value> {
         if location.is_none() {
             context.location().at(span)?;
+        } else {
+            engine.sink.warn(warning!(
+                span, "calling `state.final` with a location is deprecated";
+                hint: "try removing the location argument"
+            ));
         }
 
         let sequence = self.sequence(engine)?;
@@ -365,6 +371,8 @@ impl State {
     #[func]
     pub fn display(
         self,
+        /// The engine.
+        engine: &mut Engine,
         /// The span of the `display` call.
         span: Span,
         /// A function which receives the value of the state and can return
@@ -373,6 +381,11 @@ impl State {
         #[default]
         func: Option<Func>,
     ) -> Content {
+        engine.sink.warn(warning!(
+            span, "`state.display` is deprecated";
+            hint: "use `state.get` in a `context` expression instead"
+        ));
+
         StateDisplayElem::new(self, func).pack().spanned(span)
     }
 }
diff --git a/crates/typst/src/layout/measure.rs b/crates/typst/src/layout/measure.rs
index af093f243..cb08e5913 100644
--- a/crates/typst/src/layout/measure.rs
+++ b/crates/typst/src/layout/measure.rs
@@ -1,6 +1,6 @@
 use comemo::Tracked;
 
-use crate::diag::{At, SourceResult};
+use crate::diag::{warning, At, SourceResult};
 use crate::engine::Engine;
 use crate::foundations::{
     dict, func, Content, Context, Dict, Resolve, Smart, StyleChain, Styles,
@@ -76,13 +76,19 @@ pub fn measure(
     height: Smart<Length>,
     /// The content whose size to measure.
     content: Content,
-    /// _Compatibility:_ This argument only exists for compatibility with
-    /// Typst 0.10 and lower and shouldn't be used anymore.
+    /// _Compatibility:_ This argument is deprecated. It only exists for
+    /// compatibility with Typst 0.10 and lower and shouldn't be used anymore.
     #[default]
     styles: Option<Styles>,
 ) -> SourceResult<Dict> {
     let styles = match &styles {
-        Some(styles) => StyleChain::new(styles),
+        Some(styles) => {
+            engine.sink.warn(warning!(
+                span, "calling `measure` with a styles argument is deprecated";
+                hint: "try removing the styles argument"
+            ));
+            StyleChain::new(styles)
+        }
         None => context.styles().at(span)?,
     };
 
diff --git a/tests/suite/foundations/context.typ b/tests/suite/foundations/context.typ
index fea9f544c..0906fb1e4 100644
--- a/tests/suite/foundations/context.typ
+++ b/tests/suite/foundations/context.typ
@@ -43,10 +43,16 @@
   #s.update(x =>
     eval(expr.replace("x", str(x)))
   )
+  // Warning: 17-28 `state.display` is deprecated
+  // Hint: 17-28 use `state.get` in a `context` expression instead
   New value is #s.display().
 ]
 
+// Warning: 1:2-6:3 `locate` with callback function is deprecated
+// Hint: 1:2-6:3 use a `context` expression instead
 #locate(loc => {
+  // Warning: 14-32 calling `query` with a location is deprecated
+  // Hint: 14-32 try removing the location argument
   let elem = query(<here>, loc).first()
   test(s.at(elem.location()), 13)
 })
@@ -58,8 +64,15 @@
 #compute("x - 5")
 
 --- context-compatibility-styling ---
+// Warning: 2-53 `style` is deprecated
+// Hint: 2-53 use a `context` expression instead
+// Warning: 18-39 calling `measure` with a styles argument is deprecated
+// Hint: 18-39 try removing the styles argument
 #style(styles => measure([it], styles).width < 20pt)
 
 --- context-compatibility-counter-display ---
 #counter(heading).update(10)
+
+// Warning: 2-44 `counter.display` without context is deprecated
+// Hint: 2-44 use it in a `context` expression instead
 #counter(heading).display(n => test(n, 10))
diff --git a/tests/suite/introspection/counter.typ b/tests/suite/introspection/counter.typ
index c0b179211..be17d7e06 100644
--- a/tests/suite/introspection/counter.typ
+++ b/tests/suite/introspection/counter.typ
@@ -79,7 +79,7 @@ At Beta, it was #context {
 
 --- issue-2480-counter-reset ---
 #let q = counter("question")
-#let step-show =  q.step() + q.display("1")
+#let step-show =  q.step() + context q.display("1")
 #let g = grid(step-show, step-show, gutter: 2pt)
 
 #g
diff --git a/tests/suite/layout/grid/footers.typ b/tests/suite/layout/grid/footers.typ
index 7cd09003c..edbb36fb1 100644
--- a/tests/suite/layout/grid/footers.typ
+++ b/tests/suite/layout/grid/footers.typ
@@ -282,17 +282,17 @@
   rows: (auto, 2em, auto, auto),
   table.header(
     [eeec],
-    table.cell(rowspan: 2, count.step() + count.display()),
+    table.cell(rowspan: 2, count.step() + context count.display()),
   ),
   [d],
   block(width: 5em, fill: yellow, lorem(7)),
   [d],
   table.footer(
     [eeec],
-    table.cell(rowspan: 2, count.step() + count.display()),
+    table.cell(rowspan: 2, count.step() + context count.display()),
   )
 )
-#count.display()
+#context count.display()
 
 --- grid-nested-with-footers ---
 // Nested table with footer should repeat both footers
diff --git a/tests/suite/layout/grid/headers.typ b/tests/suite/layout/grid/headers.typ
index 78a2540f4..c9c95e134 100644
--- a/tests/suite/layout/grid/headers.typ
+++ b/tests/suite/layout/grid/headers.typ
@@ -265,13 +265,13 @@
   rows: (auto, 2em, auto, auto),
   table.header(
     [eeec],
-    table.cell(rowspan: 2, count.step() + count.display()),
+    table.cell(rowspan: 2, count.step() + context count.display()),
   ),
   [d],
   block(width: 5em, fill: yellow, lorem(15)),
   [d]
 )
-#count.display()
+#context count.display()
 
 --- grid-header-expand ---
 // Ensure header expands to fit cell placed in it after its declaration
diff --git a/tests/suite/layout/grid/rowspan.typ b/tests/suite/layout/grid/rowspan.typ
index f7a377b6e..e5c8bbc8c 100644
--- a/tests/suite/layout/grid/rowspan.typ
+++ b/tests/suite/layout/grid/rowspan.typ
@@ -163,7 +163,7 @@
 #let count = counter("count")
 #show grid.cell: it => {
   count.step()
-  count.display()
+  context count.display()
 }
 
 #grid(
diff --git a/tests/suite/layout/spacing.typ b/tests/suite/layout/spacing.typ
index c32e6c8f9..f59389956 100644
--- a/tests/suite/layout/spacing.typ
+++ b/tests/suite/layout/spacing.typ
@@ -34,7 +34,7 @@ Totally #h() ignored
   h(1em)
   counter(heading).update(4)
   [Hello ]
-  counter(heading).display()
+  context counter(heading).display()
 }
 
 --- trim-weak-space-line-beginning ---
diff --git a/tests/suite/styling/fold.typ b/tests/suite/styling/fold.typ
index 26fe991b2..4b77f9d52 100644
--- a/tests/suite/styling/fold.typ
+++ b/tests/suite/styling/fold.typ
@@ -12,8 +12,13 @@ fi
 --- fold-vec-order-meta ---
 #let c = counter("mycounter")
 #c.update(1)
+
+// Warning: 1:2-7:3 `locate` with callback function is deprecated
+// Hint: 1:2-7:3 use a `context` expression instead
 #locate(loc => [
   #c.update(2)
   #c.at(loc) \
+  // Warning: 12-36 `locate` with callback function is deprecated
+  // Hint: 12-36 use a `context` expression instead
   Second: #locate(loc => c.at(loc))
 ])