diff options
Diffstat (limited to 'crates/typst-library/src/meta/query.rs')
| -rw-r--r-- | crates/typst-library/src/meta/query.rs | 49 |
1 files changed, 15 insertions, 34 deletions
diff --git a/crates/typst-library/src/meta/query.rs b/crates/typst-library/src/meta/query.rs index eb520896..d6c600d7 100644 --- a/crates/typst-library/src/meta/query.rs +++ b/crates/typst-library/src/meta/query.rs @@ -4,10 +4,10 @@ use crate::prelude::*; /// /// The `query` functions lets you search your document for elements of a /// particular type or with a particular label. To use it, you first need to -/// retrieve the current document location with the [`locate`]($func/locate) +/// retrieve the current document location with the [`locate`]($locate) /// function. /// -/// ## Finding elements { #finding-elements } +/// # Finding elements /// In the example below, we create a custom page header that displays the text /// "Typst Academy" in small capitals and the current section title. On the /// first page, the section title is omitted because the header is before the @@ -59,7 +59,7 @@ use crate::prelude::*; /// #lorem(15) /// ``` /// -/// ## A word of caution { #caution } +/// # A word of caution { #caution } /// To resolve all your queries, Typst evaluates and layouts parts of the /// document multiple times. However, there is no guarantee that your queries /// can actually be completely resolved. If you aren't careful a query can @@ -73,9 +73,9 @@ use crate::prelude::*; /// on. As we can see, the output has five headings. This is because Typst /// simply gives up after five attempts. /// -/// In general, you should try not to write queries that affect themselves. -/// The same words of caution also apply to other introspection features like -/// [counters]($func/counter) and [state]($func/state). +/// In general, you should try not to write queries that affect themselves. The +/// same words of caution also apply to other introspection features like +/// [counters]($counter) and [state]($state). /// /// ```example /// = Real @@ -86,11 +86,11 @@ use crate::prelude::*; /// }) /// ``` /// -/// ## Command line queries { #command-line-queries } +/// # Command line queries /// You can also perform queries from the command line with the `typst query` /// command. This command executes an arbitrary query on the document and /// returns the resulting elements in serialized form. Consider the following -/// `example.typ` file which contains some invisible [metadata]($func/metadata): +/// `example.typ` file which contains some invisible [metadata]($metadata): /// /// ```typ /// #metadata("This is a note") <note> @@ -125,32 +125,29 @@ use crate::prelude::*; /// $ typst query example.typ "<note>" --field value --one /// "This is a note" /// ``` -/// -/// Display: Query -/// Category: meta #[func] pub fn query( + /// The virtual machine. + vm: &mut Vm, /// Can be an element function like a `heading` or `figure`, a `{<label>}` /// or a more complex selector like `{heading.where(level: 1)}`. /// /// Currently, only a subset of element functions is supported. Aside from /// headings and figures, this includes equations, references and all /// elements with an explicit label. As a result, you _can_ query for e.g. - /// [`strong`]($func/strong) elements, but you will find only those that - /// have an explicit label attached to them. This limitation will be - /// resolved in the future. + /// [`strong`]($strong) elements, but you will find only those that have an + /// explicit label attached to them. This limitation will be resolved in the + /// future. target: LocatableSelector, /// Can be an arbitrary location, as its value is irrelevant for the /// function's return value. Why is it required then? As noted before, Typst /// has to evaluate parts of your code multiple times to determine the /// values of all state. By only allowing this function within - /// [`locate`]($func/locate) calls, the amount of code that can depend on - /// the query's result is reduced. If you could call it directly at the top + /// [`locate`]($locate) calls, the amount of code that can depend on the + /// query's result is reduced. If you could call it directly at the top /// level of a module, the evaluation of the whole module and its exports /// could depend on the query's result. location: Location, - /// The virtual machine. - vm: &mut Vm, ) -> Array { let _ = location; let vec = vm.vt.introspector.query(&target.0); @@ -158,19 +155,3 @@ pub fn query( .map(|elem| Value::Content(elem.into_inner())) .collect() } - -/// Turns a value into a selector. The following values are accepted: -/// - An element function like a `heading` or `figure`. -/// - A `{<label>}`. -/// - A more complex selector like `{heading.where(level: 1)}`. -/// -/// Display: Selector -/// Category: meta -#[func] -pub fn selector( - /// Can be an element function like a `heading` or `figure`, a `{<label>}` - /// or a more complex selector like `{heading.where(level: 1)}`. - target: Selector, -) -> Selector { - target -} |