typst 0.12.0

A new markup-based typesetting system that is powerful and easy to learn.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119

use comemo::{Track, Tracked};

use crate::diag::{warning, HintedStrResult, SourceResult};
use crate::engine::Engine;
use crate::foundations::{
    cast, elem, func, Content, Context, Func, LocatableSelector, NativeElement, Packed,
    Show, StyleChain, Value,
};
use crate::introspection::{Locatable, Location};
use crate::syntax::Span;

/// Determines the location of an element in the document.
///
/// Takes a selector that must match exactly one element and returns that
/// element's [`location`]. This location can, in particular, be used to
/// retrieve the physical [`page`]($location.page) number and
/// [`position`]($location.position) (page, x, y) for that element.
///
/// # Examples
/// Locating a specific element:
/// ```example
/// #context [
///   Introduction is at: \
///   #locate(<intro>).position()
/// ]
///
/// = Introduction <intro>
/// ```
///
/// # 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). 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.
    engine: &mut Engine,
    /// The callsite context.
    context: Tracked<Context>,
    /// The span of the `locate` call.
    span: Span,
    /// A selector that should match exactly one element. This element will be
    /// located.
    ///
    /// Especially useful in combination with
    /// - [`here`] to locate the current context,
    /// - a [`location`] retrieved from some queried element via the
    ///   [`location()`]($content.location) method on content.
    selector: LocateInput,
) -> HintedStrResult<LocateOutput> {
    Ok(match selector {
        LocateInput::Selector(selector) => {
            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))
        }
    })
}

/// Compatible input type.
pub enum LocateInput {
    Selector(LocatableSelector),
    Func(Func),
}

cast! {
    LocateInput,
    v: Func => {
        if v.element().is_some() {
            Self::Selector(Value::Func(v).cast()?)
        } else {
            Self::Func(v)
        }
    },
    v: LocatableSelector => Self::Selector(v),
}

/// Compatible output type.
pub enum LocateOutput {
    Location(Location),
    Content(Content),
}

cast! {
    LocateOutput,
    self => match self {
        Self::Location(v) => v.into_value(),
        Self::Content(v) => v.into_value(),
    },
    v: Location => Self::Location(v),
    v: Content => Self::Content(v),
}

/// Executes a `locate` call.
#[elem(Locatable, Show)]
struct LocateElem {
    /// The function to call with the location.
    #[required]
    func: Func,
}

impl Show for Packed<LocateElem> {
    #[typst_macros::time(name = "locate", span = self.span())]
    fn show(&self, engine: &mut Engine, styles: StyleChain) -> SourceResult<Content> {
        let location = self.location().unwrap();
        let context = Context::new(Some(location), Some(styles));
        Ok(self.func().call(engine, context.track(), [location])?.display())
    }
}