caisin/typst
1
0
Fork 0
mirror of https://github.com/typst/typst synced 2025-05-14 17:15:28 +08:00
Code Issues Packages Projects Releases Wiki Activity

First-class types

Browse Source 
Makes types first-class values.
This commit is contained in:
Laurenz 2023-09-11 14:40:22 +02:00
parent 8f36fca684
commit b471ac7d59
140 changed files with 6932 additions and 6098 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
Cargo.lock generated
View File

@ -625,9 +625,9 @@ checksum = "9ea835d29036a4087793836fa931b08837ad5e957da9e23886b29586fb9b6650"
[[package]] [[package]]
name = "ecow" name = "ecow"
version = "0.1.1" version = "0.1.2"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c5c5051925c54d9a42c8652313b5358a7432eed209466b443ed5220431243a14" checksum = "1d1990d053cf6edf3f030682dba3b0eb65ef01fabb2686072765d8a17d6728e8"
dependencies = [ dependencies = [
"serde", "serde",
] ]

2
crates/typst-library/Cargo.toml
View File

@ -22,7 +22,7 @@ az = "1.2"
chinese-number = { version = "0.7.2", default-features = false, features = ["number-to-chinese"] } chinese-number = { version = "0.7.2", default-features = false, features = ["number-to-chinese"] }
comemo = "0.3" comemo = "0.3"
csv = "1" csv = "1"
ecow = "0.1" ecow = { version = "0.1.2", features = ["serde"] }
hayagriva = "0.3.2" hayagriva = "0.3.2"
hypher = "0.1.3" hypher = "0.1.3"
icu_properties = { version = "1.2.0", features = ["serde"] } icu_properties = { version = "1.2.0", features = ["serde"] }

295
crates/typst-library/src/compute/calc.rs
View File

@ -8,62 +8,65 @@ use typst::eval::{Module, Scope};
use crate::prelude::*; use crate::prelude::*;
/// A module with computational functions. /// Hook up all calculation definitions.
pub fn module() -> Module { pub(super) fn define(global: &mut Scope) {
global.category("calculate");
global.define_module(module());
}
/// A module with calculation definitions.
fn module() -> Module {
let mut scope = Scope::new(); let mut scope = Scope::new();
scope.define("abs", abs_func()); scope.category("calculate");
scope.define("pow", pow_func()); scope.define_func::<abs>();
scope.define("exp", exp_func()); scope.define_func::<pow>();
scope.define("sqrt", sqrt_func()); scope.define_func::<exp>();
scope.define("sin", sin_func()); scope.define_func::<sqrt>();
scope.define("cos", cos_func()); scope.define_func::<sin>();
scope.define("tan", tan_func()); scope.define_func::<cos>();
scope.define("asin", asin_func()); scope.define_func::<tan>();
scope.define("acos", acos_func()); scope.define_func::<asin>();
scope.define("atan", atan_func()); scope.define_func::<acos>();
scope.define("atan2", atan2_func()); scope.define_func::<atan>();
scope.define("sinh", sinh_func()); scope.define_func::<atan2>();
scope.define("cosh", cosh_func()); scope.define_func::<sinh>();
scope.define("tanh", tanh_func()); scope.define_func::<cosh>();
scope.define("log", log_func()); scope.define_func::<tanh>();
scope.define("ln", ln_func()); scope.define_func::<log>();
scope.define("fact", fact_func()); scope.define_func::<ln>();
scope.define("perm", perm_func()); scope.define_func::<fact>();
scope.define("binom", binom_func()); scope.define_func::<perm>();
scope.define("gcd", gcd_func()); scope.define_func::<binom>();
scope.define("lcm", lcm_func()); scope.define_func::<gcd>();
scope.define("floor", floor_func()); scope.define_func::<lcm>();
scope.define("ceil", ceil_func()); scope.define_func::<floor>();
scope.define("trunc", trunc_func()); scope.define_func::<ceil>();
scope.define("fract", fract_func()); scope.define_func::<trunc>();
scope.define("round", round_func()); scope.define_func::<fract>();
scope.define("clamp", clamp_func()); scope.define_func::<round>();
scope.define("min", min_func()); scope.define_func::<clamp>();
scope.define("max", max_func()); scope.define_func::<min>();
scope.define("even", even_func()); scope.define_func::<max>();
scope.define("odd", odd_func()); scope.define_func::<even>();
scope.define("rem", rem_func()); scope.define_func::<odd>();
scope.define("quo", quo_func()); scope.define_func::<rem>();
scope.define_func::<quo>();
scope.define("inf", f64::INFINITY); scope.define("inf", f64::INFINITY);
scope.define("nan", f64::NAN); scope.define("nan", f64::NAN);
scope.define("pi", std::f64::consts::PI); scope.define("pi", std::f64::consts::PI);
scope.define("tau", std::f64::consts::TAU); scope.define("tau", std::f64::consts::TAU);
scope.define("e", std::f64::consts::E); scope.define("e", std::f64::consts::E);
Module::new("calc").with_scope(scope) Module::new("calc", scope)
} }
/// Calculates the absolute value of a numeric value. /// Calculates the absolute value of a numeric value.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #calc.abs(-5) \ /// #calc.abs(-5) \
/// #calc.abs(5pt - 2cm) \ /// #calc.abs(5pt - 2cm) \
/// #calc.abs(2fr) /// #calc.abs(2fr)
/// ``` /// ```
/// #[func(title = "Absolute")]
/// Display: Absolute
/// Category: calculate
#[func]
pub fn abs( pub fn abs(
/// The value whose absolute value to calculate. /// The value whose absolute value to calculate.
value: ToAbs, value: ToAbs,
@ -87,21 +90,17 @@ cast! {
/// Raises a value to some exponent. /// Raises a value to some exponent.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #calc.pow(2, 3) /// #calc.pow(2, 3)
/// ``` /// ```
/// #[func(title = "Power")]
/// Display: Power
/// Category: calculate
#[func]
pub fn pow( pub fn pow(
/// The callsite span.
span: Span,
/// The base of the power. /// The base of the power.
base: Num, base: Num,
/// The exponent of the power. /// The exponent of the power.
exponent: Spanned<Num>, exponent: Spanned<Num>,
/// The callsite span.
span: Span,
) -> SourceResult<Num> { ) -> SourceResult<Num> {
match exponent.v { match exponent.v {
_ if exponent.v.float() == 0.0 && base.float() == 0.0 => { _ if exponent.v.float() == 0.0 && base.float() == 0.0 => {
@ -142,19 +141,15 @@ pub fn pow(
/// Raises a value to some exponent of e. /// Raises a value to some exponent of e.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #calc.exp(1) /// #calc.exp(1)
/// ``` /// ```
/// #[func(title = "Exponential")]
/// Display: Exponential
/// Category: calculate
#[func]
pub fn exp( pub fn exp(
/// The exponent of the power.
exponent: Spanned<Num>,
/// The callsite span. /// The callsite span.
span: Span, span: Span,
/// The exponent of the power.
exponent: Spanned<Num>,
) -> SourceResult<f64> { ) -> SourceResult<f64> {
match exponent.v { match exponent.v {
Num::Int(i) if i32::try_from(i).is_err() => { Num::Int(i) if i32::try_from(i).is_err() => {
@ -176,15 +171,11 @@ pub fn exp(
/// Extracts the square root of a number. /// Extracts the square root of a number.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #calc.sqrt(16) \ /// #calc.sqrt(16) \
/// #calc.sqrt(2.5) /// #calc.sqrt(2.5)
/// ``` /// ```
/// #[func(title = "Square Root")]
/// Display: Square Root
/// Category: calculate
#[func]
pub fn sqrt( pub fn sqrt(
/// The number whose square root to calculate. Must be non-negative. /// The number whose square root to calculate. Must be non-negative.
value: Spanned<Num>, value: Spanned<Num>,
@ -200,16 +191,12 @@ pub fn sqrt(
/// When called with an integer or a float, they will be interpreted as /// When called with an integer or a float, they will be interpreted as
/// radians. /// radians.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #assert(calc.sin(90deg) == calc.sin(-270deg)) /// #assert(calc.sin(90deg) == calc.sin(-270deg))
/// #calc.sin(1.5) \ /// #calc.sin(1.5) \
/// #calc.sin(90deg) /// #calc.sin(90deg)
/// ``` /// ```
/// #[func(title = "Sine")]
/// Display: Sine
/// Category: calculate
#[func]
pub fn sin( pub fn sin(
/// The angle whose sine to calculate. /// The angle whose sine to calculate.
angle: AngleLike, angle: AngleLike,
@ -226,16 +213,12 @@ pub fn sin(
/// When called with an integer or a float, they will be interpreted as /// When called with an integer or a float, they will be interpreted as
/// radians. /// radians.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #calc.cos(90deg) \ /// #calc.cos(90deg) \
/// #calc.cos(1.5) \ /// #calc.cos(1.5) \
/// #calc.cos(90deg) /// #calc.cos(90deg)
/// ``` /// ```
/// #[func(title = "Cosine")]
/// Display: Cosine
/// Category: calculate
#[func]
pub fn cos( pub fn cos(
/// The angle whose cosine to calculate. /// The angle whose cosine to calculate.
angle: AngleLike, angle: AngleLike,
@ -252,15 +235,11 @@ pub fn cos(
/// When called with an integer or a float, they will be interpreted as /// When called with an integer or a float, they will be interpreted as
/// radians. /// radians.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #calc.tan(1.5) \ /// #calc.tan(1.5) \
/// #calc.tan(90deg) /// #calc.tan(90deg)
/// ``` /// ```
/// #[func(title = "Tangent")]
/// Display: Tangent
/// Category: calculate
#[func]
pub fn tan( pub fn tan(
/// The angle whose tangent to calculate. /// The angle whose tangent to calculate.
angle: AngleLike, angle: AngleLike,
@ -274,15 +253,11 @@ pub fn tan(
/// Calculates the arcsine of a number. /// Calculates the arcsine of a number.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #calc.asin(0) \ /// #calc.asin(0) \
/// #calc.asin(1) /// #calc.asin(1)
/// ``` /// ```
/// #[func(title = "Arcsine")]
/// Display: Arcsine
/// Category: calculate
#[func]
pub fn asin( pub fn asin(
/// The number whose arcsine to calculate. Must be between -1 and 1. /// The number whose arcsine to calculate. Must be between -1 and 1.
value: Spanned<Num>, value: Spanned<Num>,
@ -296,15 +271,11 @@ pub fn asin(
/// Calculates the arccosine of a number. /// Calculates the arccosine of a number.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #calc.acos(0) \ /// #calc.acos(0) \
/// #calc.acos(1) /// #calc.acos(1)
/// ``` /// ```
/// #[func(title = "Arccosine")]
/// Display: Arccosine
/// Category: calculate
#[func]
pub fn acos( pub fn acos(
/// The number whose arcsine to calculate. Must be between -1 and 1. /// The number whose arcsine to calculate. Must be between -1 and 1.
value: Spanned<Num>, value: Spanned<Num>,
@ -318,15 +289,11 @@ pub fn acos(
/// Calculates the arctangent of a number. /// Calculates the arctangent of a number.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #calc.atan(0) \ /// #calc.atan(0) \
/// #calc.atan(1) /// #calc.atan(1)
/// ``` /// ```
/// #[func(title = "Arctangent")]
/// Display: Arctangent
/// Category: calculate
#[func]
pub fn atan( pub fn atan(
/// The number whose arctangent to calculate. /// The number whose arctangent to calculate.
value: Num, value: Num,
@ -338,15 +305,11 @@ pub fn atan(
/// ///
/// The arguments are `(x, y)`, not `(y, x)`. /// The arguments are `(x, y)`, not `(y, x)`.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #calc.atan2(1, 1) \ /// #calc.atan2(1, 1) \
/// #calc.atan2(-2, -3) /// #calc.atan2(-2, -3)
/// ``` /// ```
/// #[func(title = "Four-quadrant Arctangent")]
/// Display: Four-quadrant Arctangent
/// Category: calculate
#[func]
pub fn atan2( pub fn atan2(
/// The X coordinate. /// The X coordinate.
x: Num, x: Num,
@ -358,15 +321,11 @@ pub fn atan2(
/// Calculates the hyperbolic sine of a hyperbolic angle. /// Calculates the hyperbolic sine of a hyperbolic angle.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #calc.sinh(0) \ /// #calc.sinh(0) \
/// #calc.sinh(1.5) /// #calc.sinh(1.5)
/// ``` /// ```
/// #[func(title = "Hyperbolic Sine")]
/// Display: Hyperbolic sine
/// Category: calculate
#[func]
pub fn sinh( pub fn sinh(
/// The hyperbolic angle whose hyperbolic sine to calculate. /// The hyperbolic angle whose hyperbolic sine to calculate.
value: f64, value: f64,
@ -376,15 +335,11 @@ pub fn sinh(
/// Calculates the hyperbolic cosine of a hyperbolic angle. /// Calculates the hyperbolic cosine of a hyperbolic angle.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #calc.cosh(0) \ /// #calc.cosh(0) \
/// #calc.cosh(1.5) /// #calc.cosh(1.5)
/// ``` /// ```
/// #[func(title = "Hyperbolic Cosine")]
/// Display: Hyperbolic cosine
/// Category: calculate
#[func]
pub fn cosh( pub fn cosh(
/// The hyperbolic angle whose hyperbolic cosine to calculate. /// The hyperbolic angle whose hyperbolic cosine to calculate.
value: f64, value: f64,
@ -394,15 +349,11 @@ pub fn cosh(
/// Calculates the hyperbolic tangent of an hyperbolic angle. /// Calculates the hyperbolic tangent of an hyperbolic angle.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #calc.tanh(0) \ /// #calc.tanh(0) \
/// #calc.tanh(1.5) /// #calc.tanh(1.5)
/// ``` /// ```
/// #[func(title = "Hyperbolic Tangent")]
/// Display: Hyperbolic tangent
/// Category: calculate
#[func]
pub fn tanh( pub fn tanh(
/// The hyperbolic angle whose hyperbolic tangent to calculate. /// The hyperbolic angle whose hyperbolic tangent to calculate.
value: f64, value: f64,
@ -414,23 +365,19 @@ pub fn tanh(
/// ///
/// If the base is not specified, the logarithm is calculated in base 10. /// If the base is not specified, the logarithm is calculated in base 10.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #calc.log(100) /// #calc.log(100)
/// ``` /// ```
/// #[func(title = "Logarithm")]
/// Display: Logarithm
/// Category: calculate
#[func]
pub fn log( pub fn log(
/// The callsite span.
span: Span,
/// The number whose logarithm to calculate. Must be strictly positive. /// The number whose logarithm to calculate. Must be strictly positive.
value: Spanned<Num>, value: Spanned<Num>,
/// The base of the logarithm. May not be zero. /// The base of the logarithm. May not be zero.
#[named] #[named]
#[default(Spanned::new(10.0, Span::detached()))] #[default(Spanned::new(10.0, Span::detached()))]
base: Spanned<f64>, base: Spanned<f64>,
/// The callsite span.
span: Span,
) -> SourceResult<f64> { ) -> SourceResult<f64> {
let number = value.v.float(); let number = value.v.float();
if number <= 0.0 { if number <= 0.0 {
@ -460,19 +407,15 @@ pub fn log(
/// Calculates the natural logarithm of a number. /// Calculates the natural logarithm of a number.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #calc.ln(calc.e) /// #calc.ln(calc.e)
/// ``` /// ```
/// #[func(title = "Natural Logarithm")]
/// Display: Natural Logarithm
/// Category: calculate
#[func]
pub fn ln( pub fn ln(
/// The number whose logarithm to calculate. Must be strictly positive.
value: Spanned<Num>,
/// The callsite span. /// The callsite span.
span: Span, span: Span,
/// The number whose logarithm to calculate. Must be strictly positive.
value: Spanned<Num>,
) -> SourceResult<f64> { ) -> SourceResult<f64> {
let number = value.v.float(); let number = value.v.float();
if number <= 0.0 { if number <= 0.0 {
@ -489,14 +432,10 @@ pub fn ln(
/// Calculates the factorial of a number. /// Calculates the factorial of a number.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #calc.fact(5) /// #calc.fact(5)
/// ``` /// ```
/// #[func(title = "Factorial")]
/// Display: Factorial
/// Category: calculate
#[func]
pub fn fact( pub fn fact(
/// The number whose factorial to calculate. Must be non-negative. /// The number whose factorial to calculate. Must be non-negative.
number: u64, number: u64,
@ -506,14 +445,10 @@ pub fn fact(
/// Calculates a permutation. /// Calculates a permutation.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #calc.perm(10, 5) /// #calc.perm(10, 5)
/// ``` /// ```
/// #[func(title = "Permutation")]
/// Display: Permutation
/// Category: calculate
#[func]
pub fn perm( pub fn perm(
/// The base number. Must be non-negative. /// The base number. Must be non-negative.
base: u64, base: u64,
@ -547,14 +482,10 @@ fn fact_impl(start: u64, end: u64) -> Option<i64> {
/// Calculates a binomial coefficient. /// Calculates a binomial coefficient.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #calc.binom(10, 5) /// #calc.binom(10, 5)
/// ``` /// ```
/// #[func(title = "Binomial")]
/// Display: Binomial
/// Category: calculate
#[func]
pub fn binom( pub fn binom(
/// The upper coefficient. Must be non-negative. /// The upper coefficient. Must be non-negative.
n: u64, n: u64,
@ -588,14 +519,10 @@ fn binom_impl(n: u64, k: u64) -> Option<i64> {
/// Calculates the greatest common divisor of two integers. /// Calculates the greatest common divisor of two integers.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #calc.gcd(7, 42) /// #calc.gcd(7, 42)
/// ``` /// ```
/// #[func(title = "Greatest Common Divisor")]
/// Display: Greatest Common Divisor
/// Category: calculate
#[func]
pub fn gcd( pub fn gcd(
/// The first integer. /// The first integer.
a: i64, a: i64,
@ -614,14 +541,10 @@ pub fn gcd(
/// Calculates the least common multiple of two integers. /// Calculates the least common multiple of two integers.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #calc.lcm(96, 13) /// #calc.lcm(96, 13)
/// ``` /// ```
/// #[func(title = "Least Common Multiple")]
/// Display: Least Common Multiple
/// Category: calculate
#[func]
pub fn lcm( pub fn lcm(
/// The first integer. /// The first integer.
a: i64, a: i64,
@ -642,15 +565,11 @@ pub fn lcm(
/// ///
/// If the number is already an integer, it is returned unchanged. /// If the number is already an integer, it is returned unchanged.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #assert(calc.floor(3.14) == 3) /// #assert(calc.floor(3.14) == 3)
/// #assert(calc.floor(3) == 3) /// #assert(calc.floor(3) == 3)
/// #calc.floor(500.1) /// #calc.floor(500.1)
/// ``` /// ```
///
/// Display: Round down
/// Category: calculate
#[func] #[func]
pub fn floor( pub fn floor(
/// The number to round down. /// The number to round down.
@ -666,15 +585,11 @@ pub fn floor(
/// ///
/// If the number is already an integer, it is returned unchanged. /// If the number is already an integer, it is returned unchanged.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #assert(calc.ceil(3.14) == 4) /// #assert(calc.ceil(3.14) == 4)
/// #assert(calc.ceil(3) == 3) /// #assert(calc.ceil(3) == 3)
/// #calc.ceil(500.1) /// #calc.ceil(500.1)
/// ``` /// ```
///
/// Display: Round up
/// Category: calculate
#[func] #[func]
pub fn ceil( pub fn ceil(
/// The number to round up. /// The number to round up.
@ -690,16 +605,12 @@ pub fn ceil(
/// ///
/// If the number is already an integer, it is returned unchanged. /// If the number is already an integer, it is returned unchanged.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #assert(calc.trunc(3) == 3) /// #assert(calc.trunc(3) == 3)
/// #assert(calc.trunc(-3.7) == -3) /// #assert(calc.trunc(-3.7) == -3)
/// #assert(calc.trunc(15.9) == 15) /// #assert(calc.trunc(15.9) == 15)
/// ``` /// ```
/// #[func(title = "Truncate")]
/// Display: Truncate
/// Category: calculate
#[func]
pub fn trunc( pub fn trunc(
/// The number to truncate. /// The number to truncate.
value: Num, value: Num,
@ -714,15 +625,11 @@ pub fn trunc(
/// ///
/// If the number is an integer, returns `0`. /// If the number is an integer, returns `0`.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #assert(calc.fract(3) == 0) /// #assert(calc.fract(3) == 0)
/// #calc.fract(-3.1) /// #calc.fract(-3.1)
/// ``` /// ```
/// #[func(title = "Fractional")]
/// Display: Fractional
/// Category: calculate
#[func]
pub fn fract( pub fn fract(
/// The number to truncate. /// The number to truncate.
value: Num, value: Num,
@ -737,15 +644,11 @@ pub fn fract(
/// ///
/// Optionally, a number of decimal places can be specified. /// Optionally, a number of decimal places can be specified.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #assert(calc.round(3.14) == 3) /// #assert(calc.round(3.14) == 3)
/// #assert(calc.round(3.5) == 4) /// #assert(calc.round(3.5) == 4)
/// #calc.round(3.1415, digits: 2) /// #calc.round(3.1415, digits: 2)
/// ``` /// ```
///
/// Display: Round
/// Category: calculate
#[func] #[func]
pub fn round( pub fn round(
/// The number to round. /// The number to round.
@ -767,15 +670,11 @@ pub fn round(
/// Clamps a number between a minimum and maximum value. /// Clamps a number between a minimum and maximum value.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #assert(calc.clamp(5, 0, 10) == 5) /// #assert(calc.clamp(5, 0, 10) == 5)
/// #assert(calc.clamp(5, 6, 10) == 6) /// #assert(calc.clamp(5, 6, 10) == 6)
/// #calc.clamp(5, 0, 4) /// #calc.clamp(5, 0, 4)
/// ``` /// ```
///
/// Display: Clamp
/// Category: calculate
#[func] #[func]
pub fn clamp( pub fn clamp(
/// The number to clamp. /// The number to clamp.
@ -793,44 +692,36 @@ pub fn clamp(
/// Determines the minimum of a sequence of values. /// Determines the minimum of a sequence of values.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #calc.min(1, -3, -5, 20, 3, 6) \ /// #calc.min(1, -3, -5, 20, 3, 6) \
/// #calc.min("typst", "in", "beta") /// #calc.min("typst", "in", "beta")
/// ``` /// ```
/// #[func(title = "Minimum")]
/// Display: Minimum
/// Category: calculate
#[func]
pub fn min( pub fn min(
/// The callsite span.
span: Span,
/// The sequence of values from which to extract the minimum. /// The sequence of values from which to extract the minimum.
/// Must not be empty. /// Must not be empty.
#[variadic] #[variadic]
values: Vec<Spanned<Value>>, values: Vec<Spanned<Value>>,
/// The callsite span.
span: Span,
) -> SourceResult<Value> { ) -> SourceResult<Value> {
minmax(span, values, Ordering::Less) minmax(span, values, Ordering::Less)
} }
/// Determines the maximum of a sequence of values. /// Determines the maximum of a sequence of values.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #calc.max(1, -3, -5, 20, 3, 6) \ /// #calc.max(1, -3, -5, 20, 3, 6) \
/// #calc.max("typst", "in", "beta") /// #calc.max("typst", "in", "beta")
/// ``` /// ```
/// #[func(title = "Maximum")]
/// Display: Maximum
/// Category: calculate
#[func]
pub fn max( pub fn max(
/// The callsite span.
span: Span,
/// The sequence of values from which to extract the maximum. /// The sequence of values from which to extract the maximum.
/// Must not be empty. /// Must not be empty.
#[variadic] #[variadic]
values: Vec<Spanned<Value>>, values: Vec<Spanned<Value>>,
/// The callsite span.
span: Span,
) -> SourceResult<Value> { ) -> SourceResult<Value> {
minmax(span, values, Ordering::Greater) minmax(span, values, Ordering::Greater)
} }
@ -858,15 +749,11 @@ fn minmax(
/// Determines whether an integer is even. /// Determines whether an integer is even.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #calc.even(4) \ /// #calc.even(4) \
/// #calc.even(5) \ /// #calc.even(5) \
/// #range(10).filter(calc.even) /// #range(10).filter(calc.even)
/// ``` /// ```
///
/// Display: Even
/// Category: calculate
#[func] #[func]
pub fn even( pub fn even(
/// The number to check for evenness. /// The number to check for evenness.
@ -877,15 +764,11 @@ pub fn even(
/// Determines whether an integer is odd. /// Determines whether an integer is odd.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #calc.odd(4) \ /// #calc.odd(4) \
/// #calc.odd(5) \ /// #calc.odd(5) \
/// #range(10).filter(calc.odd) /// #range(10).filter(calc.odd)
/// ``` /// ```
///
/// Display: Odd
/// Category: calculate
#[func] #[func]
pub fn odd( pub fn odd(
/// The number to check for oddness. /// The number to check for oddness.
@ -896,15 +779,11 @@ pub fn odd(
/// Calculates the remainder of two numbers. /// Calculates the remainder of two numbers.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #calc.rem(20, 6) \ /// #calc.rem(20, 6) \
/// #calc.rem(1.75, 0.5) /// #calc.rem(1.75, 0.5)
/// ``` /// ```
/// #[func(title = "Remainder")]
/// Display: Remainder
/// Category: calculate
#[func]
pub fn rem( pub fn rem(
/// The dividend of the remainder. /// The dividend of the remainder.
dividend: Num, dividend: Num,
@ -919,15 +798,11 @@ pub fn rem(
/// Calculates the quotient of two numbers. /// Calculates the quotient of two numbers.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #calc.quo(14, 5) \ /// #calc.quo(14, 5) \
/// #calc.quo(3.46, 0.5) /// #calc.quo(3.46, 0.5)
/// ``` /// ```
/// #[func(title = "Quotient")]
/// Display: Quotient
/// Category: calculate
#[func]
pub fn quo( pub fn quo(
/// The dividend of the quotient. /// The dividend of the quotient.
dividend: Num, dividend: Num,
@ -949,7 +824,7 @@ pub enum Num {
} }
impl Num { impl Num {
pub fn apply2( fn apply2(
self, self,
other: Self, other: Self,
int: impl FnOnce(i64, i64) -> i64, int: impl FnOnce(i64, i64) -> i64,
@ -961,7 +836,7 @@ impl Num {
} }
} }
pub fn apply3( fn apply3(
self, self,
other: Self, other: Self,
third: Self, third: Self,
@ -974,7 +849,7 @@ impl Num {
} }
} }
pub fn float(self) -> f64 { fn float(self) -> f64 {
match self { match self {
Self::Int(v) => v as f64, Self::Int(v) => v as f64,
Self::Float(v) => v, Self::Float(v) => v,

1015
crates/typst-library/src/compute/construct.rs
View File

File diff suppressed because it is too large Load Diff

236
crates/typst-library/src/compute/data.rs
View File

@ -4,15 +4,25 @@ use typst::syntax::is_newline;
use crate::prelude::*; use crate::prelude::*;
/// Hook up all data loading definitions.
pub(super) fn define(global: &mut Scope) {
global.category("data-loading");
global.define_func::<read>();
global.define_func::<csv>();
global.define_func::<json>();
global.define_func::<toml>();
global.define_func::<yaml>();
global.define_func::<cbor>();
global.define_func::<xml>();
}
/// Reads plain text or data from a file. /// Reads plain text or data from a file.
/// ///
/// By default, the file will be read as UTF-8 and returned as a /// By default, the file will be read as UTF-8 and returned as a [string]($str).
/// [string]($type/string).
/// ///
/// If you specify `{encoding: none}`, this returns raw [bytes]($type/bytes) /// If you specify `{encoding: none}`, this returns raw [bytes]($bytes) instead.
/// instead.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// An example for a HTML file: \ /// An example for a HTML file: \
/// #let text = read("data.html") /// #let text = read("data.html")
@ -21,11 +31,10 @@ use crate::prelude::*;
/// Raw bytes: /// Raw bytes:
/// #read("tiger.jpg", encoding: none) /// #read("tiger.jpg", encoding: none)
/// ``` /// ```
///
/// Display: Read
/// Category: data-loading
#[func] #[func]
pub fn read( pub fn read(
/// The virtual machine.
vm: &mut Vm,
/// Path to a file. /// Path to a file.
path: Spanned<EcoString>, path: Spanned<EcoString>,
/// The encoding to read the file with. /// The encoding to read the file with.
@ -34,8 +43,6 @@ pub fn read(
#[named] #[named]
#[default(Some(Encoding::Utf8))] #[default(Some(Encoding::Utf8))]
encoding: Option<Encoding>, encoding: Option<Encoding>,
/// The virtual machine.
vm: &mut Vm,
) -> SourceResult<Readable> { ) -> SourceResult<Readable> {
let Spanned { v: path, span } = path; let Spanned { v: path, span } = path;
let id = vm.resolve_path(&path).at(span)?; let id = vm.resolve_path(&path).at(span)?;
@ -101,7 +108,7 @@ impl From<Readable> for Bytes {
/// rows will be collected into a single array. Header rows will not be /// rows will be collected into a single array. Header rows will not be
/// stripped. /// stripped.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #let results = csv("data.csv") /// #let results = csv("data.csv")
/// ///
@ -111,15 +118,10 @@ impl From<Readable> for Bytes {
/// ..results.flatten(), /// ..results.flatten(),
/// ) /// )
/// ``` /// ```
/// #[func(scope, title = "CSV")]
/// Display: CSV
/// Category: data-loading
#[func]
#[scope(
scope.define("decode", csv_decode_func());
scope
)]
pub fn csv( pub fn csv(
/// The virtual machine.
vm: &mut Vm,
/// Path to a CSV file. /// Path to a CSV file.
path: Spanned<EcoString>, path: Spanned<EcoString>,
/// The delimiter that separates columns in the CSV file. /// The delimiter that separates columns in the CSV file.
@ -127,21 +129,18 @@ pub fn csv(
#[named] #[named]
#[default] #[default]
delimiter: Delimiter, delimiter: Delimiter,
/// The virtual machine.
vm: &mut Vm,
) -> SourceResult<Array> { ) -> SourceResult<Array> {
let Spanned { v: path, span } = path; let Spanned { v: path, span } = path;
let id = vm.resolve_path(&path).at(span)?; let id = vm.resolve_path(&path).at(span)?;
let data = vm.world().file(id).at(span)?; let data = vm.world().file(id).at(span)?;
csv_decode(Spanned::new(Readable::Bytes(data), span), delimiter) self::csv::decode(Spanned::new(Readable::Bytes(data), span), delimiter)
} }
#[scope]
impl csv {
/// Reads structured data from a CSV string/bytes. /// Reads structured data from a CSV string/bytes.
/// #[func(title = "Decode CSV")]
/// Display: Decode CSV pub fn decode(
/// Category: data-loading
#[func]
pub fn csv_decode(
/// CSV data. /// CSV data.
data: Spanned<Readable>, data: Spanned<Readable>,
/// The delimiter that separates columns in the CSV file. /// The delimiter that separates columns in the CSV file.
@ -151,7 +150,7 @@ pub fn csv_decode(
delimiter: Delimiter, delimiter: Delimiter,
) -> SourceResult<Array> { ) -> SourceResult<Array> {
let Spanned { v: data, span } = data; let Spanned { v: data, span } = data;
let mut builder = csv::ReaderBuilder::new(); let mut builder = ::csv::ReaderBuilder::new();
builder.has_headers(false); builder.has_headers(false);
builder.delimiter(delimiter.0 as u8); builder.delimiter(delimiter.0 as u8);
let mut reader = builder.from_reader(data.as_slice()); let mut reader = builder.from_reader(data.as_slice());
@ -169,6 +168,7 @@ pub fn csv_decode(
Ok(array) Ok(array)
} }
}
/// The delimiter to use when parsing CSV files. /// The delimiter to use when parsing CSV files.
pub struct Delimiter(char); pub struct Delimiter(char);
@ -198,10 +198,10 @@ cast! {
} }
/// Format the user-facing CSV error message. /// Format the user-facing CSV error message.
fn format_csv_error(err: csv::Error, line: usize) -> EcoString { fn format_csv_error(err: ::csv::Error, line: usize) -> EcoString {
match err.kind() { match err.kind() {
csv::ErrorKind::Utf8 { .. } => "file is not valid utf-8".into(), ::csv::ErrorKind::Utf8 { .. } => "file is not valid utf-8".into(),
csv::ErrorKind::UnequalLengths { expected_len, len, .. } => { ::csv::ErrorKind::UnequalLengths { expected_len, len, .. } => {
eco_format!( eco_format!(
"failed to parse CSV (found {len} instead of \ "failed to parse CSV (found {len} instead of \
{expected_len} fields in line {line})" {expected_len} fields in line {line})"
@ -224,7 +224,7 @@ fn format_csv_error(err: csv::Error, line: usize) -> EcoString {
/// The JSON files in the example contain objects with the keys `temperature`, /// The JSON files in the example contain objects with the keys `temperature`,
/// `unit`, and `weather`. /// `unit`, and `weather`.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #let forecast(day) = block[ /// #let forecast(day) = block[
/// #box(square( /// #box(square(
@ -248,33 +248,24 @@ fn format_csv_error(err: csv::Error, line: usize) -> EcoString {
/// #forecast(json("monday.json")) /// #forecast(json("monday.json"))
/// #forecast(json("tuesday.json")) /// #forecast(json("tuesday.json"))
/// ``` /// ```
/// #[func(scope, title = "JSON")]
/// Display: JSON
/// Category: data-loading
#[func]
#[scope(
scope.define("decode", json_decode_func());
scope.define("encode", json_encode_func());
scope
)]
pub fn json( pub fn json(
/// Path to a JSON file.
path: Spanned<EcoString>,
/// The virtual machine. /// The virtual machine.
vm: &mut Vm, vm: &mut Vm,
/// Path to a JSON file.
path: Spanned<EcoString>,
) -> SourceResult<Value> { ) -> SourceResult<Value> {
let Spanned { v: path, span } = path; let Spanned { v: path, span } = path;
let id = vm.resolve_path(&path).at(span)?; let id = vm.resolve_path(&path).at(span)?;
let data = vm.world().file(id).at(span)?; let data = vm.world().file(id).at(span)?;
json_decode(Spanned::new(Readable::Bytes(data), span)) json::decode(Spanned::new(Readable::Bytes(data), span))
} }
#[scope]
impl json {
/// Reads structured data from a JSON string/bytes. /// Reads structured data from a JSON string/bytes.
/// #[func(title = "Decode JSON")]
/// Display: JSON pub fn decode(
/// Category: data-loading
#[func]
pub fn json_decode(
/// JSON data. /// JSON data.
data: Spanned<Readable>, data: Spanned<Readable>,
) -> SourceResult<Value> { ) -> SourceResult<Value> {
@ -285,11 +276,8 @@ pub fn json_decode(
} }
/// Encodes structured data into a JSON string. /// Encodes structured data into a JSON string.
/// #[func(title = "Encode JSON")]
/// Display: Encode JSON pub fn encode(
/// Category: data-loading
#[func]
pub fn json_encode(
/// Value to be encoded. /// Value to be encoded.
value: Spanned<Value>, value: Spanned<Value>,
/// Whether to pretty print the JSON with newlines and indentation. /// Whether to pretty print the JSON with newlines and indentation.
@ -307,6 +295,7 @@ pub fn json_encode(
.map_err(|err| eco_format!("failed to encode value as JSON ({err})")) .map_err(|err| eco_format!("failed to encode value as JSON ({err})"))
.at(span) .at(span)
} }
}
/// Reads structured data from a TOML file. /// Reads structured data from a TOML file.
/// ///
@ -319,7 +308,7 @@ pub fn json_encode(
/// The TOML file in the example consists of a table with the keys `title`, /// The TOML file in the example consists of a table with the keys `title`,
/// `version`, and `authors`. /// `version`, and `authors`.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #let details = toml("details.toml") /// #let details = toml("details.toml")
/// ///
@ -328,33 +317,24 @@ pub fn json_encode(
/// Authors: #(details.authors /// Authors: #(details.authors
/// .join(", ", last: " and ")) /// .join(", ", last: " and "))
/// ``` /// ```
/// #[func(scope, title = "TOML")]
/// Display: TOML
/// Category: data-loading
#[func]
#[scope(
scope.define("decode", toml_decode_func());
scope.define("encode", toml_encode_func());
scope
)]
pub fn toml( pub fn toml(
/// Path to a TOML file.
path: Spanned<EcoString>,
/// The virtual machine. /// The virtual machine.
vm: &mut Vm, vm: &mut Vm,
/// Path to a TOML file.
path: Spanned<EcoString>,
) -> SourceResult<Value> { ) -> SourceResult<Value> {
let Spanned { v: path, span } = path; let Spanned { v: path, span } = path;
let id = vm.resolve_path(&path).at(span)?; let id = vm.resolve_path(&path).at(span)?;
let data = vm.world().file(id).at(span)?; let data = vm.world().file(id).at(span)?;
toml_decode(Spanned::new(Readable::Bytes(data), span)) toml::decode(Spanned::new(Readable::Bytes(data), span))
} }
#[scope]
impl toml {
/// Reads structured data from a TOML string/bytes. /// Reads structured data from a TOML string/bytes.
/// #[func(title = "Decode TOML")]
/// Display: Decode TOML pub fn decode(
/// Category: data-loading
#[func]
pub fn toml_decode(
/// TOML data. /// TOML data.
data: Spanned<Readable>, data: Spanned<Readable>,
) -> SourceResult<Value> { ) -> SourceResult<Value> {
@ -362,17 +342,14 @@ pub fn toml_decode(
let raw = std::str::from_utf8(data.as_slice()) let raw = std::str::from_utf8(data.as_slice())
.map_err(|_| "file is not valid utf-8") .map_err(|_| "file is not valid utf-8")
.at(span)?; .at(span)?;
toml::from_str(raw) ::toml::from_str(raw)
.map_err(|err| format_toml_error(err, raw)) .map_err(|err| format_toml_error(err, raw))
.at(span) .at(span)
} }
/// Encodes structured data into a TOML string. /// Encodes structured data into a TOML string.
/// #[func(title = "Encode TOML")]
/// Display: Encode TOML pub fn encode(
/// Category: data-loading
#[func]
pub fn toml_encode(
/// Value to be encoded. /// Value to be encoded.
value: Spanned<Value>, value: Spanned<Value>,
/// Whether to pretty-print the resulting TOML. /// Whether to pretty-print the resulting TOML.
@ -381,14 +358,15 @@ pub fn toml_encode(
pretty: bool, pretty: bool,
) -> SourceResult<Str> { ) -> SourceResult<Str> {
let Spanned { v: value, span } = value; let Spanned { v: value, span } = value;
if pretty { toml::to_string_pretty(&value) } else { toml::to_string(&value) } if pretty { ::toml::to_string_pretty(&value) } else { ::toml::to_string(&value) }
.map(|v| v.into()) .map(|v| v.into())
.map_err(|err| eco_format!("failed to encode value as TOML ({err})")) .map_err(|err| eco_format!("failed to encode value as TOML ({err})"))
.at(span) .at(span)
} }
}
/// Format the user-facing TOML error message. /// Format the user-facing TOML error message.
fn format_toml_error(error: toml::de::Error, raw: &str) -> EcoString { fn format_toml_error(error: ::toml::de::Error, raw: &str) -> EcoString {
if let Some(head) = error.span().and_then(|range| raw.get(..range.start)) { if let Some(head) = error.span().and_then(|range| raw.get(..range.start)) {
let line = head.lines().count(); let line = head.lines().count();
let column = 1 + head.chars().rev().take_while(|&c| !is_newline(c)).count(); let column = 1 + head.chars().rev().take_while(|&c| !is_newline(c)).count();
@ -415,7 +393,7 @@ fn format_toml_error(error: toml::de::Error, raw: &str) -> EcoString {
/// each with a sequence of their own submapping with the keys /// each with a sequence of their own submapping with the keys
/// "title" and "published" /// "title" and "published"
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #let bookshelf(contents) = { /// #let bookshelf(contents) = {
/// for (author, works) in contents { /// for (author, works) in contents {
@ -430,33 +408,24 @@ fn format_toml_error(error: toml::de::Error, raw: &str) -> EcoString {
/// yaml("scifi-authors.yaml") /// yaml("scifi-authors.yaml")
/// ) /// )
/// ``` /// ```
/// #[func(scope, title = "YAML")]
/// Display: YAML
/// Category: data-loading
#[func]
#[scope(
scope.define("decode", yaml_decode_func());
scope.define("encode", yaml_encode_func());
scope
)]
pub fn yaml( pub fn yaml(
/// Path to a YAML file.
path: Spanned<EcoString>,
/// The virtual machine. /// The virtual machine.
vm: &mut Vm, vm: &mut Vm,
/// Path to a YAML file.
path: Spanned<EcoString>,
) -> SourceResult<Value> { ) -> SourceResult<Value> {
let Spanned { v: path, span } = path; let Spanned { v: path, span } = path;
let id = vm.resolve_path(&path).at(span)?; let id = vm.resolve_path(&path).at(span)?;
let data = vm.world().file(id).at(span)?; let data = vm.world().file(id).at(span)?;
yaml_decode(Spanned::new(Readable::Bytes(data), span)) yaml::decode(Spanned::new(Readable::Bytes(data), span))
} }
#[scope]
impl yaml {
/// Reads structured data from a YAML string/bytes. /// Reads structured data from a YAML string/bytes.
/// #[func(title = "Decode YAML")]
/// Display: Decode YAML pub fn decode(
/// Category: data-loading
#[func]
pub fn yaml_decode(
/// YAML data. /// YAML data.
data: Spanned<Readable>, data: Spanned<Readable>,
) -> SourceResult<Value> { ) -> SourceResult<Value> {
@ -467,11 +436,8 @@ pub fn yaml_decode(
} }
/// Encode structured data into a YAML string. /// Encode structured data into a YAML string.
/// #[func(title = "Encode YAML")]
/// Display: Encode YAML pub fn encode(
/// Category: data-loading
#[func]
pub fn yaml_encode(
/// Value to be encoded. /// Value to be encoded.
value: Spanned<Value>, value: Spanned<Value>,
) -> SourceResult<Str> { ) -> SourceResult<Str> {
@ -481,6 +447,7 @@ pub fn yaml_encode(
.map_err(|err| eco_format!("failed to encode value as YAML ({err})")) .map_err(|err| eco_format!("failed to encode value as YAML ({err})"))
.at(span) .at(span)
} }
}
/// Reads structured data from a CBOR file. /// Reads structured data from a CBOR file.
/// ///
@ -490,33 +457,24 @@ pub fn yaml_encode(
/// equivalents, null-values (`null`, `~` or empty ``) will be converted into /// equivalents, null-values (`null`, `~` or empty ``) will be converted into
/// `{none}`, and numbers will be converted to floats or integers depending on /// `{none}`, and numbers will be converted to floats or integers depending on
/// whether they are whole numbers. /// whether they are whole numbers.
/// #[func(scope, title = "CBOR")]
/// Display: CBOR
/// Category: data-loading
#[func]
#[scope(
scope.define("decode", cbor_decode_func());
scope.define("encode", cbor_encode_func());
scope
)]
pub fn cbor( pub fn cbor(
/// Path to a CBOR file.
path: Spanned<EcoString>,
/// The virtual machine. /// The virtual machine.
vm: &mut Vm, vm: &mut Vm,
/// Path to a CBOR file.
path: Spanned<EcoString>,
) -> SourceResult<Value> { ) -> SourceResult<Value> {
let Spanned { v: path, span } = path; let Spanned { v: path, span } = path;
let id = vm.resolve_path(&path).at(span)?; let id = vm.resolve_path(&path).at(span)?;
let data = vm.world().file(id).at(span)?; let data = vm.world().file(id).at(span)?;
cbor_decode(Spanned::new(data, span)) cbor::decode(Spanned::new(data, span))
} }
#[scope]
impl cbor {
/// Reads structured data from CBOR bytes. /// Reads structured data from CBOR bytes.
/// #[func(title = "Decode CBOR")]
/// Display: Decode CBOR pub fn decode(
/// Category: data-loading
#[func]
pub fn cbor_decode(
/// cbor data. /// cbor data.
data: Spanned<Bytes>, data: Spanned<Bytes>,
) -> SourceResult<Value> { ) -> SourceResult<Value> {
@ -527,11 +485,8 @@ pub fn cbor_decode(
} }
/// Encode structured data into CBOR bytes. /// Encode structured data into CBOR bytes.
/// #[func(title = "Encode CBOR")]
/// Display: Encode CBOR pub fn encode(
/// Category: data-loading
#[func]
pub fn cbor_encode(
/// Value to be encoded. /// Value to be encoded.
value: Spanned<Value>, value: Spanned<Value>,
) -> SourceResult<Bytes> { ) -> SourceResult<Bytes> {
@ -542,6 +497,7 @@ pub fn cbor_encode(
.map_err(|err| eco_format!("failed to encode value as CBOR ({err})")) .map_err(|err| eco_format!("failed to encode value as CBOR ({err})"))
.at(span) .at(span)
} }
}
/// Reads structured data from an XML file. /// Reads structured data from an XML file.
/// ///
@ -558,7 +514,7 @@ pub fn cbor_encode(
/// `content` tag contains one or more paragraphs, which are represented as `p` /// `content` tag contains one or more paragraphs, which are represented as `p`
/// tags. /// tags.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #let find-child(elem, tag) = { /// #let find-child(elem, tag) = {
/// elem.children /// elem.children
@ -591,32 +547,24 @@ pub fn cbor_encode(
/// } /// }
/// } /// }
/// ``` /// ```
/// #[func(scope, title = "XML")]
/// Display: XML
/// Category: data-loading
#[func]
#[scope(
scope.define("decode", xml_decode_func());
scope
)]
pub fn xml( pub fn xml(
/// Path to an XML file.
path: Spanned<EcoString>,
/// The virtual machine. /// The virtual machine.
vm: &mut Vm, vm: &mut Vm,
/// Path to an XML file.
path: Spanned<EcoString>,
) -> SourceResult<Value> { ) -> SourceResult<Value> {
let Spanned { v: path, span } = path; let Spanned { v: path, span } = path;
let id = vm.resolve_path(&path).at(span)?; let id = vm.resolve_path(&path).at(span)?;
let data = vm.world().file(id).at(span)?; let data = vm.world().file(id).at(span)?;
xml_decode(Spanned::new(Readable::Bytes(data), span)) xml::decode(Spanned::new(Readable::Bytes(data), span))
} }
#[scope]
impl xml {
/// Reads structured data from an XML string/bytes. /// Reads structured data from an XML string/bytes.
/// #[func(title = "Decode XML")]
/// Display: Decode XML pub fn decode(
/// Category: data-loading
#[func]
pub fn xml_decode(
/// XML data. /// XML data.
data: Spanned<Readable>, data: Spanned<Readable>,
) -> SourceResult<Value> { ) -> SourceResult<Value> {
@ -624,9 +572,11 @@ pub fn xml_decode(
let text = std::str::from_utf8(data.as_slice()) let text = std::str::from_utf8(data.as_slice())
.map_err(FileError::from) .map_err(FileError::from)
.at(span)?; .at(span)?;
let document = roxmltree::Document::parse(text).map_err(format_xml_error).at(span)?; let document =
roxmltree::Document::parse(text).map_err(format_xml_error).at(span)?;
Ok(convert_xml(document.root())) Ok(convert_xml(document.root()))
} }
}
/// Convert an XML node to a Typst value. /// Convert an XML node to a Typst value.
fn convert_xml(node: roxmltree::Node) -> Value { fn convert_xml(node: roxmltree::Node) -> Value {

116
crates/typst-library/src/compute/foundations.rs
View File

@ -1,29 +1,32 @@
use typst::eval::EvalMode; use typst::eval::{
Datetime, Duration, EvalMode, Module, Never, NoneValue, Plugin, Regex,
};
use crate::prelude::*; use crate::prelude::*;
/// Determines the type of a value. /// Hook up all foundational definitions.
/// pub(super) fn define(global: &mut Scope) {
/// Returns the name of the value's type. global.category("foundations");
/// global.define_type::<bool>();
/// ## Example { #example } global.define_type::<i64>();
/// ```example global.define_type::<f64>();
/// #type(12) \ global.define_type::<Str>();
/// #type(14.7) \ global.define_type::<Bytes>();
/// #type("hello") \ global.define_type::<Content>();
/// #type(none) \ global.define_type::<Array>();
/// #type([Hi]) \ global.define_type::<Dict>();
/// #type(x => x + 1) global.define_type::<Func>();
/// ``` global.define_type::<Args>();
/// global.define_type::<Type>();
/// Display: Type global.define_type::<Module>();
/// Category: foundations global.define_type::<Regex>();
#[func] global.define_type::<Datetime>();
pub fn type_( global.define_type::<Duration>();
/// The value whose type's to determine. global.define_type::<Plugin>();
value: Value, global.define_func::<repr>();
) -> Str { global.define_func::<panic>();
value.type_name().into() global.define_func::<assert>();
global.define_func::<eval>();
} }
/// Returns the string representation of a value. /// Returns the string representation of a value.
@ -35,17 +38,14 @@ pub fn type_(
/// **Note:** This function is for debugging purposes. Its output should not be /// **Note:** This function is for debugging purposes. Its output should not be
/// considered stable and may change at any time! /// considered stable and may change at any time!
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #none vs #repr(none) \ /// #none vs #repr(none) \
/// #"hello" vs #repr("hello") \ /// #"hello" vs #repr("hello") \
/// #(1, 2) vs #repr((1, 2)) \ /// #(1, 2) vs #repr((1, 2)) \
/// #[*Hi*] vs #repr([*Hi*]) /// #[*Hi*] vs #repr([*Hi*])
/// ``` /// ```
/// #[func(title = "Representation")]
/// Display: Representation
/// Category: foundations
#[func]
pub fn repr( pub fn repr(
/// The value whose string representation to produce. /// The value whose string representation to produce.
value: Value, value: Value,
@ -55,16 +55,12 @@ pub fn repr(
/// Fails with an error. /// Fails with an error.
/// ///
/// ## Example { #example } /// # Example
/// The code below produces the error `panicked with: "this is wrong"`. /// The code below produces the error `panicked with: "this is wrong"`.
/// ```typ /// ```typ
/// #panic("this is wrong") /// #panic("this is wrong")
/// ``` /// ```
/// #[func(keywords = ["error"])]
/// Display: Panic
/// Category: foundations
/// Keywords: error
#[func]
pub fn panic( pub fn panic(
/// The values to panic with. /// The values to panic with.
#[variadic] #[variadic]
@ -89,21 +85,13 @@ pub fn panic(
/// produce any output in the document. /// produce any output in the document.
/// ///
/// If you wish to test equality between two values, see /// If you wish to test equality between two values, see
/// [`assert.eq`]($func/assert.eq) and [`assert.ne`]($func/assert.ne). /// [`assert.eq`]($assert.eq) and [`assert.ne`]($assert.ne).
/// ///
/// ## Example { #example } /// # Example
/// ```typ /// ```typ
/// #assert(1 < 2, message: "math broke") /// #assert(1 < 2, message: "math broke")
/// ``` /// ```
/// #[func(scope)]
/// Display: Assert
/// Category: foundations
#[func]
#[scope(
scope.define("eq", assert_eq_func());
scope.define("ne", assert_ne_func());
scope
)]
pub fn assert( pub fn assert(
/// The condition that must be true for the assertion to pass. /// The condition that must be true for the assertion to pass.
condition: bool, condition: bool,
@ -121,26 +109,22 @@ pub fn assert(
Ok(NoneValue) Ok(NoneValue)
} }
#[scope]
impl assert {
/// Ensures that two values are equal. /// Ensures that two values are equal.
/// ///
/// Fails with an error if the first value is not equal to the second. Does not /// Fails with an error if the first value is not equal to the second. Does not
/// produce any output in the document. /// produce any output in the document.
/// ///
/// ## Example { #example }
/// ```typ /// ```typ
/// #assert.eq(10, 10) /// #assert.eq(10, 10)
/// ``` /// ```
/// #[func(title = "Assert Equal")]
/// Display: Assert Equals pub fn eq(
/// Category: foundations
#[func]
pub fn assert_eq(
/// The first value to compare. /// The first value to compare.
left: Value, left: Value,
/// The second value to compare. /// The second value to compare.
right: Value, right: Value,
/// An optional message to display on error instead of the representations /// An optional message to display on error instead of the representations
/// of the compared values. /// of the compared values.
#[named] #[named]
@ -161,21 +145,15 @@ pub fn assert_eq(
/// Fails with an error if the first value is equal to the second. Does not /// Fails with an error if the first value is equal to the second. Does not
/// produce any output in the document. /// produce any output in the document.
/// ///
/// ## Example { #example }
/// ```typ /// ```typ
/// #assert.ne(3, 4) /// #assert.ne(3, 4)
/// ``` /// ```
/// #[func(title = "Assert Not Equal")]
/// Display: Assert Not Equals pub fn ne(
/// Category: foundations
#[func]
pub fn assert_ne(
/// The first value to compare. /// The first value to compare.
left: Value, left: Value,
/// The second value to compare. /// The second value to compare.
right: Value, right: Value,
/// An optional message to display on error instead of the representations /// An optional message to display on error instead of the representations
/// of the compared values. /// of the compared values.
#[named] #[named]
@ -185,27 +163,29 @@ pub fn assert_ne(
if let Some(message) = message { if let Some(message) = message {
bail!("inequality assertion failed: {message}"); bail!("inequality assertion failed: {message}");
} else { } else {
bail!("inequality assertion failed: value {left:?} was equal to {right:?}"); bail!(
"inequality assertion failed: value {left:?} was equal to {right:?}"
);
} }
} }
Ok(NoneValue) Ok(NoneValue)
} }
}
/// Evaluates a string as Typst code. /// Evaluates a string as Typst code.
/// ///
/// This function should only be used as a last resort. /// This function should only be used as a last resort.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #eval("1 + 1") \ /// #eval("1 + 1") \
/// #eval("(1, 2, 3, 4)").len() \ /// #eval("(1, 2, 3, 4)").len() \
/// #eval("*Markup!*", mode: "markup") \ /// #eval("*Markup!*", mode: "markup") \
/// ``` /// ```
/// #[func(title = "Evaluate")]
/// Display: Evaluate
/// Category: foundations
#[func]
pub fn eval( pub fn eval(
/// The virtual machine.
vm: &mut Vm,
/// A string of Typst code to evaluate. /// A string of Typst code to evaluate.
/// ///
/// The code in the string cannot interact with the file system. /// The code in the string cannot interact with the file system.
@ -235,8 +215,6 @@ pub fn eval(
#[named] #[named]
#[default] #[default]
scope: Dict, scope: Dict,
/// The virtual machine.
vm: &mut Vm,
) -> SourceResult<Value> { ) -> SourceResult<Value> {
let Spanned { v: text, span } = source; let Spanned { v: text, span } = source;
let dict = scope; let dict = scope;

35
crates/typst-library/src/compute/mod.rs
View File

@ -1,11 +1,10 @@
//! Computational functions. //! Computational functions.
pub mod calc; pub mod calc;
mod construct;
mod data; mod data;
mod foundations; mod foundations;
pub use self::construct::*;
pub use self::data::*; pub use self::data::*;
pub use self::foundations::*; pub use self::foundations::*;
@ -13,33 +12,7 @@ use crate::prelude::*;
/// Hook up all compute definitions. /// Hook up all compute definitions.
pub(super) fn define(global: &mut Scope) { pub(super) fn define(global: &mut Scope) {
global.define("type", type_func()); self::foundations::define(global);
global.define("repr", repr_func()); self::data::define(global);
global.define("panic", panic_func()); self::calc::define(global);
global.define("assert", assert_func());
global.define("eval", eval_func());
global.define("int", int_func());
global.define("float", float_func());
global.define("luma", luma_func());
global.define("rgb", rgb_func());
global.define("cmyk", cmyk_func());
global.define("color", color_module());
global.define("datetime", datetime_func());
global.define("duration", duration_func());
global.define("symbol", symbol_func());
global.define("str", str_func());
global.define("bytes", bytes_func());
global.define("label", label_func());
global.define("regex", regex_func());
global.define("array", array_func());
global.define("range", range_func());
global.define("read", read_func());
global.define("csv", csv_func());
global.define("json", json_func());
global.define("toml", toml_func());
global.define("yaml", yaml_func());
global.define("cbor", cbor_func());
global.define("xml", xml_func());
global.define("calc", calc::module());
global.define("plugin", plugin_func());
} }

48
crates/typst-library/src/layout/align.rs
View File

@ -2,7 +2,7 @@ use crate::prelude::*;
/// Aligns content horizontally and vertically. /// Aligns content horizontally and vertically.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #set align(center) /// #set align(center)
/// ///
@ -11,43 +11,9 @@ use crate::prelude::*;
/// Not left nor right, it stands alone \ /// Not left nor right, it stands alone \
/// A work of art, a visual throne /// A work of art, a visual throne
/// ``` /// ```
/// #[elem(Show)]
/// Display: Align
/// Category: layout
#[element(Show)]
pub struct AlignElem { pub struct AlignElem {
/// The alignment along both axes. /// The [alignment]($alignment) along both axes.
///
/// Possible values for horizontal alignments are:
/// - `start`
/// - `end`
/// - `left`
/// - `center`
/// - `right`
///
/// The `start` and `end` alignments are relative to the current [text
/// direction]($func/text.dir).
///
/// Possible values for vertical alignments are:
/// - `top`
/// - `horizon`
/// - `bottom`
///
/// You can use the `axis` method on a single-axis alignment to obtain
/// whether it is `{"horizontal"}` or `{"vertical"}`. You can also use the
/// `inv` method to obtain its inverse alignment. For example,
/// `{top.axis()}` is `{"vertical"}`, while `{top.inv()}` is equal to
/// `{bottom}`.
///
/// To align along both axes at the same time, add the two alignments using
/// the `+` operator to get a `2d alignment`. For example, `top + right`
/// aligns the content to the top right corner.
///
/// For 2d alignments, the `x` and `y` fields hold their horizontal and
/// vertical components, respectively. Additionally, you can use the `inv`
/// method to obtain a 2d alignment with both components inverted. For
/// instance, `{(top + right).x}` is `right`, `{(top + right).y}` is `top`,
/// and `{(top + right).inv()}` is equal to `bottom + left`.
/// ///
/// ```example /// ```example
/// #set page(height: 6cm) /// #set page(height: 6cm)
@ -61,8 +27,8 @@ pub struct AlignElem {
/// ``` /// ```
#[positional] #[positional]
#[fold] #[fold]
#[default(Axes::new(GenAlign::Start, GenAlign::Specific(Align::Top)))] #[default]
pub alignment: Axes<Option<GenAlign>>, pub alignment: Align,
/// The content to align. /// The content to align.
#[required] #[required]
@ -72,8 +38,6 @@ pub struct AlignElem {
impl Show for AlignElem { impl Show for AlignElem {
#[tracing::instrument(name = "AlignElem::show", skip_all)] #[tracing::instrument(name = "AlignElem::show", skip_all)]
fn show(&self, _: &mut Vt, styles: StyleChain) -> SourceResult<Content> { fn show(&self, _: &mut Vt, styles: StyleChain) -> SourceResult<Content> {
Ok(self Ok(self.body().styled(Self::set_alignment(self.alignment(styles))))
.body()
.styled(Self::set_alignment(self.alignment(styles).map(Some))))
} }
} }

18
crates/typst-library/src/layout/columns.rs
View File

@ -10,9 +10,9 @@ use crate::text::TextElem;
/// necessary. /// necessary.
/// ///
/// If you need to insert columns across your whole document, you can use the /// If you need to insert columns across your whole document, you can use the
/// [`{page}` function's `columns` parameter]($func/page.columns) instead. /// [`{page}` function's `columns` parameter]($page.columns) instead.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// = Towards Advanced Deep Learning /// = Towards Advanced Deep Learning
/// ///
@ -32,10 +32,7 @@ use crate::text::TextElem;
/// increasingly been used to solve a /// increasingly been used to solve a
/// variety of problems. /// variety of problems.
/// ``` /// ```
/// #[elem(Layout)]
/// Display: Columns
/// Category: layout
#[element(Layout)]
pub struct ColumnsElem { pub struct ColumnsElem {
/// The number of columns. /// The number of columns.
#[positional] #[positional]
@ -132,11 +129,11 @@ impl Layout for ColumnsElem {
/// Forces a column break. /// Forces a column break.
/// ///
/// The function will behave like a [page break]($func/pagebreak) when used in a /// The function will behave like a [page break]($pagebreak) when used in a
/// single column layout or the last column on a page. Otherwise, content after /// single column layout or the last column on a page. Otherwise, content after
/// the column break will be placed in the next column. /// the column break will be placed in the next column.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #set page(columns: 2) /// #set page(columns: 2)
/// Preliminary findings from our /// Preliminary findings from our
@ -153,10 +150,7 @@ impl Layout for ColumnsElem {
/// understanding of the fundamental /// understanding of the fundamental
/// laws of nature. /// laws of nature.
/// ``` /// ```
/// #[elem(title = "Column Break", Behave)]
/// Display: Column Break
/// Category: layout
#[element(Behave)]
pub struct ColbreakElem { pub struct ColbreakElem {
/// If `{true}`, the column break is skipped if the current column is /// If `{true}`, the column break is skipped if the current column is
/// already empty. /// already empty.

68
crates/typst-library/src/layout/container.rs
View File

@ -11,7 +11,7 @@ use crate::prelude::*;
/// elements into a paragraph. Boxes take the size of their contents by default /// elements into a paragraph. Boxes take the size of their contents by default
/// but can also be sized explicitly. /// but can also be sized explicitly.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// Refer to the docs /// Refer to the docs
/// #box( /// #box(
@ -20,15 +20,12 @@ use crate::prelude::*;
/// ) /// )
/// for more information. /// for more information.
/// ``` /// ```
/// #[elem(Layout)]
/// Display: Box
/// Category: layout
#[element(Layout)]
pub struct BoxElem { pub struct BoxElem {
/// The width of the box. /// The width of the box.
/// ///
/// Boxes can have [fractional]($type/fraction) widths, as the example /// Boxes can have [fractional]($fraction) widths, as the example below
/// below demonstrates. /// demonstrates.
/// ///
/// _Note:_ Currently, only boxes and only their widths might be fractionally /// _Note:_ Currently, only boxes and only their widths might be fractionally
/// sized within paragraphs. Support for fractionally sized images, shapes, /// sized within paragraphs. Support for fractionally sized images, shapes,
@ -51,23 +48,29 @@ pub struct BoxElem {
pub baseline: Rel<Length>, pub baseline: Rel<Length>,
/// The box's background color. See the /// The box's background color. See the
/// [rectangle's documentation]($func/rect.fill) for more details. /// [rectangle's documentation]($rect.fill) for more details.
pub fill: Option<Paint>, pub fill: Option<Paint>,
/// The box's border color. See the /// The box's border color. See the
/// [rectangle's documentation]($func/rect.stroke) for more details. /// [rectangle's documentation]($rect.stroke) for more details.
#[resolve] #[resolve]
#[fold] #[fold]
pub stroke: Sides<Option<Option<PartialStroke>>>, pub stroke: Sides<Option<Option<Stroke>>>,
/// How much to round the box's corners. See the [rectangle's /// How much to round the box's corners. See the
/// documentation]($func/rect.radius) for more details. /// [rectangle's documentation]($rect.radius) for more details.
#[resolve] #[resolve]
#[fold] #[fold]
pub radius: Corners<Option<Rel<Length>>>, pub radius: Corners<Option<Rel<Length>>>,
/// How much to pad the box's content. See the [rectangle's /// How much to pad the box's content.
/// documentation]($func/rect.inset) for more details. ///
/// _Note:_ When the box contains text, its exact size depends on the
/// current [text edges]($text.top-edge).
///
/// ```example
/// #rect(inset: 0pt)[Tight]
/// ```
#[resolve] #[resolve]
#[fold] #[fold]
pub inset: Sides<Option<Rel<Length>>>, pub inset: Sides<Option<Rel<Length>>>,
@ -76,7 +79,7 @@ pub struct BoxElem {
/// ///
/// This is useful to prevent padding from affecting line layout. For a /// This is useful to prevent padding from affecting line layout. For a
/// generalized version of the example below, see the documentation for the /// generalized version of the example below, see the documentation for the
/// [raw text's block parameter]($func/raw.block). /// [raw text's block parameter]($raw.block).
/// ///
/// ```example /// ```example
/// An inline /// An inline
@ -119,8 +122,7 @@ impl Layout for BoxElem {
let expand = sizing.as_ref().map(Smart::is_custom); let expand = sizing.as_ref().map(Smart::is_custom);
let size = sizing let size = sizing
.resolve(styles) .resolve(styles)
.zip(regions.base()) .zip_map(regions.base(), |s, b| s.map(|v| v.relative_to(b)))
.map(|(s, b)| s.map(|v| v.relative_to(b)))
.unwrap_or(regions.base()); .unwrap_or(regions.base());
// Apply inset. // Apply inset.
@ -151,7 +153,7 @@ impl Layout for BoxElem {
// Prepare fill and stroke. // Prepare fill and stroke.
let fill = self.fill(styles); let fill = self.fill(styles);
let stroke = self.stroke(styles).map(|s| s.map(PartialStroke::unwrap_or_default)); let stroke = self.stroke(styles).map(|s| s.map(Stroke::unwrap_or_default));
// Add fill and/or stroke. // Add fill and/or stroke.
if fill.is_some() || stroke.iter().any(Option::is_some) { if fill.is_some() || stroke.iter().any(Option::is_some) {
@ -172,7 +174,7 @@ impl Layout for BoxElem {
/// Such a container can be used to separate content, size it, and give it a /// Such a container can be used to separate content, size it, and give it a
/// background or border. /// background or border.
/// ///
/// ## Examples { #examples } /// # Examples
/// With a block, you can give a background to content while still allowing it /// With a block, you can give a background to content while still allowing it
/// to break across multiple pages. /// to break across multiple pages.
/// ```example /// ```example
@ -196,10 +198,7 @@ impl Layout for BoxElem {
/// = Blocky /// = Blocky
/// More text. /// More text.
/// ``` /// ```
/// #[elem(Layout)]
/// Display: Block
/// Category: layout
#[element(Layout)]
pub struct BlockElem { pub struct BlockElem {
/// The block's width. /// The block's width.
/// ///
@ -215,7 +214,7 @@ pub struct BlockElem {
pub width: Smart<Rel<Length>>, pub width: Smart<Rel<Length>>,
/// The block's height. When the height is larger than the remaining space /// The block's height. When the height is larger than the remaining space
/// on a page and [`breakable`]($func/block.breakable) is `{true}`, the /// on a page and [`breakable`]($block.breakable) is `{true}`, the
/// block will continue on the next page with the remaining height. /// block will continue on the next page with the remaining height.
/// ///
/// ```example /// ```example
@ -244,29 +243,29 @@ pub struct BlockElem {
pub breakable: bool, pub breakable: bool,
/// The block's background color. See the /// The block's background color. See the
/// [rectangle's documentation]($func/rect.fill) for more details. /// [rectangle's documentation]($rect.fill) for more details.
pub fill: Option<Paint>, pub fill: Option<Paint>,
/// The block's border color. See the /// The block's border color. See the
/// [rectangle's documentation]($func/rect.stroke) for more details. /// [rectangle's documentation]($rect.stroke) for more details.
#[resolve] #[resolve]
#[fold] #[fold]
pub stroke: Sides<Option<Option<PartialStroke>>>, pub stroke: Sides<Option<Option<Stroke>>>,
/// How much to round the block's corners. See the [rectangle's /// How much to round the block's corners. See the
/// documentation]($func/rect.radius) for more details. /// [rectangle's documentation]($rect.radius) for more details.
#[resolve] #[resolve]
#[fold] #[fold]
pub radius: Corners<Option<Rel<Length>>>, pub radius: Corners<Option<Rel<Length>>>,
/// How much to pad the block's content. See the [rectangle's /// How much to pad the block's content. See the
/// documentation]($func/rect.inset) for more details. /// [box's documentation]($box.inset) for more details.
#[resolve] #[resolve]
#[fold] #[fold]
pub inset: Sides<Option<Rel<Length>>>, pub inset: Sides<Option<Rel<Length>>>,
/// How much to expand the block's size without affecting the layout. See /// How much to expand the block's size without affecting the layout. See
/// the [rectangle's documentation]($func/rect.outset) for more details. /// the [box's documentation]($box.outset) for more details.
#[resolve] #[resolve]
#[fold] #[fold]
pub outset: Sides<Option<Rel<Length>>>, pub outset: Sides<Option<Rel<Length>>>,
@ -352,8 +351,7 @@ impl Layout for BlockElem {
let mut expand = sizing.as_ref().map(Smart::is_custom); let mut expand = sizing.as_ref().map(Smart::is_custom);
let mut size = sizing let mut size = sizing
.resolve(styles) .resolve(styles)
.zip(regions.base()) .zip_map(regions.base(), |s, b| s.map(|v| v.relative_to(b)))
.map(|(s, b)| s.map(|v| v.relative_to(b)))
.unwrap_or(regions.base()); .unwrap_or(regions.base());
// Layout the child. // Layout the child.
@ -418,7 +416,7 @@ impl Layout for BlockElem {
// Prepare fill and stroke. // Prepare fill and stroke.
let fill = self.fill(styles); let fill = self.fill(styles);
let stroke = self.stroke(styles).map(|s| s.map(PartialStroke::unwrap_or_default)); let stroke = self.stroke(styles).map(|s| s.map(Stroke::unwrap_or_default));
// Add fill and/or stroke. // Add fill and/or stroke.
if fill.is_some() || stroke.iter().any(Option::is_some) { if fill.is_some() || stroke.iter().any(Option::is_some) {

49
crates/typst-library/src/layout/enum.rs
View File

@ -11,7 +11,7 @@ use super::GridLayouter;
/// ///
/// Displays a sequence of items vertically and numbers them consecutively. /// Displays a sequence of items vertically and numbers them consecutively.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// Automatically numbered: /// Automatically numbered:
/// + Preparations /// + Preparations
@ -41,8 +41,8 @@ use super::GridLayouter;
/// + Don't forget step two /// + Don't forget step two
/// ``` /// ```
/// ///
/// You can also use [`enum.item`]($func/enum.item) to programmatically /// You can also use [`enum.item`]($enum.item) to programmatically customize the
/// customize the number of each item in the enumeration: /// number of each item in the enumeration:
/// ///
/// ```example /// ```example
/// #enum( /// #enum(
@ -52,7 +52,7 @@ use super::GridLayouter;
/// ) /// )
/// ``` /// ```
/// ///
/// ## Syntax { #syntax } /// # Syntax
/// This functions also has dedicated syntax: /// This functions also has dedicated syntax:
/// ///
/// - Starting a line with a plus sign creates an automatically numbered /// - Starting a line with a plus sign creates an automatically numbered
@ -63,18 +63,11 @@ use super::GridLayouter;
/// Enumeration items can contain multiple paragraphs and other block-level /// Enumeration items can contain multiple paragraphs and other block-level
/// content. All content that is indented more than an item's marker becomes /// content. All content that is indented more than an item's marker becomes
/// part of that item. /// part of that item.
/// #[elem(scope, title = "Numbered List", Layout)]
/// Display: Numbered List
/// Category: layout
#[element(Layout)]
#[scope(
scope.define("item", EnumItem::func());
scope
)]
pub struct EnumElem { pub struct EnumElem {
/// If this is `{false}`, the items are spaced apart with /// If this is `{false}`, the items are spaced apart with
/// [enum spacing]($func/enum.spacing). If it is `{true}`, they use normal /// [enum spacing]($enum.spacing). If it is `{true}`, they use normal
/// [leading]($func/par.leading) instead. This makes the enumeration more /// [leading]($par.leading) instead. This makes the enumeration more
/// compact, which can look better if the items are short. /// compact, which can look better if the items are short.
/// ///
/// In markup mode, the value of this parameter is determined based on /// In markup mode, the value of this parameter is determined based on
@ -95,7 +88,7 @@ pub struct EnumElem {
pub tight: bool, pub tight: bool,
/// How to number the enumeration. Accepts a /// How to number the enumeration. Accepts a
/// [numbering pattern or function]($func/numbering). /// [numbering pattern or function]($numbering).
/// ///
/// If the numbering pattern contains multiple counting symbols, they apply /// If the numbering pattern contains multiple counting symbols, they apply
/// to nested enums. If given a function, the function receives one argument /// to nested enums. If given a function, the function receives one argument
@ -153,7 +146,7 @@ pub struct EnumElem {
/// The spacing between the items of a wide (non-tight) enumeration. /// The spacing between the items of a wide (non-tight) enumeration.
/// ///
/// If set to `{auto}`, uses the spacing [below blocks]($func/block.below). /// If set to `{auto}`, uses the spacing [below blocks]($block.below).
pub spacing: Smart<Spacing>, pub spacing: Smart<Spacing>,
/// The horizontal alignment that enum numbers should have. /// The horizontal alignment that enum numbers should have.
@ -177,8 +170,8 @@ pub struct EnumElem {
/// 16. Sixteen /// 16. Sixteen
/// 32. Thirty two /// 32. Thirty two
/// ```` /// ````
#[default(HorizontalAlign(GenAlign::End))] #[default(HAlign::End)]
pub number_align: HorizontalAlign, pub number_align: HAlign,
/// The numbered list's items. /// The numbered list's items.
/// ///
@ -201,6 +194,12 @@ pub struct EnumElem {
parents: Parent, parents: Parent,
} }
#[scope]
impl EnumElem {
#[elem]
type EnumItem;
}
impl Layout for EnumElem { impl Layout for EnumElem {
#[tracing::instrument(name = "EnumElem::layout", skip_all)] #[tracing::instrument(name = "EnumElem::layout", skip_all)]
fn layout( fn layout(
@ -225,11 +224,10 @@ impl Layout for EnumElem {
let full = self.full(styles); let full = self.full(styles);
// Horizontally align based on the given respective parameter. // Horizontally align based on the given respective parameter.
// Vertically align to the top to avoid inheriting 'horizon' or // Vertically align to the top to avoid inheriting `horizon` or `bottom`
// 'bottom' alignment from the context and having the number be // alignment from the context and having the number be displaced in
// displaced in relation to the item it refers to. // relation to the item it refers to.
let number_align: Axes<Option<GenAlign>> = let number_align = self.number_align(styles) + VAlign::Top;
Axes::new(self.number_align(styles).into(), Align::Top.into()).map(Some);
for item in self.children() { for item in self.children() {
number = item.number(styles).unwrap_or(number); number = item.number(styles).unwrap_or(number);
@ -278,10 +276,7 @@ impl Layout for EnumElem {
} }
/// An enumeration item. /// An enumeration item.
/// #[elem(name = "item", title = "Numbered List Item")]
/// Display: Numbered List Item
/// Category: layout
#[element]
pub struct EnumItem { pub struct EnumItem {
/// The item's number. /// The item's number.
#[positional] #[positional]

55
crates/typst-library/src/layout/flow.rs
View File

@ -14,10 +14,7 @@ use crate::visualize::{
/// ///
/// This element is responsible for layouting both the top-level content flow /// This element is responsible for layouting both the top-level content flow
/// and the contents of boxes. /// and the contents of boxes.
/// #[elem(Layout)]
/// Display: Flow
/// Category: layout
#[element(Layout)]
pub struct FlowElem { pub struct FlowElem {
/// The children that will be arranges into a flow. /// The children that will be arranges into a flow.
#[variadic] #[variadic]
@ -62,7 +59,7 @@ impl Layout for FlowElem {
frame.meta(styles, true); frame.meta(styles, true);
layouter.items.push(FlowItem::Frame { layouter.items.push(FlowItem::Frame {
frame, frame,
aligns: Axes::new(Align::Top, Align::Left), align: Axes::splat(FixedAlign::Start),
sticky: true, sticky: true,
movable: false, movable: false,
}); });
@ -128,12 +125,12 @@ enum FlowItem {
/// A frame for a layouted block, how to align it, whether it sticks to the /// A frame for a layouted block, how to align it, whether it sticks to the
/// item after it (for orphan prevention), and whether it is movable /// item after it (for orphan prevention), and whether it is movable
/// (to keep it together with its footnotes). /// (to keep it together with its footnotes).
Frame { frame: Frame, aligns: Axes<Align>, sticky: bool, movable: bool }, Frame { frame: Frame, align: Axes<FixedAlign>, sticky: bool, movable: bool },
/// An absolutely placed frame. /// An absolutely placed frame.
Placed { Placed {
frame: Frame, frame: Frame,
x_align: Align, x_align: FixedAlign,
y_align: Smart<Option<Align>>, y_align: Smart<Option<FixedAlign>>,
delta: Axes<Rel<Abs>>, delta: Axes<Rel<Abs>>,
float: bool, float: bool,
clearance: Abs, clearance: Abs,
@ -209,7 +206,7 @@ impl<'a> FlowLayouter<'a> {
par: &ParElem, par: &ParElem,
styles: StyleChain, styles: StyleChain,
) -> SourceResult<()> { ) -> SourceResult<()> {
let aligns = AlignElem::alignment_in(styles).resolve(styles); let align = AlignElem::alignment_in(styles).resolve(styles);
let leading = ParElem::leading_in(styles); let leading = ParElem::leading_in(styles);
let consecutive = self.last_was_par; let consecutive = self.last_was_par;
let lines = par let lines = par
@ -242,7 +239,7 @@ impl<'a> FlowLayouter<'a> {
self.layout_item( self.layout_item(
vt, vt,
FlowItem::Frame { frame, aligns, sticky: false, movable: true }, FlowItem::Frame { frame, align, sticky: false, movable: true },
)?; )?;
} }
@ -258,11 +255,11 @@ impl<'a> FlowLayouter<'a> {
content: &dyn Layout, content: &dyn Layout,
styles: StyleChain, styles: StyleChain,
) -> SourceResult<()> { ) -> SourceResult<()> {
let aligns = AlignElem::alignment_in(styles).resolve(styles); let align = AlignElem::alignment_in(styles).resolve(styles);
let sticky = BlockElem::sticky_in(styles); let sticky = BlockElem::sticky_in(styles);
let pod = Regions::one(self.regions.base(), Axes::splat(false)); let pod = Regions::one(self.regions.base(), Axes::splat(false));
let frame = content.layout(vt, styles, pod)?.into_frame(); let frame = content.layout(vt, styles, pod)?.into_frame();
self.layout_item(vt, FlowItem::Frame { frame, aligns, sticky, movable: true })?; self.layout_item(vt, FlowItem::Frame { frame, align, sticky, movable: true })?;
self.last_was_par = false; self.last_was_par = false;
Ok(()) Ok(())
} }
@ -278,10 +275,10 @@ impl<'a> FlowLayouter<'a> {
let clearance = placed.clearance(styles); let clearance = placed.clearance(styles);
let alignment = placed.alignment(styles); let alignment = placed.alignment(styles);
let delta = Axes::new(placed.dx(styles), placed.dy(styles)).resolve(styles); let delta = Axes::new(placed.dx(styles), placed.dy(styles)).resolve(styles);
let x_align = alignment.map_or(Align::Center, |aligns| { let x_align = alignment.map_or(FixedAlign::Center, |align| {
aligns.x.unwrap_or(GenAlign::Start).resolve(styles) align.x().unwrap_or_default().resolve(styles)
}); });
let y_align = alignment.map(|align| align.y.resolve(styles)); let y_align = alignment.map(|align| align.y().map(VAlign::fix));
let frame = placed.layout(vt, styles, self.regions)?.into_frame(); let frame = placed.layout(vt, styles, self.regions)?.into_frame();
let item = FlowItem::Placed { frame, x_align, y_align, delta, float, clearance }; let item = FlowItem::Placed { frame, x_align, y_align, delta, float, clearance };
self.layout_item(vt, item) self.layout_item(vt, item)
@ -309,7 +306,7 @@ impl<'a> FlowLayouter<'a> {
} }
// How to align the block. // How to align the block.
let aligns = if let Some(align) = block.to::<AlignElem>() { let align = if let Some(align) = block.to::<AlignElem>() {
align.alignment(styles) align.alignment(styles)
} else if let Some((_, local)) = block.to_styled() { } else if let Some((_, local)) = block.to_styled() {
AlignElem::alignment_in(styles.chain(local)) AlignElem::alignment_in(styles.chain(local))
@ -332,7 +329,7 @@ impl<'a> FlowLayouter<'a> {
self.finish_region(vt)?; self.finish_region(vt)?;
} }
let item = FlowItem::Frame { frame, aligns, sticky, movable: false }; let item = FlowItem::Frame { frame, align, sticky, movable: false };
self.layout_item(vt, item)?; self.layout_item(vt, item)?;
} }
@ -404,14 +401,14 @@ impl<'a> FlowLayouter<'a> {
- (frame.height() + clearance) / 2.0) - (frame.height() + clearance) / 2.0)
/ self.regions.full; / self.regions.full;
let better_align = let better_align =
if ratio <= 0.5 { Align::Bottom } else { Align::Top }; if ratio <= 0.5 { FixedAlign::End } else { FixedAlign::Start };
*y_align = Smart::Custom(Some(better_align)); *y_align = Smart::Custom(Some(better_align));
} }
// Add some clearance so that the float doesn't touch the main // Add some clearance so that the float doesn't touch the main
// content. // content.
frame.size_mut().y += clearance; frame.size_mut().y += clearance;
if *y_align == Smart::Custom(Some(Align::Bottom)) { if *y_align == Smart::Custom(Some(FixedAlign::End)) {
frame.translate(Point::with_y(clearance)); frame.translate(Point::with_y(clearance));
} }
@ -459,8 +456,10 @@ impl<'a> FlowLayouter<'a> {
} }
FlowItem::Placed { float: false, .. } => {} FlowItem::Placed { float: false, .. } => {}
FlowItem::Placed { frame, float: true, y_align, .. } => match y_align { FlowItem::Placed { frame, float: true, y_align, .. } => match y_align {
Smart::Custom(Some(Align::Top)) => float_top_height += frame.height(), Smart::Custom(Some(FixedAlign::Start)) => {
Smart::Custom(Some(Align::Bottom)) => { float_top_height += frame.height()
}
Smart::Custom(Some(FixedAlign::End)) => {
float_bottom_height += frame.height() float_bottom_height += frame.height()
} }
_ => {} _ => {}
@ -486,7 +485,7 @@ impl<'a> FlowLayouter<'a> {
} }
let mut output = Frame::new(size); let mut output = Frame::new(size);
let mut ruler = Align::Top; let mut ruler = FixedAlign::Start;
let mut float_top_offset = Abs::zero(); let mut float_top_offset = Abs::zero();
let mut offset = float_top_height; let mut offset = float_top_height;
let mut float_bottom_offset = Abs::zero(); let mut float_bottom_offset = Abs::zero();
@ -502,9 +501,9 @@ impl<'a> FlowLayouter<'a> {
let remaining = self.initial.y - used.y; let remaining = self.initial.y - used.y;
offset += v.share(fr, remaining); offset += v.share(fr, remaining);
} }
FlowItem::Frame { frame, aligns, .. } => { FlowItem::Frame { frame, align, .. } => {
ruler = ruler.max(aligns.y); ruler = ruler.max(align.y);
let x = aligns.x.position(size.x - frame.width()); let x = align.x.position(size.x - frame.width());
let y = offset + ruler.position(size.y - used.y); let y = offset + ruler.position(size.y - used.y);
let pos = Point::new(x, y); let pos = Point::new(x, y);
offset += frame.height(); offset += frame.height();
@ -514,12 +513,12 @@ impl<'a> FlowLayouter<'a> {
let x = x_align.position(size.x - frame.width()); let x = x_align.position(size.x - frame.width());
let y = if float { let y = if float {
match y_align { match y_align {
Smart::Custom(Some(Align::Top)) => { Smart::Custom(Some(FixedAlign::Start)) => {
let y = float_top_offset; let y = float_top_offset;
float_top_offset += frame.height(); float_top_offset += frame.height();
y y
} }
Smart::Custom(Some(Align::Bottom)) => { Smart::Custom(Some(FixedAlign::End)) => {
let y = size.y - footnote_height - float_bottom_height let y = size.y - footnote_height - float_bottom_height
+ float_bottom_offset; + float_bottom_offset;
float_bottom_offset += frame.height(); float_bottom_offset += frame.height();
@ -537,7 +536,7 @@ impl<'a> FlowLayouter<'a> {
}; };
let pos = Point::new(x, y) let pos = Point::new(x, y)
+ delta.zip(size).map(|(d, s)| d.relative_to(s)).to_point(); + delta.zip_map(size, Rel::relative_to).to_point();
output.push_frame(pos, frame); output.push_frame(pos, frame);
} }

7
crates/typst-library/src/layout/grid.rs
View File

@ -34,7 +34,7 @@ use super::Sizing;
/// instead of an array. For example, `columns:` `{3}` is equivalent to /// instead of an array. For example, `columns:` `{3}` is equivalent to
/// `columns:` `{(auto, auto, auto)}`. /// `columns:` `{(auto, auto, auto)}`.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #set text(10pt, style: "italic") /// #set text(10pt, style: "italic")
/// #let cell = rect.with( /// #let cell = rect.with(
@ -58,10 +58,7 @@ use super::Sizing;
/// cell[One more thing...], /// cell[One more thing...],
/// ) /// )
/// ``` /// ```
/// #[elem(Layout)]
/// Display: Grid
/// Category: layout
#[element(Layout)]
pub struct GridElem { pub struct GridElem {
/// The column sizes. /// The column sizes.
/// ///

7
crates/typst-library/src/layout/hide.rs
View File

@ -7,15 +7,12 @@ use crate::prelude::*;
/// content. It may also be useful to redact content because its arguments are /// content. It may also be useful to redact content because its arguments are
/// not included in the output. /// not included in the output.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// Hello Jane \ /// Hello Jane \
/// #hide[Hello] Joe /// #hide[Hello] Joe
/// ``` /// ```
/// #[elem(Show)]
/// Display: Hide
/// Category: layout
#[element(Show)]
pub struct HideElem { pub struct HideElem {
/// The content to hide. /// The content to hide.
#[required] #[required]

36
crates/typst-library/src/layout/list.rs
View File

@ -9,7 +9,7 @@ use super::GridLayouter;
/// Displays a sequence of items vertically, with each item introduced by a /// Displays a sequence of items vertically, with each item introduced by a
/// marker. /// marker.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// Normal list. /// Normal list.
/// - Text /// - Text
@ -30,24 +30,17 @@ use super::GridLayouter;
/// ) /// )
/// ``` /// ```
/// ///
/// ## Syntax { #syntax } /// # Syntax
/// This functions also has dedicated syntax: Start a line with a hyphen, /// This functions also has dedicated syntax: Start a line with a hyphen,
/// followed by a space to create a list item. A list item can contain multiple /// followed by a space to create a list item. A list item can contain multiple
/// paragraphs and other block-level content. All content that is indented /// paragraphs and other block-level content. All content that is indented
/// more than an item's marker becomes part of that item. /// more than an item's marker becomes part of that item.
/// #[elem(scope, title = "Bullet List", Layout)]
/// Display: Bullet List
/// Category: layout
#[element(Layout)]
#[scope(
scope.define("item", ListItem::func());
scope
)]
pub struct ListElem { pub struct ListElem {
/// If this is `{false}`, the items are spaced apart with [list /// If this is `{false}`, the items are spaced apart with
/// spacing]($func/list.spacing). If it is `{true}`, they use normal /// [list spacing]($list.spacing). If it is `{true}`, they use normal
/// [leading]($func/par.leading) instead. This makes the list more compact, /// [leading]($par.leading) instead. This makes the list more compact, which
/// which can look better if the items are short. /// can look better if the items are short.
/// ///
/// In markup mode, the value of this parameter is determined based on /// In markup mode, the value of this parameter is determined based on
/// whether items are separated with a blank line. If items directly follow /// whether items are separated with a blank line. If items directly follow
@ -98,7 +91,7 @@ pub struct ListElem {
/// The spacing between the items of a wide (non-tight) list. /// The spacing between the items of a wide (non-tight) list.
/// ///
/// If set to `{auto}`, uses the spacing [below blocks]($func/block.below). /// If set to `{auto}`, uses the spacing [below blocks]($block.below).
pub spacing: Smart<Spacing>, pub spacing: Smart<Spacing>,
/// The bullet list's children. /// The bullet list's children.
@ -120,6 +113,12 @@ pub struct ListElem {
depth: Depth, depth: Depth,
} }
#[scope]
impl ListElem {
#[elem]
type ListItem;
}
impl Layout for ListElem { impl Layout for ListElem {
#[tracing::instrument(name = "ListElem::layout", skip_all)] #[tracing::instrument(name = "ListElem::layout", skip_all)]
fn layout( fn layout(
@ -142,7 +141,7 @@ impl Layout for ListElem {
.marker(styles) .marker(styles)
.resolve(vt, depth)? .resolve(vt, depth)?
// avoid '#set align' interference with the list // avoid '#set align' interference with the list
.aligned(Align::LEFT_TOP.into()); .aligned(HAlign::Start + VAlign::Top);
let mut cells = vec![]; let mut cells = vec![];
for item in self.children() { for item in self.children() {
@ -170,10 +169,7 @@ impl Layout for ListElem {
} }
/// A bullet list item. /// A bullet list item.
/// #[elem(name = "item", title = "Bullet List Item")]
/// Display: Bullet List Item
/// Category: layout
#[element]
pub struct ListItem { pub struct ListItem {
/// The item's body. /// The item's body.
#[required] #[required]

25
crates/typst-library/src/layout/measure.rs
View File

@ -2,13 +2,13 @@ use crate::prelude::*;
/// Measures the layouted size of content. /// Measures the layouted size of content.
/// ///
/// The `measure` function lets you determine the layouted size of content. /// The `measure` function lets you determine the layouted size of content. Note
/// Note that an infinite space is assumed, therefore the measured height/width /// that an infinite space is assumed, therefore the measured height/width may
/// may not necessarily match the final height/width of the measured content. /// not necessarily match the final height/width of the measured content. If you
/// If you want to measure in the current layout dimensions, you can combined /// want to measure in the current layout dimensions, you can combine `measure`
/// `measure` and [`layout`]($func/layout). /// and [`layout`]($layout).
/// ///
/// # Example { #example } /// # Example
/// The same content can have a different size depending on the styles that /// The same content can have a different size depending on the styles that
/// are active when it is layouted. For example, in the example below /// are active when it is layouted. For example, in the example below
/// `[#content]` is of course bigger when we increase the font size. /// `[#content]` is of course bigger when we increase the font size.
@ -21,8 +21,8 @@ use crate::prelude::*;
/// ``` /// ```
/// ///
/// To do a meaningful measurement, you therefore first need to retrieve the /// To do a meaningful measurement, you therefore first need to retrieve the
/// active styles with the [`style`]($func/style) function. You can then pass /// active styles with the [`style`]($style) function. You can then pass them to
/// them to the `measure` function. /// the `measure` function.
/// ///
/// ```example /// ```example
/// #let thing(body) = style(styles => { /// #let thing(body) = style(styles => {
@ -35,18 +35,15 @@ use crate::prelude::*;
/// ``` /// ```
/// ///
/// The measure function returns a dictionary with the entries `width` and /// The measure function returns a dictionary with the entries `width` and
/// `height`, both of type [`length`]($type/length). /// `height`, both of type [`length`]($length).
///
/// Display: Measure
/// Category: layout
#[func] #[func]
pub fn measure( pub fn measure(
/// The virtual machine.
vm: &mut Vm,
/// The content whose size to measure. /// The content whose size to measure.
content: Content, content: Content,
/// The styles with which to layout the content. /// The styles with which to layout the content.
styles: Styles, styles: Styles,
/// The virtual machine.
vm: &mut Vm,
) -> SourceResult<Dict> { ) -> SourceResult<Dict> {
let pod = Regions::one(Axes::splat(Abs::inf()), Axes::splat(false)); let pod = Regions::one(Axes::splat(Abs::inf()), Axes::splat(false));
let styles = StyleChain::new(&styles); let styles = StyleChain::new(&styles);

79
crates/typst-library/src/layout/mod.rs
View File

@ -10,7 +10,8 @@ mod fragment;
mod grid; mod grid;
mod hide; mod hide;
mod list; mod list;
mod measure; #[path = "measure.rs"]
mod measure_;
mod pad; mod pad;
mod page; mod page;
mod par; mod par;
@ -32,7 +33,7 @@ pub use self::fragment::*;
pub use self::grid::*; pub use self::grid::*;
pub use self::hide::*; pub use self::hide::*;
pub use self::list::*; pub use self::list::*;
pub use self::measure::*; pub use self::measure_::*;
pub use self::pad::*; pub use self::pad::*;
pub use self::page::*; pub use self::page::*;
pub use self::par::*; pub use self::par::*;
@ -57,7 +58,7 @@ use crate::math::{EquationElem, LayoutMath};
use crate::meta::DocumentElem; use crate::meta::DocumentElem;
use crate::prelude::*; use crate::prelude::*;
use crate::shared::BehavedBuilder; use crate::shared::BehavedBuilder;
use crate::text::{LinebreakElem, SmartQuoteElem, SpaceElem, TextElem}; use crate::text::{LinebreakElem, SmartquoteElem, SpaceElem, TextElem};
use crate::visualize::{ use crate::visualize::{
CircleElem, EllipseElem, ImageElem, LineElem, PathElem, PolygonElem, RectElem, CircleElem, EllipseElem, ImageElem, LineElem, PathElem, PolygonElem, RectElem,
SquareElem, SquareElem,
@ -65,43 +66,39 @@ use crate::visualize::{
/// Hook up all layout definitions. /// Hook up all layout definitions.
pub(super) fn define(global: &mut Scope) { pub(super) fn define(global: &mut Scope) {
global.define("page", PageElem::func()); global.category("layout");
global.define("pagebreak", PagebreakElem::func()); global.define_type::<Length>();
global.define("v", VElem::func()); global.define_type::<Angle>();
global.define("par", ParElem::func()); global.define_type::<Ratio>();
global.define("parbreak", ParbreakElem::func()); global.define_type::<Rel<Length>>();
global.define("h", HElem::func()); global.define_type::<Fr>();
global.define("box", BoxElem::func()); global.define_type::<Dir>();
global.define("block", BlockElem::func()); global.define_type::<Align>();
global.define("list", ListElem::func()); global.define_elem::<PageElem>();
global.define("enum", EnumElem::func()); global.define_elem::<PagebreakElem>();
global.define("terms", TermsElem::func()); global.define_elem::<VElem>();
global.define("table", TableElem::func()); global.define_elem::<ParElem>();
global.define("stack", StackElem::func()); global.define_elem::<ParbreakElem>();
global.define("grid", GridElem::func()); global.define_elem::<HElem>();
global.define("columns", ColumnsElem::func()); global.define_elem::<BoxElem>();
global.define("colbreak", ColbreakElem::func()); global.define_elem::<BlockElem>();
global.define("place", PlaceElem::func()); global.define_elem::<ListElem>();
global.define("align", AlignElem::func()); global.define_elem::<EnumElem>();
global.define("pad", PadElem::func()); global.define_elem::<TermsElem>();
global.define("repeat", RepeatElem::func()); global.define_elem::<TableElem>();
global.define("move", MoveElem::func()); global.define_elem::<StackElem>();
global.define("scale", ScaleElem::func()); global.define_elem::<GridElem>();
global.define("rotate", RotateElem::func()); global.define_elem::<ColumnsElem>();
global.define("hide", HideElem::func()); global.define_elem::<ColbreakElem>();
global.define("measure", measure_func()); global.define_elem::<PlaceElem>();
global.define("ltr", Dir::LTR); global.define_elem::<AlignElem>();
global.define("rtl", Dir::RTL); global.define_elem::<PadElem>();
global.define("ttb", Dir::TTB); global.define_elem::<RepeatElem>();
global.define("btt", Dir::BTT); global.define_elem::<MoveElem>();
global.define("start", GenAlign::Start); global.define_elem::<ScaleElem>();
global.define("end", GenAlign::End); global.define_elem::<RotateElem>();
global.define("left", GenAlign::Specific(Align::Left)); global.define_elem::<HideElem>();
global.define("center", GenAlign::Specific(Align::Center)); global.define_func::<measure>();
global.define("right", GenAlign::Specific(Align::Right));
global.define("top", GenAlign::Specific(Align::Top));
global.define("horizon", GenAlign::Specific(Align::Horizon));
global.define("bottom", GenAlign::Specific(Align::Bottom));
} }
/// Root-level layout. /// Root-level layout.
@ -598,7 +595,7 @@ impl<'a> ParBuilder<'a> {
|| content.is::<TextElem>() || content.is::<TextElem>()
|| content.is::<HElem>() || content.is::<HElem>()
|| content.is::<LinebreakElem>() || content.is::<LinebreakElem>()
|| content.is::<SmartQuoteElem>() || content.is::<SmartquoteElem>()
|| content.to::<EquationElem>().map_or(false, |elem| !elem.block(styles)) || content.to::<EquationElem>().map_or(false, |elem| !elem.block(styles))
|| content.is::<BoxElem>() || content.is::<BoxElem>()
{ {

10
crates/typst-library/src/layout/pad.rs
View File

@ -5,7 +5,7 @@ use crate::prelude::*;
/// The spacing can be specified for each side individually, or for all sides at /// The spacing can be specified for each side individually, or for all sides at
/// once by specifying a positional argument. /// once by specifying a positional argument.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #set align(center) /// #set align(center)
/// ///
@ -13,10 +13,7 @@ use crate::prelude::*;
/// _Typing speeds can be /// _Typing speeds can be
/// measured in words per minute._ /// measured in words per minute._
/// ``` /// ```
/// #[elem(title = "Padding", Layout)]
/// Display: Padding
/// Category: layout
#[element(Layout)]
pub struct PadElem { pub struct PadElem {
/// The padding at the left side. /// The padding at the left side.
#[parse( #[parse(
@ -120,6 +117,5 @@ fn shrink(size: Size, padding: Sides<Rel<Abs>>) -> Size {
/// <=> (1 - p.rel) * w = s + p.abs /// <=> (1 - p.rel) * w = s + p.abs
/// <=> w = (s + p.abs) / (1 - p.rel) /// <=> w = (s + p.abs) / (1 - p.rel)
fn grow(size: Size, padding: Sides<Rel<Abs>>) -> Size { fn grow(size: Size, padding: Sides<Rel<Abs>>) -> Size {
size.zip(padding.sum_by_axis()) size.zip_map(padding.sum_by_axis(), |s, p| (s + p.abs).safe_div(1.0 - p.rel.get()))
.map(|(s, p)| (s + p.abs).safe_div(1.0 - p.rel.get()))
} }

68
crates/typst-library/src/layout/page.rs
View File

@ -1,6 +1,8 @@
use std::ptr; use std::ptr;
use std::str::FromStr; use std::str::FromStr;
use typst::eval::AutoValue;
use super::{AlignElem, ColumnsElem}; use super::{AlignElem, ColumnsElem};
use crate::meta::{Counter, CounterKey, Numbering}; use crate::meta::{Counter, CounterKey, Numbering};
use crate::prelude::*; use crate::prelude::*;
@ -18,17 +20,14 @@ use crate::text::TextElem;
/// The [Guide for Page Setup]($guides/page-setup-guide) explains how to use /// The [Guide for Page Setup]($guides/page-setup-guide) explains how to use
/// this and related functions to set up a document with many examples. /// this and related functions to set up a document with many examples.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// >>> #set page(margin: auto) /// >>> #set page(margin: auto)
/// #set page("us-letter") /// #set page("us-letter")
/// ///
/// There you go, US friends! /// There you go, US friends!
/// ``` /// ```
/// #[elem]
/// Display: Page
/// Category: layout
#[element]
pub struct PageElem { pub struct PageElem {
/// A standard paper size to set width and height. /// A standard paper size to set width and height.
#[external] #[external]
@ -59,9 +58,9 @@ pub struct PageElem {
/// The height of the page. /// The height of the page.
/// ///
/// If this is set to `{auto}`, page breaks can only be triggered manually /// If this is set to `{auto}`, page breaks can only be triggered manually
/// by inserting a [page break]($func/pagebreak). Most examples throughout /// by inserting a [page break]($pagebreak). Most examples throughout this
/// this documentation use `{auto}` for the height of the page to /// documentation use `{auto}` for the height of the page to dynamically
/// dynamically grow and shrink to fit their content. /// grow and shrink to fit their content.
#[resolve] #[resolve]
#[parse( #[parse(
args.named("height")? args.named("height")?
@ -103,9 +102,9 @@ pub struct PageElem {
/// - `bottom`: The bottom margin. /// - `bottom`: The bottom margin.
/// - `left`: The left margin. /// - `left`: The left margin.
/// - `inside`: The margin at the inner side of the page (where the /// - `inside`: The margin at the inner side of the page (where the
/// [binding]($func/page.binding) is). /// [binding]($page.binding) is).
/// - `outside`: The margin at the outer side of the page (opposite to the /// - `outside`: The margin at the outer side of the page (opposite to the
/// [binding]($func/page.binding)). /// [binding]($page.binding)).
/// - `x`: The horizontal margins. /// - `x`: The horizontal margins.
/// - `y`: The vertical margins. /// - `y`: The vertical margins.
/// - `rest`: The margins on all sides except those for which the /// - `rest`: The margins on all sides except those for which the
@ -132,7 +131,7 @@ pub struct PageElem {
/// On which side the pages will be bound. /// On which side the pages will be bound.
/// ///
/// - `{auto}`: Equivalent to `left` if the [text direction]($func/text.dir) /// - `{auto}`: Equivalent to `left` if the [text direction]($text.dir)
/// is left-to-right and `right` if it is right-to-left. /// is left-to-right and `right` if it is right-to-left.
/// - `left`: Bound on the left side. /// - `left`: Bound on the left side.
/// - `right`: Bound on the right side. /// - `right`: Bound on the right side.
@ -144,7 +143,7 @@ pub struct PageElem {
/// How many columns the page has. /// How many columns the page has.
/// ///
/// If you need to insert columns into a page or other container, you can /// If you need to insert columns into a page or other container, you can
/// also use the [`columns` function]($func/columns). /// also use the [`columns` function]($columns).
/// ///
/// ```example:single /// ```example:single
/// #set page(columns: 2, height: 4.8cm) /// #set page(columns: 2, height: 4.8cm)
@ -175,7 +174,7 @@ pub struct PageElem {
/// ``` /// ```
pub fill: Option<Paint>, pub fill: Option<Paint>,
/// How to [number]($func/numbering) the pages. /// How to [number]($numbering) the pages.
/// ///
/// If an explicit `footer` (or `header` for top-aligned numbering) is /// If an explicit `footer` (or `header` for top-aligned numbering) is
/// given, the numbering is ignored. /// given, the numbering is ignored.
@ -207,17 +206,17 @@ pub struct PageElem {
/// ///
/// #lorem(30) /// #lorem(30)
/// ``` /// ```
#[default(Align::Center.into())] #[default(HAlign::Center + VAlign::Bottom)]
#[parse({ #[parse({
let spanned: Option<Spanned<Axes<_>>> = args.named("number-align")?; let option: Option<Spanned<Align>> = args.named("number-align")?;
if let Some(Spanned { v, span }) = spanned { if let Some(Spanned { v: align, span }) = option {
if matches!(v.y, Some(GenAlign::Specific(Align::Horizon))) { if align.y() == Some(VAlign::Horizon) {
bail!(span, "page number cannot be `horizon`-aligned"); bail!(span, "page number cannot be `horizon`-aligned");
} }
} }
spanned.map(|s| s.v) option.map(|spanned| spanned.v)
})] })]
pub number_align: Axes<Option<GenAlign>>, pub number_align: Align,
/// The page's header. Fills the top margin of each page. /// The page's header. Fills the top margin of each page.
/// ///
@ -245,7 +244,7 @@ pub struct PageElem {
/// ///
/// For just a page number, the `numbering` property, typically suffices. If /// For just a page number, the `numbering` property, typically suffices. If
/// you want to create a custom footer, but still display the page number, /// you want to create a custom footer, but still display the page number,
/// you can directly access the [page counter]($func/counter). /// you can directly access the [page counter]($counter).
/// ///
/// ```example /// ```example
/// #set par(justify: true) /// #set par(justify: true)
@ -406,14 +405,14 @@ impl PageElem {
// We interpret the Y alignment as selecting header or footer // We interpret the Y alignment as selecting header or footer
// and then ignore it for aligning the actual number. // and then ignore it for aligning the actual number.
if let Some(x) = number_align.x { if let Some(x) = number_align.x() {
counter = counter.aligned(Axes::with_x(Some(x))); counter = counter.aligned(x.into());
} }
counter counter
}); });
if matches!(number_align.y, Some(GenAlign::Specific(Align::Top))) { if matches!(number_align.y(), Some(VAlign::Top)) {
header = header.or(numbering_marginal); header = header.or(numbering_marginal);
} else { } else {
footer = footer.or(numbering_marginal); footer = footer.or(numbering_marginal);
@ -461,16 +460,16 @@ impl PageElem {
let ascent = header_ascent.relative_to(margin.top); let ascent = header_ascent.relative_to(margin.top);
pos = Point::with_x(margin.left); pos = Point::with_x(margin.left);
area = Size::new(pw, margin.top - ascent); area = Size::new(pw, margin.top - ascent);
align = Align::Bottom.into(); align = Align::BOTTOM;
} else if ptr::eq(marginal, &footer) { } else if ptr::eq(marginal, &footer) {
let descent = footer_descent.relative_to(margin.bottom); let descent = footer_descent.relative_to(margin.bottom);
pos = Point::new(margin.left, size.y - margin.bottom + descent); pos = Point::new(margin.left, size.y - margin.bottom + descent);
area = Size::new(pw, margin.bottom - descent); area = Size::new(pw, margin.bottom - descent);
align = Align::Top.into(); align = Align::TOP;
} else { } else {
pos = Point::zero(); pos = Point::zero();
area = size; area = size;
align = Align::CENTER_HORIZON.into(); align = HAlign::Center + VAlign::Horizon;
}; };
let pod = Regions::one(area, Axes::splat(true)); let pod = Regions::one(area, Axes::splat(true));
@ -626,12 +625,12 @@ impl Binding {
cast! { cast! {
Binding, Binding,
self => match self { self => match self {
Self::Left => GenAlign::Specific(Align::Left).into_value(), Self::Left => Align::LEFT.into_value(),
Self::Right => GenAlign::Specific(Align::Right).into_value(), Self::Right => Align::RIGHT.into_value(),
}, },
v: GenAlign => match v { v: Align => match v {
GenAlign::Specific(Align::Left) => Self::Left, Align::LEFT => Self::Left,
GenAlign::Specific(Align::Right) => Self::Right, Align::RIGHT => Self::Right,
_ => bail!("must be `left` or `right`"), _ => bail!("must be `left` or `right`"),
}, },
} }
@ -669,7 +668,7 @@ cast! {
/// ///
/// Must not be used inside any containers. /// Must not be used inside any containers.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// The next page contains /// The next page contains
/// more details on compound theory. /// more details on compound theory.
@ -678,10 +677,7 @@ cast! {
/// == Compound Theory /// == Compound Theory
/// In 1984, the first ... /// In 1984, the first ...
/// ``` /// ```
/// #[elem(title = "Page Break")]
/// Display: Page Break
/// Category: layout
#[element]
pub struct PagebreakElem { pub struct PagebreakElem {
/// If `{true}`, the page break is skipped if the current page is already /// If `{true}`, the page break is skipped if the current page is already
/// empty. /// empty.

54
crates/typst-library/src/layout/par.rs
View File

@ -16,7 +16,7 @@ use crate::layout::AlignElem;
use crate::math::EquationElem; use crate::math::EquationElem;
use crate::prelude::*; use crate::prelude::*;
use crate::text::{ use crate::text::{
is_gb_style, shape, LinebreakElem, Quoter, Quotes, ShapedText, SmartQuoteElem, is_gb_style, shape, LinebreakElem, Quoter, Quotes, ShapedText, SmartquoteElem,
SpaceElem, TextElem, SpaceElem, TextElem,
}; };
@ -26,7 +26,7 @@ use crate::text::{
/// properties, it can also be used to explicitly render its argument onto a /// properties, it can also be used to explicitly render its argument onto a
/// paragraph of its own. /// paragraph of its own.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #show par: set block(spacing: 0.65em) /// #show par: set block(spacing: 0.65em)
/// #set par( /// #set par(
@ -45,10 +45,7 @@ use crate::text::{
/// let $a$ be the smallest of the /// let $a$ be the smallest of the
/// three integers. Then, we ... /// three integers. Then, we ...
/// ``` /// ```
/// #[elem(title = "Paragraph", Construct)]
/// Display: Paragraph
/// Category: layout
#[element(Construct)]
pub struct ParElem { pub struct ParElem {
/// The spacing between lines. /// The spacing between lines.
#[resolve] #[resolve]
@ -57,13 +54,13 @@ pub struct ParElem {
/// Whether to justify text in its line. /// Whether to justify text in its line.
/// ///
/// Hyphenation will be enabled for justified paragraphs if the [text /// Hyphenation will be enabled for justified paragraphs if the
/// property hyphenate]($func/text.hyphenate) is set to `{auto}` and the /// [text function's `hyphenate` property]($text.hyphenate) is set to
/// current language is known. /// `{auto}` and the current language is known.
/// ///
/// Note that the current [alignment]($func/align) still has an effect on /// Note that the current [alignment]($align) still has an effect on the
/// the placement of the last line except if it ends with a [justified line /// placement of the last line except if it ends with a
/// break]($func/linebreak.justify). /// [justified line break]($linebreak.justify).
#[default(false)] #[default(false)]
pub justify: bool, pub justify: bool,
@ -88,7 +85,6 @@ pub struct ParElem {
/// challenging to break in a visually /// challenging to break in a visually
/// pleasing way. /// pleasing way.
/// ``` /// ```
#[default]
pub linebreaks: Smart<Linebreaks>, pub linebreaks: Smart<Linebreaks>,
/// The indent the first line of a paragraph should have. /// The indent the first line of a paragraph should have.
@ -98,7 +94,7 @@ pub struct ParElem {
/// ///
/// By typographic convention, paragraph breaks are indicated either by some /// By typographic convention, paragraph breaks are indicated either by some
/// space between paragraphs or by indented first lines. Consider reducing /// space between paragraphs or by indented first lines. Consider reducing
/// the [paragraph spacing]($func/block.spacing) to the [`leading`] when /// the [paragraph spacing]($block.spacing) to the [`leading`] when
/// using this property (e.g. using /// using this property (e.g. using
/// `[#show par: set block(spacing: 0.65em)]`). /// `[#show par: set block(spacing: 0.65em)]`).
pub first_line_indent: Length, pub first_line_indent: Length,
@ -219,7 +215,7 @@ pub enum Linebreaks {
/// [for loops]($scripting/#loops). Multiple consecutive /// [for loops]($scripting/#loops). Multiple consecutive
/// paragraph breaks collapse into a single one. /// paragraph breaks collapse into a single one.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #for i in range(3) { /// #for i in range(3) {
/// [Blind text #i: ] /// [Blind text #i: ]
@ -228,13 +224,10 @@ pub enum Linebreaks {
/// } /// }
/// ``` /// ```
/// ///
/// ## Syntax { #syntax } /// # Syntax
/// Instead of calling this function, you can insert a blank line into your /// Instead of calling this function, you can insert a blank line into your
/// markup to create a paragraph break. /// markup to create a paragraph break.
/// #[elem(title = "Paragraph Break", Unlabellable)]
/// Display: Paragraph Break
/// Category: layout
#[element(Unlabellable)]
pub struct ParbreakElem {} pub struct ParbreakElem {}
impl Unlabellable for ParbreakElem {} impl Unlabellable for ParbreakElem {}
@ -266,8 +259,8 @@ struct Preparation<'a> {
hyphenate: Option<bool>, hyphenate: Option<bool>,
/// The text language if it's the same for all children. /// The text language if it's the same for all children.
lang: Option<Lang>, lang: Option<Lang>,
/// The paragraph's resolved alignment. /// The paragraph's resolved horizontal alignment.
align: Align, align: FixedAlign,
/// Whether to justify the paragraph. /// Whether to justify the paragraph.
justify: bool, justify: bool,
/// The paragraph's hanging indent. /// The paragraph's hanging indent.
@ -550,7 +543,7 @@ fn collect<'a>(
let first_line_indent = ParElem::first_line_indent_in(*styles); let first_line_indent = ParElem::first_line_indent_in(*styles);
if !first_line_indent.is_zero() if !first_line_indent.is_zero()
&& consecutive && consecutive
&& AlignElem::alignment_in(*styles).x.resolve(*styles) && AlignElem::alignment_in(*styles).resolve(*styles).x
== TextElem::dir_in(*styles).start().into() == TextElem::dir_in(*styles).start().into()
{ {
full.push(SPACING_REPLACE); full.push(SPACING_REPLACE);
@ -593,15 +586,15 @@ fn collect<'a>(
let c = if elem.justify(styles) { '\u{2028}' } else { '\n' }; let c = if elem.justify(styles) { '\u{2028}' } else { '\n' };
full.push(c); full.push(c);
Segment::Text(c.len_utf8()) Segment::Text(c.len_utf8())
} else if let Some(elem) = child.to::<SmartQuoteElem>() { } else if let Some(elem) = child.to::<SmartquoteElem>() {
let prev = full.len(); let prev = full.len();
if SmartQuoteElem::enabled_in(styles) { if SmartquoteElem::enabled_in(styles) {
let lang = TextElem::lang_in(styles); let lang = TextElem::lang_in(styles);
let region = TextElem::region_in(styles); let region = TextElem::region_in(styles);
let quotes = Quotes::from_lang( let quotes = Quotes::from_lang(
lang, lang,
region, region,
SmartQuoteElem::alternative_in(styles), SmartquoteElem::alternative_in(styles),
); );
let peeked = iter.peek().and_then(|child| { let peeked = iter.peek().and_then(|child| {
let child = if let Some((child, _)) = child.to_styled() { let child = if let Some((child, _)) = child.to_styled() {
@ -611,7 +604,7 @@ fn collect<'a>(
}; };
if let Some(elem) = child.to::<TextElem>() { if let Some(elem) = child.to::<TextElem>() {
elem.text().chars().next() elem.text().chars().next()
} else if child.is::<SmartQuoteElem>() { } else if child.is::<SmartquoteElem>() {
Some('"') Some('"')
} else if child.is::<SpaceElem>() } else if child.is::<SpaceElem>()
|| child.is::<HElem>() || child.is::<HElem>()
@ -642,7 +635,7 @@ fn collect<'a>(
}; };
if let Some(last) = full.chars().last() { if let Some(last) = full.chars().last() {
quoter.last(last, child.is::<SmartQuoteElem>()); quoter.last(last, child.is::<SmartquoteElem>());
} }
spans.push(segment.len(), child.span()); spans.push(segment.len(), child.span());
@ -673,9 +666,10 @@ fn prepare<'a>(
styles: StyleChain<'a>, styles: StyleChain<'a>,
region: Size, region: Size,
) -> SourceResult<Preparation<'a>> { ) -> SourceResult<Preparation<'a>> {
let dir = TextElem::dir_in(styles);
let bidi = BidiInfo::new( let bidi = BidiInfo::new(
text, text,
match TextElem::dir_in(styles) { match dir {
Dir::LTR => Some(BidiLevel::ltr()), Dir::LTR => Some(BidiLevel::ltr()),
Dir::RTL => Some(BidiLevel::rtl()), Dir::RTL => Some(BidiLevel::rtl()),
_ => None, _ => None,
@ -734,7 +728,7 @@ fn prepare<'a>(
styles, styles,
hyphenate: shared_get(styles, children, TextElem::hyphenate_in), hyphenate: shared_get(styles, children, TextElem::hyphenate_in),
lang: shared_get(styles, children, TextElem::lang_in), lang: shared_get(styles, children, TextElem::lang_in),
align: AlignElem::alignment_in(styles).x.resolve(styles), align: AlignElem::alignment_in(styles).resolve(styles).x,
justify: ParElem::justify_in(styles), justify: ParElem::justify_in(styles),
hang: ParElem::hanging_indent_in(styles), hang: ParElem::hanging_indent_in(styles),
}) })

26
crates/typst-library/src/layout/place.rs
View File

@ -7,7 +7,7 @@ use crate::prelude::*;
/// other content in the container. Page margins will be respected. /// other content in the container. Page margins will be respected.
/// ///
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #set page(height: 60pt) /// #set page(height: 60pt)
/// Hello, world! /// Hello, world!
@ -20,10 +20,7 @@ use crate::prelude::*;
/// ), /// ),
/// ) /// )
/// ``` /// ```
/// #[elem(Layout, Behave)]
/// Display: Place
/// Category: layout
#[element(Layout, Behave)]
pub struct PlaceElem { pub struct PlaceElem {
/// Relative to which position in the parent container to place the content. /// Relative to which position in the parent container to place the content.
/// ///
@ -34,8 +31,8 @@ pub struct PlaceElem {
/// that axis will be ignored, instead, the item will be placed in the /// that axis will be ignored, instead, the item will be placed in the
/// origin of the axis. /// origin of the axis.
#[positional] #[positional]
#[default(Smart::Custom(Axes::with_x(Some(GenAlign::Start))))] #[default(Smart::Custom(Align::START))]
pub alignment: Smart<Axes<Option<GenAlign>>>, pub alignment: Smart<Align>,
/// Whether the placed element has floating layout. /// Whether the placed element has floating layout.
/// ///
@ -98,16 +95,7 @@ impl Layout for PlaceElem {
let float = self.float(styles); let float = self.float(styles);
let alignment = self.alignment(styles); let alignment = self.alignment(styles);
if float if float && alignment.map_or(false, |align| align.y() == Some(VAlign::Horizon)) {
&& !matches!(
alignment,
Smart::Auto
| Smart::Custom(Axes {
y: Some(GenAlign::Specific(Align::Top | Align::Bottom)),
..
})
)
{
bail!(self.span(), "floating placement must be `auto`, `top`, or `bottom`"); bail!(self.span(), "floating placement must be `auto`, `top`, or `bottom`");
} else if !float && alignment.is_auto() { } else if !float && alignment.is_auto() {
return Err("automatic positioning is only available for floating placement") return Err("automatic positioning is only available for floating placement")
@ -115,9 +103,7 @@ impl Layout for PlaceElem {
.at(self.span()); .at(self.span());
} }
let child = self.body().aligned( let child = self.body().aligned(alignment.unwrap_or_else(|| Align::CENTER));
alignment.unwrap_or_else(|| Axes::with_x(Some(Align::Center.into()))),
);
let pod = Regions::one(base, Axes::splat(false)); let pod = Regions::one(base, Axes::splat(false));
let frame = child.layout(vt, styles, pod)?.into_frame(); let frame = child.layout(vt, styles, pod)?.into_frame();

11
crates/typst-library/src/layout/repeat.rs
View File

@ -12,7 +12,7 @@ use super::AlignElem;
/// Errors if there no bounds on the available space, as it would create /// Errors if there no bounds on the available space, as it would create
/// infinite content. /// infinite content.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// Sign on the dotted line: /// Sign on the dotted line:
/// #box(width: 1fr, repeat[.]) /// #box(width: 1fr, repeat[.])
@ -23,10 +23,7 @@ use super::AlignElem;
/// Berlin, the 22nd of December, 2022 /// Berlin, the 22nd of December, 2022
/// ] /// ]
/// ``` /// ```
/// #[elem(Layout)]
/// Display: Repeat
/// Category: layout
#[element(Layout)]
pub struct RepeatElem { pub struct RepeatElem {
/// The content to repeat. /// The content to repeat.
#[required] #[required]
@ -43,7 +40,7 @@ impl Layout for RepeatElem {
) -> SourceResult<Fragment> { ) -> SourceResult<Fragment> {
let pod = Regions::one(regions.size, Axes::new(false, false)); let pod = Regions::one(regions.size, Axes::new(false, false));
let piece = self.body().layout(vt, styles, pod)?.into_frame(); let piece = self.body().layout(vt, styles, pod)?.into_frame();
let align = AlignElem::alignment_in(styles).x.resolve(styles); let align = AlignElem::alignment_in(styles).resolve(styles);
let fill = regions.size.x; let fill = regions.size.x;
let width = piece.width(); let width = piece.width();
@ -64,7 +61,7 @@ impl Layout for RepeatElem {
let mut offset = Abs::zero(); let mut offset = Abs::zero();
if count == 1.0 { if count == 1.0 {
offset += align.position(remaining); offset += align.x.position(remaining);
} }
if width > Abs::zero() { if width > Abs::zero() {

16
crates/typst-library/src/layout/spacing.rs
View File

@ -8,20 +8,17 @@ use crate::prelude::*;
/// remaining space on the line is distributed among all fractional spacings /// remaining space on the line is distributed among all fractional spacings
/// according to their relative fractions. /// according to their relative fractions.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// First #h(1cm) Second \ /// First #h(1cm) Second \
/// First #h(30%) Second \ /// First #h(30%) Second \
/// First #h(2fr) Second #h(1fr) Third /// First #h(2fr) Second #h(1fr) Third
/// ``` /// ```
/// ///
/// ## Mathematical Spacing { #math-spacing } /// # Mathematical Spacing { #math-spacing }
/// In [mathematical formulas]($category/math), you can additionally use these /// In [mathematical formulas]($category/math), you can additionally use these
/// constants to add spacing between elements: `thin`, `med`, `thick`, `quad`. /// constants to add spacing between elements: `thin`, `med`, `thick`, `quad`.
/// #[elem(title = "Spacing (H)", Behave)]
/// Display: Spacing (H)
/// Category: layout
#[element(Behave)]
pub struct HElem { pub struct HElem {
/// How much spacing to insert. /// How much spacing to insert.
#[required] #[required]
@ -79,7 +76,7 @@ impl Behave for HElem {
/// the remaining space on the page is distributed among all fractional spacings /// the remaining space on the page is distributed among all fractional spacings
/// according to their relative fractions. /// according to their relative fractions.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #grid( /// #grid(
/// rows: 3cm, /// rows: 3cm,
@ -93,10 +90,7 @@ impl Behave for HElem {
/// [A #v(1fr) B], /// [A #v(1fr) B],
/// ) /// )
/// ``` /// ```
/// #[elem(title = "Spacing (V)", Behave)]
/// Display: Spacing (V)
/// Category: layout
#[element(Behave)]
pub struct VElem { pub struct VElem {
/// How much spacing to insert. /// How much spacing to insert.
#[required] #[required]

25
crates/typst-library/src/layout/stack.rs
View File

@ -6,7 +6,7 @@ use crate::prelude::*;
/// The stack places a list of items along an axis, with optional spacing /// The stack places a list of items along an axis, with optional spacing
/// between each item. /// between each item.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #stack( /// #stack(
/// dir: ttb, /// dir: ttb,
@ -15,10 +15,7 @@ use crate::prelude::*;
/// rect(width: 90pt), /// rect(width: 90pt),
/// ) /// )
/// ``` /// ```
/// #[elem(Layout)]
/// Display: Stack
/// Category: layout
#[element(Layout)]
pub struct StackElem { pub struct StackElem {
/// The direction along which the items are stacked. Possible values are: /// The direction along which the items are stacked. Possible values are:
/// ///
@ -27,7 +24,7 @@ pub struct StackElem {
/// - `{ttb}`: Top to bottom. /// - `{ttb}`: Top to bottom.
/// - `{btt}`: Bottom to top. /// - `{btt}`: Bottom to top.
/// ///
/// You cab use the `start` and `end` methods to obtain the initial and /// You can use the `start` and `end` methods to obtain the initial and
/// final points (respectively) of a direction, as `alignment`. You can also /// final points (respectively) of a direction, as `alignment`. You can also
/// use the `axis` method to determine whether a direction is /// use the `axis` method to determine whether a direction is
/// `{"horizontal"}` or `{"vertical"}`. The `inv` method returns a /// `{"horizontal"}` or `{"vertical"}`. The `inv` method returns a
@ -141,7 +138,7 @@ enum StackItem {
/// Fractional spacing between other items. /// Fractional spacing between other items.
Fractional(Fr), Fractional(Fr),
/// A frame for a layouted block. /// A frame for a layouted block.
Frame(Frame, Axes<Align>), Frame(Frame, Axes<FixedAlign>),
} }
impl<'a> StackLayouter<'a> { impl<'a> StackLayouter<'a> {
@ -204,7 +201,7 @@ impl<'a> StackLayouter<'a> {
} }
// Block-axis alignment of the `AlignElement` is respected by stacks. // Block-axis alignment of the `AlignElement` is respected by stacks.
let aligns = if let Some(align) = block.to::<AlignElem>() { let align = if let Some(align) = block.to::<AlignElem>() {
align.alignment(styles) align.alignment(styles)
} else if let Some((_, local)) = block.to_styled() { } else if let Some((_, local)) = block.to_styled() {
AlignElem::alignment_in(styles.chain(local)) AlignElem::alignment_in(styles.chain(local))
@ -230,7 +227,7 @@ impl<'a> StackLayouter<'a> {
self.used.main += gen.main; self.used.main += gen.main;
self.used.cross.set_max(gen.cross); self.used.cross.set_max(gen.cross);
self.items.push(StackItem::Frame(frame, aligns)); self.items.push(StackItem::Frame(frame, align));
if i + 1 < len { if i + 1 < len {
self.finish_region(); self.finish_region();
@ -259,18 +256,18 @@ impl<'a> StackLayouter<'a> {
let mut output = Frame::new(size); let mut output = Frame::new(size);
let mut cursor = Abs::zero(); let mut cursor = Abs::zero();
let mut ruler: Align = self.dir.start().into(); let mut ruler: FixedAlign = self.dir.start().into();
// Place all frames. // Place all frames.
for item in self.items.drain(..) { for item in self.items.drain(..) {
match item { match item {
StackItem::Absolute(v) => cursor += v, StackItem::Absolute(v) => cursor += v,
StackItem::Fractional(v) => cursor += v.share(self.fr, remaining), StackItem::Fractional(v) => cursor += v.share(self.fr, remaining),
StackItem::Frame(frame, aligns) => { StackItem::Frame(frame, align) => {
if self.dir.is_positive() { if self.dir.is_positive() {
ruler = ruler.max(aligns.get(self.axis)); ruler = ruler.max(align.get(self.axis));
} else { } else {
ruler = ruler.min(aligns.get(self.axis)); ruler = ruler.min(align.get(self.axis));
} }
// Align along the main axis. // Align along the main axis.
@ -285,7 +282,7 @@ impl<'a> StackLayouter<'a> {
// Align along the cross axis. // Align along the cross axis.
let other = self.axis.other(); let other = self.axis.other();
let cross = aligns let cross = align
.get(other) .get(other)
.position(size.get(other) - frame.size().get(other)); .position(size.get(other) - frame.size().get(other));

54
crates/typst-library/src/layout/table.rs
View File

@ -9,13 +9,13 @@ use crate::prelude::*;
/// Tables are used to arrange content in cells. Cells can contain arbitrary /// Tables are used to arrange content in cells. Cells can contain arbitrary
/// content, including multiple paragraphs and are specified in row-major order. /// content, including multiple paragraphs and are specified in row-major order.
/// Because tables are just grids with configurable cell properties, refer to /// Because tables are just grids with configurable cell properties, refer to
/// the [grid documentation]($func/grid) for more information on how to size the /// the [grid documentation]($grid) for more information on how to size the
/// table tracks. /// table tracks.
/// ///
/// To give a table a caption and make it [referenceable]($func/ref), put it /// To give a table a caption and make it [referenceable]($ref), put it into a
/// into a [figure]($func/figure). /// [figure]($figure).
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #table( /// #table(
/// columns: (1fr, auto, auto), /// columns: (1fr, auto, auto),
@ -34,34 +34,31 @@ use crate::prelude::*;
/// [$a$: edge length] /// [$a$: edge length]
/// ) /// )
/// ``` /// ```
/// #[elem(Layout, LocalName, Figurable)]
/// Display: Table
/// Category: layout
#[element(Layout, LocalName, Figurable)]
pub struct TableElem { pub struct TableElem {
/// The column sizes. See the [grid documentation]($func/grid) for more /// The column sizes. See the [grid documentation]($grid) for more
/// information on track sizing. /// information on track sizing.
pub columns: TrackSizings, pub columns: TrackSizings,
/// The row sizes. See the [grid documentation]($func/grid) for more /// The row sizes. See the [grid documentation]($grid) for more information
/// information on track sizing. /// on track sizing.
pub rows: TrackSizings, pub rows: TrackSizings,
/// The gaps between rows & columns. See the [grid /// The gaps between rows & columns. See the [grid documentation]($grid) for
/// documentation]($func/grid) for more information on gutters. /// more information on gutters.
#[external] #[external]
pub gutter: TrackSizings, pub gutter: TrackSizings,
/// The gaps between columns. Takes precedence over `gutter`. See the [grid /// The gaps between columns. Takes precedence over `gutter`. See the
/// documentation]($func/grid) for more information on gutters. /// [grid documentation]($grid) for more information on gutters.
#[parse( #[parse(
let gutter = args.named("gutter")?; let gutter = args.named("gutter")?;
args.named("column-gutter")?.or_else(|| gutter.clone()) args.named("column-gutter")?.or_else(|| gutter.clone())
)] )]
pub column_gutter: TrackSizings, pub column_gutter: TrackSizings,
/// The gaps between rows. Takes precedence over `gutter`. See the [grid /// The gaps between rows. Takes precedence over `gutter`. See the
/// documentation]($func/grid) for more information on gutters. /// [grid documentation]($grid) for more information on gutters.
#[parse(args.named("row-gutter")?.or_else(|| gutter.clone()))] #[parse(args.named("row-gutter")?.or_else(|| gutter.clone()))]
pub row_gutter: TrackSizings, pub row_gutter: TrackSizings,
@ -102,20 +99,19 @@ pub struct TableElem {
/// [A], [B], [C], /// [A], [B], [C],
/// ) /// )
/// ``` /// ```
pub align: Celled<Smart<Axes<Option<GenAlign>>>>, pub align: Celled<Smart<Align>>,
/// How to stroke the cells. /// How to [stroke]($stroke) the cells.
/// ///
/// See the [line's documentation]($func/line.stroke) for more details.
/// Strokes can be disabled by setting this to `{none}`. /// Strokes can be disabled by setting this to `{none}`.
/// ///
/// _Note:_ Richer stroke customization for individual cells is not yet /// _Note:_ Richer stroke customization for individual cells is not yet
/// implemented, but will be in the future. In the meantime, you can use /// implemented, but will be in the future. In the meantime, you can use the
/// the third-party [tablex library](https://github.com/PgBiel/typst-tablex/). /// third-party [tablex library](https://github.com/PgBiel/typst-tablex/).
#[resolve] #[resolve]
#[fold] #[fold]
#[default(Some(PartialStroke::default()))] #[default(Some(Stroke::default()))]
pub stroke: Option<PartialStroke>, pub stroke: Option<Stroke>,
/// How much to pad the cells' content. /// How much to pad the cells' content.
#[default(Abs::pt(5.0).into())] #[default(Abs::pt(5.0).into())]
@ -158,7 +154,7 @@ impl Layout for TableElem {
.collect::<SourceResult<_>>()?; .collect::<SourceResult<_>>()?;
let fill = self.fill(styles); let fill = self.fill(styles);
let stroke = self.stroke(styles).map(PartialStroke::unwrap_or_default); let stroke = self.stroke(styles).map(Stroke::unwrap_or_default);
// Prepare grid layout by unifying content and gutter tracks. // Prepare grid layout by unifying content and gutter tracks.
let layouter = GridLayouter::new( let layouter = GridLayouter::new(
@ -268,8 +264,12 @@ impl<T: Default> Default for Celled<T> {
} }
impl<T: Reflect> Reflect for Celled<T> { impl<T: Reflect> Reflect for Celled<T> {
fn describe() -> CastInfo { fn input() -> CastInfo {
T::describe() + Array::describe() + Func::describe() T::input() + Array::input() + Func::input()
}
fn output() -> CastInfo {
T::output() + Array::output() + Func::output()
} }
fn castable(value: &Value) -> bool { fn castable(value: &Value) -> bool {

34
crates/typst-library/src/layout/terms.rs
View File

@ -8,29 +8,22 @@ use crate::prelude::*;
/// descriptions span over multiple lines, they use hanging indent to /// descriptions span over multiple lines, they use hanging indent to
/// communicate the visual hierarchy. /// communicate the visual hierarchy.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// / Ligature: A merged glyph. /// / Ligature: A merged glyph.
/// / Kerning: A spacing adjustment /// / Kerning: A spacing adjustment
/// between two adjacent letters. /// between two adjacent letters.
/// ``` /// ```
/// ///
/// ## Syntax { #syntax } /// # Syntax
/// This function also has dedicated syntax: Starting a line with a slash, /// This function also has dedicated syntax: Starting a line with a slash,
/// followed by a term, a colon and a description creates a term list item. /// followed by a term, a colon and a description creates a term list item.
/// #[elem(scope, title = "Term List", Layout)]
/// Display: Term List
/// Category: layout
#[element(Layout)]
#[scope(
scope.define("item", TermItem::func());
scope
)]
pub struct TermsElem { pub struct TermsElem {
/// If this is `{false}`, the items are spaced apart with [term list /// If this is `{false}`, the items are spaced apart with
/// spacing]($func/terms.spacing). If it is `{true}`, they use normal /// [term list spacing]($terms.spacing). If it is `{true}`, they use normal
/// [leading]($func/par.leading) instead. This makes the term list more /// [leading]($par.leading) instead. This makes the term list more compact,
/// compact, which can look better if the items are short. /// which can look better if the items are short.
/// ///
/// In markup mode, the value of this parameter is determined based on /// In markup mode, the value of this parameter is determined based on
/// whether items are separated with a blank line. If items directly follow /// whether items are separated with a blank line. If items directly follow
@ -81,7 +74,7 @@ pub struct TermsElem {
/// The spacing between the items of a wide (non-tight) term list. /// The spacing between the items of a wide (non-tight) term list.
/// ///
/// If set to `{auto}`, uses the spacing [below blocks]($func/block.below). /// If set to `{auto}`, uses the spacing [below blocks]($block.below).
pub spacing: Smart<Spacing>, pub spacing: Smart<Spacing>,
/// The term list's children. /// The term list's children.
@ -100,6 +93,12 @@ pub struct TermsElem {
pub children: Vec<TermItem>, pub children: Vec<TermItem>,
} }
#[scope]
impl TermsElem {
#[elem]
type TermItem;
}
impl Layout for TermsElem { impl Layout for TermsElem {
#[tracing::instrument(name = "TermsElem::layout", skip_all)] #[tracing::instrument(name = "TermsElem::layout", skip_all)]
fn layout( fn layout(
@ -138,10 +137,7 @@ impl Layout for TermsElem {
} }
/// A term list item. /// A term list item.
/// #[elem(name = "item", title = "Term List Item")]
/// Display: Term List Item
/// Category: layout
#[element]
pub struct TermItem { pub struct TermItem {
/// The term described by the list item. /// The term described by the list item.
#[required] #[required]

45
crates/typst-library/src/layout/transform.rs
View File

@ -8,7 +8,7 @@ use crate::prelude::*;
/// it at the original positions. Containers will still be sized as if the /// it at the original positions. Containers will still be sized as if the
/// content was not moved. /// content was not moved.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #rect(inset: 0pt, move( /// #rect(inset: 0pt, move(
/// dx: 6pt, dy: 6pt, /// dx: 6pt, dy: 6pt,
@ -20,10 +20,7 @@ use crate::prelude::*;
/// ) /// )
/// )) /// ))
/// ``` /// ```
/// #[elem(Layout)]
/// Display: Move
/// Category: layout
#[element(Layout)]
pub struct MoveElem { pub struct MoveElem {
/// The horizontal displacement of the content. /// The horizontal displacement of the content.
pub dx: Rel<Length>, pub dx: Rel<Length>,
@ -47,7 +44,7 @@ impl Layout for MoveElem {
let pod = Regions::one(regions.base(), Axes::splat(false)); let pod = Regions::one(regions.base(), Axes::splat(false));
let mut frame = self.body().layout(vt, styles, pod)?.into_frame(); let mut frame = self.body().layout(vt, styles, pod)?.into_frame();
let delta = Axes::new(self.dx(styles), self.dy(styles)).resolve(styles); let delta = Axes::new(self.dx(styles), self.dy(styles)).resolve(styles);
let delta = delta.zip(regions.base()).map(|(d, s)| d.relative_to(s)); let delta = delta.zip_map(regions.base(), Rel::relative_to);
frame.translate(delta.to_point()); frame.translate(delta.to_point());
Ok(Fragment::frame(frame)) Ok(Fragment::frame(frame))
} }
@ -58,7 +55,7 @@ impl Layout for MoveElem {
/// Rotates an element by a given angle. The layout will act as if the element /// Rotates an element by a given angle. The layout will act as if the element
/// was not rotated. /// was not rotated.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #stack( /// #stack(
/// dir: ltr, /// dir: ltr,
@ -67,10 +64,7 @@ impl Layout for MoveElem {
/// .map(i => rotate(24deg * i)[X]), /// .map(i => rotate(24deg * i)[X]),
/// ) /// )
/// ``` /// ```
/// #[elem(Layout)]
/// Display: Rotate
/// Category: layout
#[element(Layout)]
pub struct RotateElem { pub struct RotateElem {
/// The amount of rotation. /// The amount of rotation.
/// ///
@ -96,10 +90,9 @@ pub struct RotateElem {
/// #box(rotate(30deg, origin: top + left, square())) /// #box(rotate(30deg, origin: top + left, square()))
/// #box(rotate(30deg, origin: bottom + right, square())) /// #box(rotate(30deg, origin: bottom + right, square()))
/// ``` /// ```
#[resolve]
#[fold] #[fold]
#[default(Align::CENTER_HORIZON)] #[default(HAlign::Center + VAlign::Horizon)]
pub origin: Axes<Option<GenAlign>>, pub origin: Align,
/// The content to rotate. /// The content to rotate.
#[required] #[required]
@ -116,8 +109,10 @@ impl Layout for RotateElem {
) -> SourceResult<Fragment> { ) -> SourceResult<Fragment> {
let pod = Regions::one(regions.base(), Axes::splat(false)); let pod = Regions::one(regions.base(), Axes::splat(false));
let mut frame = self.body().layout(vt, styles, pod)?.into_frame(); let mut frame = self.body().layout(vt, styles, pod)?.into_frame();
let Axes { x, y } = let Axes { x, y } = self
self.origin(styles).zip(frame.size()).map(|(o, s)| o.position(s)); .origin(styles)
.resolve(styles)
.zip_map(frame.size(), FixedAlign::position);
let ts = Transform::translate(x, y) let ts = Transform::translate(x, y)
.pre_concat(Transform::rotate(self.angle(styles))) .pre_concat(Transform::rotate(self.angle(styles)))
.pre_concat(Transform::translate(-x, -y)); .pre_concat(Transform::translate(-x, -y));
@ -130,15 +125,12 @@ impl Layout for RotateElem {
/// ///
/// Lets you mirror content by specifying a negative scale on a single axis. /// Lets you mirror content by specifying a negative scale on a single axis.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #set align(center) /// #set align(center)
/// #scale(x: -100%)[This is mirrored.] /// #scale(x: -100%)[This is mirrored.]
/// ``` /// ```
/// #[elem(Layout)]
/// Display: Scale
/// Category: layout
#[element(Layout)]
pub struct ScaleElem { pub struct ScaleElem {
/// The horizontal scaling factor. /// The horizontal scaling factor.
/// ///
@ -163,10 +155,9 @@ pub struct ScaleElem {
/// A#box(scale(75%)[A])A \ /// A#box(scale(75%)[A])A \
/// B#box(scale(75%, origin: bottom + left)[B])B /// B#box(scale(75%, origin: bottom + left)[B])B
/// ``` /// ```
#[resolve]
#[fold] #[fold]
#[default(Align::CENTER_HORIZON)] #[default(HAlign::Center + VAlign::Horizon)]
pub origin: Axes<Option<GenAlign>>, pub origin: Align,
/// The content to scale. /// The content to scale.
#[required] #[required]
@ -183,8 +174,10 @@ impl Layout for ScaleElem {
) -> SourceResult<Fragment> { ) -> SourceResult<Fragment> {
let pod = Regions::one(regions.base(), Axes::splat(false)); let pod = Regions::one(regions.base(), Axes::splat(false));
let mut frame = self.body().layout(vt, styles, pod)?.into_frame(); let mut frame = self.body().layout(vt, styles, pod)?.into_frame();
let Axes { x, y } = let Axes { x, y } = self
self.origin(styles).zip(frame.size()).map(|(o, s)| o.position(s)); .origin(styles)
.resolve(styles)
.zip_map(frame.size(), FixedAlign::position);
let transform = Transform::translate(x, y) let transform = Transform::translate(x, y)
.pre_concat(Transform::scale(self.x(styles), self.y(styles))) .pre_concat(Transform::scale(self.x(styles), self.y(styles)))
.pre_concat(Transform::translate(-x, -y)); .pre_concat(Transform::translate(-x, -y));

72
crates/typst-library/src/lib.rs
View File

@ -14,10 +14,9 @@ pub mod symbols;
pub mod text; pub mod text;
pub mod visualize; pub mod visualize;
use typst::diag::At; use typst::eval::{Array, LangItems, Library, Module, Scope};
use typst::eval::{LangItems, Library, Module, Scope}; use typst::geom::{Align, Color, Dir, Smart};
use typst::geom::Smart; use typst::model::{NativeElement, Styles};
use typst::model::{Element, Styles};
use self::layout::LayoutRoot; use self::layout::LayoutRoot;
@ -32,17 +31,53 @@ pub fn build() -> Library {
#[tracing::instrument(skip_all)] #[tracing::instrument(skip_all)]
fn global(math: Module) -> Module { fn global(math: Module) -> Module {
let mut global = Scope::deduplicating(); let mut global = Scope::deduplicating();
// Categories.
text::define(&mut global); text::define(&mut global);
global.define_module(math);
layout::define(&mut global); layout::define(&mut global);
visualize::define(&mut global); visualize::define(&mut global);
meta::define(&mut global); meta::define(&mut global);
compute::define(&mut global);
symbols::define(&mut global); symbols::define(&mut global);
global.define("math", math); compute::define(&mut global);
prelude(&mut global);
Module::new("global", global)
}
Module::new("global").with_scope(global) /// Defines scoped values that are globally available, too.
fn prelude(global: &mut Scope) {
global.define("black", Color::BLACK);
global.define("gray", Color::GRAY);
global.define("silver", Color::SILVER);
global.define("white", Color::WHITE);
global.define("navy", Color::NAVY);
global.define("blue", Color::BLUE);
global.define("aqua", Color::AQUA);
global.define("teal", Color::TEAL);
global.define("eastern", Color::EASTERN);
global.define("purple", Color::PURPLE);
global.define("fuchsia", Color::FUCHSIA);
global.define("maroon", Color::MAROON);
global.define("red", Color::RED);
global.define("orange", Color::ORANGE);
global.define("yellow", Color::YELLOW);
global.define("olive", Color::OLIVE);
global.define("green", Color::GREEN);
global.define("lime", Color::LIME);
global.define("luma", Color::luma_data());
global.define("rgb", Color::rgb_data());
global.define("cmyk", Color::cmyk_data());
global.define("range", Array::range_data());
global.define("ltr", Dir::LTR);
global.define("rtl", Dir::RTL);
global.define("ttb", Dir::TTB);
global.define("btt", Dir::BTT);
global.define("start", Align::START);
global.define("left", Align::LEFT);
global.define("center", Align::CENTER);
global.define("right", Align::RIGHT);
global.define("end", Align::END);
global.define("top", Align::TOP);
global.define("horizon", Align::HORIZON);
global.define("bottom", Align::BOTTOM);
} }
/// Construct the standard style map. /// Construct the standard style map.
@ -59,9 +94,9 @@ fn items() -> LangItems {
space: || text::SpaceElem::new().pack(), space: || text::SpaceElem::new().pack(),
linebreak: || text::LinebreakElem::new().pack(), linebreak: || text::LinebreakElem::new().pack(),
text: |text| text::TextElem::new(text).pack(), text: |text| text::TextElem::new(text).pack(),
text_func: text::TextElem::func(), text_elem: text::TextElem::elem(),
text_str: |content| Some(content.to::<text::TextElem>()?.text()), text_str: |content| Some(content.to::<text::TextElem>()?.text()),
smart_quote: |double| text::SmartQuoteElem::new().with_double(double).pack(), smart_quote: |double| text::SmartquoteElem::new().with_double(double).pack(),
parbreak: || layout::ParbreakElem::new().pack(), parbreak: || layout::ParbreakElem::new().pack(),
strong: |body| text::StrongElem::new(body).pack(), strong: |body| text::StrongElem::new(body).pack(),
emph: |body| text::EmphElem::new(body).pack(), emph: |body| text::EmphElem::new(body).pack(),
@ -85,7 +120,7 @@ fn items() -> LangItems {
}, },
bibliography_keys: meta::BibliographyElem::keys, bibliography_keys: meta::BibliographyElem::keys,
heading: |level, title| meta::HeadingElem::new(title).with_level(level).pack(), heading: |level, title| meta::HeadingElem::new(title).with_level(level).pack(),
heading_func: meta::HeadingElem::func(), heading_elem: meta::HeadingElem::elem(),
list_item: |body| layout::ListItem::new(body).pack(), list_item: |body| layout::ListItem::new(body).pack(),
enum_item: |number, body| { enum_item: |number, body| {
let mut elem = layout::EnumItem::new(body); let mut elem = layout::EnumItem::new(body);
@ -95,9 +130,6 @@ fn items() -> LangItems {
elem.pack() elem.pack()
}, },
term_item: |term, description| layout::TermItem::new(term, description).pack(), term_item: |term, description| layout::TermItem::new(term, description).pack(),
rgb_func: compute::rgb_func(),
cmyk_func: compute::cmyk_func(),
luma_func: compute::luma_func(),
equation: |body, block| math::EquationElem::new(body).with_block(block).pack(), equation: |body, block| math::EquationElem::new(body).with_block(block).pack(),
math_align_point: || math::AlignPointElem::new().pack(), math_align_point: || math::AlignPointElem::new().pack(),
math_delimited: |open, body, close| math::LrElem::new(open + body + close).pack(), math_delimited: |open, body, close| math::LrElem::new(open + body + close).pack(),
@ -131,15 +163,5 @@ fn items() -> LangItems {
math_root: |index, radicand| { math_root: |index, radicand| {
math::RootElem::new(radicand).with_index(index).pack() math::RootElem::new(radicand).with_index(index).pack()
}, },
library_method: |vm, dynamic, method, args, span| {
if let Some(counter) = dynamic.downcast::<meta::Counter>().cloned() {
counter.call_method(vm, method, args, span)
} else if let Some(state) = dynamic.downcast::<meta::State>().cloned() {
state.call_method(vm, method, args, span)
} else {
Err(format!("type {} has no method `{method}`", dynamic.type_name()))
.at(span)
}
},
} }
} }

7
crates/typst-library/src/math/accent.rs
View File

@ -5,16 +5,13 @@ const ACCENT_SHORT_FALL: Em = Em::new(0.5);
/// Attaches an accent to a base. /// Attaches an accent to a base.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// $grave(a) = accent(a, `)$ \ /// $grave(a) = accent(a, `)$ \
/// $arrow(a) = accent(a, arrow)$ \ /// $arrow(a) = accent(a, arrow)$ \
/// $tilde(a) = accent(a, \u{0303})$ /// $tilde(a) = accent(a, \u{0303})$
/// ``` /// ```
/// #[elem(LayoutMath)]
/// Display: Accent
/// Category: math
#[element(LayoutMath)]
pub struct AccentElem { pub struct AccentElem {
/// The base to which the accent is applied. /// The base to which the accent is applied.
/// May consist of multiple letters. /// May consist of multiple letters.

5
crates/typst-library/src/math/align.rs
View File

@ -1,10 +1,7 @@
use super::*; use super::*;
/// A math alignment point: `&`, `&&`. /// A math alignment point: `&`, `&&`.
/// #[elem(title = "Alignment Point", LayoutMath)]
/// Display: Alignment Point
/// Category: math
#[element(LayoutMath)]
pub struct AlignPointElem {} pub struct AlignPointElem {}
impl LayoutMath for AlignPointElem { impl LayoutMath for AlignPointElem {

35
crates/typst-library/src/math/attach.rs
View File

@ -2,26 +2,13 @@ use super::*;
/// A base with optional attachments. /// A base with optional attachments.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// // With syntax.
/// $ sum_(i=0)^n a_i = 2^(1+i) $
///
/// // With function call.
/// $ attach( /// $ attach(
/// Pi, t: alpha, b: beta, /// Pi, t: alpha, b: beta,
/// tl: 1, tr: 2+3, bl: 4+5, br: 6, /// tl: 1, tr: 2+3, bl: 4+5, br: 6,
/// ) $ /// ) $
/// ``` /// ```
/// #[elem(LayoutMath)]
/// ## Syntax { #syntax }
/// This function also has dedicated syntax for attachments after the base: Use
/// the underscore (`_`) to indicate a subscript i.e. bottom attachment and the
/// hat (`^`) to indicate a superscript i.e. top attachment.
///
/// Display: Attachment
/// Category: math
#[element(LayoutMath)]
pub struct AttachElem { pub struct AttachElem {
/// The base to which things are attached. /// The base to which things are attached.
#[required] #[required]
@ -86,19 +73,15 @@ impl LayoutMath for AttachElem {
/// Grouped primes. /// Grouped primes.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// $ a'''_b = a^'''_b $ /// $ a'''_b = a^'''_b $
/// ``` /// ```
/// ///
/// ## Syntax /// # Syntax
/// This function has dedicated syntax: use apostrophes instead of primes. They /// This function has dedicated syntax: use apostrophes instead of primes. They
/// will automatically attach to the previous element, moving superscripts to /// will automatically attach to the previous element, moving superscripts to
/// the next level. /// the next level.
/// #[elem(LayoutMath)]
/// Display: Attachment
/// Category: math
#[element(LayoutMath)]
pub struct PrimesElem { pub struct PrimesElem {
/// The number of grouped primes. /// The number of grouped primes.
#[required] #[required]
@ -141,14 +124,10 @@ impl LayoutMath for PrimesElem {
/// Forces a base to display attachments as scripts. /// Forces a base to display attachments as scripts.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// $ scripts(sum)_1^2 != sum_1^2 $ /// $ scripts(sum)_1^2 != sum_1^2 $
/// ``` /// ```
/// #[elem(LayoutMath)]
/// Display: Scripts
/// Category: math
#[element(LayoutMath)]
pub struct ScriptsElem { pub struct ScriptsElem {
/// The base to attach the scripts to. /// The base to attach the scripts to.
#[required] #[required]
@ -167,14 +146,10 @@ impl LayoutMath for ScriptsElem {
/// Forces a base to display attachments as limits. /// Forces a base to display attachments as limits.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// $ limits(A)_1^2 != A_1^2 $ /// $ limits(A)_1^2 != A_1^2 $
/// ``` /// ```
/// #[elem(LayoutMath)]
/// Display: Limits
/// Category: math
#[element(LayoutMath)]
pub struct LimitsElem { pub struct LimitsElem {
/// The base to attach the limits to. /// The base to attach the limits to.
#[required] #[required]

26
crates/typst-library/src/math/cancel.rs
View File

@ -4,17 +4,14 @@ use super::*;
/// ///
/// This is commonly used to show the elimination of a term. /// This is commonly used to show the elimination of a term.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// >>> #set page(width: 140pt) /// >>> #set page(width: 140pt)
/// Here, we can simplify: /// Here, we can simplify:
/// $ (a dot b dot cancel(x)) / /// $ (a dot b dot cancel(x)) /
/// cancel(x) $ /// cancel(x) $
/// ``` /// ```
/// #[elem(LayoutMath)]
/// Display: Cancel
/// Category: math
#[element(LayoutMath)]
pub struct CancelElem { pub struct CancelElem {
/// The content over which the line should be placed. /// The content over which the line should be placed.
#[required] #[required]
@ -53,8 +50,8 @@ pub struct CancelElem {
#[default(false)] #[default(false)]
pub cross: bool, pub cross: bool,
/// How to rotate the cancel line. See the [line's /// How to rotate the cancel line. See the
/// documentation]($func/line.angle) for more details. /// [line's documentation]($line.angle) for more details.
/// ///
/// ```example /// ```example
/// >>> #set page(width: 140pt) /// >>> #set page(width: 140pt)
@ -63,8 +60,7 @@ pub struct CancelElem {
#[default(Angle::zero())] #[default(Angle::zero())]
pub rotation: Angle, pub rotation: Angle,
/// How to stroke the cancel line. See the /// How to [stroke]($stroke) the cancel line.
/// [line's documentation]($func/line.stroke) for more details.
/// ///
/// ```example /// ```example
/// >>> #set page(width: 140pt) /// >>> #set page(width: 140pt)
@ -79,12 +75,12 @@ pub struct CancelElem {
/// ``` /// ```
#[resolve] #[resolve]
#[fold] #[fold]
#[default(PartialStroke { #[default(Stroke {
// Default stroke has 0.5pt for better visuals. // Default stroke has 0.5pt for better visuals.
thickness: Smart::Custom(Abs::pt(0.5)), thickness: Smart::Custom(Abs::pt(0.5)),
..Default::default() ..Default::default()
})] })]
pub stroke: PartialStroke, pub stroke: Stroke,
} }
impl LayoutMath for CancelElem { impl LayoutMath for CancelElem {
@ -99,7 +95,7 @@ impl LayoutMath for CancelElem {
let span = self.span(); let span = self.span();
let length = self.length(styles).resolve(styles); let length = self.length(styles).resolve(styles);
let stroke = self.stroke(styles).unwrap_or(Stroke { let stroke = self.stroke(styles).unwrap_or(FixedStroke {
paint: TextElem::fill_in(styles), paint: TextElem::fill_in(styles),
..Default::default() ..Default::default()
}); });
@ -139,7 +135,7 @@ impl LayoutMath for CancelElem {
/// Draws a cancel line. /// Draws a cancel line.
fn draw_cancel_line( fn draw_cancel_line(
length: Rel<Abs>, length: Rel<Abs>,
stroke: Stroke, stroke: FixedStroke,
invert: bool, invert: bool,
angle: Angle, angle: Angle,
body_size: Size, body_size: Size,
@ -172,8 +168,8 @@ fn draw_cancel_line(
// (-width / 2, height / 2) with length components (width, -height) (sign is // (-width / 2, height / 2) with length components (width, -height) (sign is
// inverted in the y-axis). After applying the scale, the line will have the // inverted in the y-axis). After applying the scale, the line will have the
// correct length and orientation (inverted if needed). // correct length and orientation (inverted if needed).
let start = Axes::new(-mid.x, mid.y).zip(scales).map(|(l, s)| l * s); let start = Axes::new(-mid.x, mid.y).zip_map(scales, |l, s| l * s);
let delta = Axes::new(width, -height).zip(scales).map(|(l, s)| l * s); let delta = Axes::new(width, -height).zip_map(scales, |l, s| l * s);
let mut frame = Frame::new(body_size); let mut frame = Frame::new(body_size);
frame.push( frame.push(

7
crates/typst-library/src/math/class.rs
View File

@ -5,7 +5,7 @@ use super::*;
/// This is useful to treat certain symbols as if they were of a different /// This is useful to treat certain symbols as if they were of a different
/// class, e.g. to make a symbol behave like a relation. /// class, e.g. to make a symbol behave like a relation.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #let loves = math.class( /// #let loves = math.class(
/// "relation", /// "relation",
@ -14,10 +14,7 @@ use super::*;
/// ///
/// $x loves y and y loves 5$ /// $x loves y and y loves 5$
/// ``` /// ```
/// #[elem(LayoutMath)]
/// Display: Class
/// Category: math
#[element(LayoutMath)]
pub struct ClassElem { pub struct ClassElem {
/// The class to apply to the content. /// The class to apply to the content.
#[required] #[required]

20
crates/typst-library/src/math/frac.rs
View File

@ -4,21 +4,18 @@ const FRAC_AROUND: Em = Em::new(0.1);
/// A mathematical fraction. /// A mathematical fraction.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// $ 1/2 < (x+1)/2 $ /// $ 1/2 < (x+1)/2 $
/// $ ((x+1)) / 2 = frac(a, b) $ /// $ ((x+1)) / 2 = frac(a, b) $
/// ``` /// ```
/// ///
/// ## Syntax { #syntax } /// # Syntax
/// This function also has dedicated syntax: Use a slash to turn neighbouring /// This function also has dedicated syntax: Use a slash to turn neighbouring
/// expressions into a fraction. Multiple atoms can be grouped into a single /// expressions into a fraction. Multiple atoms can be grouped into a single
/// expression using round grouping parenthesis. Such parentheses are removed /// expression using round grouping parenthesis. Such parentheses are removed
/// from the output, but you can nest multiple to force them. /// from the output, but you can nest multiple to force them.
/// #[elem(title = "Fraction", LayoutMath)]
/// Display: Fraction
/// Category: math
#[element(LayoutMath)]
pub struct FracElem { pub struct FracElem {
/// The fraction's numerator. /// The fraction's numerator.
#[required] #[required]
@ -38,14 +35,11 @@ impl LayoutMath for FracElem {
/// A binomial expression. /// A binomial expression.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// $ binom(n, k) $ /// $ binom(n, k) $
/// ``` /// ```
/// #[elem(title = "Binomial", LayoutMath)]
/// Display: Binomial
/// Category: math
#[element(LayoutMath)]
pub struct BinomElem { pub struct BinomElem {
/// The binomial's upper index. /// The binomial's upper index.
#[required] #[required]
@ -135,10 +129,10 @@ fn layout(
frame.push( frame.push(
line_pos, line_pos,
FrameItem::Shape( FrameItem::Shape(
Geometry::Line(Point::with_x(line_width)).stroked(Stroke { Geometry::Line(Point::with_x(line_width)).stroked(FixedStroke {
paint: TextElem::fill_in(ctx.styles()), paint: TextElem::fill_in(ctx.styles()),
thickness, thickness,
..Stroke::default() ..FixedStroke::default()
}), }),
span, span,
), ),

32
crates/typst-library/src/math/delimited.rs → crates/typst-library/src/math/lr.rs
View File

@ -7,16 +7,7 @@ pub(super) const DELIM_SHORT_FALL: Em = Em::new(0.1);
/// ///
/// While matched delimiters scale by default, this can be used to scale /// While matched delimiters scale by default, this can be used to scale
/// unmatched delimiters and to control the delimiter scaling more precisely. /// unmatched delimiters and to control the delimiter scaling more precisely.
/// #[elem(title = "Left/Right", LayoutMath)]
/// ## Example { #example }
/// ```example
/// $ lr(]a, b/2]) $
/// $ lr(]sum_(x=1)^n] x, size: #50%) $
/// ```
///
/// Display: Left/Right
/// Category: math
#[element(LayoutMath)]
pub struct LrElem { pub struct LrElem {
/// The size of the brackets, relative to the height of the wrapped content. /// The size of the brackets, relative to the height of the wrapped content.
pub size: Smart<Rel<Length>>, pub size: Smart<Rel<Length>>,
@ -107,13 +98,9 @@ fn scale(
/// Floors an expression. /// Floors an expression.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// $ floor(x/2) $ /// $ floor(x/2) $
/// ``` /// ```
///
/// Display: Floor
/// Category: math
#[func] #[func]
pub fn floor( pub fn floor(
/// The expression to floor. /// The expression to floor.
@ -124,13 +111,9 @@ pub fn floor(
/// Ceils an expression. /// Ceils an expression.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// $ ceil(x/2) $ /// $ ceil(x/2) $
/// ``` /// ```
///
/// Display: Ceil
/// Category: math
#[func] #[func]
pub fn ceil( pub fn ceil(
/// The expression to ceil. /// The expression to ceil.
@ -141,13 +124,9 @@ pub fn ceil(
/// Rounds an expression. /// Rounds an expression.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// $ round(x/2) $ /// $ round(x/2) $
/// ``` /// ```
///
/// Display: Round
/// Category: math
#[func] #[func]
pub fn round( pub fn round(
/// The expression to round. /// The expression to round.
@ -158,14 +137,9 @@ pub fn round(
/// Takes the absolute value of an expression. /// Takes the absolute value of an expression.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// $ abs(x/2) $ /// $ abs(x/2) $
/// ``` /// ```
///
///
/// Display: Abs
/// Category: math
#[func] #[func]
pub fn abs( pub fn abs(
/// The expression to take the absolute value of. /// The expression to take the absolute value of.
@ -176,13 +150,9 @@ pub fn abs(
/// Takes the norm of an expression. /// Takes the norm of an expression.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// $ norm(x/2) $ /// $ norm(x/2) $
/// ``` /// ```
///
/// Display: Norm
/// Category: math
#[func] #[func]
pub fn norm( pub fn norm(
/// The expression to take the norm of. /// The expression to take the norm of.

47
crates/typst-library/src/math/matrix.rs
View File

@ -12,15 +12,12 @@ const DEFAULT_STROKE_THICKNESS: Em = Em::new(0.05);
/// ///
/// Content in the vector's elements can be aligned with the `&` symbol. /// Content in the vector's elements can be aligned with the `&` symbol.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// $ vec(a, b, c) dot vec(1, 2, 3) /// $ vec(a, b, c) dot vec(1, 2, 3)
/// = a + 2b + 3c $ /// = a + 2b + 3c $
/// ``` /// ```
/// #[elem(title = "Vector", LayoutMath)]
/// Display: Vector
/// Category: math
#[element(LayoutMath)]
pub struct VecElem { pub struct VecElem {
/// The delimiter to use. /// The delimiter to use.
/// ///
@ -40,7 +37,7 @@ impl LayoutMath for VecElem {
#[tracing::instrument(skip(ctx))] #[tracing::instrument(skip(ctx))]
fn layout_math(&self, ctx: &mut MathContext) -> SourceResult<()> { fn layout_math(&self, ctx: &mut MathContext) -> SourceResult<()> {
let delim = self.delim(ctx.styles()); let delim = self.delim(ctx.styles());
let frame = layout_vec_body(ctx, &self.children(), Align::Center)?; let frame = layout_vec_body(ctx, &self.children(), FixedAlign::Center)?;
layout_delimiters( layout_delimiters(
ctx, ctx,
frame, frame,
@ -61,7 +58,7 @@ impl LayoutMath for VecElem {
/// ///
/// Content in cells that are in the same row can be aligned with the `&` symbol. /// Content in cells that are in the same row can be aligned with the `&` symbol.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// $ mat( /// $ mat(
/// 1, 2, ..., 10; /// 1, 2, ..., 10;
@ -70,10 +67,7 @@ impl LayoutMath for VecElem {
/// 10, 10, ..., 10; /// 10, 10, ..., 10;
/// ) $ /// ) $
/// ``` /// ```
/// #[elem(title = "Matrix", LayoutMath)]
/// Display: Matrix
/// Category: math
#[element(LayoutMath)]
pub struct MatElem { pub struct MatElem {
/// The delimiter to use. /// The delimiter to use.
/// ///
@ -102,10 +96,8 @@ pub struct MatElem {
/// drawn after the second column of the matrix. Accepts either an /// drawn after the second column of the matrix. Accepts either an
/// integer for a single line, or an array of integers /// integer for a single line, or an array of integers
/// for multiple lines. /// for multiple lines.
/// - `stroke`: How to stroke the line. See the /// - `stroke`: How to [stroke]($stroke) the line. If set to `{auto}`,
/// [line's documentation]($func/line.stroke) /// takes on a thickness of 0.05em and square line caps.
/// for more details. If set to `{auto}`, takes on a thickness of
/// 0.05em and square line caps.
/// ///
/// ```example /// ```example
/// $ mat(1, 0, 1; 0, 1, 2; augment: #2) $ /// $ mat(1, 0, 1; 0, 1, 2; augment: #2) $
@ -204,7 +196,7 @@ impl LayoutMath for MatElem {
/// ///
/// Content across different branches can be aligned with the `&` symbol. /// Content across different branches can be aligned with the `&` symbol.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// $ f(x, y) := cases( /// $ f(x, y) := cases(
/// 1 "if" (x dot y)/2 <= 0, /// 1 "if" (x dot y)/2 <= 0,
@ -213,10 +205,7 @@ impl LayoutMath for MatElem {
/// 4 "else", /// 4 "else",
/// ) $ /// ) $
/// ``` /// ```
/// #[elem(LayoutMath)]
/// Display: Cases
/// Category: math
#[element(LayoutMath)]
pub struct CasesElem { pub struct CasesElem {
/// The delimiter to use. /// The delimiter to use.
/// ///
@ -236,7 +225,7 @@ impl LayoutMath for CasesElem {
#[tracing::instrument(skip(ctx))] #[tracing::instrument(skip(ctx))]
fn layout_math(&self, ctx: &mut MathContext) -> SourceResult<()> { fn layout_math(&self, ctx: &mut MathContext) -> SourceResult<()> {
let delim = self.delim(ctx.styles()); let delim = self.delim(ctx.styles());
let frame = layout_vec_body(ctx, &self.children(), Align::Left)?; let frame = layout_vec_body(ctx, &self.children(), FixedAlign::Start)?;
layout_delimiters(ctx, frame, Some(delim.open()), None, self.span()) layout_delimiters(ctx, frame, Some(delim.open()), None, self.span())
} }
} }
@ -289,7 +278,7 @@ impl Delimiter {
fn layout_vec_body( fn layout_vec_body(
ctx: &mut MathContext, ctx: &mut MathContext,
column: &[Content], column: &[Content],
align: Align, align: FixedAlign,
) -> SourceResult<Frame> { ) -> SourceResult<Frame> {
let gap = ROW_GAP.scaled(ctx); let gap = ROW_GAP.scaled(ctx);
ctx.style(ctx.style.for_denominator()); ctx.style(ctx.style.for_denominator());
@ -319,7 +308,7 @@ fn layout_mat_body(
// look correct by default at all matrix sizes. // look correct by default at all matrix sizes.
// The line cap is also set to square because it looks more "correct". // The line cap is also set to square because it looks more "correct".
let default_stroke_thickness = DEFAULT_STROKE_THICKNESS.scaled(ctx); let default_stroke_thickness = DEFAULT_STROKE_THICKNESS.scaled(ctx);
let default_stroke = Stroke { let default_stroke = FixedStroke {
thickness: default_stroke_thickness, thickness: default_stroke_thickness,
line_cap: LineCap::Square, line_cap: LineCap::Square,
..Default::default() ..Default::default()
@ -383,7 +372,7 @@ fn layout_mat_body(
let mut y = Abs::zero(); let mut y = Abs::zero();
for (cell, &(ascent, descent)) in col.into_iter().zip(&heights) { for (cell, &(ascent, descent)) in col.into_iter().zip(&heights) {
let cell = cell.into_aligned_frame(ctx, &points, Align::Center); let cell = cell.into_aligned_frame(ctx, &points, FixedAlign::Center);
let pos = Point::new( let pos = Point::new(
if points.is_empty() { x + (rcol - cell.width()) / 2.0 } else { x }, if points.is_empty() { x + (rcol - cell.width()) / 2.0 } else { x },
y + ascent - cell.ascent(), y + ascent - cell.ascent(),
@ -429,7 +418,7 @@ fn layout_mat_body(
Ok(frame) Ok(frame)
} }
fn line_item(length: Abs, vertical: bool, stroke: Stroke, span: Span) -> FrameItem { fn line_item(length: Abs, vertical: bool, stroke: FixedStroke, span: Span) -> FrameItem {
let line_geom = if vertical { let line_geom = if vertical {
Geometry::Line(Point::with_y(length)) Geometry::Line(Point::with_y(length))
} else { } else {
@ -482,14 +471,14 @@ fn layout_delimiters(
/// Parameters specifying how augmentation lines /// Parameters specifying how augmentation lines
/// should be drawn on a matrix. /// should be drawn on a matrix.
#[derive(Default, Clone, Hash)] #[derive(Default, Clone, Hash)]
pub struct Augment<T = Length> { pub struct Augment<T: Numeric = Length> {
pub hline: Offsets, pub hline: Offsets,
pub vline: Offsets, pub vline: Offsets,
pub stroke: Smart<PartialStroke<T>>, pub stroke: Smart<Stroke<T>>,
} }
impl Augment<Abs> { impl Augment<Abs> {
fn stroke_or(&self, fallback: Stroke) -> Stroke { fn stroke_or(&self, fallback: FixedStroke) -> FixedStroke {
match &self.stroke { match &self.stroke {
Smart::Custom(v) => v.clone().unwrap_or(fallback), Smart::Custom(v) => v.clone().unwrap_or(fallback),
_ => fallback, _ => fallback,
@ -543,7 +532,7 @@ cast! {
let vline = dict.take("vline").ok().map(Offsets::from_value) let vline = dict.take("vline").ok().map(Offsets::from_value)
.transpose().unwrap_or_default().unwrap_or_default(); .transpose().unwrap_or_default().unwrap_or_default();
let stroke = dict.take("stroke").ok().map(PartialStroke::from_value) let stroke = dict.take("stroke").ok().map(Stroke::from_value)
.transpose()?.map(Smart::Custom).unwrap_or(Smart::Auto); .transpose()?.map(Smart::Custom).unwrap_or(Smart::Auto);
Augment { hline, vline, stroke } Augment { hline, vline, stroke }

128
crates/typst-library/src/math/mod.rs
View File

@ -7,9 +7,9 @@ mod align;
mod attach; mod attach;
mod cancel; mod cancel;
mod class; mod class;
mod delimited;
mod frac; mod frac;
mod fragment; mod fragment;
mod lr;
mod matrix; mod matrix;
mod op; mod op;
mod root; mod root;
@ -24,8 +24,8 @@ pub use self::align::*;
pub use self::attach::*; pub use self::attach::*;
pub use self::cancel::*; pub use self::cancel::*;
pub use self::class::*; pub use self::class::*;
pub use self::delimited::*;
pub use self::frac::*; pub use self::frac::*;
pub use self::lr::*;
pub use self::matrix::*; pub use self::matrix::*;
pub use self::op::*; pub use self::op::*;
pub use self::root::*; pub use self::root::*;
@ -57,79 +57,64 @@ use crate::text::{
/// Create a module with all math definitions. /// Create a module with all math definitions.
pub fn module() -> Module { pub fn module() -> Module {
let mut math = Scope::deduplicating(); let mut math = Scope::deduplicating();
math.define("equation", EquationElem::func()); math.category("math");
math.define("text", TextElem::func()); math.define_elem::<EquationElem>();
math.define_elem::<TextElem>();
math.define_elem::<LrElem>();
math.define_elem::<AttachElem>();
math.define_elem::<ScriptsElem>();
math.define_elem::<LimitsElem>();
math.define_elem::<AccentElem>();
math.define_elem::<UnderlineElem>();
math.define_elem::<OverlineElem>();
math.define_elem::<UnderbraceElem>();
math.define_elem::<OverbraceElem>();
math.define_elem::<UnderbracketElem>();
math.define_elem::<OverbracketElem>();
math.define_elem::<CancelElem>();
math.define_elem::<FracElem>();
math.define_elem::<BinomElem>();
math.define_elem::<VecElem>();
math.define_elem::<MatElem>();
math.define_elem::<CasesElem>();
math.define_elem::<RootElem>();
math.define_elem::<ClassElem>();
math.define_elem::<OpElem>();
math.define_func::<abs>();
math.define_func::<norm>();
math.define_func::<floor>();
math.define_func::<ceil>();
math.define_func::<round>();
math.define_func::<sqrt>();
math.define_func::<upright>();
math.define_func::<bold>();
math.define_func::<italic>();
math.define_func::<serif>();
math.define_func::<sans>();
math.define_func::<cal>();
math.define_func::<frak>();
math.define_func::<mono>();
math.define_func::<bb>();
math.define_func::<display>();
math.define_func::<inline>();
math.define_func::<script>();
math.define_func::<sscript>();
// Grouping. // Text operators, spacings, and symbols.
math.define("lr", LrElem::func());
math.define("abs", abs_func());
math.define("norm", norm_func());
math.define("floor", floor_func());
math.define("ceil", ceil_func());
math.define("round", round_func());
// Attachments and accents.
math.define("attach", AttachElem::func());
math.define("scripts", ScriptsElem::func());
math.define("limits", LimitsElem::func());
math.define("accent", AccentElem::func());
math.define("underline", UnderlineElem::func());
math.define("overline", OverlineElem::func());
math.define("underbrace", UnderbraceElem::func());
math.define("overbrace", OverbraceElem::func());
math.define("underbracket", UnderbracketElem::func());
math.define("overbracket", OverbracketElem::func());
math.define("cancel", CancelElem::func());
// Fractions and matrix-likes.
math.define("frac", FracElem::func());
math.define("binom", BinomElem::func());
math.define("vec", VecElem::func());
math.define("mat", MatElem::func());
math.define("cases", CasesElem::func());
// Roots.
math.define("sqrt", sqrt_func());
math.define("root", RootElem::func());
// Styles.
math.define("upright", upright_func());
math.define("bold", bold_func());
math.define("italic", italic_func());
math.define("serif", serif_func());
math.define("sans", sans_func());
math.define("cal", cal_func());
math.define("frak", frak_func());
math.define("mono", mono_func());
math.define("bb", bb_func());
math.define("display", display_func());
math.define("inline", inline_func());
math.define("script", script_func());
math.define("sscript", sscript_func());
math.define("class", ClassElem::func());
// Text operators.
math.define("op", OpElem::func());
op::define(&mut math); op::define(&mut math);
// Spacings.
spacing::define(&mut math); spacing::define(&mut math);
// Symbols.
for (name, symbol) in crate::symbols::SYM { for (name, symbol) in crate::symbols::SYM {
math.define(*name, symbol.clone()); math.define(*name, symbol.clone());
} }
Module::new("math").with_scope(math) Module::new("math", math)
} }
/// A mathematical equation. /// A mathematical equation.
/// ///
/// Can be displayed inline with text or as a separate block. /// Can be displayed inline with text or as a separate block.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #set text(font: "New Computer Modern") /// #set text(font: "New Computer Modern")
/// ///
@ -142,16 +127,13 @@ pub fn module() -> Module {
/// $ sum_(k=1)^n k = (n(n+1)) / 2 $ /// $ sum_(k=1)^n k = (n(n+1)) / 2 $
/// ``` /// ```
/// ///
/// ## Syntax { #syntax } /// # Syntax
/// This function also has dedicated syntax: Write mathematical markup within /// This function also has dedicated syntax: Write mathematical markup within
/// dollar signs to create an equation. Starting and ending the equation with at /// dollar signs to create an equation. Starting and ending the equation with at
/// least one space lifts it into a separate block that is centered /// least one space lifts it into a separate block that is centered
/// horizontally. For more details about math syntax, see the /// horizontally. For more details about math syntax, see the
/// [main math page]($category/math). /// [main math page]($category/math).
/// #[elem(
/// Display: Equation
/// Category: math
#[element(
Locatable, Synthesize, Show, Finalize, Layout, LayoutMath, Count, LocalName, Refable, Locatable, Synthesize, Show, Finalize, Layout, LayoutMath, Count, LocalName, Refable,
Outlinable Outlinable
)] )]
@ -160,7 +142,7 @@ pub struct EquationElem {
#[default(false)] #[default(false)]
pub block: bool, pub block: bool,
/// How to [number]($func/numbering) block-level equations. /// How to [number]($numbering) block-level equations.
/// ///
/// ```example /// ```example
/// #set math.equation(numbering: "(1)") /// #set math.equation(numbering: "(1)")
@ -216,9 +198,9 @@ impl Synthesize for EquationElem {
impl Show for EquationElem { impl Show for EquationElem {
#[tracing::instrument(name = "EquationElem::show", skip_all)] #[tracing::instrument(name = "EquationElem::show", skip_all)]
fn show(&self, _: &mut Vt, styles: StyleChain) -> SourceResult<Content> { fn show(&self, _: &mut Vt, styles: StyleChain) -> SourceResult<Content> {
let mut realized = self.clone().pack().guarded(Guard::Base(Self::func())); let mut realized = self.clone().pack().guarded(Guard::Base(Self::elem()));
if self.block(styles) { if self.block(styles) {
realized = realized.aligned(Axes::with_x(Some(Align::Center.into()))) realized = realized.aligned(Align::CENTER);
} }
Ok(realized) Ok(realized)
} }
@ -264,7 +246,7 @@ impl Layout for EquationElem {
if block { if block {
if let Some(numbering) = self.numbering(styles) { if let Some(numbering) = self.numbering(styles) {
let pod = Regions::one(regions.base(), Axes::splat(false)); let pod = Regions::one(regions.base(), Axes::splat(false));
let counter = Counter::of(Self::func()) let counter = Counter::of(Self::elem())
.display(Some(numbering), false) .display(Some(numbering), false)
.layout(vt, styles, pod)? .layout(vt, styles, pod)?
.into_frame(); .into_frame();
@ -277,7 +259,7 @@ impl Layout for EquationElem {
}; };
let height = frame.height().max(counter.height()); let height = frame.height().max(counter.height());
frame.resize(Size::new(width, height), Align::CENTER_HORIZON); frame.resize(Size::new(width, height), Axes::splat(FixedAlign::Center));
let x = if TextElem::dir_in(styles).is_positive() { let x = if TextElem::dir_in(styles).is_positive() {
frame.width() - counter.width() frame.width() - counter.width()
@ -358,7 +340,7 @@ impl Refable for EquationElem {
} }
fn counter(&self) -> Counter { fn counter(&self) -> Counter {
Counter::of(Self::func()) Counter::of(Self::elem())
} }
fn numbering(&self) -> Option<Numbering> { fn numbering(&self) -> Option<Numbering> {

9
crates/typst-library/src/math/op.rs
View File

@ -4,23 +4,20 @@ use super::*;
/// A text operator in an equation. /// A text operator in an equation.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// $ tan x = (sin x)/(cos x) $ /// $ tan x = (sin x)/(cos x) $
/// $ op("custom", /// $ op("custom",
/// limits: #true)_(n->oo) n $ /// limits: #true)_(n->oo) n $
/// ``` /// ```
/// ///
/// ## Predefined Operators { #predefined } /// # Predefined Operators { #predefined }
/// Typst predefines the operators `arccos`, `arcsin`, `arctan`, `arg`, `cos`, /// Typst predefines the operators `arccos`, `arcsin`, `arctan`, `arg`, `cos`,
/// `cosh`, `cot`, `coth`, `csc`, `ctg`, `deg`, `det`, `dim`, `exp`, `gcd`, /// `cosh`, `cot`, `coth`, `csc`, `ctg`, `deg`, `det`, `dim`, `exp`, `gcd`,
/// `hom`, `id`, `im`, `inf`, `ker`, `lg`, `lim`, `liminf`, `limsup`, `ln`, /// `hom`, `id`, `im`, `inf`, `ker`, `lg`, `lim`, `liminf`, `limsup`, `ln`,
/// `log`, `max`, `min`, `mod`, `Pr`, `sec`, `sin`, `sinc`, `sinh`, `sup`, /// `log`, `max`, `min`, `mod`, `Pr`, `sec`, `sin`, `sinc`, `sinh`, `sup`,
/// `tan`, `tanh`, `tg` and `tr`. /// `tan`, `tanh`, `tg` and `tr`.
/// #[elem(title = "Text Operator", LayoutMath)]
/// Display: Text Operator
/// Category: math
#[element(LayoutMath)]
pub struct OpElem { pub struct OpElem {
/// The operator's text. /// The operator's text.
#[required] #[required]

16
crates/typst-library/src/math/root.rs
View File

@ -2,14 +2,10 @@ use super::*;
/// A square root. /// A square root.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// $ sqrt(3 - 2 sqrt(2)) = sqrt(2) - 1 $ /// $ sqrt(3 - 2 sqrt(2)) = sqrt(2) - 1 $
/// ``` /// ```
/// #[func(title = "Square Root")]
/// Display: Square Root
/// Category: math
#[func]
pub fn sqrt( pub fn sqrt(
/// The expression to take the square root of. /// The expression to take the square root of.
radicand: Content, radicand: Content,
@ -19,14 +15,10 @@ pub fn sqrt(
/// A general root. /// A general root.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// $ root(3, x) $ /// $ root(3, x) $
/// ``` /// ```
/// #[elem(LayoutMath)]
/// Display: Root
/// Category: math
#[element(LayoutMath)]
pub struct RootElem { pub struct RootElem {
/// Which root of the radicand to take. /// Which root of the radicand to take.
#[positional] #[positional]
@ -129,10 +121,10 @@ fn layout(
frame.push( frame.push(
line_pos, line_pos,
FrameItem::Shape( FrameItem::Shape(
Geometry::Line(Point::with_x(radicand.width())).stroked(Stroke { Geometry::Line(Point::with_x(radicand.width())).stroked(FixedStroke {
paint: TextElem::fill_in(ctx.styles()), paint: TextElem::fill_in(ctx.styles()),
thickness, thickness,
..Stroke::default() ..FixedStroke::default()
}), }),
span, span,
), ),

23
crates/typst-library/src/math/row.rs
View File

@ -121,7 +121,7 @@ impl MathRow {
pub fn into_frame(self, ctx: &MathContext) -> Frame { pub fn into_frame(self, ctx: &MathContext) -> Frame {
let styles = ctx.styles(); let styles = ctx.styles();
let align = AlignElem::alignment_in(styles).x.resolve(styles); let align = AlignElem::alignment_in(styles).resolve(styles).x;
self.into_aligned_frame(ctx, &[], align) self.into_aligned_frame(ctx, &[], align)
} }
@ -137,9 +137,12 @@ impl MathRow {
self, self,
ctx: &MathContext, ctx: &MathContext,
points: &[Abs], points: &[Abs],
align: Align, align: FixedAlign,
) -> Frame { ) -> Frame {
if self.iter().any(|frag| matches!(frag, MathFragment::Linebreak)) { if !self.iter().any(|frag| matches!(frag, MathFragment::Linebreak)) {
return self.into_line_frame(points, align);
}
let leading = if ctx.style.size >= MathSize::Text { let leading = if ctx.style.size >= MathSize::Text {
ParElem::leading_in(ctx.styles()) ParElem::leading_in(ctx.styles())
} else { } else {
@ -170,20 +173,18 @@ impl MathRow {
size.x.set_max(sub.width()); size.x.set_max(sub.width());
frame.push_frame(pos, sub); frame.push_frame(pos, sub);
} }
frame frame
} else {
self.into_line_frame(points, align)
}
} }
fn into_line_frame(self, points: &[Abs], align: Align) -> Frame { fn into_line_frame(self, points: &[Abs], align: FixedAlign) -> Frame {
let ascent = self.ascent(); let ascent = self.ascent();
let mut frame = Frame::new(Size::new(Abs::zero(), ascent + self.descent())); let mut frame = Frame::new(Size::new(Abs::zero(), ascent + self.descent()));
frame.set_baseline(ascent); frame.set_baseline(ascent);
let mut next_x = { let mut next_x = {
let mut widths = Vec::new(); let mut widths = Vec::new();
if !points.is_empty() && align != Align::Left { if !points.is_empty() && align != FixedAlign::Start {
let mut width = Abs::zero(); let mut width = Abs::zero();
for fragment in self.iter() { for fragment in self.iter() {
if matches!(fragment, MathFragment::Align) { if matches!(fragment, MathFragment::Align) {
@ -201,8 +202,10 @@ impl MathRow {
let mut point_widths = points.iter().copied().zip(widths); let mut point_widths = points.iter().copied().zip(widths);
let mut alternator = LeftRightAlternator::Right; let mut alternator = LeftRightAlternator::Right;
move || match align { move || match align {
Align::Left => prev_points.next(), FixedAlign::Start => prev_points.next(),
Align::Right => point_widths.next().map(|(point, width)| point - width), FixedAlign::End => {
point_widths.next().map(|(point, width)| point - width)
}
_ => point_widths _ => point_widths
.next() .next()
.zip(prev_points.next()) .zip(prev_points.next())

73
crates/typst-library/src/math/style.rs
View File

@ -2,13 +2,9 @@ use super::*;
/// Bold font style in math. /// Bold font style in math.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// $ bold(A) := B^+ $ /// $ bold(A) := B^+ $
/// ``` /// ```
///
/// Display: Bold
/// Category: math
#[func] #[func]
pub fn bold( pub fn bold(
/// The content to style. /// The content to style.
@ -19,13 +15,9 @@ pub fn bold(
/// Upright (non-italic) font style in math. /// Upright (non-italic) font style in math.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// $ upright(A) != A $ /// $ upright(A) != A $
/// ``` /// ```
///
/// Display: Upright
/// Category: math
#[func] #[func]
pub fn upright( pub fn upright(
/// The content to style. /// The content to style.
@ -37,9 +29,6 @@ pub fn upright(
/// Italic font style in math. /// Italic font style in math.
/// ///
/// For roman letters and greek lowercase letters, this is already the default. /// For roman letters and greek lowercase letters, this is already the default.
///
/// Display: Italic
/// Category: math
#[func] #[func]
pub fn italic( pub fn italic(
/// The content to style. /// The content to style.
@ -50,9 +39,6 @@ pub fn italic(
/// Serif (roman) font style in math. /// Serif (roman) font style in math.
/// ///
/// This is already the default. /// This is already the default.
///
/// Display: Serif
/// Category: math
#[func] #[func]
pub fn serif( pub fn serif(
/// The content to style. /// The content to style.
@ -63,14 +49,10 @@ pub fn serif(
/// Sans-serif font style in math. /// Sans-serif font style in math.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// $ sans(A B C) $ /// $ sans(A B C) $
/// ``` /// ```
/// #[func(title = "Sans Serif")]
/// Display: Sans-serif
/// Category: math
#[func]
pub fn sans( pub fn sans(
/// The content to style. /// The content to style.
body: Content, body: Content,
@ -80,14 +62,10 @@ pub fn sans(
/// Calligraphic font style in math. /// Calligraphic font style in math.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// Let $cal(P)$ be the set of ... /// Let $cal(P)$ be the set of ...
/// ``` /// ```
/// #[func(title = "Calligraphic")]
/// Display: Calligraphic
/// Category: math
#[func]
pub fn cal( pub fn cal(
/// The content to style. /// The content to style.
body: Content, body: Content,
@ -97,14 +75,10 @@ pub fn cal(
/// Fraktur font style in math. /// Fraktur font style in math.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// $ frak(P) $ /// $ frak(P) $
/// ``` /// ```
/// #[func(title = "Fraktur")]
/// Display: Fraktur
/// Category: math
#[func]
pub fn frak( pub fn frak(
/// The content to style. /// The content to style.
body: Content, body: Content,
@ -114,14 +88,10 @@ pub fn frak(
/// Monospace font style in math. /// Monospace font style in math.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// $ mono(x + y = z) $ /// $ mono(x + y = z) $
/// ``` /// ```
/// #[func(title = "Monospace")]
/// Display: Monospace
/// Category: math
#[func]
pub fn mono( pub fn mono(
/// The content to style. /// The content to style.
body: Content, body: Content,
@ -134,16 +104,12 @@ pub fn mono(
/// For uppercase latin letters, blackboard bold is additionally available /// For uppercase latin letters, blackboard bold is additionally available
/// through [symbols]($category/symbols/sym) of the form `NN` and `RR`. /// through [symbols]($category/symbols/sym) of the form `NN` and `RR`.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// $ bb(b) $ /// $ bb(b) $
/// $ bb(N) = NN $ /// $ bb(N) = NN $
/// $ f: NN -> RR $ /// $ f: NN -> RR $
/// ``` /// ```
/// #[func(title = "Blackboard Bold")]
/// Display: Blackboard Bold
/// Category: math
#[func]
pub fn bb( pub fn bb(
/// The content to style. /// The content to style.
body: Content, body: Content,
@ -155,14 +121,10 @@ pub fn bb(
/// ///
/// This is the normal size for block equations. /// This is the normal size for block equations.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// $sum_i x_i/2 = display(sum_i x_i/2)$ /// $sum_i x_i/2 = display(sum_i x_i/2)$
/// ``` /// ```
/// #[func(title = "Display Size")]
/// Display: Display Size
/// Category: math
#[func]
pub fn display( pub fn display(
/// The content to size. /// The content to size.
body: Content, body: Content,
@ -182,15 +144,11 @@ pub fn display(
/// ///
/// This is the normal size for inline equations. /// This is the normal size for inline equations.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// $ sum_i x_i/2 /// $ sum_i x_i/2
/// = inline(sum_i x_i/2) $ /// = inline(sum_i x_i/2) $
/// ``` /// ```
/// #[func(title = "Inline Size")]
/// Display: Inline Size
/// Category: math
#[func]
pub fn inline( pub fn inline(
/// The content to size. /// The content to size.
body: Content, body: Content,
@ -210,14 +168,10 @@ pub fn inline(
/// ///
/// This is the smaller size used in powers or sub- or superscripts. /// This is the smaller size used in powers or sub- or superscripts.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// $sum_i x_i/2 = script(sum_i x_i/2)$ /// $sum_i x_i/2 = script(sum_i x_i/2)$
/// ``` /// ```
/// #[func(title = "Script Size")]
/// Display: Script Size
/// Category: math
#[func]
pub fn script( pub fn script(
/// The content to size. /// The content to size.
body: Content, body: Content,
@ -238,14 +192,10 @@ pub fn script(
/// This is the smallest size, used in second-level sub- and superscripts /// This is the smallest size, used in second-level sub- and superscripts
/// (script of the script). /// (script of the script).
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// $sum_i x_i/2 = sscript(sum_i x_i/2)$ /// $sum_i x_i/2 = sscript(sum_i x_i/2)$
/// ``` /// ```
/// #[func(title = "Script-Script Size")]
/// Display: Script-Script Size
/// Category: math
#[func]
pub fn sscript( pub fn sscript(
/// The content to size. /// The content to size.
body: Content, body: Content,
@ -262,10 +212,7 @@ pub fn sscript(
} }
/// A font variant in math. /// A font variant in math.
/// #[elem(LayoutMath)]
/// Display: Bold
/// Category: math
#[element(LayoutMath)]
pub struct MathStyleElem { pub struct MathStyleElem {
/// The content to style. /// The content to style.
#[required] #[required]

44
crates/typst-library/src/math/underover.rs
View File

@ -11,14 +11,10 @@ enum LineKind {
/// A horizontal line under content. /// A horizontal line under content.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// $ underline(1 + 2 + ... + 5) $ /// $ underline(1 + 2 + ... + 5) $
/// ``` /// ```
/// #[elem(LayoutMath)]
/// Display: Underline
/// Category: math
#[element(LayoutMath)]
pub struct UnderlineElem { pub struct UnderlineElem {
/// The content above the line. /// The content above the line.
#[required] #[required]
@ -34,14 +30,10 @@ impl LayoutMath for UnderlineElem {
/// A horizontal line over content. /// A horizontal line over content.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// $ overline(1 + 2 + ... + 5) $ /// $ overline(1 + 2 + ... + 5) $
/// ``` /// ```
/// #[elem(LayoutMath)]
/// Display: Overline
/// Category: math
#[element(LayoutMath)]
pub struct OverlineElem { pub struct OverlineElem {
/// The content below the line. /// The content below the line.
#[required] #[required]
@ -103,10 +95,10 @@ fn layout_underoverline(
frame.push( frame.push(
line_pos, line_pos,
FrameItem::Shape( FrameItem::Shape(
Geometry::Line(Point::with_x(width)).stroked(Stroke { Geometry::Line(Point::with_x(width)).stroked(FixedStroke {
paint: TextElem::fill_in(ctx.styles()), paint: TextElem::fill_in(ctx.styles()),
thickness: bar_height, thickness: bar_height,
..Stroke::default() ..FixedStroke::default()
}), }),
span, span,
), ),
@ -119,14 +111,10 @@ fn layout_underoverline(
/// A horizontal brace under content, with an optional annotation below. /// A horizontal brace under content, with an optional annotation below.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// $ underbrace(1 + 2 + ... + 5, "numbers") $ /// $ underbrace(1 + 2 + ... + 5, "numbers") $
/// ``` /// ```
/// #[elem(LayoutMath)]
/// Display: Underbrace
/// Category: math
#[element(LayoutMath)]
pub struct UnderbraceElem { pub struct UnderbraceElem {
/// The content above the brace. /// The content above the brace.
#[required] #[required]
@ -154,14 +142,10 @@ impl LayoutMath for UnderbraceElem {
/// A horizontal brace over content, with an optional annotation above. /// A horizontal brace over content, with an optional annotation above.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// $ overbrace(1 + 2 + ... + 5, "numbers") $ /// $ overbrace(1 + 2 + ... + 5, "numbers") $
/// ``` /// ```
/// #[elem(LayoutMath)]
/// Display: Overbrace
/// Category: math
#[element(LayoutMath)]
pub struct OverbraceElem { pub struct OverbraceElem {
/// The content below the brace. /// The content below the brace.
#[required] #[required]
@ -189,14 +173,10 @@ impl LayoutMath for OverbraceElem {
/// A horizontal bracket under content, with an optional annotation below. /// A horizontal bracket under content, with an optional annotation below.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// $ underbracket(1 + 2 + ... + 5, "numbers") $ /// $ underbracket(1 + 2 + ... + 5, "numbers") $
/// ``` /// ```
/// #[elem(LayoutMath)]
/// Display: Underbracket
/// Category: math
#[element(LayoutMath)]
pub struct UnderbracketElem { pub struct UnderbracketElem {
/// The content above the bracket. /// The content above the bracket.
#[required] #[required]
@ -224,14 +204,10 @@ impl LayoutMath for UnderbracketElem {
/// A horizontal bracket over content, with an optional annotation above. /// A horizontal bracket over content, with an optional annotation above.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// $ overbracket(1 + 2 + ... + 5, "numbers") $ /// $ overbracket(1 + 2 + ... + 5, "numbers") $
/// ``` /// ```
/// #[elem(LayoutMath)]
/// Display: Overbracket
/// Category: math
#[element(LayoutMath)]
pub struct OverbracketElem { pub struct OverbracketElem {
/// The content below the bracket. /// The content below the bracket.
#[required] #[required]
@ -294,7 +270,7 @@ fn layout_underoverspreader(
baseline = rows.len() - 1; baseline = rows.len() - 1;
} }
let frame = stack(ctx, rows, Align::Center, gap, baseline); let frame = stack(ctx, rows, FixedAlign::Center, gap, baseline);
ctx.push(FrameFragment::new(ctx, frame).with_class(body_class)); ctx.push(FrameFragment::new(ctx, frame).with_class(body_class));
Ok(()) Ok(())
@ -307,7 +283,7 @@ fn layout_underoverspreader(
pub(super) fn stack( pub(super) fn stack(
ctx: &MathContext, ctx: &MathContext,
rows: Vec<MathRow>, rows: Vec<MathRow>,
align: Align, align: FixedAlign,
gap: Abs, gap: Abs,
baseline: usize, baseline: usize,
) -> Frame { ) -> Frame {

37
crates/typst-library/src/meta/bibliography.rs
View File

@ -30,8 +30,8 @@ use crate::text::TextElem;
/// ///
/// As soon as you add a bibliography somewhere in your document, you can start /// As soon as you add a bibliography somewhere in your document, you can start
/// citing things with reference syntax (`[@key]`) or explicit calls to the /// citing things with reference syntax (`[@key]`) or explicit calls to the
/// [citation]($func/cite) function (`[#cite("key")]`). The bibliography will /// [citation]($cite) function (`[#cite("key")]`). The bibliography will only
/// only show entries for works that were referenced in the document. /// show entries for works that were referenced in the document.
/// ///
/// # Example /// # Example
/// ```example /// ```example
@ -43,10 +43,7 @@ use crate::text::TextElem;
/// ///
/// #bibliography("works.bib") /// #bibliography("works.bib")
/// ``` /// ```
/// #[elem(Locatable, Synthesize, Show, Finalize, LocalName)]
/// Display: Bibliography
/// Category: meta
#[element(Locatable, Synthesize, Show, Finalize, LocalName)]
pub struct BibliographyElem { pub struct BibliographyElem {
/// Path to a Hayagriva `.yml` or BibLaTeX `.bib` file. /// Path to a Hayagriva `.yml` or BibLaTeX `.bib` file.
#[required] #[required]
@ -78,8 +75,8 @@ pub struct BibliographyElem {
/// The title of the bibliography. /// The title of the bibliography.
/// ///
/// - When set to `{auto}`, an appropriate title for the [text /// - When set to `{auto}`, an appropriate title for the
/// language]($func/text.lang) will be used. This is the default. /// [text language]($text.lang) will be used. This is the default.
/// - When set to `{none}`, the bibliography will not have a title. /// - When set to `{none}`, the bibliography will not have a title.
/// - A custom title can be set by passing content. /// - A custom title can be set by passing content.
/// ///
@ -109,7 +106,7 @@ cast! {
impl BibliographyElem { impl BibliographyElem {
/// Find the document's bibliography. /// Find the document's bibliography.
pub fn find(introspector: Tracked<Introspector>) -> StrResult<Self> { pub fn find(introspector: Tracked<Introspector>) -> StrResult<Self> {
let mut iter = introspector.query(&Self::func().select()).into_iter(); let mut iter = introspector.query(&Self::elem().select()).into_iter();
let Some(elem) = iter.next() else { let Some(elem) = iter.next() else {
bail!("the document does not contain a bibliography"); bail!("the document does not contain a bibliography");
}; };
@ -124,7 +121,7 @@ impl BibliographyElem {
/// Whether the bibliography contains the given key. /// Whether the bibliography contains the given key.
pub fn has(vt: &Vt, key: &str) -> bool { pub fn has(vt: &Vt, key: &str) -> bool {
vt.introspector vt.introspector
.query(&Self::func().select()) .query(&Self::elem().select())
.into_iter() .into_iter()
.flat_map(|elem| { .flat_map(|elem| {
let elem = elem.to::<Self>().unwrap(); let elem = elem.to::<Self>().unwrap();
@ -289,8 +286,8 @@ impl BibliographyStyle {
/// Cite a work from the bibliography. /// Cite a work from the bibliography.
/// ///
/// Before you starting citing, you need to add a /// Before you starting citing, you need to add a [bibliography]($bibliography)
/// [bibliography]($func/bibliography) somewhere in your document. /// somewhere in your document.
/// ///
/// # Example /// # Example
/// ```example /// ```example
@ -304,13 +301,10 @@ impl BibliographyStyle {
/// ``` /// ```
/// ///
/// # Syntax /// # Syntax
/// This function indirectly has dedicated syntax. [References]($func/ref) /// This function indirectly has dedicated syntax. [References]($ref) can be
/// can be used to cite works from the bibliography. The label then /// used to cite works from the bibliography. The label then corresponds to the
/// corresponds to the citation key. /// citation key.
/// #[elem(Locatable, Synthesize, Show)]
/// Display: Citation
/// Category: meta
#[element(Locatable, Synthesize, Show)]
pub struct CiteElem { pub struct CiteElem {
/// The citation keys that identify the elements that shall be cited in /// The citation keys that identify the elements that shall be cited in
/// the bibliography. /// the bibliography.
@ -329,7 +323,6 @@ pub struct CiteElem {
/// ///
/// #bibliography("works.bib") /// #bibliography("works.bib")
/// ``` /// ```
#[positional]
pub supplement: Option<Content>, pub supplement: Option<Content>,
/// Whether the citation should include brackets. /// Whether the citation should include brackets.
@ -435,8 +428,8 @@ impl Works {
let citations = vt let citations = vt
.introspector .introspector
.query(&Selector::Or(eco_vec![ .query(&Selector::Or(eco_vec![
RefElem::func().select(), RefElem::elem().select(),
CiteElem::func().select(), CiteElem::elem().select(),
])) ]))
.into_iter() .into_iter()
.map(|elem| match elem.to::<RefElem>() { .map(|elem| match elem.to::<RefElem>() {

83
crates/typst-library/src/meta/context.rs
View File

@ -2,9 +2,9 @@ use crate::prelude::*;
/// Provides access to the location of content. /// Provides access to the location of content.
/// ///
/// This is useful in combination with [queries]($func/query), /// This is useful in combination with [queries]($query), [counters]($counter),
/// [counters]($func/counter), [state]($func/state), and [links]($func/link). /// [state]($state), and [links]($link). See their documentation for more
/// See their documentation for more details. /// details.
/// ///
/// ```example /// ```example
/// #locate(loc => [ /// #locate(loc => [
@ -12,44 +12,10 @@ use crate::prelude::*;
/// #loc.position()! /// #loc.position()!
/// ]) /// ])
/// ``` /// ```
///
/// ## Methods
/// ### page()
/// Returns the page number for this location.
///
/// Note that this does not return the value of the [page counter]($func/counter)
/// at this location, but the true page number (starting from one).
///
/// If you want to know the value of the page counter, use
/// `{counter(page).at(loc)}` instead.
///
/// - returns: integer
///
/// ### position()
/// Returns a dictionary with the page number and the x, y position for this
/// location. The page number starts at one and the coordinates are measured
/// from the top-left of the page.
///
/// If you only need the page number, use `page()` instead as it allows Typst
/// to skip unnecessary work.
///
/// - returns: dictionary
///
/// ### page-numbering()
/// Returns the page numbering pattern of the page at this location. This can be
/// used when displaying the page counter in order to obtain the local numbering.
/// This is useful if you are building custom indices or outlines.
///
/// If the page numbering is set to `none` at that location, this function returns `none`.
///
/// - returns: string or function or none
///
/// Display: Locate
/// Category: meta
#[func] #[func]
pub fn locate( pub fn locate(
/// A function that receives a `location`. Its return value is displayed /// A function that receives a [`location`]($location). Its return value is
/// in the document. /// displayed in the document.
/// ///
/// This function is called once for each time the content returned by /// This function is called once for each time the content returned by
/// `locate` appears in the document. That makes it possible to generate /// `locate` appears in the document. That makes it possible to generate
@ -60,10 +26,7 @@ pub fn locate(
} }
/// Executes a `locate` call. /// Executes a `locate` call.
/// #[elem(Locatable, Show)]
/// Display: Locate
/// Category: special
#[element(Locatable, Show)]
struct LocateElem { struct LocateElem {
/// The function to call with the location. /// The function to call with the location.
#[required] #[required]
@ -83,9 +46,9 @@ impl Show for LocateElem {
/// Provides access to active styles. /// Provides access to active styles.
/// ///
/// The styles are currently opaque and only useful in combination with the /// The styles are currently opaque and only useful in combination with the
/// [`measure`]($func/measure) function. See its documentation for more details. /// [`measure`]($measure) function. See its documentation for more details. In
/// In the future, the provided styles might also be directly accessed to look /// the future, the provided styles might also be directly accessed to look up
/// up styles defined by [set rules]($styling/#set-rules). /// styles defined by [set rules]($styling/#set-rules).
/// ///
/// ```example /// ```example
/// #let thing(body) = style(styles => { /// #let thing(body) = style(styles => {
@ -96,9 +59,6 @@ impl Show for LocateElem {
/// #thing[Hey] \ /// #thing[Hey] \
/// #thing[Welcome] /// #thing[Welcome]
/// ``` /// ```
///
/// Display: Style
/// Category: meta
#[func] #[func]
pub fn style( pub fn style(
/// A function to call with the styles. Its return value is displayed /// A function to call with the styles. Its return value is displayed
@ -113,10 +73,7 @@ pub fn style(
} }
/// Executes a style access. /// Executes a style access.
/// #[elem(Show)]
/// Display: Style
/// Category: special
#[element(Show)]
struct StyleElem { struct StyleElem {
/// The function to call with the styles. /// The function to call with the styles.
#[required] #[required]
@ -134,10 +91,8 @@ impl Show for StyleElem {
/// (width and height). /// (width and height).
/// ///
/// The given function must accept a single parameter, `size`, which is a /// The given function must accept a single parameter, `size`, which is a
/// dictionary with keys `width` and `height`, both of type /// dictionary with keys `width` and `height`, both of type [`length`]($length).
/// [`length`]($type/length).
/// ///
/// ```example /// ```example
/// #let text = lorem(30) /// #let text = lorem(30)
/// #layout(size => style(styles => [ /// #layout(size => style(styles => [
@ -155,9 +110,9 @@ impl Show for StyleElem {
/// and a height of `{400pt}`, then the specified function will be given the /// and a height of `{400pt}`, then the specified function will be given the
/// parameter `{(width: 800pt, height: 400pt)}`. If it placed directly into the /// parameter `{(width: 800pt, height: 400pt)}`. If it placed directly into the
/// page it receives the page's dimensions minus its margins. This is mostly /// page it receives the page's dimensions minus its margins. This is mostly
/// useful in combination with [measurement]($func/measure). /// useful in combination with [measurement]($measure).
/// ///
/// You can also use this function to resolve [`ratio`]($type/ratio) to fixed /// You can also use this function to resolve [`ratio`]($ratio) to fixed
/// lengths. This might come in handy if you're building your own layout /// lengths. This might come in handy if you're building your own layout
/// abstractions. /// abstractions.
/// ///
@ -170,16 +125,13 @@ impl Show for StyleElem {
/// ///
/// Note that this function will provide an infinite width or height if one of /// Note that this function will provide an infinite width or height if one of
/// the page width or height is `auto`, respectively. /// the page width or height is `auto`, respectively.
///
/// Display: Layout
/// Category: meta
#[func] #[func]
pub fn layout( pub fn layout(
/// A function to call with the outer container's size. Its return value is /// A function to call with the outer container's size. Its return value is
/// displayed in the document. /// displayed in the document.
/// ///
/// The container's size is given as a [dictionary]($type/dictionary) with /// The container's size is given as a [dictionary]($dictionary) with the
/// the keys `width` and `height`. /// keys `width` and `height`.
/// ///
/// This function is called once for each time the content returned by /// This function is called once for each time the content returned by
/// `layout` appears in the document. That makes it possible to generate /// `layout` appears in the document. That makes it possible to generate
@ -190,10 +142,7 @@ pub fn layout(
} }
/// Executes a `layout` call. /// Executes a `layout` call.
/// #[elem(Layout)]
/// Display: Layout
/// Category: special
#[element(Layout)]
struct LayoutElem { struct LayoutElem {
/// The function to call with the outer container's (or page's) size. /// The function to call with the outer container's (or page's) size.
#[required] #[required]

373
crates/typst-library/src/meta/counter.rs
View File

@ -17,15 +17,14 @@ use crate::prelude::*;
/// headings, figures, and more. Moreover, you can define custom counters for /// headings, figures, and more. Moreover, you can define custom counters for
/// other things you want to count. /// other things you want to count.
/// ///
/// ## Displaying a counter { #displaying } /// # Displaying a counter { #displaying }
/// To display the current value of the heading counter, you call the `counter` /// To display the current value of the heading counter, you call the `counter`
/// function with the `key` set to `heading` and then call the `display` method /// function with the `key` set to `heading` and then call the `display` method
/// on the counter. To see any output, you also have to enable heading /// on the counter. To see any output, you also have to enable heading
/// [numbering]($func/heading.numbering). /// [numbering]($heading.numbering).
/// ///
/// The `display` method optionally takes an argument telling it how to format /// The `display` method optionally takes an argument telling it how to format
/// the counter. This can be a [numbering pattern or a /// the counter. This can be a [numbering pattern or a function]($numbering).
/// function]($func/numbering).
/// ///
/// ```example /// ```example
/// #set heading(numbering: "1.") /// #set heading(numbering: "1.")
@ -41,7 +40,7 @@ use crate::prelude::*;
/// #counter(heading).display("I") /// #counter(heading).display("I")
/// ``` /// ```
/// ///
/// ## Modifying a counter { #modifying } /// # Modifying a counter { #modifying }
/// To modify a counter, you can use the `step` and `update` methods: /// To modify a counter, you can use the `step` and `update` methods:
/// ///
/// - The `step` method increases the value of the counter by one. Because /// - The `step` method increases the value of the counter by one. Because
@ -76,7 +75,6 @@ use crate::prelude::*;
/// Still at #counter(heading).display(). /// Still at #counter(heading).display().
/// ``` /// ```
/// ///
/// ## Custom counters { #custom-counters }
/// To define your own counter, call the `counter` function with a string as a /// To define your own counter, call the `counter` function with a string as a
/// key. This key identifies the counter globally. /// key. This key identifies the counter globally.
/// ///
@ -89,7 +87,7 @@ use crate::prelude::*;
/// #mine.display() \ /// #mine.display() \
/// ``` /// ```
/// ///
/// ## How to step { #how-to-step } /// # How to step
/// When you define and use a custom counter, in general, you should first step /// When you define and use a custom counter, in general, you should first step
/// the counter and then display it. This way, the stepping behaviour of a /// the counter and then display it. This way, the stepping behaviour of a
/// counter can depend on the element it is stepped for. If you were writing a /// counter can depend on the element it is stepped for. If you were writing a
@ -118,7 +116,7 @@ use crate::prelude::*;
/// they always start at zero. This way, they are at one for the first display /// they always start at zero. This way, they are at one for the first display
/// (which happens after the first step). /// (which happens after the first step).
/// ///
/// ## Page counter { #page-counter } /// # Page counter
/// The page counter is special. It is automatically stepped at each pagebreak. /// The page counter is special. It is automatically stepped at each pagebreak.
/// But like other counters, you can also step it manually. For example, you /// But like other counters, you can also step it manually. For example, you
/// could have Roman page numbers for your preface, then switch to Arabic page /// could have Roman page numbers for your preface, then switch to Arabic page
@ -145,7 +143,7 @@ use crate::prelude::*;
/// Arabic numbers. /// Arabic numbers.
/// ``` /// ```
/// ///
/// ## Time travel { #time-travel } /// # Time travel
/// Counters can travel through time! You can find out the final value of the /// Counters can travel through time! You can find out the final value of the
/// counter before it is reached and even determine what the value was at any /// counter before it is reached and even determine what the value was at any
/// particular location in the document. /// particular location in the document.
@ -177,16 +175,16 @@ use crate::prelude::*;
/// ///
/// Let's dissect what happens in the example above: /// Let's dissect what happens in the example above:
/// ///
/// - We call [`locate`]($func/locate) to get access to the current location in /// - We call [`locate`]($locate) to get access to the current location in the
/// the document. We then pass this location to our counter's `at` method to /// document. We then pass this location to our counter's `at` method to get
/// get its value at the current location. The `at` method always returns an /// its value at the current location. The `at` method always returns an array
/// array because counters can have multiple levels. As the counter starts at /// because counters can have multiple levels. As the counter starts at zero,
/// zero, the first value is thus `{(0,)}`. /// the first value is thus `{(0,)}`.
/// ///
/// - We now [`query`]($func/query) the document for all elements with the /// - We now [`query`]($query) the document for all elements with the
/// `{<intro>}` label. The result is an array from which we extract the first /// `{<intro>}` label. The result is an array from which we extract the first
/// (and only) element's [location]($type/content.location). We then look up /// (and only) element's [location]($content.location). We then look up the
/// the value of the counter at that location. The first update to the counter /// value of the counter at that location. The first update to the counter
/// sets it to `{0 + 3 = 3}`. At the introduction heading, the value is thus /// sets it to `{0 + 3 = 3}`. At the introduction heading, the value is thus
/// `{(3,)}`. /// `{(3,)}`.
/// ///
@ -196,180 +194,31 @@ use crate::prelude::*;
/// which one doesn't matter. After the heading follow two calls to `step()`, /// which one doesn't matter. After the heading follow two calls to `step()`,
/// so the final value is `{(5,)}`. /// so the final value is `{(5,)}`.
/// ///
/// ## Other kinds of state { #other-state } /// # Other kinds of state { #other-state }
/// The `counter` function is closely related to [state]($func/state) function. /// The `counter` type is closely related to [state]($state) type. Read its
/// Read its documentation for more details on state management in Typst and /// documentation for more details on state management in Typst and why it
/// why it doesn't just use normal variables for counters. /// doesn't just use normal variables for counters.
/// #[ty(scope)]
/// ## Methods
/// ### display()
/// Displays the value of the counter.
///
/// - numbering: string or function (positional)
/// A [numbering pattern or a function]($func/numbering), which specifies how
/// to display the counter. If given a function, that function receives each
/// number of the counter as a separate argument. If the amount of numbers
/// varies, e.g. for the heading argument, you can use an
/// [argument sink]($type/arguments).
///
/// If this is omitted, displays the counter with the numbering style for the
/// counted element or with the pattern `{"1.1"}` if no such style exists.
///
/// - both: boolean (named)
/// If enabled, displays the current and final top-level count together. Both
/// can be styled through a single numbering pattern. This is used by the page
/// numbering property to display the current and total number of pages when a
/// pattern like `{"1 / 1"}` is given.
///
/// - returns: content
///
/// ### step()
/// Increases the value of the counter by one.
///
/// The update will be in effect at the position where the returned content is
/// inserted into the document. If you don't put the output into the document,
/// nothing happens! This would be the case, for example, if you write
/// `{let _ = counter(page).step()}`. Counter updates are always applied in
/// layout order and in that case, Typst wouldn't know when to step the counter.
///
/// - level: integer (named)
/// The depth at which to step the counter. Defaults to `{1}`.
///
/// - returns: content
///
/// ### update()
/// Updates the value of the counter.
///
/// Just like with `step`, the update only occurs if you put the resulting
/// content into the document.
///
/// - value: integer or array or function (positional, required)
/// If given an integer or array of integers, sets the counter to that value.
/// If given a function, that function receives the previous counter value
/// (with each number as a separate argument) and has to return the new
/// value (integer or array).
///
/// - returns: content
///
/// ### at()
/// Gets the value of the counter at the given location. Always returns an
/// array of integers, even if the counter has just one number.
///
/// - location: location (positional, required)
/// The location at which the counter value should be retrieved. A suitable
/// location can be retrieved from [`locate`]($func/locate) or
/// [`query`]($func/query).
///
/// - returns: array
///
/// ### final()
/// Gets the value of the counter at the end of the document. Always returns an
/// array of integers, even if the counter has just one number.
///
/// - location: location (positional, required)
/// Can be an arbitrary location, as its value is irrelevant for the method's
/// return value. Why is it required then? Typst has to evaluate parts of your
/// code multiple times to determine all counter values. By only allowing this
/// method within [`locate`]($func/locate) calls, the amount of code that can
/// depend on the method's result is reduced. If you could call `final`
/// directly at the top level of a module, the evaluation of the whole module
/// and its exports could depend on the counter's value.
///
/// - returns: array
///
/// Display: Counter
/// Category: meta
#[func]
pub fn counter(
/// The key that identifies this counter.
///
/// - If it is a string, creates a custom counter that is only affected by
/// manual updates,
/// - If this is a `{<label>}`, counts through all elements with that label,
/// - If this is an element function or selector, counts through its elements,
/// - If this is the [`page`]($func/page) function, counts through pages.
key: CounterKey,
) -> Counter {
Counter::new(key)
}
/// Counts through pages, elements, and more.
#[derive(Clone, PartialEq, Hash)] #[derive(Clone, PartialEq, Hash)]
pub struct Counter(CounterKey); pub struct Counter(CounterKey);
impl Counter { impl Counter {
/// Create a new counter from a key. /// Create a new counter identified by a key.
pub fn new(key: CounterKey) -> Self { pub fn new(key: CounterKey) -> Counter {
Self(key) Self(key)
} }
/// The counter for the given element. /// The counter for the given element.
pub fn of(func: ElemFunc) -> Self { pub fn of(func: Element) -> Self {
Self::new(CounterKey::Selector(Selector::Elem(func, None))) Self::construct(CounterKey::Selector(Selector::Elem(func, None)))
} }
/// Call a method on counter. /// Gets the current and final value of the state combined in one state.
#[tracing::instrument(skip(vm))]
pub fn call_method(
self,
vm: &mut Vm,
method: &str,
mut args: Args,
span: Span,
) -> SourceResult<Value> {
let value = match method {
"display" => self
.display(args.eat()?, args.named("both")?.unwrap_or(false))
.into_value(),
"step" => self
.update(CounterUpdate::Step(
args.named("level")?.unwrap_or(NonZeroUsize::ONE),
))
.into_value(),
"update" => self.update(args.expect("value or function")?).into_value(),
"at" => self.at(&mut vm.vt, args.expect("location")?)?.into_value(),
"final" => self.final_(&mut vm.vt, args.expect("location")?)?.into_value(),
_ => bail!(span, "type counter has no method `{}`", method),
};
args.finish()?;
Ok(value)
}
/// Display the current value of the counter.
pub fn display(self, numbering: Option<Numbering>, both: bool) -> Content {
DisplayElem::new(self, numbering, both).pack()
}
/// Get the value of the state at the given location.
pub fn at(&self, vt: &mut Vt, location: Location) -> SourceResult<CounterState> {
let sequence = self.sequence(vt)?;
let offset = vt.introspector.query(&self.selector().before(location, true)).len();
let (mut state, page) = sequence[offset].clone();
if self.is_page() {
let delta = vt.introspector.page(location).get().saturating_sub(page.get());
state.step(NonZeroUsize::ONE, delta);
}
Ok(state)
}
/// Get the value of the state at the final location.
pub fn final_(&self, vt: &mut Vt, _: Location) -> SourceResult<CounterState> {
let sequence = self.sequence(vt)?;
let (mut state, page) = sequence.last().unwrap().clone();
if self.is_page() {
let delta = vt.introspector.pages().get().saturating_sub(page.get());
state.step(NonZeroUsize::ONE, delta);
}
Ok(state)
}
/// Get the current and final value of the state combined in one state.
pub fn both(&self, vt: &mut Vt, location: Location) -> SourceResult<CounterState> { pub fn both(&self, vt: &mut Vt, location: Location) -> SourceResult<CounterState> {
let sequence = self.sequence(vt)?; let sequence = self.sequence(vt)?;
let offset = vt let offset = vt
.introspector .introspector
.query(&Selector::before(self.selector(), location, true)) .query(&self.selector().before(location.into(), true))
.len(); .len();
let (mut at_state, at_page) = sequence[offset].clone(); let (mut at_state, at_page) = sequence[offset].clone();
let (mut final_state, final_page) = sequence.last().unwrap().clone(); let (mut final_state, final_page) = sequence.last().unwrap().clone();
@ -384,12 +233,7 @@ impl Counter {
Ok(CounterState(smallvec![at_state.first(), final_state.first()])) Ok(CounterState(smallvec![at_state.first(), final_state.first()]))
} }
/// Produce content that performs a state update. /// Produces the whole sequence of counter states.
pub fn update(self, update: CounterUpdate) -> Content {
UpdateElem::new(self.0, update).pack()
}
/// Produce the whole sequence of counter states.
/// ///
/// This has to happen just once for all counters, cutting down the number /// This has to happen just once for all counters, cutting down the number
/// of counter updates from quadratic to linear. /// of counter updates from quadratic to linear.
@ -462,7 +306,7 @@ impl Counter {
/// The selector relevant for this counter's updates. /// The selector relevant for this counter's updates.
fn selector(&self) -> Selector { fn selector(&self) -> Selector {
let mut selector = let mut selector =
Selector::Elem(UpdateElem::func(), Some(dict! { "key" => self.0.clone() })); Selector::Elem(UpdateElem::elem(), Some(dict! { "key" => self.0.clone() }));
if let CounterKey::Selector(key) = &self.0 { if let CounterKey::Selector(key) = &self.0 {
selector = Selector::Or(eco_vec![selector, key.clone()]); selector = Selector::Or(eco_vec![selector, key.clone()]);
@ -477,6 +321,140 @@ impl Counter {
} }
} }
#[scope]
impl Counter {
/// Create a new counter identified by a key.
#[func(constructor)]
pub fn construct(
/// The key that identifies this counter.
///
/// - If it is a string, creates a custom counter that is only affected
/// by manual updates,
/// - If this is a `{<label>}`, counts through all elements with that
/// label,
/// - If this is an element function or selector, counts through its
/// elements,
/// - If this is the [`page`]($page) function, counts through pages.
key: CounterKey,
) -> Counter {
Self(key)
}
/// Displays the current value of the counter.
#[func]
pub fn display(
self,
/// A [numbering pattern or a function]($numbering), which specifies how
/// to display the counter. If given a function, that function receives
/// each number of the counter as a separate argument. If the amount of
/// numbers varies, e.g. for the heading argument, you can use an
/// [argument sink]($arguments).
///
/// If this is omitted, displays the counter with the numbering style
/// for the counted element or with the pattern `{"1.1"}` if no such
/// style exists.
#[default]
numbering: Option<Numbering>,
/// If enabled, displays the current and final top-level count together.
/// Both can be styled through a single numbering pattern. This is used
/// by the page numbering property to display the current and total
/// number of pages when a pattern like `{"1 / 1"}` is given.
#[named]
#[default(false)]
both: bool,
) -> Content {
DisplayElem::new(self, numbering, both).pack()
}
/// Increases the value of the counter by one.
///
/// The update will be in effect at the position where the returned content
/// is inserted into the document. If you don't put the output into the
/// document, nothing happens! This would be the case, for example, if you
/// write `{let _ = counter(page).step()}`. Counter updates are always
/// applied in layout order and in that case, Typst wouldn't know when to
/// step the counter.
#[func]
pub fn step(
self,
/// The depth at which to step the counter. Defaults to `{1}`.
#[named]
#[default(NonZeroUsize::ONE)]
level: NonZeroUsize,
) -> Content {
self.update(CounterUpdate::Step(level))
}
/// Updates the value of the counter.
///
/// Just like with `step`, the update only occurs if you put the resulting
/// content into the document.
#[func]
pub fn update(
self,
/// If given an integer or array of integers, sets the counter to that
/// value. If given a function, that function receives the previous
/// counter value (with each number as a separate argument) and has to
/// return the new value (integer or array).
update: CounterUpdate,
) -> Content {
UpdateElem::new(self.0, update).pack()
}
/// Gets the value of the counter at the given location. Always returns an
/// array of integers, even if the counter has just one number.
#[func]
pub fn at(
&self,
/// The virtual typesetter.
vt: &mut Vt,
/// The location at which the counter value should be retrieved. A
/// suitable location can be retrieved from [`locate`]($locate) or
/// [`query`]($query).
location: Location,
) -> SourceResult<CounterState> {
let sequence = self.sequence(vt)?;
let offset = vt
.introspector
.query(&self.selector().before(location.into(), true))
.len();
let (mut state, page) = sequence[offset].clone();
if self.is_page() {
let delta = vt.introspector.page(location).get().saturating_sub(page.get());
state.step(NonZeroUsize::ONE, delta);
}
Ok(state)
}
/// Gets the value of the counter at the end of the document. Always returns
/// an array of integers, even if the counter has just one number.
#[func]
pub fn final_(
&self,
/// The virtual typesetter.
vt: &mut Vt,
/// Can be an arbitrary location, as its value is irrelevant for the
/// method's return value. Why is it required then? Typst has to
/// evaluate parts of your code multiple times to determine all counter
/// values. By only allowing this method within [`locate`]($locate)
/// calls, the amount of code that can depend on the method's result is
/// reduced. If you could call `final` directly at the top level of a
/// module, the evaluation of the whole module and its exports could
/// depend on the counter's value.
location: Location,
) -> SourceResult<CounterState> {
let _ = location;
let sequence = self.sequence(vt)?;
let (mut state, page) = sequence.last().unwrap().clone();
if self.is_page() {
let delta = vt.introspector.pages().get().saturating_sub(page.get());
state.step(NonZeroUsize::ONE, delta);
}
Ok(state)
}
}
impl Debug for Counter { impl Debug for Counter {
fn fmt(&self, f: &mut Formatter) -> fmt::Result { fn fmt(&self, f: &mut Formatter) -> fmt::Result {
f.write_str("counter(")?; f.write_str("counter(")?;
@ -486,7 +464,7 @@ impl Debug for Counter {
} }
cast! { cast! {
type Counter: "counter", type Counter,
} }
/// Identifies a counter. /// Identifies a counter.
@ -504,14 +482,14 @@ pub enum CounterKey {
cast! { cast! {
CounterKey, CounterKey,
self => match self { self => match self {
Self::Page => PageElem::func().into_value(), Self::Page => PageElem::elem().into_value(),
Self::Selector(v) => v.into_value(), Self::Selector(v) => v.into_value(),
Self::Str(v) => v.into_value(), Self::Str(v) => v.into_value(),
}, },
v: Str => Self::Str(v), v: Str => Self::Str(v),
v: Label => Self::Selector(Selector::Label(v)), v: Label => Self::Selector(Selector::Label(v)),
v: ElemFunc => { v: Element => {
if v == PageElem::func() { if v == PageElem::elem() {
Self::Page Self::Page
} else { } else {
Self::Selector(LocatableSelector::from_value(v.into_value())?.0) Self::Selector(LocatableSelector::from_value(v.into_value())?.0)
@ -531,6 +509,7 @@ impl Debug for CounterKey {
} }
/// An update to perform on a counter. /// An update to perform on a counter.
#[ty]
#[derive(Clone, PartialEq, Hash)] #[derive(Clone, PartialEq, Hash)]
pub enum CounterUpdate { pub enum CounterUpdate {
/// Set the counter to the specified state. /// Set the counter to the specified state.
@ -548,7 +527,7 @@ impl Debug for CounterUpdate {
} }
cast! { cast! {
type CounterUpdate: "counter update", type CounterUpdate,
v: CounterState => Self::Set(v), v: CounterState => Self::Set(v),
v: Func => Self::Func(v), v: Func => Self::Func(v),
} }
@ -612,10 +591,7 @@ cast! {
} }
/// Executes a display of a state. /// Executes a display of a state.
/// #[elem(Locatable, Show)]
/// Display: State
/// Category: special
#[element(Locatable, Show)]
struct DisplayElem { struct DisplayElem {
/// The counter. /// The counter.
#[required] #[required]
@ -643,11 +619,11 @@ impl Show for DisplayElem {
return None; return None;
}; };
if func == HeadingElem::func() { if func == HeadingElem::elem() {
HeadingElem::numbering_in(styles) HeadingElem::numbering_in(styles)
} else if func == FigureElem::func() { } else if func == FigureElem::elem() {
FigureElem::numbering_in(styles) FigureElem::numbering_in(styles)
} else if func == EquationElem::func() { } else if func == EquationElem::elem() {
EquationElem::numbering_in(styles) EquationElem::numbering_in(styles)
} else { } else {
None None
@ -667,10 +643,7 @@ impl Show for DisplayElem {
} }
/// Executes a display of a state. /// Executes a display of a state.
/// #[elem(Locatable, Show)]
/// Display: State
/// Category: special
#[element(Locatable, Show)]
struct UpdateElem { struct UpdateElem {
/// The key that identifies the counter. /// The key that identifies the counter.
#[required] #[required]

5
crates/typst-library/src/meta/document.rs
View File

@ -17,10 +17,7 @@ use crate::prelude::*;
/// ///
/// Note that metadata set with this function is not rendered within the /// Note that metadata set with this function is not rendered within the
/// document. Instead, it is embedded in the compiled PDF file. /// document. Instead, it is embedded in the compiled PDF file.
/// #[elem(Construct, LayoutRoot)]
/// Display: Document
/// Category: meta
#[element(Construct, LayoutRoot)]
pub struct DocumentElem { pub struct DocumentElem {
/// The document's title. This is often rendered as the title of the /// The document's title. This is often rendered as the title of the
/// PDF viewer window. /// PDF viewer window.

82
crates/typst-library/src/meta/figure.rs
View File

@ -15,7 +15,7 @@ use crate::visualize::ImageElem;
/// For example, figures containing images will be numbered separately from /// For example, figures containing images will be numbered separately from
/// figures containing tables. /// figures containing tables.
/// ///
/// ## Examples { #examples } /// # Examples
/// The example below shows a basic figure with an image: /// The example below shows a basic figure with an image:
/// ```example /// ```example
/// @glacier shows a glacier. Glaciers /// @glacier shows a glacier. Glaciers
@ -27,9 +27,8 @@ use crate::visualize::ImageElem;
/// ) <glacier> /// ) <glacier>
/// ``` /// ```
/// ///
/// You can also insert [tables]($func/table) into figures to give them a /// You can also insert [tables]($table) into figures to give them a caption.
/// caption. The figure will detect this and automatically use a separate /// The figure will detect this and automatically use a separate counter.
/// counter.
/// ///
/// ```example /// ```example
/// #figure( /// #figure(
@ -45,7 +44,7 @@ use crate::visualize::ImageElem;
/// This behaviour can be overridden by explicitly specifying the figure's /// This behaviour can be overridden by explicitly specifying the figure's
/// `kind`. All figures of the same kind share a common counter. /// `kind`. All figures of the same kind share a common counter.
/// ///
/// ## Modifying the appearance { #modifying-appearance } /// # Modifying the appearance { #modifying-appearance }
/// You can completely customize the look of your figures with a [show /// You can completely customize the look of your figures with a [show
/// rule]($styling/#show-rules). In the example below, we show the figure's /// rule]($styling/#show-rules). In the example below, we show the figure's
/// caption above its body and display its supplement and counter after the /// caption above its body and display its supplement and counter after the
@ -73,13 +72,10 @@ use crate::visualize::ImageElem;
/// If your figure is too large and its contents are breakable across pages /// If your figure is too large and its contents are breakable across pages
/// (e.g. if it contains a large table), then you can make the figure breakable /// (e.g. if it contains a large table), then you can make the figure breakable
/// across pages as well by using `[#show figure: set block(breakable: true)]` /// across pages as well by using `[#show figure: set block(breakable: true)]`
/// (see the [block]($func/block) documentation for more information). /// (see the [block]($block) documentation for more information).
/// #[elem(Locatable, Synthesize, Count, Show, Finalize, Refable, Outlinable)]
/// Display: Figure
/// Category: meta
#[element(Locatable, Synthesize, Count, Show, Finalize, Refable, Outlinable)]
pub struct FigureElem { pub struct FigureElem {
/// The content of the figure. Often, an [image]($func/image). /// The content of the figure. Often, an [image]($image).
#[required] #[required]
pub body: Content, pub body: Content,
@ -103,7 +99,7 @@ pub struct FigureElem {
/// ) /// )
/// #lorem(60) /// #lorem(60)
/// ``` /// ```
pub placement: Option<Smart<VerticalAlign>>, pub placement: Option<Smart<VAlign>>,
/// The figure's caption. /// The figure's caption.
pub caption: Option<Content>, pub caption: Option<Content>,
@ -122,8 +118,17 @@ pub struct FigureElem {
/// caption: [I'm down here], /// caption: [I'm down here],
/// ) /// )
/// ``` /// ```
#[default(VerticalAlign(GenAlign::Specific(Align::Bottom)))] #[default(VAlign::Bottom)]
pub caption_pos: VerticalAlign, #[parse({
let option: Option<Spanned<VAlign>> = args.named("caption-pos")?;
if let Some(Spanned { v: align, span }) = option {
if align == VAlign::Horizon {
bail!(span, "expected `top` or `bottom`");
}
}
option.map(|spanned| spanned.v)
})]
pub caption_pos: VAlign,
/// The kind of figure this is. /// The kind of figure this is.
/// ///
@ -133,7 +138,7 @@ pub struct FigureElem {
/// Setting this to something other than `{auto}` will override the /// Setting this to something other than `{auto}` will override the
/// automatic detection. This can be useful if /// automatic detection. This can be useful if
/// - you wish to create a custom figure type that is not an /// - you wish to create a custom figure type that is not an
/// [image]($func/image), a [table]($func/table) or [code]($func/raw), /// [image]($image), a [table]($table) or [code]($raw),
/// - you want to force the figure to use a specific counter regardless of /// - you want to force the figure to use a specific counter regardless of
/// its content. /// its content.
/// ///
@ -155,8 +160,8 @@ pub struct FigureElem {
/// The figure's supplement. /// The figure's supplement.
/// ///
/// If set to `{auto}`, the figure will try to automatically determine the /// If set to `{auto}`, the figure will try to automatically determine the
/// correct supplement based on the `kind` and the active [text /// correct supplement based on the `kind` and the active
/// language]($func/text.lang). If you are using a custom figure type, you /// [text language]($text.lang). If you are using a custom figure type, you
/// will need to manually specify the supplement. /// will need to manually specify the supplement.
/// ///
/// If a function is specified, it is passed the first descendant of the /// If a function is specified, it is passed the first descendant of the
@ -174,7 +179,7 @@ pub struct FigureElem {
pub supplement: Smart<Option<Supplement>>, pub supplement: Smart<Option<Supplement>>,
/// How to number the figure. Accepts a /// How to number the figure. Accepts a
/// [numbering pattern or function]($func/numbering). /// [numbering pattern or function]($numbering).
#[default(Some(NumberingPattern::from_str("1").unwrap().into()))] #[default(Some(NumberingPattern::from_str("1").unwrap().into()))]
pub numbering: Option<Numbering>, pub numbering: Option<Numbering>,
@ -182,16 +187,15 @@ pub struct FigureElem {
#[default(Em::new(0.65).into())] #[default(Em::new(0.65).into())]
pub gap: Length, pub gap: Length,
/// Whether the figure should appear in an [`outline`]($func/outline) /// Whether the figure should appear in an [`outline`]($outline) of figures.
/// of figures.
#[default(true)] #[default(true)]
pub outlined: bool, pub outlined: bool,
/// Convenience field to get access to the counter for this figure. /// Convenience field to get access to the counter for this figure.
/// ///
/// The counter only depends on the `kind`: /// The counter only depends on the `kind`:
/// - For (tables)[$func/table]: `{counter(figure.where(kind: table))}` /// - For (tables)[@table]: `{counter(figure.where(kind: table))}`
/// - For (images)[$func/image]: `{counter(figure.where(kind: image))}` /// - For (images)[@image]: `{counter(figure.where(kind: image))}`
/// - For a custom kind: `{counter(figure.where(kind: kind))}` /// - For a custom kind: `{counter(figure.where(kind: kind))}`
/// ///
/// These are the counters you'll need to modify if you want to skip a /// These are the counters you'll need to modify if you want to skip a
@ -210,16 +214,9 @@ impl Synthesize for FigureElem {
.query_first(Selector::can::<dyn Figurable>()) .query_first(Selector::can::<dyn Figurable>())
.cloned() .cloned()
.map(|elem| FigureKind::Elem(elem.func())) .map(|elem| FigureKind::Elem(elem.func()))
.unwrap_or_else(|| FigureKind::Elem(ImageElem::func())) .unwrap_or_else(|| FigureKind::Elem(ImageElem::elem()))
}); });
let caption_pos =
VerticalAlign(GenAlign::Specific(match self.caption_pos(styles) {
VerticalAlign(GenAlign::Specific(Align::Top)) => Align::Top,
VerticalAlign(GenAlign::Specific(Align::Bottom)) => Align::Bottom,
_ => bail!(self.span(), "caption-pos can only be top or bottom"),
}));
// Resolve the supplement. // Resolve the supplement.
let supplement = match self.supplement(styles) { let supplement = match self.supplement(styles) {
Smart::Auto => { Smart::Auto => {
@ -261,14 +258,14 @@ impl Synthesize for FigureElem {
// Construct the figure's counter. // Construct the figure's counter.
let counter = Counter::new(CounterKey::Selector(Selector::Elem( let counter = Counter::new(CounterKey::Selector(Selector::Elem(
Self::func(), Self::elem(),
Some(dict! { Some(dict! {
"kind" => kind.clone(), "kind" => kind.clone(),
}), }),
))); )));
self.push_placement(self.placement(styles)); self.push_placement(self.placement(styles));
self.push_caption_pos(caption_pos); self.push_caption_pos(self.caption_pos(styles));
self.push_caption(self.caption(styles)); self.push_caption(self.caption(styles));
self.push_kind(Smart::Custom(kind)); self.push_kind(Smart::Custom(kind));
self.push_supplement(Smart::Custom(Some(Supplement::Content(supplement)))); self.push_supplement(Smart::Custom(Some(Supplement::Content(supplement))));
@ -288,10 +285,7 @@ impl Show for FigureElem {
// Build the caption, if any. // Build the caption, if any.
if let Some(caption) = self.full_caption(vt)? { if let Some(caption) = self.full_caption(vt)? {
let v = VElem::weak(self.gap(styles).into()).pack(); let v = VElem::weak(self.gap(styles).into()).pack();
realized = if matches!( realized = if self.caption_pos(styles) == VAlign::Bottom {
self.caption_pos(styles),
VerticalAlign(GenAlign::Specific(Align::Bottom))
) {
realized + v + caption realized + v + caption
} else { } else {
caption + v + realized caption + v + realized
@ -302,15 +296,13 @@ impl Show for FigureElem {
realized = BlockElem::new() realized = BlockElem::new()
.with_body(Some(realized)) .with_body(Some(realized))
.pack() .pack()
.aligned(Axes::with_x(Some(Align::Center.into()))); .aligned(Align::CENTER);
// Wrap in a float. // Wrap in a float.
if let Some(align) = self.placement(styles) { if let Some(align) = self.placement(styles) {
realized = PlaceElem::new(realized) realized = PlaceElem::new(realized)
.with_float(true) .with_float(true)
.with_alignment(align.map(|VerticalAlign(align)| { .with_alignment(align.map(|align| HAlign::Center + align))
Axes::new(Some(Align::Center.into()), Some(align))
}))
.pack(); .pack();
} }
@ -345,7 +337,7 @@ impl Refable for FigureElem {
} }
fn counter(&self) -> Counter { fn counter(&self) -> Counter {
self.counter().unwrap_or_else(|| Counter::of(Self::func())) self.counter().unwrap_or_else(|| Counter::of(Self::elem()))
} }
fn numbering(&self) -> Option<Numbering> { fn numbering(&self) -> Option<Numbering> {
@ -379,8 +371,8 @@ impl FigureElem {
self.counter(), self.counter(),
self.numbering(StyleChain::default()), self.numbering(StyleChain::default()),
) { ) {
let loc = self.0.location().unwrap(); let location = self.0.location().unwrap();
let numbers = counter.at(vt, loc)?.display(vt, &numbering)?; let numbers = counter.at(vt, location)?.display(vt, &numbering)?;
if !supplement.is_empty() { if !supplement.is_empty() {
supplement += TextElem::packed("\u{a0}"); supplement += TextElem::packed("\u{a0}");
@ -397,7 +389,7 @@ impl FigureElem {
#[derive(Debug, Clone)] #[derive(Debug, Clone)]
pub enum FigureKind { pub enum FigureKind {
/// The kind is an element function. /// The kind is an element function.
Elem(ElemFunc), Elem(Element),
/// The kind is a name. /// The kind is a name.
Name(EcoString), Name(EcoString),
} }
@ -408,7 +400,7 @@ cast! {
Self::Elem(v) => v.into_value(), Self::Elem(v) => v.into_value(),
Self::Name(v) => v.into_value(), Self::Name(v) => v.into_value(),
}, },
v: ElemFunc => Self::Elem(v), v: Element => Self::Elem(v),
v: EcoString => Self::Name(v), v: EcoString => Self::Name(v),
} }

46
crates/typst-library/src/meta/footnote.rs
View File

@ -34,11 +34,11 @@ cast! {
/// and can break across multiple pages. /// and can break across multiple pages.
/// ///
/// To customize the appearance of the entry in the footnote listing, see /// To customize the appearance of the entry in the footnote listing, see
/// [`footnote.entry`]($func/footnote.entry). The footnote itself is realized as /// [`footnote.entry`]($footnote.entry). The footnote itself is realized as a
/// a normal superscript, so you can use a set rule on the /// normal superscript, so you can use a set rule on the [`super`]($super)
/// [`super`]($func/super) function to customize it. /// function to customize it.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// Check the docs for more details. /// Check the docs for more details.
/// #footnote[https://typst.app/docs] /// #footnote[https://typst.app/docs]
@ -46,7 +46,7 @@ cast! {
/// ///
/// The footnote automatically attaches itself to the preceding word, even if /// The footnote automatically attaches itself to the preceding word, even if
/// there is a space before it in the markup. To force space, you can use the /// there is a space before it in the markup. To force space, you can use the
/// string `[#" "]` or explicit [horizontal spacing]($func/h). /// string `[#" "]` or explicit [horizontal spacing]($h).
/// ///
/// By giving a label to a footnote, you can have multiple references to it. /// By giving a label to a footnote, you can have multiple references to it.
/// ///
@ -61,21 +61,14 @@ cast! {
/// apply to the footnote's content. See [here][issue] for more information. /// apply to the footnote's content. See [here][issue] for more information.
/// ///
/// [issue]: https://github.com/typst/typst/issues/1467#issuecomment-1588799440 /// [issue]: https://github.com/typst/typst/issues/1467#issuecomment-1588799440
/// #[elem(scope, Locatable, Synthesize, Show, Count)]
/// Display: Footnote
/// Category: meta
#[element(Locatable, Synthesize, Show, Count)]
#[scope(
scope.define("entry", FootnoteEntry::func());
scope
)]
pub struct FootnoteElem { pub struct FootnoteElem {
/// How to number footnotes. /// How to number footnotes.
/// ///
/// By default, the footnote numbering continues throughout your document. /// By default, the footnote numbering continues throughout your document.
/// If you prefer per-page footnote numbering, you can reset the footnote /// If you prefer per-page footnote numbering, you can reset the footnote
/// [counter]($func/counter) in the page [header]($func/page.header). In the /// [counter]($counter) in the page [header]($page.header). In the future,
/// future, there might be a simpler way to achieve this. /// there might be a simpler way to achieve this.
/// ///
/// ```example /// ```example
/// #set footnote(numbering: "*") /// #set footnote(numbering: "*")
@ -93,6 +86,12 @@ pub struct FootnoteElem {
pub body: FootnoteBody, pub body: FootnoteBody,
} }
#[scope]
impl FootnoteElem {
#[elem]
type FootnoteEntry;
}
impl FootnoteElem { impl FootnoteElem {
/// Creates a new footnote that the passed content as its body. /// Creates a new footnote that the passed content as its body.
pub fn with_content(content: Content) -> Self { pub fn with_content(content: Content) -> Self {
@ -145,7 +144,7 @@ impl Show for FootnoteElem {
Ok(vt.delayed(|vt| { Ok(vt.delayed(|vt| {
let loc = self.declaration_location(vt).at(self.span())?; let loc = self.declaration_location(vt).at(self.span())?;
let numbering = self.numbering(styles); let numbering = self.numbering(styles);
let counter = Counter::of(Self::func()); let counter = Counter::of(Self::elem());
let num = counter.at(vt, loc)?.display(vt, &numbering)?; let num = counter.at(vt, loc)?.display(vt, &numbering)?;
let sup = SuperElem::new(num).pack(); let sup = SuperElem::new(num).pack();
let hole = HElem::new(Abs::zero().into()).with_weak(true).pack(); let hole = HElem::new(Abs::zero().into()).with_weak(true).pack();
@ -168,11 +167,9 @@ impl Count for FootnoteElem {
/// ///
/// _Note:_ Set and show rules for `footnote.entry` must be defined at the /// _Note:_ Set and show rules for `footnote.entry` must be defined at the
/// beginning of the document in order to work correctly. /// beginning of the document in order to work correctly.
/// See [here][issue] for more information. /// See [here](https://github.com/typst/typst/issues/1348#issuecomment-1566316463)
/// for more information.
/// ///
/// [issue]: https://github.com/typst/typst/issues/1348#issuecomment-1566316463
///
/// ## Example { #example }
/// ```example /// ```example
/// #show footnote.entry: set text(red) /// #show footnote.entry: set text(red)
/// ///
@ -180,10 +177,7 @@ impl Count for FootnoteElem {
/// #footnote[It's down here] /// #footnote[It's down here]
/// has red text! /// has red text!
/// ``` /// ```
/// #[elem(name = "entry", title = "Footnote Entry", Show, Finalize)]
/// Display: Footnote Entry
/// Category: meta
#[element(Show, Finalize)]
pub struct FootnoteEntry { pub struct FootnoteEntry {
/// The footnote for this entry. It's location can be used to determine /// The footnote for this entry. It's location can be used to determine
/// the footnote counter state. /// the footnote counter state.
@ -220,7 +214,7 @@ pub struct FootnoteEntry {
#[default( #[default(
LineElem::new() LineElem::new()
.with_length(Ratio::new(0.3).into()) .with_length(Ratio::new(0.3).into())
.with_stroke(PartialStroke { .with_stroke(Stroke {
thickness: Smart::Custom(Abs::pt(0.5).into()), thickness: Smart::Custom(Abs::pt(0.5).into()),
..Default::default() ..Default::default()
}) })
@ -273,7 +267,7 @@ impl Show for FootnoteEntry {
let note = self.note(); let note = self.note();
let number_gap = Em::new(0.05); let number_gap = Em::new(0.05);
let numbering = note.numbering(StyleChain::default()); let numbering = note.numbering(StyleChain::default());
let counter = Counter::of(FootnoteElem::func()); let counter = Counter::of(FootnoteElem::elem());
let loc = note.0.location().unwrap(); let loc = note.0.location().unwrap();
let num = counter.at(vt, loc)?.display(vt, &numbering)?; let num = counter.at(vt, loc)?.display(vt, &numbering)?;
let sup = SuperElem::new(num) let sup = SuperElem::new(num)

37
crates/typst-library/src/meta/heading.rs
View File

@ -17,14 +17,13 @@ use crate::text::{SpaceElem, TextElem, TextSize};
/// ///
/// Typst can automatically number your headings for you. To enable numbering, /// Typst can automatically number your headings for you. To enable numbering,
/// specify how you want your headings to be numbered with a /// specify how you want your headings to be numbered with a
/// [numbering pattern or function]($func/numbering). /// [numbering pattern or function]($numbering).
/// ///
/// Independently from the numbering, Typst can also automatically generate an /// Independently from the numbering, Typst can also automatically generate an
/// [outline]($func/outline) of all headings for you. To exclude one or more /// [outline]($outline) of all headings for you. To exclude one or more headings
/// headings from this outline, you can set the `outlined` parameter to /// from this outline, you can set the `outlined` parameter to `{false}`.
/// `{false}`.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #set heading(numbering: "1.a)") /// #set heading(numbering: "1.a)")
/// ///
@ -35,21 +34,18 @@ use crate::text::{SpaceElem, TextElem, TextSize};
/// To start, ... /// To start, ...
/// ``` /// ```
/// ///
/// ## Syntax { #syntax } /// # Syntax
/// Headings have dedicated syntax: They can be created by starting a line with /// Headings have dedicated syntax: They can be created by starting a line with
/// one or multiple equals signs, followed by a space. The number of equals /// one or multiple equals signs, followed by a space. The number of equals
/// signs determines the heading's logical nesting depth. /// signs determines the heading's logical nesting depth.
/// #[elem(Locatable, Synthesize, Count, Show, Finalize, LocalName, Refable, Outlinable)]
/// Display: Heading
/// Category: meta
#[element(Locatable, Synthesize, Count, Show, Finalize, LocalName, Refable, Outlinable)]
pub struct HeadingElem { pub struct HeadingElem {
/// The logical nesting depth of the heading, starting from one. /// The logical nesting depth of the heading, starting from one.
#[default(NonZeroUsize::ONE)] #[default(NonZeroUsize::ONE)]
pub level: NonZeroUsize, pub level: NonZeroUsize,
/// How to number the heading. Accepts a /// How to number the heading. Accepts a
/// [numbering pattern or function]($func/numbering). /// [numbering pattern or function]($numbering).
/// ///
/// ```example /// ```example
/// #set heading(numbering: "1.a.") /// #set heading(numbering: "1.a.")
@ -78,11 +74,11 @@ pub struct HeadingElem {
/// ``` /// ```
pub supplement: Smart<Option<Supplement>>, pub supplement: Smart<Option<Supplement>>,
/// Whether the heading should appear in the [outline]($func/outline). /// Whether the heading should appear in the [outline]($outline).
/// ///
/// Note that this property, if set to `{true}`, ensures the heading is /// Note that this property, if set to `{true}`, ensures the heading is also
/// also shown as a bookmark in the exported PDF's outline (when exporting /// shown as a bookmark in the exported PDF's outline (when exporting to
/// to PDF). To change that behavior, use the `bookmarked` property. /// PDF). To change that behavior, use the `bookmarked` property.
/// ///
/// ```example /// ```example
/// #outline() /// #outline()
@ -103,9 +99,8 @@ pub struct HeadingElem {
/// The default value of `{auto}` indicates that the heading will only /// The default value of `{auto}` indicates that the heading will only
/// appear in the exported PDF's outline if its `outlined` property is set /// appear in the exported PDF's outline if its `outlined` property is set
/// to `{true}`, that is, if it would also be listed in Typst's /// to `{true}`, that is, if it would also be listed in Typst's
/// [outline]($func/outline). Setting this property to either /// [outline]($outline). Setting this property to either `{true}` (bookmark)
/// `{true}` (bookmark) or `{false}` (don't bookmark) bypasses that /// or `{false}` (don't bookmark) bypasses that behavior.
/// behavior.
/// ///
/// ```example /// ```example
/// #heading[Normal heading] /// #heading[Normal heading]
@ -149,7 +144,7 @@ impl Show for HeadingElem {
fn show(&self, _: &mut Vt, styles: StyleChain) -> SourceResult<Content> { fn show(&self, _: &mut Vt, styles: StyleChain) -> SourceResult<Content> {
let mut realized = self.body(); let mut realized = self.body();
if let Some(numbering) = self.numbering(styles) { if let Some(numbering) = self.numbering(styles) {
realized = Counter::of(Self::func()) realized = Counter::of(Self::elem())
.display(Some(numbering), false) .display(Some(numbering), false)
.spanned(self.span()) .spanned(self.span())
+ HElem::new(Em::new(0.3).into()).with_weak(true).pack() + HElem::new(Em::new(0.3).into()).with_weak(true).pack()
@ -205,7 +200,7 @@ impl Refable for HeadingElem {
} }
fn counter(&self) -> Counter { fn counter(&self) -> Counter {
Counter::of(Self::func()) Counter::of(Self::elem())
} }
fn numbering(&self) -> Option<Numbering> { fn numbering(&self) -> Option<Numbering> {
@ -221,7 +216,7 @@ impl Outlinable for HeadingElem {
let mut content = self.body(); let mut content = self.body();
if let Some(numbering) = self.numbering(StyleChain::default()) { if let Some(numbering) = self.numbering(StyleChain::default()) {
let numbers = Counter::of(Self::func()) let numbers = Counter::of(Self::elem())
.at(vt, self.0.location().unwrap())? .at(vt, self.0.location().unwrap())?
.display(vt, &numbering)?; .display(vt, &numbering)?;
content = numbers + SpaceElem::new().pack() + content; content = numbers + SpaceElem::new().pack() + content;

26
crates/typst-library/src/meta/link.rs
View File

@ -6,7 +6,7 @@ use crate::text::{Hyphenate, TextElem};
/// By default, links are not styled any different from normal text. However, /// By default, links are not styled any different from normal text. However,
/// you can easily apply a style of your choice with a show rule. /// you can easily apply a style of your choice with a show rule.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #show link: underline /// #show link: underline
/// ///
@ -18,13 +18,10 @@ use crate::text::{Hyphenate, TextElem};
/// ] /// ]
/// ``` /// ```
/// ///
/// ## Syntax { #syntax } /// # Syntax
/// This function also has dedicated syntax: Text that starts with `http://` or /// This function also has dedicated syntax: Text that starts with `http://` or
/// `https://` is automatically turned into a link. /// `https://` is automatically turned into a link.
/// #[elem(Show)]
/// Display: Link
/// Category: meta
#[element(Show)]
pub struct LinkElem { pub struct LinkElem {
/// The destination the link points to. /// The destination the link points to.
/// ///
@ -35,17 +32,16 @@ pub struct LinkElem {
/// ///
/// - To link to another part of the document, `dest` can take one of three /// - To link to another part of the document, `dest` can take one of three
/// forms: /// forms:
/// - A [label]($func/label) attached to an element. If you also want /// - A [label]($label) attached to an element. If you also want automatic
/// automatic text for the link based on the element, consider using /// text for the link based on the element, consider using a
/// a [reference]($func/ref) instead. /// [reference]($ref) instead.
/// ///
/// - A [location]($func/locate) resulting from a [`locate`]($func/locate) /// - A [location]($locate) resulting from a [`locate`]($locate) call or
/// call or [`query`]($func/query). /// [`query`]($query).
/// ///
/// - A dictionary with a `page` key of type [integer]($type/integer) and /// - A dictionary with a `page` key of type [integer]($int) and `x` and
/// `x` and `y` coordinates of type [length]($type/length). Pages are /// `y` coordinates of type [length]($length). Pages are counted from
/// counted from one, and the coordinates are relative to the page's top /// one, and the coordinates are relative to the page's top left corner.
/// left corner.
/// ///
/// ```example /// ```example
/// = Introduction <intro> /// = Introduction <intro>

15
crates/typst-library/src/meta/metadata.rs
View File

@ -2,11 +2,11 @@ use crate::prelude::*;
/// Exposes a value to the query system without producing visible content. /// Exposes a value to the query system without producing visible content.
/// ///
/// This element can be retrieved with the [`query`]($func/query) function and /// This element can be retrieved with the [`query`]($query) function and from
/// from the command with [`typst query`]($reference/meta/query/#cli-queries). /// the command with [`typst query`]($reference/meta/query/#cli-queries). Its
/// Its purpose is to expose an arbitrary value to the introspection system. To /// purpose is to expose an arbitrary value to the introspection system. To
/// identify a metadata value among others, you can attach a /// identify a metadata value among others, you can attach a [`label`]($label)
/// [`label`]($func/label) to it and query for that label. /// to it and query for that label.
/// ///
/// The `metadata` element is especially useful for command line queries because /// The `metadata` element is especially useful for command line queries because
/// it allows you to expose arbitrary values to the outside world. /// it allows you to expose arbitrary values to the outside world.
@ -20,10 +20,7 @@ use crate::prelude::*;
/// query(<note>, loc).first().value /// query(<note>, loc).first().value
/// }) /// })
/// ``` /// ```
/// #[elem(Behave, Show, Locatable)]
/// Display: Metadata
/// Category: meta
#[element(Behave, Show, Locatable)]
pub struct MetadataElem { pub struct MetadataElem {
/// The value to embed into the document. /// The value to embed into the document.
#[required] #[required]

49
crates/typst-library/src/meta/mod.rs
View File

@ -9,9 +9,11 @@ mod footnote;
mod heading; mod heading;
mod link; mod link;
mod metadata; mod metadata;
mod numbering; #[path = "numbering.rs"]
mod numbering_;
mod outline; mod outline;
mod query; #[path = "query.rs"]
mod query_;
mod reference; mod reference;
mod state; mod state;
@ -24,9 +26,9 @@ pub use self::footnote::*;
pub use self::heading::*; pub use self::heading::*;
pub use self::link::*; pub use self::link::*;
pub use self::metadata::*; pub use self::metadata::*;
pub use self::numbering::*; pub use self::numbering_::*;
pub use self::outline::*; pub use self::outline::*;
pub use self::query::*; pub use self::query_::*;
pub use self::reference::*; pub use self::reference::*;
pub use self::state::*; pub use self::state::*;
@ -35,24 +37,27 @@ use crate::text::TextElem;
/// Hook up all meta definitions. /// Hook up all meta definitions.
pub(super) fn define(global: &mut Scope) { pub(super) fn define(global: &mut Scope) {
global.define("document", DocumentElem::func()); global.category("meta");
global.define("ref", RefElem::func()); global.define_type::<Label>();
global.define("link", LinkElem::func()); global.define_type::<Selector>();
global.define("outline", OutlineElem::func()); global.define_type::<Location>();
global.define("heading", HeadingElem::func()); global.define_type::<Counter>();
global.define("figure", FigureElem::func()); global.define_type::<State>();
global.define("footnote", FootnoteElem::func()); global.define_elem::<DocumentElem>();
global.define("cite", CiteElem::func()); global.define_elem::<RefElem>();
global.define("bibliography", BibliographyElem::func()); global.define_elem::<LinkElem>();
global.define("locate", locate_func()); global.define_elem::<OutlineElem>();
global.define("style", style_func()); global.define_elem::<HeadingElem>();
global.define("layout", layout_func()); global.define_elem::<FigureElem>();
global.define("counter", counter_func()); global.define_elem::<FootnoteElem>();
global.define("numbering", numbering_func()); global.define_elem::<CiteElem>();
global.define("state", state_func()); global.define_elem::<BibliographyElem>();
global.define("query", query_func()); global.define_elem::<MetadataElem>();
global.define("selector", selector_func()); global.define_func::<locate>();
global.define("metadata", MetadataElem::func()); global.define_func::<style>();
global.define_func::<layout>();
global.define_func::<numbering>();
global.define_func::<query>();
} }
/// The named with which an element is referenced. /// The named with which an element is referenced.

9
crates/typst-library/src/meta/numbering.rs
View File

@ -16,7 +16,7 @@ use crate::text::Case;
/// number is substituted, their prefixes, and one suffix. The prefixes and the /// number is substituted, their prefixes, and one suffix. The prefixes and the
/// suffix are repeated as-is. /// suffix are repeated as-is.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #numbering("1.1)", 1, 2, 3) \ /// #numbering("1.1)", 1, 2, 3) \
/// #numbering("1.a.i", 1, 2) \ /// #numbering("1.a.i", 1, 2) \
@ -29,11 +29,10 @@ use crate::text::Case;
/// 1, 2, 3, /// 1, 2, 3,
/// ) /// )
/// ``` /// ```
///
/// Display: Numbering
/// Category: meta
#[func] #[func]
pub fn numbering( pub fn numbering(
/// The virtual machine.
vm: &mut Vm,
/// Defines how the numbering works. /// Defines how the numbering works.
/// ///
/// **Counting symbols** are `1`, `a`, `A`, `i`, `I`, `い`, `イ`, `א`, `가`, /// **Counting symbols** are `1`, `a`, `A`, `i`, `I`, `い`, `イ`, `א`, `가`,
@ -64,8 +63,6 @@ pub fn numbering(
/// given, the last counting symbol with its prefix is repeated. /// given, the last counting symbol with its prefix is repeated.
#[variadic] #[variadic]
numbers: Vec<usize>, numbers: Vec<usize>,
/// The virtual machine.
vm: &mut Vm,
) -> SourceResult<Value> { ) -> SourceResult<Value> {
numbering.apply_vm(vm, &numbers) numbering.apply_vm(vm, &numbers)
} }

73
crates/typst-library/src/meta/outline.rs
View File

@ -16,7 +16,7 @@ use crate::text::{LinebreakElem, SpaceElem, TextElem};
/// be displayed in the outline alongside its title or caption. By default this /// be displayed in the outline alongside its title or caption. By default this
/// generates a table of contents. /// generates a table of contents.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #outline() /// #outline()
/// ///
@ -27,13 +27,13 @@ use crate::text::{LinebreakElem, SpaceElem, TextElem};
/// #lorem(10) /// #lorem(10)
/// ``` /// ```
/// ///
/// ## Alternative outlines { #alternative-outlines } /// # Alternative outlines
/// By setting the `target` parameter, the outline can be used to generate a /// By setting the `target` parameter, the outline can be used to generate a
/// list of other kinds of elements than headings. In the example below, we list /// list of other kinds of elements than headings. In the example below, we list
/// all figures containing images by setting `target` to `{figure.where(kind: /// all figures containing images by setting `target` to `{figure.where(kind:
/// image)}`. We could have also set it to just `figure`, but then the list /// image)}`. We could have also set it to just `figure`, but then the list
/// would also include figures containing tables or other material. For more /// would also include figures containing tables or other material. For more
/// details on the `where` selector, [see here]($type/content.where). /// details on the `where` selector, [see here]($function.where).
/// ///
/// ```example /// ```example
/// #outline( /// #outline(
@ -47,25 +47,17 @@ use crate::text::{LinebreakElem, SpaceElem, TextElem};
/// ) /// )
/// ``` /// ```
/// ///
/// ## Styling the outline { #styling-the-outline } /// # Styling the outline
/// The outline element has several options for customization, such as its /// The outline element has several options for customization, such as its
/// `title` and `indent` parameters. If desired, however, it is possible to /// `title` and `indent` parameters. If desired, however, it is possible to have
/// have more control over the outline's look and style through the /// more control over the outline's look and style through the
/// [`outline.entry`]($func/outline.entry) element. /// [`outline.entry`]($outline.entry) element.
/// #[elem(scope, keywords = ["Table of Contents"], Show, Finalize, LocalName)]
/// Display: Outline
/// Category: meta
/// Keywords: Table of Contents
#[element(Show, Finalize, LocalName)]
#[scope(
scope.define("entry", OutlineEntry::func());
scope
)]
pub struct OutlineElem { pub struct OutlineElem {
/// The title of the outline. /// The title of the outline.
/// ///
/// - When set to `{auto}`, an appropriate title for the /// - When set to `{auto}`, an appropriate title for the
/// [text language]($func/text.lang) will be used. This is the default. /// [text language]($text.lang) will be used. This is the default.
/// - When set to `{none}`, the outline will not have a title. /// - When set to `{none}`, the outline will not have a title.
/// - A custom title can be set by passing content. /// - A custom title can be set by passing content.
/// ///
@ -97,7 +89,7 @@ pub struct OutlineElem {
/// ) /// )
/// ``` /// ```
#[default(LocatableSelector(Selector::Elem( #[default(LocatableSelector(Selector::Elem(
HeadingElem::func(), HeadingElem::elem(),
Some(dict! { "outlined" => true }) Some(dict! { "outlined" => true })
)))] )))]
pub target: LocatableSelector, pub target: LocatableSelector,
@ -125,19 +117,18 @@ pub struct OutlineElem {
/// - `{none}`: No indent /// - `{none}`: No indent
/// - `{auto}`: Indents the numbering of the nested entry with the title of /// - `{auto}`: Indents the numbering of the nested entry with the title of
/// its parent entry. This only has an effect if the entries are numbered /// its parent entry. This only has an effect if the entries are numbered
/// (e.g., via [heading numbering]($func/heading.numbering)). /// (e.g., via [heading numbering]($heading.numbering)).
/// - [Relative length]($type/relative-length): Indents the item by this length /// - [Relative length]($relative): Indents the item by this length
/// multiplied by its nesting level. Specifying `{2em}`, for instance, /// multiplied by its nesting level. Specifying `{2em}`, for instance,
/// would indent top-level headings (not nested) by `{0em}`, second level /// would indent top-level headings (not nested) by `{0em}`, second level
/// headings by `{2em}` (nested once), third-level headings by `{4em}` /// headings by `{2em}` (nested once), third-level headings by `{4em}`
/// (nested twice) and so on. /// (nested twice) and so on.
/// - [Function]($type/function): You can completely customize this setting /// - [Function]($function): You can completely customize this setting with
/// with a function. That function receives the nesting level as a /// a function. That function receives the nesting level as a parameter
/// parameter (starting at 0 for top-level headings/elements) and can /// (starting at 0 for top-level headings/elements) and can return a
/// return a relative length or content making up the indent. For example, /// relative length or content making up the indent. For example,
/// `{n => n * 2em}` would be equivalent to just specifying `{2em}`, /// `{n => n * 2em}` would be equivalent to just specifying `{2em}`, while
/// while `{n => [→ ] * n}` would indent with one arrow per nesting /// `{n => [→ ] * n}` would indent with one arrow per nesting level.
/// level.
/// ///
/// *Migration hints:* Specifying `{true}` (equivalent to `{auto}`) or /// *Migration hints:* Specifying `{true}` (equivalent to `{auto}`) or
/// `{false}` (equivalent to `{none}`) for this option is deprecated and /// `{false}` (equivalent to `{none}`) for this option is deprecated and
@ -184,6 +175,12 @@ pub struct OutlineElem {
pub fill: Option<Content>, pub fill: Option<Content>,
} }
#[scope]
impl OutlineElem {
#[elem]
type OutlineEntry;
}
impl Show for OutlineElem { impl Show for OutlineElem {
#[tracing::instrument(name = "OutlineElem::show", skip_all)] #[tracing::instrument(name = "OutlineElem::show", skip_all)]
fn show(&self, vt: &mut Vt, styles: StyleChain) -> SourceResult<Content> { fn show(&self, vt: &mut Vt, styles: StyleChain) -> SourceResult<Content> {
@ -391,11 +388,9 @@ cast! {
/// outlined element, its page number, and the filler content between both. /// outlined element, its page number, and the filler content between both.
/// ///
/// This element is intended for use with show rules to control the appearance /// This element is intended for use with show rules to control the appearance
/// of outlines. /// of outlines. To customize an entry's line, you can build it from scratch by
/// /// accessing the `level`, `element`, `body`, `fill` and `page` fields on the
/// ## Example { #example } /// entry.
/// The example below shows how to style entries for top-level sections to make
/// them stand out.
/// ///
/// ```example /// ```example
/// #set heading(numbering: "1.") /// #set heading(numbering: "1.")
@ -416,13 +411,7 @@ cast! {
/// = Analysis /// = Analysis
/// == Setup /// == Setup
/// ``` /// ```
/// #[elem(name = "entry", title = "Outline Entry", Show)]
/// To completely customize an entry's line, you can also build it from scratch
/// by accessing the `level`, `element`, `body`, `fill` and `page` fields on the entry.
///
/// Display: Outline Entry
/// Category: meta
#[element(Show)]
pub struct OutlineEntry { pub struct OutlineEntry {
/// The nesting level of this outline entry. Starts at `{1}` for top-level /// The nesting level of this outline entry. Starts at `{1}` for top-level
/// entries. /// entries.
@ -430,8 +419,8 @@ pub struct OutlineEntry {
pub level: NonZeroUsize, pub level: NonZeroUsize,
/// The element this entry refers to. Its location will be available /// The element this entry refers to. Its location will be available
/// through the [`location`]($type/content.location) method on content /// through the [`location`]($content.location) method on content
/// and can be [linked]($func/link) to. /// and can be [linked]($link) to.
#[required] #[required]
pub element: Content, pub element: Content,
@ -446,7 +435,7 @@ pub struct OutlineEntry {
/// located in. When `{none}`, empty space is inserted in that gap instead. /// located in. When `{none}`, empty space is inserted in that gap instead.
/// ///
/// Note that, when using show rules to override outline entries, it is /// Note that, when using show rules to override outline entries, it is
/// recommended to wrap the filling content in a [`box`]($func/box) with /// recommended to wrap the filling content in a [`box`]($box) with
/// fractional width. For example, `{box(width: 1fr, repeat[-])}` would show /// fractional width. For example, `{box(width: 1fr, repeat[-])}` would show
/// precisely as many `-` characters as necessary to fill a particular gap. /// precisely as many `-` characters as necessary to fill a particular gap.
#[required] #[required]

49
crates/typst-library/src/meta/query.rs
View File

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

30
crates/typst-library/src/meta/reference.rs
View File

@ -9,20 +9,19 @@ use crate::text::TextElem;
/// Produces a textual reference to a label. For example, a reference to a /// Produces a textual reference to a label. For example, a reference to a
/// heading will yield an appropriate string such as "Section 1" for a reference /// heading will yield an appropriate string such as "Section 1" for a reference
/// to the first heading. The references are also links to the respective /// to the first heading. The references are also links to the respective
/// element. Reference syntax can also be used to [cite]($func/cite) from a /// element. Reference syntax can also be used to [cite]($cite) from a
/// bibliography. /// bibliography.
/// ///
/// Referenceable elements include [headings]($func/heading), /// Referenceable elements include [headings]($heading), [figures]($figure),
/// [figures]($func/figure), [equations]($func/math.equation), and /// [equations]($math.equation), and [footnotes]($footnote). To create a custom
/// [footnotes]($func/footnote). To create a custom referenceable element like a /// referenceable element like a theorem, you can create a figure of a custom
/// theorem, you can create a figure of a custom [`kind`]($func/figure.kind) and /// [`kind`]($figure.kind) and write a show rule for it. In the future, there
/// write a show rule for it. In the future, there might be a more direct way to /// might be a more direct way to define a custom referenceable element.
/// define a custom referenceable element.
/// ///
/// If you just want to link to a labelled element and not get an automatic /// If you just want to link to a labelled element and not get an automatic
/// textual reference, consider using the [`link`]($func/link) function instead. /// textual reference, consider using the [`link`]($link) function instead.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #set heading(numbering: "1.") /// #set heading(numbering: "1.")
/// #set math.equation(numbering: "(1)") /// #set math.equation(numbering: "(1)")
@ -46,7 +45,7 @@ use crate::text::TextElem;
/// #bibliography("works.bib") /// #bibliography("works.bib")
/// ``` /// ```
/// ///
/// ## Syntax { #syntax } /// # Syntax
/// This function also has dedicated syntax: A reference to a label can be /// This function also has dedicated syntax: A reference to a label can be
/// created by typing an `@` followed by the name of the label (e.g. /// created by typing an `@` followed by the name of the label (e.g.
/// `[= Introduction <intro>]` can be referenced by typing `[@intro]`). /// `[= Introduction <intro>]` can be referenced by typing `[@intro]`).
@ -54,7 +53,7 @@ use crate::text::TextElem;
/// To customize the supplement, add content in square brackets after the /// To customize the supplement, add content in square brackets after the
/// reference: `[@intro[Chapter]]`. /// reference: `[@intro[Chapter]]`.
/// ///
/// ## Customization { #customization } /// # Customization
/// If you write a show rule for references, you can access the referenced /// If you write a show rule for references, you can access the referenced
/// element through the `element` field of the reference. The `element` may /// element through the `element` field of the reference. The `element` may
/// be `{none}` even if it exists if Typst hasn't discovered it yet, so you /// be `{none}` even if it exists if Typst hasn't discovered it yet, so you
@ -83,10 +82,7 @@ use crate::text::TextElem;
/// In @beginning we prove @pythagoras. /// In @beginning we prove @pythagoras.
/// $ a^2 + b^2 = c^2 $ <pythagoras> /// $ a^2 + b^2 = c^2 $ <pythagoras>
/// ``` /// ```
/// #[elem(title = "Reference", Synthesize, Locatable, Show)]
/// Display: Reference
/// Category: meta
#[element(Synthesize, Locatable, Show)]
pub struct RefElem { pub struct RefElem {
/// The target label that should be referenced. /// The target label that should be referenced.
#[required] #[required]
@ -163,7 +159,7 @@ impl Show for RefElem {
let elem = elem.at(span)?; let elem = elem.at(span)?;
if elem.func() == FootnoteElem::func() { if elem.func() == FootnoteElem::elem() {
return Ok(FootnoteElem::with_label(target).pack().spanned(span)); return Ok(FootnoteElem::with_label(target).pack().spanned(span));
} }
@ -192,7 +188,7 @@ impl Show for RefElem {
.hint(eco_format!( .hint(eco_format!(
"you can enable {} numbering with `#set {}(numbering: \"1.\")`", "you can enable {} numbering with `#set {}(numbering: \"1.\")`",
elem.func().name(), elem.func().name(),
if elem.func() == EquationElem::func() { if elem.func() == EquationElem::elem() {
"math.equation" "math.equation"
} else { } else {
elem.func().name() elem.func().name()

236
crates/typst-library/src/meta/state.rs
View File

@ -30,7 +30,7 @@ use crate::prelude::*;
/// #compute("x - 5") /// #compute("x - 5")
/// ``` /// ```
/// ///
/// ## State and document markup { #state-and-markup } /// # State and document markup { #state-and-markup }
/// Why does it do that? Because, in general, this kind of computation with side /// Why does it do that? Because, in general, this kind of computation with side
/// effects is problematic in document markup and Typst is upfront about that. /// effects is problematic in document markup and Typst is upfront about that.
/// For the results to make sense, the computation must proceed in the same /// For the results to make sense, the computation must proceed in the same
@ -61,7 +61,7 @@ use crate::prelude::*;
/// `template` function and only then sees the `Outline`. Just counting up would /// `template` function and only then sees the `Outline`. Just counting up would
/// number the `Introduction` with `1` and the `Outline` with `2`. /// number the `Introduction` with `1` and the `Outline` with `2`.
/// ///
/// ## Managing state in Typst { #state-in-typst } /// # Managing state in Typst { #state-in-typst }
/// So what do we do instead? We use Typst's state management system. Calling /// So what do we do instead? We use Typst's state management system. Calling
/// the `state` function with an identifying string key and an optional initial /// the `state` function with an identifying string key and an optional initial
/// value gives you a state value which exposes a few methods. The two most /// value gives you a state value which exposes a few methods. The two most
@ -122,14 +122,14 @@ use crate::prelude::*;
/// ///
/// This example is of course a bit silly, but in practice this is often exactly /// This example is of course a bit silly, but in practice this is often exactly
/// what you want! A good example are heading counters, which is why Typst's /// what you want! A good example are heading counters, which is why Typst's
/// [counting system]($func/counter) is very similar to its state system. /// [counting system]($counter) is very similar to its state system.
/// ///
/// ## Time Travel { #time-travel } /// # Time Travel
/// By using Typst's state management system you also get time travel /// By using Typst's state management system you also get time travel
/// capabilities! By combining the state system with [`locate`]($func/locate) /// capabilities! By combining the state system with [`locate`]($locate) and
/// and [`query`]($func/query), we can find out what the value of the state will /// [`query`]($query), we can find out what the value of the state will be at
/// be at any position in the document from anywhere else. In particular, the /// any position in the document from anywhere else. In particular, the `at`
/// `at` method gives us the value of the state at any location and the `final` /// method gives us the value of the state at any location and the `final`
/// methods gives us the value of the state at the end of the document. /// methods gives us the value of the state at the end of the document.
/// ///
/// ```example /// ```example
@ -156,7 +156,7 @@ use crate::prelude::*;
/// #compute("x - 5") /// #compute("x - 5")
/// ``` /// ```
/// ///
/// ## A word of caution { #caution } /// # A word of caution { #caution }
/// To resolve the values of all states, Typst evaluates parts of your code /// To resolve the values of all states, Typst evaluates parts of your code
/// multiple times. However, there is no guarantee that your state manipulation /// multiple times. However, there is no guarantee that your state manipulation
/// can actually be completely resolved. /// can actually be completely resolved.
@ -180,73 +180,7 @@ use crate::prelude::*;
/// `locate` calls or `display` calls of state or counters. Instead, pass a /// `locate` calls or `display` calls of state or counters. Instead, pass a
/// function to `update` that determines the value of the state based on its /// function to `update` that determines the value of the state based on its
/// previous value. /// previous value.
/// #[ty(scope)]
/// ## Methods
/// ### display()
/// Displays the value of the state.
///
/// - format: function (positional)
/// A function which receives the value of the state and can return arbitrary
/// content which is then displayed. If this is omitted, the value is directly
/// displayed.
///
/// - returns: content
///
/// ### update()
/// Updates the value of the state.
///
/// The update will be in effect at the position where the returned content is
/// inserted into the document. If you don't put the output into the document,
/// nothing happens! This would be the case, for example, if you write
/// `{let _ = state("key").update(7)}`. State updates are always applied in
/// layout order and in that case, Typst wouldn't know when to update the state.
///
/// - value: any or function (positional, required)
/// If given a non function-value, sets the state to that value. If given a
/// function, that function receives the previous state and has to return the
/// new state.
///
/// - returns: content
///
/// ### at()
/// Gets the value of the state at the given location.
///
/// - location: location (positional, required)
/// The location at which the state's value should be retrieved. A suitable
/// location can be retrieved from [`locate`]($func/locate) or
/// [`query`]($func/query).
///
/// - returns: any
///
/// ### final()
/// Gets the value of the state at the end of the document.
///
/// - location: location (positional, required)
/// Can be an arbitrary location, as its value is irrelevant for the method'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 method within [`locate`]($func/locate) calls,
/// the amount of code that can depend on the method's result is reduced. If
/// you could call `final` directly at the top level of a module, the
/// evaluation of the whole module and its exports could depend on the state's
/// value.
///
/// - returns: any
///
/// Display: State
/// Category: meta
#[func]
pub fn state(
/// The key that identifies this state.
key: Str,
/// The initial value of the state.
#[default]
init: Value,
) -> State {
State { key, init }
}
/// A state.
#[derive(Clone, PartialEq, Hash)] #[derive(Clone, PartialEq, Hash)]
pub struct State { pub struct State {
/// The key that identifies the state. /// The key that identifies the state.
@ -256,49 +190,9 @@ pub struct State {
} }
impl State { impl State {
/// Call a method on a state. /// Create a new state identified by a key.
#[tracing::instrument(skip(vm))] pub fn new(key: Str, init: Value) -> State {
pub fn call_method( Self { key, init }
self,
vm: &mut Vm,
method: &str,
mut args: Args,
span: Span,
) -> SourceResult<Value> {
let value = match method {
"display" => self.display(args.eat()?).into_value(),
"at" => self.at(&mut vm.vt, args.expect("location")?)?,
"final" => self.final_(&mut vm.vt, args.expect("location")?)?,
"update" => self.update(args.expect("value or function")?).into_value(),
_ => bail!(span, "type state has no method `{}`", method),
};
args.finish()?;
Ok(value)
}
/// Display the current value of the state.
pub fn display(self, func: Option<Func>) -> Content {
DisplayElem::new(self, func).pack()
}
/// Get the value of the state at the given location.
#[tracing::instrument(skip(self, vt))]
pub fn at(self, vt: &mut Vt, location: Location) -> SourceResult<Value> {
let sequence = self.sequence(vt)?;
let offset = vt.introspector.query(&self.selector().before(location, true)).len();
Ok(sequence[offset].clone())
}
/// Get the value of the state at the final location.
#[tracing::instrument(skip(self, vt))]
pub fn final_(self, vt: &mut Vt, _: Location) -> SourceResult<Value> {
let sequence = self.sequence(vt)?;
Ok(sequence.last().unwrap().clone())
}
/// Produce content that performs a state update.
pub fn update(self, update: StateUpdate) -> Content {
UpdateElem::new(self.key, update).pack()
} }
/// Produce the whole sequence of states. /// Produce the whole sequence of states.
@ -350,7 +244,94 @@ impl State {
/// The selector for this state's updates. /// The selector for this state's updates.
fn selector(&self) -> Selector { fn selector(&self) -> Selector {
Selector::Elem(UpdateElem::func(), Some(dict! { "key" => self.key.clone() })) Selector::Elem(UpdateElem::elem(), Some(dict! { "key" => self.key.clone() }))
}
}
#[scope]
impl State {
/// Create a new state identified by a key.
#[func(constructor)]
pub fn construct(
/// The key that identifies this state.
key: Str,
/// The initial value of the state.
#[default]
init: Value,
) -> State {
Self::new(key, init)
}
/// Displays the current value of the state.
#[func]
pub fn display(
self,
/// A function which receives the value of the state and can return
/// arbitrary content which is then displayed. If this is omitted, the
/// value is directly displayed.
#[default]
func: Option<Func>,
) -> Content {
DisplayElem::new(self, func).pack()
}
/// Update the value of the state.
///
/// The update will be in effect at the position where the returned content
/// is inserted into the document. If you don't put the output into the
/// document, nothing happens! This would be the case, for example, if you
/// write `{let _ = state("key").update(7)}`. State updates are always
/// applied in layout order and in that case, Typst wouldn't know when to
/// update the state.
#[func]
pub fn update(
self,
/// If given a non function-value, sets the state to that value. If
/// given a function, that function receives the previous state and has
/// to return the new state.
update: StateUpdate,
) -> Content {
UpdateElem::new(self.key, update).pack()
}
/// Get the value of the state at the given location.
#[func]
pub fn at(
&self,
/// The virtual typesetter.
vt: &mut Vt,
/// The location at which the state's value should be retrieved. A
/// suitable location can be retrieved from [`locate`]($locate) or
/// [`query`]($query).
location: Location,
) -> SourceResult<Value> {
let sequence = self.sequence(vt)?;
let offset = vt
.introspector
.query(&self.selector().before(location.into(), true))
.len();
Ok(sequence[offset].clone())
}
/// Get the value of the state at the end of the document.
#[func]
pub fn final_(
&self,
/// The virtual typesetter.
vt: &mut Vt,
/// Can be an arbitrary location, as its value is irrelevant for the
/// method'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 method within
/// [`locate`]($locate) calls, the amount of code that can depend on the
/// method's result is reduced. If you could call `final` directly at
/// the top level of a module, the evaluation of the whole module and
/// its exports could depend on the state's value.
location: Location,
) -> SourceResult<Value> {
let _ = location;
let sequence = self.sequence(vt)?;
Ok(sequence.last().unwrap().clone())
} }
} }
@ -365,10 +346,11 @@ impl Debug for State {
} }
cast! { cast! {
type State: "state", type State,
} }
/// An update to perform on a state. /// An update to perform on a state.
#[ty]
#[derive(Clone, PartialEq, Hash)] #[derive(Clone, PartialEq, Hash)]
pub enum StateUpdate { pub enum StateUpdate {
/// Set the state to the specified value. /// Set the state to the specified value.
@ -384,16 +366,13 @@ impl Debug for StateUpdate {
} }
cast! { cast! {
type StateUpdate: "state update", type StateUpdate,
v: Func => Self::Func(v), v: Func => Self::Func(v),
v: Value => Self::Set(v), v: Value => Self::Set(v),
} }
/// Executes a display of a state. /// Executes a display of a state.
/// #[elem(Locatable, Show)]
/// Display: State
/// Category: special
#[element(Locatable, Show)]
struct DisplayElem { struct DisplayElem {
/// The state. /// The state.
#[required] #[required]
@ -419,10 +398,7 @@ impl Show for DisplayElem {
} }
/// Executes a display of a state. /// Executes a display of a state.
/// #[elem(Locatable, Show)]
/// Display: State
/// Category: special
#[element(Locatable, Show)]
struct UpdateElem { struct UpdateElem {
/// The key that identifies the state. /// The key that identifies the state.
#[required] #[required]

8
crates/typst-library/src/prelude.rs
View File

@ -15,15 +15,15 @@ pub use typst::diag::{bail, error, At, Hint, SourceResult, StrResult};
pub use typst::doc::*; pub use typst::doc::*;
#[doc(no_inline)] #[doc(no_inline)]
pub use typst::eval::{ pub use typst::eval::{
array, cast, dict, format_str, func, Args, Array, AutoValue, Cast, Dict, FromValue, array, cast, dict, format_str, func, scope, ty, Args, Array, Bytes, Cast, Dict,
Func, IntoValue, Never, NoneValue, Scope, Str, Symbol, Type, Value, Vm, FromValue, Func, IntoValue, Scope, Str, Symbol, Type, Value, Vm,
}; };
#[doc(no_inline)] #[doc(no_inline)]
pub use typst::geom::*; pub use typst::geom::*;
#[doc(no_inline)] #[doc(no_inline)]
pub use typst::model::{ pub use typst::model::{
element, Behave, Behaviour, Construct, Content, ElemFunc, Element, Finalize, Fold, elem, Behave, Behaviour, Construct, Content, Element, Finalize, Fold, Introspector,
Introspector, Label, Locatable, LocatableSelector, Location, Locator, MetaElem, Label, Locatable, LocatableSelector, Location, Locator, MetaElem, NativeElement,
PlainText, Resolve, Selector, Set, Show, StyleChain, StyleVec, Styles, Synthesize, PlainText, Resolve, Selector, Set, Show, StyleChain, StyleVec, Styles, Synthesize,
Unlabellable, Vt, Unlabellable, Vt,
}; };

6
crates/typst-library/src/shared/ext.rs
View File

@ -24,7 +24,7 @@ pub trait ContentExt {
fn backlinked(self, loc: Location) -> Self; fn backlinked(self, loc: Location) -> Self;
/// Set alignments for this content. /// Set alignments for this content.
fn aligned(self, aligns: Axes<Option<GenAlign>>) -> Self; fn aligned(self, align: Align) -> Self;
/// Pad this content at the sides. /// Pad this content at the sides.
fn padded(self, padding: Sides<Rel<Length>>) -> Self; fn padded(self, padding: Sides<Rel<Length>>) -> Self;
@ -56,8 +56,8 @@ impl ContentExt for Content {
self.styled(MetaElem::set_data(vec![Meta::Elem(backlink)])) self.styled(MetaElem::set_data(vec![Meta::Elem(backlink)]))
} }
fn aligned(self, aligns: Axes<Option<GenAlign>>) -> Self { fn aligned(self, align: Align) -> Self {
self.styled(AlignElem::set_alignment(aligns)) self.styled(AlignElem::set_alignment(align))
} }
fn padded(self, padding: Sides<Rel<Length>>) -> Self { fn padded(self, padding: Sides<Rel<Length>>) -> Self {

2
crates/typst-library/src/symbols/emoji.rs
View File

@ -6,7 +6,7 @@ pub fn emoji() -> Module {
for (name, symbol) in EMOJI { for (name, symbol) in EMOJI {
scope.define(*name, symbol.clone()); scope.define(*name, symbol.clone());
} }
Module::new("emoji").with_scope(scope) Module::new("emoji", scope)
} }
/// A list of named emoji. /// A list of named emoji.

6
crates/typst-library/src/symbols/mod.rs
View File

@ -10,6 +10,8 @@ use crate::prelude::*;
/// Hook up all symbol definitions. /// Hook up all symbol definitions.
pub(super) fn define(global: &mut Scope) { pub(super) fn define(global: &mut Scope) {
global.define("sym", sym()); global.category("symbols");
global.define("emoji", emoji()); global.define_type::<Symbol>();
global.define_module(sym());
global.define_module(emoji());
} }

2
crates/typst-library/src/symbols/sym.rs
View File

@ -6,7 +6,7 @@ pub fn sym() -> Module {
for (name, symbol) in SYM { for (name, symbol) in SYM {
scope.define(*name, symbol.clone()); scope.define(*name, symbol.clone());
} }
Module::new("sym").with_scope(scope) Module::new("sym", scope)
} }
/// The list of general symbols. /// The list of general symbols.

66
crates/typst-library/src/text/deco.rs
View File

@ -6,19 +6,15 @@ use crate::prelude::*;
/// Underlines text. /// Underlines text.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// This is #underline[important]. /// This is #underline[important].
/// ``` /// ```
/// #[elem(Show)]
/// Display: Underline
/// Category: text
#[element(Show)]
pub struct UnderlineElem { pub struct UnderlineElem {
/// How to stroke the line. /// How to [stroke]($stroke) the line.
/// ///
/// See the [line's documentation]($func/line.stroke) for more details. If /// If set to `{auto}`, takes on the text's color and a thickness defined in
/// set to `{auto}`, takes on the text's color and a thickness defined in
/// the current font. /// the current font.
/// ///
/// ```example /// ```example
@ -30,7 +26,7 @@ pub struct UnderlineElem {
/// ``` /// ```
#[resolve] #[resolve]
#[fold] #[fold]
pub stroke: Smart<PartialStroke>, pub stroke: Smart<Stroke>,
/// The position of the line relative to the baseline, read from the font /// The position of the line relative to the baseline, read from the font
/// tables if `{auto}`. /// tables if `{auto}`.
@ -85,19 +81,15 @@ impl Show for UnderlineElem {
/// Adds a line over text. /// Adds a line over text.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #overline[A line over text.] /// #overline[A line over text.]
/// ``` /// ```
/// #[elem(Show)]
/// Display: Overline
/// Category: text
#[element(Show)]
pub struct OverlineElem { pub struct OverlineElem {
/// How to stroke the line. /// How to [stroke]($stroke) the line.
/// ///
/// See the [line's documentation]($func/line.stroke) for more details. If /// If set to `{auto}`, takes on the text's color and a thickness defined in
/// set to `{auto}`, takes on the text's color and a thickness defined in
/// the current font. /// the current font.
/// ///
/// ```example /// ```example
@ -110,7 +102,7 @@ pub struct OverlineElem {
/// ``` /// ```
#[resolve] #[resolve]
#[fold] #[fold]
pub stroke: Smart<PartialStroke>, pub stroke: Smart<Stroke>,
/// The position of the line relative to the baseline. Read from the font /// The position of the line relative to the baseline. Read from the font
/// tables if `{auto}`. /// tables if `{auto}`.
@ -170,23 +162,19 @@ impl Show for OverlineElem {
/// Strikes through text. /// Strikes through text.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// This is #strike[not] relevant. /// This is #strike[not] relevant.
/// ``` /// ```
/// #[elem(title = "Strikethrough", Show)]
/// Display: Strikethrough
/// Category: text
#[element(Show)]
pub struct StrikeElem { pub struct StrikeElem {
/// How to stroke the line. /// How to [stroke]($stroke) the line.
/// ///
/// See the [line's documentation]($func/line.stroke) for more details. If /// If set to `{auto}`, takes on the text's color and a thickness defined in
/// set to `{auto}`, takes on the text's color and a thickness defined in
/// the current font. /// the current font.
/// ///
/// _Note:_ Please don't use this for real redaction as you can still /// _Note:_ Please don't use this for real redaction as you can still copy
/// copy paste the text. /// paste the text.
/// ///
/// ```example /// ```example
/// This is #strike(stroke: 1.5pt + red)[very stricken through]. \ /// This is #strike(stroke: 1.5pt + red)[very stricken through]. \
@ -194,7 +182,7 @@ pub struct StrikeElem {
/// ``` /// ```
#[resolve] #[resolve]
#[fold] #[fold]
pub stroke: Smart<PartialStroke>, pub stroke: Smart<Stroke>,
/// The position of the line relative to the baseline. Read from the font /// The position of the line relative to the baseline. Read from the font
/// tables if `{auto}`. /// tables if `{auto}`.
@ -240,14 +228,11 @@ impl Show for StrikeElem {
/// Highlights text with a background color. /// Highlights text with a background color.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// This is #highlight[important]. /// This is #highlight[important].
/// ``` /// ```
/// #[elem(Show)]
/// Display: Highlight
/// Category: text
#[element(Show)]
pub struct HighlightElem { pub struct HighlightElem {
/// The color to highlight the text with. /// The color to highlight the text with.
/// (Default: 0xffff5f) /// (Default: 0xffff5f)
@ -316,6 +301,7 @@ impl Show for HighlightElem {
/// Defines a line-based decoration that is positioned over, under or on top of text, /// Defines a line-based decoration that is positioned over, under or on top of text,
/// or highlights the text with a background. /// or highlights the text with a background.
#[ty]
#[derive(Debug, Clone, Eq, PartialEq, Hash)] #[derive(Debug, Clone, Eq, PartialEq, Hash)]
pub struct Decoration { pub struct Decoration {
line: DecoLine, line: DecoLine,
@ -332,15 +318,15 @@ impl Fold for Decoration {
} }
cast! { cast! {
type Decoration: "decoration", type Decoration,
} }
/// A kind of decorative line. /// A kind of decorative line.
#[derive(Debug, Clone, Eq, PartialEq, Hash)] #[derive(Debug, Clone, Eq, PartialEq, Hash)]
enum DecoLine { enum DecoLine {
Underline { stroke: PartialStroke<Abs>, offset: Smart<Abs>, evade: bool }, Underline { stroke: Stroke<Abs>, offset: Smart<Abs>, evade: bool },
Strikethrough { stroke: PartialStroke<Abs>, offset: Smart<Abs> }, Strikethrough { stroke: Stroke<Abs>, offset: Smart<Abs> },
Overline { stroke: PartialStroke<Abs>, offset: Smart<Abs>, evade: bool }, Overline { stroke: Stroke<Abs>, offset: Smart<Abs>, evade: bool },
Highlight { fill: Paint, top_edge: TopEdge, bottom_edge: BottomEdge }, Highlight { fill: Paint, top_edge: TopEdge, bottom_edge: BottomEdge },
} }
@ -378,10 +364,10 @@ pub(super) fn decorate(
}; };
let offset = offset.unwrap_or(-metrics.position.at(text.size)) - shift; let offset = offset.unwrap_or(-metrics.position.at(text.size)) - shift;
let stroke = stroke.clone().unwrap_or(Stroke { let stroke = stroke.clone().unwrap_or(FixedStroke {
paint: text.fill.clone(), paint: text.fill.clone(),
thickness: metrics.thickness.at(text.size), thickness: metrics.thickness.at(text.size),
..Stroke::default() ..FixedStroke::default()
}); });
let gap_padding = 0.08 * text.size; let gap_padding = 0.08 * text.size;

68
crates/typst-library/src/text/misc.rs
View File

@ -2,10 +2,7 @@ use super::TextElem;
use crate::prelude::*; use crate::prelude::*;
/// A text space. /// A text space.
/// #[elem(Behave, Unlabellable, PlainText)]
/// Display: Space
/// Category: text
#[element(Behave, Unlabellable, PlainText)]
pub struct SpaceElem {} pub struct SpaceElem {}
impl Behave for SpaceElem { impl Behave for SpaceElem {
@ -28,21 +25,18 @@ impl PlainText for SpaceElem {
/// end of a paragraph is ignored, but more than one creates additional empty /// end of a paragraph is ignored, but more than one creates additional empty
/// lines. /// lines.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// *Date:* 26.12.2022 \ /// *Date:* 26.12.2022 \
/// *Topic:* Infrastructure Test \ /// *Topic:* Infrastructure Test \
/// *Severity:* High \ /// *Severity:* High \
/// ``` /// ```
/// ///
/// ## Syntax { #syntax } /// # Syntax
/// This function also has dedicated syntax: To insert a line break, simply write /// This function also has dedicated syntax: To insert a line break, simply write
/// a backslash followed by whitespace. This always creates an unjustified /// a backslash followed by whitespace. This always creates an unjustified
/// break. /// break.
/// #[elem(title = "Line Break", Behave)]
/// Display: Line Break
/// Category: text
#[element(Behave)]
pub struct LinebreakElem { pub struct LinebreakElem {
/// Whether to justify the line before the break. /// Whether to justify the line before the break.
/// ///
@ -71,7 +65,7 @@ impl Behave for LinebreakElem {
/// ///
/// Increases the current font weight by a given `delta`. /// Increases the current font weight by a given `delta`.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// This is *strong.* \ /// This is *strong.* \
/// This is #strong[too.] \ /// This is #strong[too.] \
@ -80,15 +74,12 @@ impl Behave for LinebreakElem {
/// And this is *evermore.* /// And this is *evermore.*
/// ``` /// ```
/// ///
/// ## Syntax { #syntax } /// # Syntax
/// This function also has dedicated syntax: To strongly emphasize content, /// This function also has dedicated syntax: To strongly emphasize content,
/// simply enclose it in stars/asterisks (`*`). Note that this only works at /// simply enclose it in stars/asterisks (`*`). Note that this only works at
/// word boundaries. To strongly emphasize part of a word, you have to use the /// word boundaries. To strongly emphasize part of a word, you have to use the
/// function. /// function.
/// #[elem(title = "Strong Emphasis", Show)]
/// Display: Strong Emphasis
/// Category: text
#[element(Show)]
pub struct StrongElem { pub struct StrongElem {
/// The delta to apply on the font weight. /// The delta to apply on the font weight.
/// ///
@ -131,12 +122,12 @@ impl Fold for Delta {
/// Emphasizes content by setting it in italics. /// Emphasizes content by setting it in italics.
/// ///
/// - If the current [text style]($func/text.style) is `{"normal"}`, /// - If the current [text style]($text.style) is `{"normal"}`, this turns it
/// this turns it into `{"italic"}`. /// into `{"italic"}`.
/// - If it is already `{"italic"}` or `{"oblique"}`, /// - If it is already `{"italic"}` or `{"oblique"}`, it turns it back to
/// it turns it back to `{"normal"}`. /// `{"normal"}`.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// This is _emphasized._ \ /// This is _emphasized._ \
/// This is #emph[too.] /// This is #emph[too.]
@ -148,14 +139,11 @@ impl Fold for Delta {
/// This is _emphasized_ differently. /// This is _emphasized_ differently.
/// ``` /// ```
/// ///
/// ## Syntax { #syntax } /// # Syntax
/// This function also has dedicated syntax: To emphasize content, simply /// This function also has dedicated syntax: To emphasize content, simply
/// enclose it in underscores (`_`). Note that this only works at word /// enclose it in underscores (`_`). Note that this only works at word
/// boundaries. To emphasize part of a word, you have to use the function. /// boundaries. To emphasize part of a word, you have to use the function.
/// #[elem(title = "Emphasis", Show)]
/// Display: Emphasis
/// Category: text
#[element(Show)]
pub struct EmphElem { pub struct EmphElem {
/// The content to emphasize. /// The content to emphasize.
#[required] #[required]
@ -189,16 +177,13 @@ impl Fold for Toggle {
/// Converts text or content to lowercase. /// Converts text or content to lowercase.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #lower("ABC") \ /// #lower("ABC") \
/// #lower[*My Text*] \ /// #lower[*My Text*] \
/// #lower[already low] /// #lower[already low]
/// ``` /// ```
/// #[func(title = "Lowercase")]
/// Display: Lowercase
/// Category: text
#[func]
pub fn lower( pub fn lower(
/// The text to convert to lowercase. /// The text to convert to lowercase.
text: Caseable, text: Caseable,
@ -208,16 +193,13 @@ pub fn lower(
/// Converts text or content to uppercase. /// Converts text or content to uppercase.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #upper("abc") \ /// #upper("abc") \
/// #upper[*my text*] \ /// #upper[*my text*] \
/// #upper[ALREADY HIGH] /// #upper[ALREADY HIGH]
/// ``` /// ```
/// #[func(title = "Uppercase")]
/// Display: Uppercase
/// Category: text
#[func]
pub fn upper( pub fn upper(
/// The text to convert to uppercase. /// The text to convert to uppercase.
text: Caseable, text: Caseable,
@ -278,7 +260,7 @@ impl Case {
/// support selecting a dedicated smallcaps font as well as synthesizing /// support selecting a dedicated smallcaps font as well as synthesizing
/// smallcaps from normal letters, but this is not yet implemented. /// smallcaps from normal letters, but this is not yet implemented.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #set par(justify: true) /// #set par(justify: true)
/// #set heading(numbering: "I.") /// #set heading(numbering: "I.")
@ -292,10 +274,7 @@ impl Case {
/// = Introduction /// = Introduction
/// #lorem(40) /// #lorem(40)
/// ``` /// ```
/// #[func(title = "Small Capitals")]
/// Display: Small Capitals
/// Category: text
#[func]
pub fn smallcaps( pub fn smallcaps(
/// The text to display to small capitals. /// The text to display to small capitals.
body: Content, body: Content,
@ -310,7 +289,7 @@ pub fn smallcaps(
/// the same but randomly chosen. As usual for blind texts, it does not make any /// the same but randomly chosen. As usual for blind texts, it does not make any
/// sense. Use it as a placeholder to try layouts. /// sense. Use it as a placeholder to try layouts.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// = Blind Text /// = Blind Text
/// #lorem(30) /// #lorem(30)
@ -318,10 +297,7 @@ pub fn smallcaps(
/// = More Blind Text /// = More Blind Text
/// #lorem(15) /// #lorem(15)
/// ``` /// ```
/// #[func(keywords = ["Blind Text"])]
/// Display: Blind Text
/// Category: text
#[func]
pub fn lorem( pub fn lorem(
/// The length of the blind text in words. /// The length of the blind text in words.
words: usize, words: usize,

68
crates/typst-library/src/text/mod.rs
View File

@ -23,22 +23,23 @@ use crate::prelude::*;
/// Hook up all text definitions. /// Hook up all text definitions.
pub(super) fn define(global: &mut Scope) { pub(super) fn define(global: &mut Scope) {
global.define("text", TextElem::func()); global.category("text");
global.define("linebreak", LinebreakElem::func()); global.define_elem::<TextElem>();
global.define("smartquote", SmartQuoteElem::func()); global.define_elem::<LinebreakElem>();
global.define("strong", StrongElem::func()); global.define_elem::<SmartquoteElem>();
global.define("emph", EmphElem::func()); global.define_elem::<StrongElem>();
global.define("lower", lower_func()); global.define_elem::<EmphElem>();
global.define("upper", upper_func()); global.define_elem::<SubElem>();
global.define("smallcaps", smallcaps_func()); global.define_elem::<SuperElem>();
global.define("sub", SubElem::func()); global.define_elem::<UnderlineElem>();
global.define("super", SuperElem::func()); global.define_elem::<OverlineElem>();
global.define("underline", UnderlineElem::func()); global.define_elem::<StrikeElem>();
global.define("strike", StrikeElem::func()); global.define_elem::<HighlightElem>();
global.define("highlight", HighlightElem::func()); global.define_elem::<RawElem>();
global.define("overline", OverlineElem::func()); global.define_func::<lower>();
global.define("raw", RawElem::func()); global.define_func::<upper>();
global.define("lorem", lorem_func()); global.define_func::<smallcaps>();
global.define_func::<lorem>();
} }
/// Customizes the look and layout of text in a variety of ways. /// Customizes the look and layout of text in a variety of ways.
@ -47,7 +48,7 @@ pub(super) fn define(global: &mut Scope) {
/// the set rule is often the simpler choice, calling the `text` function /// the set rule is often the simpler choice, calling the `text` function
/// directly can be useful when passing text as an argument to another function. /// directly can be useful when passing text as an argument to another function.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #set text(18pt) /// #set text(18pt)
/// With a set rule. /// With a set rule.
@ -56,10 +57,7 @@ pub(super) fn define(global: &mut Scope) {
/// With a function call. /// With a function call.
/// ]) /// ])
/// ``` /// ```
/// #[elem(Construct, PlainText)]
/// Display: Text
/// Category: text
#[element(Construct, PlainText)]
pub struct TextElem { pub struct TextElem {
/// A prioritized sequence of font families. /// A prioritized sequence of font families.
/// ///
@ -111,8 +109,8 @@ pub struct TextElem {
/// italic and oblique style is rarely observable. /// italic and oblique style is rarely observable.
/// ///
/// If you want to emphasize your text, you should do so using the /// If you want to emphasize your text, you should do so using the
/// [emph]($func/emph) function instead. This makes it easy to adapt the /// [emph]($emph) function instead. This makes it easy to adapt the style
/// style later if you change your mind about how to signify the emphasis. /// later if you change your mind about how to signify the emphasis.
/// ///
/// ```example /// ```example
/// #text(font: "Linux Libertine", style: "italic")[Italic] /// #text(font: "Linux Libertine", style: "italic")[Italic]
@ -126,7 +124,7 @@ pub struct TextElem {
/// that is closest in weight. /// that is closest in weight.
/// ///
/// If you want to strongly emphasize your text, you should do so using the /// If you want to strongly emphasize your text, you should do so using the
/// [strong]($func/strong) function instead. This makes it easy to adapt the /// [strong]($strong) function instead. This makes it easy to adapt the
/// style later if you change your mind about how to signify the strong /// style later if you change your mind about how to signify the strong
/// emphasis. /// emphasis.
/// ///
@ -147,7 +145,7 @@ pub struct TextElem {
/// the text if a condensed or expanded version of the font is available. /// the text if a condensed or expanded version of the font is available.
/// ///
/// If you want to adjust the amount of space between characters instead of /// If you want to adjust the amount of space between characters instead of
/// stretching the glyphs itself, use the [`tracking`]($func/text.tracking) /// stretching the glyphs itself, use the [`tracking`]($text.tracking)
/// property instead. /// property instead.
/// ///
/// ```example /// ```example
@ -196,7 +194,7 @@ pub struct TextElem {
/// the space character in the font. /// the space character in the font.
/// ///
/// If you want to adjust the amount of space between characters rather than /// If you want to adjust the amount of space between characters rather than
/// words, use the [`tracking`]($func/text.tracking) property instead. /// words, use the [`tracking`]($text.tracking) property instead.
/// ///
/// ```example /// ```example
/// #set text(spacing: 200%) /// #set text(spacing: 200%)
@ -272,7 +270,7 @@ pub struct TextElem {
/// ///
/// - The text processing pipeline can make more informed choices. /// - The text processing pipeline can make more informed choices.
/// - Hyphenation will use the correct patterns for the language. /// - Hyphenation will use the correct patterns for the language.
/// - [Smart quotes]($func/smartquote) turns into the correct quotes for the /// - [Smart quotes]($smartquote) turns into the correct quotes for the
/// language. /// language.
/// - And all other things which are language-aware. /// - And all other things which are language-aware.
/// ///
@ -327,13 +325,13 @@ pub struct TextElem {
/// - `{rtl}`: Layout text from right to left. /// - `{rtl}`: Layout text from right to left.
/// ///
/// When writing in right-to-left scripts like Arabic or Hebrew, you should /// When writing in right-to-left scripts like Arabic or Hebrew, you should
/// set the [text language]($func/text.lang) or direction. While individual /// set the [text language]($text.lang) or direction. While individual runs
/// runs of text are automatically layouted in the correct direction, /// of text are automatically layouted in the correct direction, setting the
/// setting the dominant direction gives the bidirectional reordering /// dominant direction gives the bidirectional reordering algorithm the
/// algorithm the necessary information to correctly place punctuation and /// necessary information to correctly place punctuation and inline objects.
/// inline objects. Furthermore, setting the direction affects the alignment /// Furthermore, setting the direction affects the alignment values `start`
/// values `start` and `end`, which are equivalent to `left` and `right` in /// and `end`, which are equivalent to `left` and `right` in `ltr` text and
/// `ltr` text and the other way around in `rtl` text. /// the other way around in `rtl` text.
/// ///
/// If you set this to `rtl` and experience bugs or in some way bad looking /// If you set this to `rtl` and experience bugs or in some way bad looking
/// output, please do get in touch with us through the /// output, please do get in touch with us through the
@ -350,7 +348,7 @@ pub struct TextElem {
/// Whether to hyphenate text to improve line breaking. When `{auto}`, text /// Whether to hyphenate text to improve line breaking. When `{auto}`, text
/// will be hyphenated if and only if justification is enabled. /// will be hyphenated if and only if justification is enabled.
/// ///
/// Setting the [text language]($func/text.lang) ensures that the correct /// Setting the [text language]($text.lang) ensures that the correct
/// hyphenation patterns are used. /// hyphenation patterns are used.
/// ///
/// ```example /// ```example

13
crates/typst-library/src/text/quotes.rs
View File

@ -5,9 +5,9 @@ use crate::prelude::*;
/// A language-aware quote that reacts to its context. /// A language-aware quote that reacts to its context.
/// ///
/// Automatically turns into an appropriate opening or closing quote based on /// Automatically turns into an appropriate opening or closing quote based on
/// the active [text language]($func/text.lang). /// the active [text language]($text.lang).
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// "This is in quotes." /// "This is in quotes."
/// ///
@ -18,14 +18,11 @@ use crate::prelude::*;
/// "C'est entre guillemets." /// "C'est entre guillemets."
/// ``` /// ```
/// ///
/// ## Syntax { #syntax } /// # Syntax
/// This function also has dedicated syntax: The normal quote characters /// This function also has dedicated syntax: The normal quote characters
/// (`'` and `"`). Typst automatically makes your quotes smart. /// (`'` and `"`). Typst automatically makes your quotes smart.
/// #[elem]
/// Display: Smart Quote pub struct SmartquoteElem {
/// Category: text
#[element]
pub struct SmartQuoteElem {
/// Whether this should be a double quote. /// Whether this should be a double quote.
#[default(true)] #[default(true)]
pub double: bool, pub double: bool,

35
crates/typst-library/src/text/raw.rs
View File

@ -12,7 +12,7 @@ use typst::util::option_eq;
use unicode_segmentation::UnicodeSegmentation; use unicode_segmentation::UnicodeSegmentation;
use super::{ use super::{
FontFamily, FontList, Hyphenate, LinebreakElem, SmartQuoteElem, TextElem, TextSize, FontFamily, FontList, Hyphenate, LinebreakElem, SmartquoteElem, TextElem, TextSize,
}; };
use crate::layout::BlockElem; use crate::layout::BlockElem;
use crate::meta::{Figurable, LocalName}; use crate::meta::{Figurable, LocalName};
@ -23,7 +23,7 @@ use crate::prelude::*;
/// Displays the text verbatim and in a monospace font. This is typically used /// Displays the text verbatim and in a monospace font. This is typically used
/// to embed computer code into your document. /// to embed computer code into your document.
/// ///
/// ## Example { #example } /// # Example
/// ````example /// ````example
/// Adding `rbx` to `rcx` gives /// Adding `rbx` to `rcx` gives
/// the desired result. /// the desired result.
@ -43,7 +43,7 @@ use crate::prelude::*;
/// also trimmed. /// also trimmed.
/// ```` /// ````
/// ///
/// ## Syntax { #syntax } /// # Syntax
/// This function also has dedicated syntax. You can enclose text in 1 or 3+ /// This function also has dedicated syntax. You can enclose text in 1 or 3+
/// backticks (`` ` ``) to make it raw. Two backticks produce empty raw text. /// backticks (`` ` ``) to make it raw. Two backticks produce empty raw text.
/// When you use three or more backticks, you can additionally specify a /// When you use three or more backticks, you can additionally specify a
@ -57,10 +57,15 @@ use crate::prelude::*;
/// needed, start the text with a single space (which will be trimmed) or use /// needed, start the text with a single space (which will be trimmed) or use
/// the single backtick syntax. If your text should start or end with a /// the single backtick syntax. If your text should start or end with a
/// backtick, put a space before or after it (it will be trimmed). /// backtick, put a space before or after it (it will be trimmed).
/// #[elem(
/// Display: Raw Text / Code title = "Raw Text / Code",
/// Category: text Synthesize,
#[element(Synthesize, Show, Finalize, LocalName, Figurable, PlainText)] Show,
Finalize,
LocalName,
Figurable,
PlainText
)]
pub struct RawElem { pub struct RawElem {
/// The raw text. /// The raw text.
/// ///
@ -153,8 +158,8 @@ pub struct RawElem {
/// code = "centered" /// code = "centered"
/// ``` /// ```
/// ```` /// ````
#[default(HorizontalAlign(GenAlign::Start))] #[default(HAlign::Start)]
pub align: HorizontalAlign, pub align: HAlign,
/// One or multiple additional syntax definitions to load. The syntax /// One or multiple additional syntax definitions to load. The syntax
/// definitions should be in the /// definitions should be in the
@ -190,10 +195,10 @@ pub struct RawElem {
/// Applying a theme only affects the color of specifically highlighted /// Applying a theme only affects the color of specifically highlighted
/// text. It does not consider the theme's foreground and background /// text. It does not consider the theme's foreground and background
/// properties, so that you retain control over the color of raw text. You /// properties, so that you retain control over the color of raw text. You
/// can apply the foreground color yourself with the [`text`]($func/text) /// can apply the foreground color yourself with the [`text`]($text)
/// function and the background with a [filled block]($func/block.fill). You /// function and the background with a [filled block]($block.fill). You
/// could also use the [`xml`]($func/xml) function to extract these /// could also use the [`xml`]($xml) function to extract these properties
/// properties from the theme. /// from the theme.
/// ///
/// ````example /// ````example
/// #set raw(theme: "halcyon.tmTheme") /// #set raw(theme: "halcyon.tmTheme")
@ -340,7 +345,7 @@ impl Show for RawElem {
if self.block(styles) { if self.block(styles) {
// Align the text before inserting it into the block. // Align the text before inserting it into the block.
realized = realized.aligned(Axes::with_x(Some(self.align(styles).into()))); realized = realized.aligned(self.align(styles).into());
realized = BlockElem::new().with_body(Some(realized)).pack(); realized = BlockElem::new().with_body(Some(realized)).pack();
} }
@ -356,7 +361,7 @@ impl Finalize for RawElem {
styles.set(TextElem::set_size(TextSize(Em::new(0.8).into()))); styles.set(TextElem::set_size(TextSize(Em::new(0.8).into())));
styles styles
.set(TextElem::set_font(FontList(vec![FontFamily::new("DejaVu Sans Mono")]))); .set(TextElem::set_font(FontList(vec![FontFamily::new("DejaVu Sans Mono")])));
styles.set(SmartQuoteElem::set_enabled(false)); styles.set(SmartquoteElem::set_enabled(false));
realized.styled_with_map(styles) realized.styled_with_map(styles)
} }
} }

14
crates/typst-library/src/text/shift.rs
View File

@ -5,14 +5,11 @@ use crate::prelude::*;
/// ///
/// The text is rendered smaller and its baseline is lowered. /// The text is rendered smaller and its baseline is lowered.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// Revenue#sub[yearly] /// Revenue#sub[yearly]
/// ``` /// ```
/// #[elem(title = "Subscript", Show)]
/// Display: Subscript
/// Category: text
#[element(Show)]
pub struct SubElem { pub struct SubElem {
/// Whether to prefer the dedicated subscript characters of the font. /// Whether to prefer the dedicated subscript characters of the font.
/// ///
@ -68,14 +65,11 @@ impl Show for SubElem {
/// ///
/// The text is rendered smaller and its baseline is raised. /// The text is rendered smaller and its baseline is raised.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// 1#super[st] try! /// 1#super[st] try!
/// ``` /// ```
/// #[elem(title = "Superscript", Show)]
/// Display: Superscript
/// Category: text
#[element(Show)]
pub struct SuperElem { pub struct SuperElem {
/// Whether to prefer the dedicated superscript characters of the font. /// Whether to prefer the dedicated superscript characters of the font.
/// ///

29
crates/typst-library/src/visualize/image.rs
View File

@ -18,7 +18,7 @@ use crate::text::families;
/// in the resulting PDF. Make sure to double-check embedded SVG images. If you /// in the resulting PDF. Make sure to double-check embedded SVG images. If you
/// have an issue, also feel free to report it on [GitHub][gh-svg]. /// have an issue, also feel free to report it on [GitHub][gh-svg].
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #figure( /// #figure(
/// image("molecular.jpg", width: 80%), /// image("molecular.jpg", width: 80%),
@ -30,14 +30,7 @@ use crate::text::families;
/// ``` /// ```
/// ///
/// [gh-svg]: https://github.com/typst/typst/issues?q=is%3Aopen+is%3Aissue+label%3Asvg /// [gh-svg]: https://github.com/typst/typst/issues?q=is%3Aopen+is%3Aissue+label%3Asvg
/// #[elem(scope, Layout, LocalName, Figurable)]
/// Display: Image
/// Category: visualize
#[element(Layout, LocalName, Figurable)]
#[scope(
scope.define("decode", image_decode_func());
scope
)]
pub struct ImageElem { pub struct ImageElem {
/// Path to an image file. /// Path to an image file.
#[required] #[required]
@ -73,24 +66,22 @@ pub struct ImageElem {
pub fit: ImageFit, pub fit: ImageFit,
} }
#[scope]
impl ImageElem {
/// Decode a raster or vector graphic from bytes or a string. /// Decode a raster or vector graphic from bytes or a string.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #let original = read("diagram.svg") /// #let original = read("diagram.svg")
/// #let changed = original.replace( /// #let changed = original.replace(
/// "#2B80FF", // blue /// "#2B80FF", // blue
/// green.hex(), /// green.to-hex(),
/// ) /// )
/// ///
/// #image.decode(original) /// #image.decode(original)
/// #image.decode(changed) /// #image.decode(changed)
/// ``` /// ```
/// #[func(title = "Decode Image")]
/// Display: Decode Image pub fn decode(
/// Category: visualize
#[func]
pub fn image_decode(
/// The data to decode as an image. Can be a string for SVGs. /// The data to decode as an image. Can be a string for SVGs.
data: Readable, data: Readable,
/// The image's format. Detected automatically by default. /// The image's format. Detected automatically by default.
@ -127,6 +118,7 @@ pub fn image_decode(
} }
Ok(elem.pack()) Ok(elem.pack())
} }
}
impl Layout for ImageElem { impl Layout for ImageElem {
#[tracing::instrument(name = "ImageElem::layout", skip_all)] #[tracing::instrument(name = "ImageElem::layout", skip_all)]
@ -175,8 +167,7 @@ impl Layout for ImageElem {
let sizing = Axes::new(self.width(styles), self.height(styles)); let sizing = Axes::new(self.width(styles), self.height(styles));
let region = sizing let region = sizing
.zip(regions.base()) .zip_map(regions.base(), |s, r| s.map(|v| v.resolve(styles).relative_to(r)))
.map(|(s, r)| s.map(|v| v.resolve(styles).relative_to(r)))
.unwrap_or(regions.base()); .unwrap_or(regions.base());
let expand = sizing.as_ref().map(Smart::is_custom) | regions.expand; let expand = sizing.as_ref().map(Smart::is_custom) | regions.expand;
@ -217,7 +208,7 @@ impl Layout for ImageElem {
// process. // process.
let mut frame = Frame::new(fitted); let mut frame = Frame::new(fitted);
frame.push(Point::zero(), FrameItem::Image(image, fitted, self.span())); frame.push(Point::zero(), FrameItem::Image(image, fitted, self.span()));
frame.resize(target, Align::CENTER_HORIZON); frame.resize(target, Axes::splat(FixedAlign::Center));
// Create a clipping group if only part of the image should be visible. // Create a clipping group if only part of the image should be visible.
if fit == ImageFit::Cover && !target.fits(fitted) { if fit == ImageFit::Cover && !target.fits(fitted) {

52
crates/typst-library/src/visualize/line.rs
View File

@ -2,7 +2,7 @@ use crate::prelude::*;
/// A line from one point to another. /// A line from one point to another.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #set page(height: 100pt) /// #set page(height: 100pt)
/// ///
@ -13,10 +13,7 @@ use crate::prelude::*;
/// stroke: 2pt + maroon, /// stroke: 2pt + maroon,
/// ) /// )
/// ``` /// ```
/// #[elem(Layout)]
/// Display: Line
/// Category: visualize
#[element(Layout)]
pub struct LineElem { pub struct LineElem {
/// The start point of the line. /// The start point of the line.
/// ///
@ -37,42 +34,7 @@ pub struct LineElem {
/// respected if `end` is `none`. /// respected if `end` is `none`.
pub angle: Angle, pub angle: Angle,
/// How to stroke the line. This can be: /// How to [stroke]($stroke) the line.
///
/// - A length specifying the stroke's thickness. The color is inherited,
/// defaulting to black.
/// - A color to use for the stroke. The thickness is inherited, defaulting
/// to `{1pt}`.
/// - A stroke combined from color and thickness using the `+` operator as
/// in `{2pt + red}`.
/// - A stroke described by a dictionary with any of the following keys:
/// - `paint`: The [color]($type/color) to use for the stroke.
/// - `thickness`: The stroke's thickness as a [length]($type/length).
/// - `cap`: How the line terminates. One of `{"butt"}`, `{"round"}`, or
/// `{"square"}`.
/// - `join`: How sharp turns of a contour are rendered. One of
/// `{"miter"}`, `{"round"}`, or `{"bevel"}`. Not applicable to lines
/// but to [polygons]($func/polygon) or [paths]($func/path).
/// - `miter-limit`: Number at which protruding sharp angles are rendered
/// with a bevel instead. The higher the number, the sharper an angle
/// can be before it is bevelled. Only applicable if `join` is
/// `{"miter"}`. Defaults to `{4.0}`.
/// - `dash`: The dash pattern to use. Can be any of the following:
/// - One of the predefined patterns `{"solid"}`, `{"dotted"}`,
/// `{"densely-dotted"}`, `{"loosely-dotted"}`, `{"dashed"}`,
/// `{"densely-dashed"}`, `{"loosely-dashed"}`, `{"dash-dotted"}`,
/// `{"densely-dash-dotted"}` or `{"loosely-dash-dotted"}`
/// - An [array]($type/array) with alternating lengths for dashes and
/// gaps. You can also use the string `{"dot"}` for a length equal to
/// the line thickness.
/// - A [dictionary]($type/dictionary) with the keys `array` (same as
/// the array above), and `phase` (of type [length]($type/length)),
/// which defines where in the pattern to start drawing.
///
/// On a `stroke` object, you can access any of the fields mentioned in the
/// dictionary format above. For example, `{(2pt + blue).thickness}` is
/// `{2pt}`, `{(2pt + blue).miter-limit}` is `{4.0}` (the default), and so
/// on.
/// ///
/// ```example /// ```example
/// #set line(length: 100%) /// #set line(length: 100%)
@ -86,7 +48,7 @@ pub struct LineElem {
/// ``` /// ```
#[resolve] #[resolve]
#[fold] #[fold]
pub stroke: PartialStroke, pub stroke: Stroke,
} }
impl Layout for LineElem { impl Layout for LineElem {
@ -97,10 +59,8 @@ impl Layout for LineElem {
styles: StyleChain, styles: StyleChain,
regions: Regions, regions: Regions,
) -> SourceResult<Fragment> { ) -> SourceResult<Fragment> {
let resolve = |axes: Axes<Rel<Abs>>| { let resolve =
axes.zip(regions.base()).map(|(l, b)| l.relative_to(b)) |axes: Axes<Rel<Abs>>| axes.zip_map(regions.base(), Rel::relative_to);
};
let start = resolve(self.start(styles)); let start = resolve(self.start(styles));
let delta = let delta =
self.end(styles).map(|end| resolve(end) - start).unwrap_or_else(|| { self.end(styles).map(|end| resolve(end) - start).unwrap_or_else(|| {

37
crates/typst-library/src/visualize/mod.rs
View File

@ -16,30 +16,15 @@ use crate::prelude::*;
/// Hook up all visualize definitions. /// Hook up all visualize definitions.
pub(super) fn define(global: &mut Scope) { pub(super) fn define(global: &mut Scope) {
global.define("image", ImageElem::func()); global.category("visualize");
global.define("line", LineElem::func()); global.define_type::<Color>();
global.define("rect", RectElem::func()); global.define_type::<Stroke>();
global.define("square", SquareElem::func()); global.define_elem::<ImageElem>();
global.define("ellipse", EllipseElem::func()); global.define_elem::<LineElem>();
global.define("circle", CircleElem::func()); global.define_elem::<RectElem>();
global.define("polygon", PolygonElem::func()); global.define_elem::<SquareElem>();
global.define("path", PathElem::func()); global.define_elem::<EllipseElem>();
global.define("black", Color::BLACK); global.define_elem::<CircleElem>();
global.define("gray", Color::GRAY); global.define_elem::<PolygonElem>();
global.define("silver", Color::SILVER); global.define_elem::<PathElem>();
global.define("white", Color::WHITE);
global.define("navy", Color::NAVY);
global.define("blue", Color::BLUE);
global.define("aqua", Color::AQUA);
global.define("teal", Color::TEAL);
global.define("eastern", Color::EASTERN);
global.define("purple", Color::PURPLE);
global.define("fuchsia", Color::FUCHSIA);
global.define("maroon", Color::MAROON);
global.define("red", Color::RED);
global.define("orange", Color::ORANGE);
global.define("yellow", Color::YELLOW);
global.define("olive", Color::OLIVE);
global.define("green", Color::GREEN);
global.define("lime", Color::LIME);
} }

39
crates/typst-library/src/visualize/path.rs
View File

@ -7,7 +7,7 @@ use PathVertex::{AllControlPoints, MirroredControlPoint, Vertex};
/// A path through a list of points, connected by Bezier curves. /// A path through a list of points, connected by Bezier curves.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #path( /// #path(
/// fill: blue.lighten(80%), /// fill: blue.lighten(80%),
@ -18,26 +18,24 @@ use PathVertex::{AllControlPoints, MirroredControlPoint, Vertex};
/// ((50%, 0pt), (40pt, 0pt)), /// ((50%, 0pt), (40pt, 0pt)),
/// ) /// )
/// ``` /// ```
/// #[elem(Layout)]
/// Display: Path
/// Category: visualize
#[element(Layout)]
pub struct PathElem { pub struct PathElem {
/// How to fill the path. See the /// How to fill the path.
/// [rectangle's documentation]($func/rect.fill) for more details.
/// ///
/// Currently all paths are filled according to the /// When setting a fill, the default stroke disappears. To create a
/// [non-zero winding rule](https://en.wikipedia.org/wiki/Nonzero-rule). /// rectangle with both fill and stroke, you have to configure both.
///
/// Currently all paths are filled according to the [non-zero winding
/// rule](https://en.wikipedia.org/wiki/Nonzero-rule).
pub fill: Option<Paint>, pub fill: Option<Paint>,
/// How to stroke the path. This can be: /// How to [stroke]($stroke) the path. This can be:
/// ///
/// See the [line's documentation]($func/line.stroke) for more details. Can /// Can be set to `{none}` to disable the stroke or to `{auto}` for a
/// be set to `{none}` to disable the stroke or to `{auto}` for a stroke of /// stroke of `{1pt}` black if and if only if no fill is given.
/// `{1pt}` black if and if only if no fill is given.
#[resolve] #[resolve]
#[fold] #[fold]
pub stroke: Smart<Option<PartialStroke>>, pub stroke: Smart<Option<Stroke>>,
/// Whether to close this path with one last bezier curve. This curve will /// Whether to close this path with one last bezier curve. This curve will
/// takes into account the adjacent control points. If you want to close /// takes into account the adjacent control points. If you want to close
@ -50,8 +48,8 @@ pub struct PathElem {
/// ///
/// Each vertex can be defined in 3 ways: /// Each vertex can be defined in 3 ways:
/// ///
/// - A regular point, as given to the [`line`]($func/line) or /// - A regular point, as given to the [`line`]($line) or
/// [`polygon`]($func/polygon) function. /// [`polygon`]($polygon) function.
/// - An array of two points, the first being the vertex and the second /// - An array of two points, the first being the vertex and the second
/// being the control point. The control point is expressed relative to /// being the control point. The control point is expressed relative to
/// the vertex and is mirrored to get the second control point. The given /// the vertex and is mirrored to get the second control point. The given
@ -60,7 +58,7 @@ pub struct PathElem {
/// the curve going out of this vertex. /// the curve going out of this vertex.
/// - An array of three points, the first being the vertex and the next /// - An array of three points, the first being the vertex and the next
/// being the control points (control point for curves coming in and out, /// being the control points (control point for curves coming in and out,
/// respectively) /// respectively).
#[variadic] #[variadic]
pub vertices: Vec<PathVertex>, pub vertices: Vec<PathVertex>,
} }
@ -75,8 +73,7 @@ impl Layout for PathElem {
) -> SourceResult<Fragment> { ) -> SourceResult<Fragment> {
let resolve = |axes: Axes<Rel<Length>>| { let resolve = |axes: Axes<Rel<Length>>| {
axes.resolve(styles) axes.resolve(styles)
.zip(regions.base()) .zip_map(regions.base(), Rel::relative_to)
.map(|(l, b)| l.relative_to(b))
.to_point() .to_point()
}; };
@ -136,9 +133,9 @@ impl Layout for PathElem {
// Prepare fill and stroke. // Prepare fill and stroke.
let fill = self.fill(styles); let fill = self.fill(styles);
let stroke = match self.stroke(styles) { let stroke = match self.stroke(styles) {
Smart::Auto if fill.is_none() => Some(Stroke::default()), Smart::Auto if fill.is_none() => Some(FixedStroke::default()),
Smart::Auto => None, Smart::Auto => None,
Smart::Custom(stroke) => stroke.map(PartialStroke::unwrap_or_default), Smart::Custom(stroke) => stroke.map(Stroke::unwrap_or_default),
}; };
let mut frame = Frame::new(size); let mut frame = Frame::new(size);

150
crates/typst-library/src/visualize/polygon.rs
View File

@ -6,7 +6,7 @@ use crate::prelude::*;
/// ///
/// The polygon is defined by its corner points and is closed automatically. /// The polygon is defined by its corner points and is closed automatically.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// #polygon( /// #polygon(
/// fill: blue.lighten(80%), /// fill: blue.lighten(80%),
@ -17,90 +17,35 @@ use crate::prelude::*;
/// (0%, 2cm), /// (0%, 2cm),
/// ) /// )
/// ``` /// ```
/// #[elem(scope, Layout)]
/// Display: Polygon
/// Category: visualize
#[element(Layout)]
#[scope(
scope.define("regular", polygon_regular_func());
scope
)]
pub struct PolygonElem { pub struct PolygonElem {
/// How to fill the polygon. See the /// How to fill the polygon.
/// [rectangle's documentation]($func/rect.fill) for more details. ///
/// When setting a fill, the default stroke disappears. To create a
/// rectangle with both fill and stroke, you have to configure both.
/// ///
/// Currently all polygons are filled according to the /// Currently all polygons are filled according to the
/// [non-zero winding rule](https://en.wikipedia.org/wiki/Nonzero-rule). /// [non-zero winding rule](https://en.wikipedia.org/wiki/Nonzero-rule).
pub fill: Option<Paint>, pub fill: Option<Paint>,
/// How to stroke the polygon. This can be: /// How to [stroke]($stroke) the polygon. This can be:
/// ///
/// See the [line's documentation]($func/line.stroke) for more details. Can /// Can be set to `{none}` to disable the stroke or to `{auto}` for a
/// be set to `{none}` to disable the stroke or to `{auto}` for a stroke of /// stroke of `{1pt}` black if and if only if no fill is given.
/// `{1pt}` black if and if only if no fill is given.
#[resolve] #[resolve]
#[fold] #[fold]
pub stroke: Smart<Option<PartialStroke>>, pub stroke: Smart<Option<Stroke>>,
/// The vertices of the polygon. Each point is specified as an array of two /// The vertices of the polygon. Each point is specified as an array of two
/// [relative lengths]($type/relative-length). /// [relative lengths]($relative).
#[variadic] #[variadic]
pub vertices: Vec<Axes<Rel<Length>>>, pub vertices: Vec<Axes<Rel<Length>>>,
} }
impl Layout for PolygonElem { #[scope]
#[tracing::instrument(name = "PolygonElem::layout", skip_all)] impl PolygonElem {
fn layout(
&self,
_: &mut Vt,
styles: StyleChain,
regions: Regions,
) -> SourceResult<Fragment> {
let points: Vec<Point> = self
.vertices()
.iter()
.map(|c| {
c.resolve(styles)
.zip(regions.base())
.map(|(l, b)| l.relative_to(b))
.to_point()
})
.collect();
let size = points.iter().fold(Point::zero(), |max, c| c.max(max)).to_size();
let mut frame = Frame::new(size);
// Only create a path if there are more than zero points.
if points.is_empty() {
return Ok(Fragment::frame(frame));
}
// Prepare fill and stroke.
let fill = self.fill(styles);
let stroke = match self.stroke(styles) {
Smart::Auto if fill.is_none() => Some(Stroke::default()),
Smart::Auto => None,
Smart::Custom(stroke) => stroke.map(PartialStroke::unwrap_or_default),
};
// Construct a closed path given all points.
let mut path = Path::new();
path.move_to(points[0]);
for &point in &points[1..] {
path.line_to(point);
}
path.close_path();
let shape = Shape { geometry: Geometry::Path(path), stroke, fill };
frame.push(Point::zero(), FrameItem::Shape(shape, self.span()));
Ok(Fragment::frame(frame))
}
}
/// A regular polygon, defined by its size and number of vertices. /// A regular polygon, defined by its size and number of vertices.
/// ///
/// ## Example { #example }
/// ```example /// ```example
/// #polygon.regular( /// #polygon.regular(
/// fill: blue.lighten(80%), /// fill: blue.lighten(80%),
@ -109,22 +54,20 @@ impl Layout for PolygonElem {
/// vertices: 3, /// vertices: 3,
/// ) /// )
/// ``` /// ```
/// #[func(title = "Regular Polygon")]
/// Display: Regular Polygon pub fn regular(
/// Category: visualize
#[func]
pub fn polygon_regular(
/// How to fill the polygon. See the general /// How to fill the polygon. See the general
/// [polygon's documentation]($func/polygon.fill) for more details. /// [polygon's documentation]($polygon.fill) for more details.
#[named] #[named]
fill: Option<Option<Paint>>, fill: Option<Option<Paint>>,
/// How to stroke the polygon. See the general /// How to stroke the polygon. See the general
/// [polygon's documentation]($func/polygon.stroke) for more details. /// [polygon's documentation]($polygon.stroke) for more details.
#[named] #[named]
stroke: Option<Smart<Option<PartialStroke>>>, stroke: Option<Smart<Option<Stroke>>>,
/// The diameter of the circumcircle of the regular polygon (https://en.wikipedia.org/wiki/Circumcircle). /// The diameter of the [circumcircle](https://en.wikipedia.org/wiki/Circumcircle)
/// of the regular polygon.
#[named] #[named]
#[default(Em::one().into())] #[default(Em::one().into())]
size: Length, size: Length,
@ -146,7 +89,10 @@ pub fn polygon_regular(
) )
}) })
.fold((radius, radius), |(min_x, min_y), (v_x, v_y)| { .fold((radius, radius), |(min_x, min_y), (v_x, v_y)| {
(if min_x < v_x { min_x } else { v_x }, if min_y < v_y { min_y } else { v_y }) (
if min_x < v_x { min_x } else { v_x },
if min_y < v_y { min_y } else { v_y },
)
}); });
let vertices = (0..=vertices) let vertices = (0..=vertices)
.map(|v| { .map(|v| {
@ -165,3 +111,51 @@ pub fn polygon_regular(
} }
elem.pack() elem.pack()
} }
}
impl Layout for PolygonElem {
#[tracing::instrument(name = "PolygonElem::layout", skip_all)]
fn layout(
&self,
_: &mut Vt,
styles: StyleChain,
regions: Regions,
) -> SourceResult<Fragment> {
let points: Vec<Point> = self
.vertices()
.iter()
.map(|c| {
c.resolve(styles).zip_map(regions.base(), Rel::relative_to).to_point()
})
.collect();
let size = points.iter().fold(Point::zero(), |max, c| c.max(max)).to_size();
let mut frame = Frame::new(size);
// Only create a path if there are more than zero points.
if points.is_empty() {
return Ok(Fragment::frame(frame));
}
// Prepare fill and stroke.
let fill = self.fill(styles);
let stroke = match self.stroke(styles) {
Smart::Auto if fill.is_none() => Some(FixedStroke::default()),
Smart::Auto => None,
Smart::Custom(stroke) => stroke.map(Stroke::unwrap_or_default),
};
// Construct a closed path given all points.
let mut path = Path::new();
path.move_to(points[0]);
for &point in &points[1..] {
path.line_to(point);
}
path.close_path();
let shape = Shape { geometry: Geometry::Path(path), stroke, fill };
frame.push(Point::zero(), FrameItem::Shape(shape, self.span()));
Ok(Fragment::frame(frame))
}
}

106
crates/typst-library/src/visualize/shape.rs
View File

@ -4,7 +4,7 @@ use crate::prelude::*;
/// A rectangle with optional content. /// A rectangle with optional content.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// // Without content. /// // Without content.
/// #rect(width: 35%, height: 30pt) /// #rect(width: 35%, height: 30pt)
@ -15,10 +15,7 @@ use crate::prelude::*;
/// to fit the content. /// to fit the content.
/// ] /// ]
/// ``` /// ```
/// #[elem(title = "Rectangle", Layout)]
/// Display: Rectangle
/// Category: visualize
#[element(Layout)]
pub struct RectElem { pub struct RectElem {
/// The rectangle's width, relative to its parent container. /// The rectangle's width, relative to its parent container.
pub width: Smart<Rel<Length>>, pub width: Smart<Rel<Length>>,
@ -41,8 +38,7 @@ pub struct RectElem {
/// - `{none}` to disable stroking /// - `{none}` to disable stroking
/// - `{auto}` for a stroke of `{1pt + black}` if and if only if no fill is /// - `{auto}` for a stroke of `{1pt + black}` if and if only if no fill is
/// given. /// given.
/// - Any kind of stroke that can also be used for /// - Any kind of [stroke]($stroke)
/// [lines]($func/line.stroke).
/// - A dictionary describing the stroke for each side inidvidually. The /// - A dictionary describing the stroke for each side inidvidually. The
/// dictionary can contain the following keys in order of precedence: /// dictionary can contain the following keys in order of precedence:
/// - `top`: The top stroke. /// - `top`: The top stroke.
@ -65,7 +61,7 @@ pub struct RectElem {
/// ``` /// ```
#[resolve] #[resolve]
#[fold] #[fold]
pub stroke: Smart<Sides<Option<Option<PartialStroke>>>>, pub stroke: Smart<Sides<Option<Option<Stroke>>>>,
/// How much to round the rectangle's corners, relative to the minimum of /// How much to round the rectangle's corners, relative to the minimum of
/// the width and height divided by two. This can be: /// the width and height divided by two. This can be:
@ -106,20 +102,14 @@ pub struct RectElem {
pub radius: Corners<Option<Rel<Length>>>, pub radius: Corners<Option<Rel<Length>>>,
/// How much to pad the rectangle's content. /// How much to pad the rectangle's content.
/// /// See the [box's documentation]($box.outset) for more details.
/// _Note:_ When the rectangle contains text, its exact size depends on the
/// current [text edges]($func/text.top-edge).
///
/// ```example
/// #rect(inset: 0pt)[Tight]
/// ```
#[resolve] #[resolve]
#[fold] #[fold]
#[default(Sides::splat(Abs::pt(5.0).into()))] #[default(Sides::splat(Abs::pt(5.0).into()))]
pub inset: Sides<Option<Rel<Length>>>, pub inset: Sides<Option<Rel<Length>>>,
/// How much to expand the rectangle's size without affecting the layout. /// How much to expand the rectangle's size without affecting the layout.
/// See the [box's documentation]($func/box.outset) for more details. /// See the [box's documentation]($box.outset) for more details.
#[resolve] #[resolve]
#[fold] #[fold]
pub outset: Sides<Option<Rel<Length>>>, pub outset: Sides<Option<Rel<Length>>>,
@ -159,7 +149,7 @@ impl Layout for RectElem {
/// A square with optional content. /// A square with optional content.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// // Without content. /// // Without content.
/// #square(size: 40pt) /// #square(size: 40pt)
@ -170,10 +160,7 @@ impl Layout for RectElem {
/// sized to fit. /// sized to fit.
/// ] /// ]
/// ``` /// ```
/// #[elem(Layout)]
/// Display: Square
/// Category: visualize
#[element(Layout)]
pub struct SquareElem { pub struct SquareElem {
/// The square's side length. This is mutually exclusive with `width` and /// The square's side length. This is mutually exclusive with `width` and
/// `height`. /// `height`.
@ -203,31 +190,31 @@ pub struct SquareElem {
})] })]
pub height: Smart<Rel<Length>>, pub height: Smart<Rel<Length>>,
/// How to fill the square. See the /// How to fill the square. See the [rectangle's documentation]($rect.fill)
/// [rectangle's documentation]($func/rect.fill) for more details. /// for more details.
pub fill: Option<Paint>, pub fill: Option<Paint>,
/// How to stroke the square. See the [rectangle's /// How to stroke the square. See the
/// documentation]($func/rect.stroke) for more details. /// [rectangle's documentation]($rect.stroke) for more details.
#[resolve] #[resolve]
#[fold] #[fold]
pub stroke: Smart<Sides<Option<Option<PartialStroke>>>>, pub stroke: Smart<Sides<Option<Option<Stroke>>>>,
/// How much to round the square's corners. See the [rectangle's /// How much to round the square's corners. See the
/// documentation]($func/rect.radius) for more details. /// [rectangle's documentation]($rect.radius) for more details.
#[resolve] #[resolve]
#[fold] #[fold]
pub radius: Corners<Option<Rel<Length>>>, pub radius: Corners<Option<Rel<Length>>>,
/// How much to pad the square's content. See the [rectangle's /// How much to pad the square's content. See the
/// documentation]($func/rect.inset) for more details. /// [box's documentation]($box.inset) for more details.
#[resolve] #[resolve]
#[fold] #[fold]
#[default(Sides::splat(Abs::pt(5.0).into()))] #[default(Sides::splat(Abs::pt(5.0).into()))]
pub inset: Sides<Option<Rel<Length>>>, pub inset: Sides<Option<Rel<Length>>>,
/// How much to expand the square's size without affecting the layout. See /// How much to expand the square's size without affecting the layout. See
/// the [rectangle's documentation]($func/rect.outset) for more details. /// the [box's documentation]($box.outset) for more details.
#[resolve] #[resolve]
#[fold] #[fold]
pub outset: Sides<Option<Rel<Length>>>, pub outset: Sides<Option<Rel<Length>>>,
@ -268,7 +255,7 @@ impl Layout for SquareElem {
/// An ellipse with optional content. /// An ellipse with optional content.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// // Without content. /// // Without content.
/// #ellipse(width: 35%, height: 30pt) /// #ellipse(width: 35%, height: 30pt)
@ -280,10 +267,7 @@ impl Layout for SquareElem {
/// to fit the content. /// to fit the content.
/// ] /// ]
/// ``` /// ```
/// #[elem(Layout)]
/// Display: Ellipse
/// Category: visualize
#[element(Layout)]
pub struct EllipseElem { pub struct EllipseElem {
/// The ellipse's width, relative to its parent container. /// The ellipse's width, relative to its parent container.
pub width: Smart<Rel<Length>>, pub width: Smart<Rel<Length>>,
@ -291,25 +275,25 @@ pub struct EllipseElem {
/// The ellipse's height, relative to its parent container. /// The ellipse's height, relative to its parent container.
pub height: Smart<Rel<Length>>, pub height: Smart<Rel<Length>>,
/// How to fill the ellipse. See the /// How to fill the ellipse. See the [rectangle's documentation]($rect.fill)
/// [rectangle's documentation]($func/rect.fill) for more details. /// for more details.
pub fill: Option<Paint>, pub fill: Option<Paint>,
/// How to stroke the ellipse. See the [rectangle's /// How to stroke the ellipse. See the
/// documentation]($func/rect.stroke) for more details. /// [rectangle's documentation]($rect.stroke) for more details.
#[resolve] #[resolve]
#[fold] #[fold]
pub stroke: Smart<Option<PartialStroke>>, pub stroke: Smart<Option<Stroke>>,
/// How much to pad the ellipse's content. See the [rectangle's /// How much to pad the ellipse's content. See the
/// documentation]($func/rect.inset) for more details. /// [box's documentation]($box.inset) for more details.
#[resolve] #[resolve]
#[fold] #[fold]
#[default(Sides::splat(Abs::pt(5.0).into()))] #[default(Sides::splat(Abs::pt(5.0).into()))]
pub inset: Sides<Option<Rel<Length>>>, pub inset: Sides<Option<Rel<Length>>>,
/// How much to expand the ellipse's size without affecting the layout. See /// How much to expand the ellipse's size without affecting the layout. See
/// the [rectangle's documentation]($func/rect.outset) for more details. /// the [box's documentation]($box.outset) for more details.
#[resolve] #[resolve]
#[fold] #[fold]
pub outset: Sides<Option<Rel<Length>>>, pub outset: Sides<Option<Rel<Length>>>,
@ -349,7 +333,7 @@ impl Layout for EllipseElem {
/// A circle with optional content. /// A circle with optional content.
/// ///
/// ## Example { #example } /// # Example
/// ```example /// ```example
/// // Without content. /// // Without content.
/// #circle(radius: 25pt) /// #circle(radius: 25pt)
@ -361,10 +345,7 @@ impl Layout for EllipseElem {
/// sized to fit. /// sized to fit.
/// ] /// ]
/// ``` /// ```
/// #[elem(Layout)]
/// Display: Circle
/// Category: visualize
#[element(Layout)]
pub struct CircleElem { pub struct CircleElem {
/// The circle's radius. This is mutually exclusive with `width` and /// The circle's radius. This is mutually exclusive with `width` and
/// `height`. /// `height`.
@ -398,26 +379,26 @@ pub struct CircleElem {
})] })]
pub height: Smart<Rel<Length>>, pub height: Smart<Rel<Length>>,
/// How to fill the circle. See the /// How to fill the circle. See the [rectangle's documentation]($rect.fill)
/// [rectangle's documentation]($func/rect.fill) for more details. /// for more details.
pub fill: Option<Paint>, pub fill: Option<Paint>,
/// How to stroke the circle. See the [rectangle's /// How to stroke the circle. See the
/// documentation]($func/rect.stroke) for more details. /// [rectangle's documentation]($rect.stroke) for more details.
#[resolve] #[resolve]
#[fold] #[fold]
#[default(Smart::Auto)] #[default(Smart::Auto)]
pub stroke: Smart<Option<PartialStroke>>, pub stroke: Smart<Option<Stroke>>,
/// How much to pad the circle's content. See the [rectangle's /// How much to pad the circle's content. See the
/// documentation]($func/rect.inset) for more details. /// [box's documentation]($box.inset) for more details.
#[resolve] #[resolve]
#[fold] #[fold]
#[default(Sides::splat(Abs::pt(5.0).into()))] #[default(Sides::splat(Abs::pt(5.0).into()))]
pub inset: Sides<Option<Rel<Length>>>, pub inset: Sides<Option<Rel<Length>>>,
/// How much to expand the circle's size without affecting the layout. See /// How much to expand the circle's size without affecting the layout. See
/// the [rectangle's documentation]($func/rect.outset) for more details. /// the [box's documentation]($box.outset) for more details.
#[resolve] #[resolve]
#[fold] #[fold]
pub outset: Sides<Option<Rel<Length>>>, pub outset: Sides<Option<Rel<Length>>>,
@ -464,15 +445,14 @@ fn layout(
body: &Option<Content>, body: &Option<Content>,
sizing: Axes<Smart<Rel<Length>>>, sizing: Axes<Smart<Rel<Length>>>,
fill: Option<Paint>, fill: Option<Paint>,
stroke: Smart<Sides<Option<PartialStroke<Abs>>>>, stroke: Smart<Sides<Option<Stroke<Abs>>>>,
mut inset: Sides<Rel<Abs>>, mut inset: Sides<Rel<Abs>>,
outset: Sides<Rel<Abs>>, outset: Sides<Rel<Abs>>,
radius: Corners<Rel<Abs>>, radius: Corners<Rel<Abs>>,
span: Span, span: Span,
) -> SourceResult<Fragment> { ) -> SourceResult<Fragment> {
let resolved = sizing let resolved = sizing
.zip(regions.base()) .zip_map(regions.base(), |s, r| s.map(|v| v.resolve(styles).relative_to(r)));
.map(|(s, r)| s.map(|v| v.resolve(styles).relative_to(r)));
let mut frame; let mut frame;
if let Some(child) = body { if let Some(child) = body {
@ -517,11 +497,9 @@ fn layout(
// Prepare stroke. // Prepare stroke.
let stroke = match stroke { let stroke = match stroke {
Smart::Auto if fill.is_none() => Sides::splat(Some(Stroke::default())), Smart::Auto if fill.is_none() => Sides::splat(Some(FixedStroke::default())),
Smart::Auto => Sides::splat(None), Smart::Auto => Sides::splat(None),
Smart::Custom(strokes) => { Smart::Custom(strokes) => strokes.map(|s| s.map(Stroke::unwrap_or_default)),
strokes.map(|s| s.map(PartialStroke::unwrap_or_default))
}
}; };
// Add fill and/or stroke. // Add fill and/or stroke.

2
crates/typst-syntax/Cargo.toml
View File

@ -17,7 +17,7 @@ bench = false
[dependencies] [dependencies]
comemo = "0.3" comemo = "0.3"
ecow = { version = "0.1.1", features = ["serde"] } ecow = { version = "0.1.2", features = ["serde"] }
once_cell = "1" once_cell = "1"
serde = { version = "1.0.184", features = ["derive"] } serde = { version = "1.0.184", features = ["derive"] }
tracing = "0.1.37" tracing = "0.1.37"

2
crates/typst/Cargo.toml
View File

@ -22,7 +22,7 @@ base64 = "0.21.2"
bitflags = { version = "2", features = ["serde"] } bitflags = { version = "2", features = ["serde"] }
bytemuck = "1" bytemuck = "1"
comemo = "0.3" comemo = "0.3"
ecow = { version = "0.1.1", features = ["serde"] } ecow = { version = "0.1.2", features = ["serde"] }
flate2 = "1" flate2 = "1"
fontdb = "0.13" fontdb = "0.13"
if_chain = "1" if_chain = "1"

12
crates/typst/src/diag.rs
View File

@ -41,7 +41,10 @@ macro_rules! __bail {
} }
#[doc(inline)] #[doc(inline)]
pub use crate::__bail as bail; pub use crate::{__bail as bail, __error as error, __warning as warning};
#[doc(hidden)]
pub use ecow::{eco_format, EcoString};
/// Construct an [`EcoString`] or [`SourceDiagnostic`] with severity `Error`. /// Construct an [`EcoString`] or [`SourceDiagnostic`] with severity `Error`.
#[macro_export] #[macro_export]
@ -71,13 +74,6 @@ macro_rules! __warning {
}; };
} }
#[doc(inline)]
pub use crate::__error as error;
#[doc(inline)]
pub use crate::__warning as warning;
#[doc(hidden)]
pub use ecow::{eco_format, EcoString};
/// A result that can carry multiple source errors. /// A result that can carry multiple source errors.
pub type SourceResult<T> = Result<T, Box<Vec<SourceDiagnostic>>>; pub type SourceResult<T> = Result<T, Box<Vec<SourceDiagnostic>>>;

29
crates/typst/src/doc.rs
View File

@ -8,11 +8,12 @@ use std::sync::Arc;
use ecow::EcoString; use ecow::EcoString;
use crate::eval::{cast, dict, Dict, Value}; use crate::eval::{cast, dict, ty, Dict, Value};
use crate::font::Font; use crate::font::Font;
use crate::geom::{ use crate::geom::{
self, rounded_rect, Abs, Align, Axes, Color, Corners, Dir, Em, Geometry, Length, self, rounded_rect, Abs, Axes, Color, Corners, Dir, Em, FixedAlign, FixedStroke,
Numeric, Paint, Point, Rel, RgbaColor, Shape, Sides, Size, Stroke, Transform, Geometry, Length, Numeric, Paint, Point, Rel, RgbaColor, Shape, Sides, Size,
Transform,
}; };
use crate::image::Image; use crate::image::Image;
use crate::model::{Content, Location, MetaElem, StyleChain}; use crate::model::{Content, Location, MetaElem, StyleChain};
@ -231,14 +232,11 @@ impl Frame {
/// Resize the frame to a new size, distributing new space according to the /// Resize the frame to a new size, distributing new space according to the
/// given alignments. /// given alignments.
pub fn resize(&mut self, target: Size, aligns: Axes<Align>) { pub fn resize(&mut self, target: Size, align: Axes<FixedAlign>) {
if self.size != target { if self.size != target {
let offset = Point::new( let offset = align.zip_map(target - self.size, FixedAlign::position);
aligns.x.position(target.x - self.size.x),
aligns.y.position(target.y - self.size.y),
);
self.size = target; self.size = target;
self.translate(offset); self.translate(offset.to_point());
} }
} }
@ -290,7 +288,7 @@ impl Frame {
pub fn fill_and_stroke( pub fn fill_and_stroke(
&mut self, &mut self,
fill: Option<Paint>, fill: Option<Paint>,
stroke: Sides<Option<Stroke>>, stroke: Sides<Option<FixedStroke>>,
outset: Sides<Rel<Abs>>, outset: Sides<Rel<Abs>>,
radius: Corners<Rel<Abs>>, radius: Corners<Rel<Abs>>,
span: Span, span: Span,
@ -357,10 +355,10 @@ impl Frame {
1, 1,
Point::with_y(self.baseline()), Point::with_y(self.baseline()),
FrameItem::Shape( FrameItem::Shape(
Geometry::Line(Point::with_x(self.size.x)).stroked(Stroke { Geometry::Line(Point::with_x(self.size.x)).stroked(FixedStroke {
paint: Color::RED.into(), paint: Color::RED.into(),
thickness: Abs::pt(1.0), thickness: Abs::pt(1.0),
..Stroke::default() ..FixedStroke::default()
}), }),
Span::detached(), Span::detached(),
), ),
@ -384,10 +382,10 @@ impl Frame {
self.push( self.push(
Point::with_y(y), Point::with_y(y),
FrameItem::Shape( FrameItem::Shape(
Geometry::Line(Point::with_x(self.size.x)).stroked(Stroke { Geometry::Line(Point::with_x(self.size.x)).stroked(FixedStroke {
paint: Color::GREEN.into(), paint: Color::GREEN.into(),
thickness: Abs::pt(1.0), thickness: Abs::pt(1.0),
..Stroke::default() ..FixedStroke::default()
}), }),
Span::detached(), Span::detached(),
), ),
@ -660,6 +658,7 @@ cast! {
} }
/// Meta information that isn't visible or renderable. /// Meta information that isn't visible or renderable.
#[ty]
#[derive(Clone, PartialEq, Hash)] #[derive(Clone, PartialEq, Hash)]
pub enum Meta { pub enum Meta {
/// An internal or external link to a destination. /// An internal or external link to a destination.
@ -676,7 +675,7 @@ pub enum Meta {
} }
cast! { cast! {
type Meta: "meta", type Meta,
} }
impl Debug for Meta { impl Debug for Meta {

62
crates/typst/src/eval/args.rs
View File

@ -2,12 +2,42 @@ use std::fmt::{self, Debug, Formatter};
use ecow::{eco_format, EcoVec}; use ecow::{eco_format, EcoVec};
use super::{Array, Dict, FromValue, IntoValue, Str, Value}; use super::{func, scope, ty, Array, Dict, FromValue, IntoValue, Str, Value};
use crate::diag::{bail, At, SourceResult}; use crate::diag::{bail, At, SourceDiagnostic, SourceResult};
use crate::syntax::{Span, Spanned}; use crate::syntax::{Span, Spanned};
use crate::util::pretty_array_like; use crate::util::pretty_array_like;
/// Evaluated arguments to a function. /// Captured arguments to a function.
///
/// # Argument Sinks
/// Like built-in functions, custom functions can also take a variable number of
/// arguments. You can specify an _argument sink_ which collects all excess
/// arguments as `..sink`. The resulting `sink` value is of the `arguments`
/// type. It exposes methods to access the positional and named arguments.
///
/// ```example
/// #let format(title, ..authors) = {
/// let by = authors
/// .pos()
/// .join(", ", last: " and ")
///
/// [*#title* \ _Written by #by;_]
/// }
///
/// #format("ArtosFlow", "Jane", "Joe")
/// ```
///
/// # Spreading
/// Inversely to an argument sink, you can _spread_ arguments, arrays and
/// dictionaries into a function call with the `..spread` operator:
///
/// ```example
/// #let array = (2, 3, 5)
/// #calc.min(..array)
/// #let dict = (fill: blue)
/// #text(..dict)[Hello]
/// ```
#[ty(scope, name = "arguments")]
#[derive(Clone, PartialEq, Hash)] #[derive(Clone, PartialEq, Hash)]
pub struct Args { pub struct Args {
/// The span of the whole argument list. /// The span of the whole argument list.
@ -125,8 +155,21 @@ impl Args {
T: FromValue<Spanned<Value>>, T: FromValue<Spanned<Value>>,
{ {
let mut list = vec![]; let mut list = vec![];
while let Some(value) = self.find()? { let mut errors = vec![];
list.push(value); self.items.retain(|item| {
if item.name.is_some() {
return true;
};
let span = item.value.span;
let spanned = Spanned::new(std::mem::take(&mut item.value.v), span);
match T::from_value(spanned) {
Ok(val) => list.push(val),
Err(err) => errors.push(SourceDiagnostic::error(span, err)),
}
false
});
if !errors.is_empty() {
return Err(Box::new(errors));
} }
Ok(list) Ok(list)
} }
@ -183,8 +226,12 @@ impl Args {
} }
Ok(()) Ok(())
} }
}
/// Extract the positional arguments as an array. #[scope]
impl Args {
/// Returns the captured positional arguments as an array.
#[func(name = "pos", title = "Positional")]
pub fn to_pos(&self) -> Array { pub fn to_pos(&self) -> Array {
self.items self.items
.iter() .iter()
@ -193,7 +240,8 @@ impl Args {
.collect() .collect()
} }
/// Extract the named arguments as a dictionary. /// Returns the captured named arguments as a dictionary.
#[func(name = "named")]
pub fn to_named(&self) -> Dict { pub fn to_named(&self) -> Dict {
self.items self.items
.iter() .iter()

825
crates/typst/src/eval/array.rs
View File

@ -1,11 +1,15 @@
use std::cmp::Ordering; use std::cmp::Ordering;
use std::fmt::{self, Debug, Formatter}; use std::fmt::{self, Debug, Formatter};
use std::num::NonZeroI64;
use std::ops::{Add, AddAssign}; use std::ops::{Add, AddAssign};
use ecow::{eco_format, EcoString, EcoVec}; use ecow::{eco_format, EcoString, EcoVec};
use serde::{Deserialize, Serialize}; use serde::{Deserialize, Serialize};
use super::{ops, Args, CastInfo, FromValue, Func, IntoValue, Reflect, Value, Vm}; use super::{
cast, func, ops, scope, ty, Args, Bytes, CastInfo, FromValue, Func, IntoValue,
Reflect, Value, Vm,
};
use crate::diag::{At, SourceResult, StrResult}; use crate::diag::{At, SourceResult, StrResult};
use crate::eval::ops::{add, mul}; use crate::eval::ops::{add, mul};
use crate::syntax::Span; use crate::syntax::Span;
@ -31,10 +35,41 @@ macro_rules! __array {
#[doc(inline)] #[doc(inline)]
pub use crate::__array as array; pub use crate::__array as array;
#[doc(hidden)] #[doc(hidden)]
pub use ecow::eco_vec; pub use ecow::eco_vec;
/// A reference counted array with value semantics. /// A sequence of values.
///
/// You can construct an array by enclosing a comma-separated sequence of values
/// in parentheses. The values do not have to be of the same type.
///
/// You can access and update array items with the `.at()` method. Indices are
/// zero-based and negative indices wrap around to the end of the array. You can
/// iterate over an array using a [for loop]($scripting/#loops). Arrays can be
/// added together with the `+` operator, [joined together]($scripting/#blocks)
/// and multiplied with integers.
///
/// **Note:** An array of length one needs a trailing comma, as in `{(1,)}`.
/// This is to disambiguate from a simple parenthesized expressions like `{(1 +
/// 2) * 3}`. An empty array is written as `{()}`.
///
/// # Example
/// ```example
/// #let values = (1, 7, 4, -3, 2)
///
/// #values.at(0) \
/// #(values.at(0) = 3)
/// #values.at(-1) \
/// #values.find(calc.even) \
/// #values.filter(calc.odd) \
/// #values.map(calc.abs) \
/// #values.rev() \
/// #(1, (2, 3)).flatten() \
/// #(("A", "B", "C")
/// .join(", ", last: " and "))
/// ```
#[ty(scope)]
#[derive(Default, Clone, PartialEq, Hash, Serialize, Deserialize)] #[derive(Default, Clone, PartialEq, Hash, Serialize, Deserialize)]
#[serde(transparent)] #[serde(transparent)]
pub struct Array(EcoVec<Value>); pub struct Array(EcoVec<Value>);
@ -52,17 +87,17 @@ impl Array {
/// Return `true` if the length is 0. /// Return `true` if the length is 0.
pub fn is_empty(&self) -> bool { pub fn is_empty(&self) -> bool {
self.0.len() == 0 self.0.is_empty()
} }
/// The length of the array. /// Extract a slice of the whole array.
pub fn len(&self) -> usize { pub fn as_slice(&self) -> &[Value] {
self.0.len() self.0.as_slice()
} }
/// The first value in the array. /// Iterate over references to the contained values.
pub fn first(&self) -> StrResult<&Value> { pub fn iter(&self) -> std::slice::Iter<Value> {
self.0.first().ok_or_else(array_is_empty) self.0.iter()
} }
/// Mutably borrow the first value in the array. /// Mutably borrow the first value in the array.
@ -70,24 +105,11 @@ impl Array {
self.0.make_mut().first_mut().ok_or_else(array_is_empty) self.0.make_mut().first_mut().ok_or_else(array_is_empty)
} }
/// The last value in the array.
pub fn last(&self) -> StrResult<&Value> {
self.0.last().ok_or_else(array_is_empty)
}
/// Mutably borrow the last value in the array. /// Mutably borrow the last value in the array.
pub fn last_mut(&mut self) -> StrResult<&mut Value> { pub fn last_mut(&mut self) -> StrResult<&mut Value> {
self.0.make_mut().last_mut().ok_or_else(array_is_empty) self.0.make_mut().last_mut().ok_or_else(array_is_empty)
} }
/// Borrow the value at the given index.
pub fn at(&self, index: i64, default: Option<Value>) -> StrResult<Value> {
self.locate_opt(index, false)
.and_then(|i| self.0.get(i).cloned())
.or(default)
.ok_or_else(|| out_of_bounds_no_default(index, self.len()))
}
/// Mutably borrow the value at the given index. /// Mutably borrow the value at the given index.
pub fn at_mut(&mut self, index: i64) -> StrResult<&mut Value> { pub fn at_mut(&mut self, index: i64) -> StrResult<&mut Value> {
let len = self.len(); let len = self.len();
@ -96,57 +118,210 @@ impl Array {
.ok_or_else(|| out_of_bounds_no_default(index, len)) .ok_or_else(|| out_of_bounds_no_default(index, len))
} }
/// Push a value to the end of the array. /// Resolve an index or throw an out of bounds error.
pub fn push(&mut self, value: Value) { fn locate(&self, index: i64, end_ok: bool) -> StrResult<usize> {
self.locate_opt(index, end_ok)
.ok_or_else(|| out_of_bounds(index, self.len()))
}
/// Resolve an index, if it is within bounds.
///
/// `index == len` is considered in bounds if and only if `end_ok` is true.
fn locate_opt(&self, index: i64, end_ok: bool) -> Option<usize> {
let wrapped =
if index >= 0 { Some(index) } else { (self.len() as i64).checked_add(index) };
wrapped
.and_then(|v| usize::try_from(v).ok())
.filter(|&v| v < self.0.len() + end_ok as usize)
}
/// Repeat this array `n` times.
pub fn repeat(&self, n: usize) -> StrResult<Self> {
let count = self
.len()
.checked_mul(n)
.ok_or_else(|| format!("cannot repeat this array {} times", n))?;
Ok(self.iter().cloned().cycle().take(count).collect())
}
}
#[scope]
impl Array {
/// Converts a value to an array.
///
/// Note that this function is only intended for conversion of a collection-like
/// value to an array, not for creation of an array from individual items. Use
/// the array syntax `(1, 2, 3)` (or `(1,)` for a single-element array) instead.
///
/// ```example
/// #let hi = "Hello 😃"
/// #array(bytes(hi))
/// ```
#[func(constructor)]
pub fn construct(
/// The value that should be converted to an array.
value: ToArray,
) -> Array {
value.0
}
/// The number of values in the array.
#[func(title = "Length")]
pub fn len(&self) -> usize {
self.0.len()
}
/// Returns the first item in the array. May be used on the left-hand side
/// of an assignment. Fails with an error if the array is empty.
#[func]
pub fn first(&self) -> StrResult<Value> {
self.0.first().cloned().ok_or_else(array_is_empty)
}
/// Returns the last item in the array. May be used on the left-hand side of
/// an assignment. Fails with an error if the array is empty.
#[func]
pub fn last(&self) -> StrResult<Value> {
self.0.last().cloned().ok_or_else(array_is_empty)
}
/// Returns the item at the specified index in the array. May be used on the
/// left-hand side of an assignment. Returns the default value if the index
/// is out of bounds or fails with an error if no default value was
/// specified.
#[func]
pub fn at(
&self,
/// The index at which to retrieve the item. If negative, indexes from
/// the back.
index: i64,
/// A default value to return if the index is out of bounds.
#[named]
default: Option<Value>,
) -> StrResult<Value> {
self.locate_opt(index, false)
.and_then(|i| self.0.get(i).cloned())
.or(default)
.ok_or_else(|| out_of_bounds_no_default(index, self.len()))
}
/// Add a value to the end of the array.
#[func]
pub fn push(
&mut self,
/// The value to insert at the end of the array.
value: Value,
) {
self.0.push(value); self.0.push(value);
} }
/// Remove the last value in the array. /// Remove the last item from the array and return it. Fails with an error
/// if the array is empty.
#[func]
pub fn pop(&mut self) -> StrResult<Value> { pub fn pop(&mut self) -> StrResult<Value> {
self.0.pop().ok_or_else(array_is_empty) self.0.pop().ok_or_else(array_is_empty)
} }
/// Insert a value at the specified index. /// Insert a value into the array at the specified index. Fails with an
pub fn insert(&mut self, index: i64, value: Value) -> StrResult<()> { /// error if the index is out of bounds.
#[func]
pub fn insert(
&mut self,
/// The index at which to insert the item. If negative, indexes from
/// the back.
index: i64,
/// The value to insert into the array.
value: Value,
) -> StrResult<()> {
let i = self.locate(index, true)?; let i = self.locate(index, true)?;
self.0.insert(i, value); self.0.insert(i, value);
Ok(()) Ok(())
} }
/// Remove and return the value at the specified index. /// Remove the value at the specified index from the array and return it.
pub fn remove(&mut self, index: i64) -> StrResult<Value> { #[func]
pub fn remove(
&mut self,
/// The index at which to remove the item. If negative, indexes from
/// the back.
index: i64,
) -> StrResult<Value> {
let i = self.locate(index, false)?; let i = self.locate(index, false)?;
Ok(self.0.remove(i)) Ok(self.0.remove(i))
} }
/// Extract a contiguous subregion of the array. /// Extract a subslice of the array. Fails with an error if the start or
pub fn slice(&self, start: i64, end: Option<i64>) -> StrResult<Self> { /// index is out of bounds.
#[func]
pub fn slice(
&self,
/// The start index (inclusive). If negative, indexes from the back.
start: i64,
/// The end index (exclusive). If omitted, the whole slice until the end
/// of the array is extracted. If negative, indexes from the back.
#[default]
end: Option<i64>,
/// The number of items to extract. This is equivalent to passing
/// `start + count` as the `end` position. Mutually exclusive with `end`.
#[named]
count: Option<i64>,
) -> StrResult<Array> {
let mut end = end;
if end.is_none() {
end = count.map(|c: i64| start + c);
}
let start = self.locate(start, true)?; let start = self.locate(start, true)?;
let end = self.locate(end.unwrap_or(self.len() as i64), true)?.max(start); let end = self.locate(end.unwrap_or(self.len() as i64), true)?.max(start);
Ok(self.0[start..end].into()) Ok(self.0[start..end].into())
} }
/// Whether the array contains a specific value. /// Whether the array contains the specified value.
pub fn contains(&self, value: &Value) -> bool { ///
self.0.contains(value) /// This method also has dedicated syntax: You can write `{2 in (1, 2, 3)}`
/// instead of `{(1, 2, 3).contains(2)}`.
#[func]
pub fn contains(
&self,
/// The value to search for.
value: Value,
) -> bool {
self.0.contains(&value)
} }
/// Return the first matching item. /// Searches for an item for which the given function returns `{true}` and
pub fn find(&self, vm: &mut Vm, func: Func) -> SourceResult<Option<Value>> { /// returns the first match or `{none}` if there is no match.
#[func]
pub fn find(
&self,
/// The virtual machine.
vm: &mut Vm,
/// The function to apply to each item. Must return a boolean.
searcher: Func,
) -> SourceResult<Option<Value>> {
for item in self.iter() { for item in self.iter() {
let args = Args::new(func.span(), [item.clone()]); let args = Args::new(searcher.span(), [item.clone()]);
if func.call_vm(vm, args)?.cast::<bool>().at(func.span())? { if searcher.call_vm(vm, args)?.cast::<bool>().at(searcher.span())? {
return Ok(Some(item.clone())); return Ok(Some(item.clone()));
} }
} }
Ok(None) Ok(None)
} }
/// Return the index of the first matching item. /// Searches for an item for which the given function returns `{true}` and
pub fn position(&self, vm: &mut Vm, func: Func) -> SourceResult<Option<i64>> { /// returns the index of the first match or `{none}` if there is no match.
#[func]
pub fn position(
&self,
/// The virtual machine.
vm: &mut Vm,
/// The function to apply to each item. Must return a boolean.
searcher: Func,
) -> SourceResult<Option<i64>> {
for (i, item) in self.iter().enumerate() { for (i, item) in self.iter().enumerate() {
let args = Args::new(func.span(), [item.clone()]); let args = Args::new(searcher.span(), [item.clone()]);
if func.call_vm(vm, args)?.cast::<bool>().at(func.span())? { if searcher.call_vm(vm, args)?.cast::<bool>().at(searcher.span())? {
return Ok(Some(i as i64)); return Ok(Some(i as i64));
} }
} }
@ -154,180 +329,153 @@ impl Array {
Ok(None) Ok(None)
} }
/// Return a new array with only those items for which the function returns /// Create an array consisting of a sequence of numbers.
/// true. ///
pub fn filter(&self, vm: &mut Vm, func: Func) -> SourceResult<Self> { /// If you pass just one positional parameter, it is interpreted as the
/// `end` of the range. If you pass two, they describe the `start` and `end`
/// of the range.
///
/// This function is available both in the array function's scope and
/// globally.
///
/// ```example
/// #range(5) \
/// #range(2, 5) \
/// #range(20, step: 4) \
/// #range(21, step: 4) \
/// #range(5, 2, step: -1)
/// ```
#[func]
pub fn range(
/// The real arguments (the other arguments are just for the docs, this
/// function is a bit involved, so we parse the arguments manually).
args: Args,
/// The start of the range (inclusive).
#[external]
#[default]
start: i64,
/// The end of the range (exclusive).
#[external]
end: i64,
/// The distance between the generated numbers.
#[named]
#[default(NonZeroI64::new(1).unwrap())]
step: NonZeroI64,
) -> SourceResult<Array> {
let mut args = args;
let first = args.expect::<i64>("end")?;
let (start, end) = match args.eat::<i64>()? {
Some(second) => (first, second),
None => (0, first),
};
args.finish()?;
let step = step.get();
let mut x = start;
let mut array = Self::new();
while x.cmp(&end) == 0.cmp(&step) {
array.push(x.into_value());
x += step;
}
Ok(array)
}
/// Produces a new array with only the items from the original one for which
/// the given function returns true.
#[func]
pub fn filter(
&self,
/// The virtual machine.
vm: &mut Vm,
/// The function to apply to each item. Must return a boolean.
test: Func,
) -> SourceResult<Array> {
let mut kept = EcoVec::new(); let mut kept = EcoVec::new();
for item in self.iter() { for item in self.iter() {
let args = Args::new(func.span(), [item.clone()]); let args = Args::new(test.span(), [item.clone()]);
if func.call_vm(vm, args)?.cast::<bool>().at(func.span())? { if test.call_vm(vm, args)?.cast::<bool>().at(test.span())? {
kept.push(item.clone()) kept.push(item.clone())
} }
} }
Ok(kept.into()) Ok(kept.into())
} }
/// Transform each item in the array with a function. /// Produces a new array in which all items from the original one were
pub fn map(&self, vm: &mut Vm, func: Func) -> SourceResult<Self> { /// transformed with the given function.
#[func]
pub fn map(
&self,
/// The virtual machine.
vm: &mut Vm,
/// The function to apply to each item.
mapper: Func,
) -> SourceResult<Array> {
self.iter() self.iter()
.map(|item| { .map(|item| {
let args = Args::new(func.span(), [item.clone()]); let args = Args::new(mapper.span(), [item.clone()]);
func.call_vm(vm, args) mapper.call_vm(vm, args)
}) })
.collect() .collect()
} }
/// Fold all of the array's items into one with a function. /// Returns a new array with the values alongside their indices.
pub fn fold(&self, vm: &mut Vm, init: Value, func: Func) -> SourceResult<Value> { ///
let mut acc = init; /// The returned array consists of `(index, value)` pairs in the form of
for item in self.iter() { /// length-2 arrays. These can be [destructured]($scripting/#bindings) with
let args = Args::new(func.span(), [acc, item.clone()]); /// a let binding or for loop.
acc = func.call_vm(vm, args)?; #[func]
} pub fn enumerate(
Ok(acc) &self,
} /// The index returned for the first pair of the returned list.
#[named]
/// Calculates the sum of the array's items #[default(0)]
pub fn sum(&self, default: Option<Value>, span: Span) -> SourceResult<Value> { start: i64,
let mut acc = self ) -> StrResult<Array> {
.first() self.iter()
.map(|x| x.clone()) .enumerate()
.or_else(|_| { .map(|(i, value)| {
default.ok_or_else(|| { Ok(array![
eco_format!("cannot calculate sum of empty array with no default") start
.checked_add_unsigned(i as u64)
.ok_or("array index is too large")?,
value.clone()
]
.into_value())
}) })
})
.at(span)?;
for i in self.iter().skip(1) {
acc = add(acc, i.clone()).at(span)?;
}
Ok(acc)
}
/// Calculates the product of the array's items
pub fn product(&self, default: Option<Value>, span: Span) -> SourceResult<Value> {
let mut acc = self
.first()
.map(|x| x.clone())
.or_else(|_| {
default.ok_or_else(|| {
eco_format!("cannot calculate product of empty array with no default")
})
})
.at(span)?;
for i in self.iter().skip(1) {
acc = mul(acc, i.clone()).at(span)?;
}
Ok(acc)
}
/// Whether any item matches.
pub fn any(&self, vm: &mut Vm, func: Func) -> SourceResult<bool> {
for item in self.iter() {
let args = Args::new(func.span(), [item.clone()]);
if func.call_vm(vm, args)?.cast::<bool>().at(func.span())? {
return Ok(true);
}
}
Ok(false)
}
/// Whether all items match.
pub fn all(&self, vm: &mut Vm, func: Func) -> SourceResult<bool> {
for item in self.iter() {
let args = Args::new(func.span(), [item.clone()]);
if !func.call_vm(vm, args)?.cast::<bool>().at(func.span())? {
return Ok(false);
}
}
Ok(true)
}
/// Return a new array with all items from this and nested arrays.
pub fn flatten(&self) -> Self {
let mut flat = EcoVec::with_capacity(self.0.len());
for item in self.iter() {
if let Value::Array(nested) = item {
flat.extend(nested.flatten().into_iter());
} else {
flat.push(item.clone());
}
}
flat.into()
}
/// Returns a new array with reversed order.
pub fn rev(&self) -> Self {
self.0.iter().cloned().rev().collect()
}
/// Split all values in the array.
pub fn split(&self, at: Value) -> Array {
self.as_slice()
.split(|value| *value == at)
.map(|subslice| Value::Array(subslice.iter().cloned().collect()))
.collect() .collect()
} }
/// Join all values in the array, optionally with separator and last /// Zips the array with other arrays. If the arrays are of unequal length,
/// separator (between the final two items). /// it will only zip up until the last element of the shortest array and the
pub fn join(&self, sep: Option<Value>, mut last: Option<Value>) -> StrResult<Value> { /// remaining elements will be ignored. The return value is an array where
let len = self.0.len(); /// each element is yet another array, the size of each of those is the
let sep = sep.unwrap_or(Value::None); /// number of zipped arrays.
///
let mut result = Value::None; /// This function is variadic, meaning that you can zip multiple arrays
for (i, value) in self.iter().cloned().enumerate() { /// together at once: `{(1, 2, 3).zip((3, 4, 5), (6, 7, 8))}` yields
if i > 0 { /// `{((1, 3, 6), (2, 4, 7), (3, 5, 8))}`.
if i + 1 == len && last.is_some() { #[func]
result = ops::join(result, last.take().unwrap())?; pub fn zip(
} else { &self,
result = ops::join(result, sep.clone())?; /// The real arguments (the other arguments are just for the docs, this
} /// function is a bit involved, so we parse the arguments manually).
} args: Args,
/// The arrays to zip with.
result = ops::join(result, value)?; #[external]
} #[variadic]
others: Vec<Array>,
Ok(result) ) -> SourceResult<Array> {
}
/// Returns an array with a copy of the separator value placed between
/// adjacent elements.
pub fn intersperse(&self, sep: Value) -> Array {
// TODO: Use https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.intersperse
// once it is stabilized.
let size = match self.len() {
0 => return Array::new(),
n => (2 * n) - 1,
};
let mut vec = EcoVec::with_capacity(size);
let mut iter = self.iter().cloned();
if let Some(first) = iter.next() {
vec.push(first);
}
for value in iter {
vec.push(sep.clone());
vec.push(value);
}
Array(vec)
}
/// The method `array.zip`, depending on the arguments, it automatically
/// detects whether it should use the single zip operator, which depends
/// on the standard library's implementation and can therefore be faster.
/// Or it zips using a manual implementation which allows for zipping more
/// than two arrays at once.
pub fn zip(&self, args: &mut Args) -> SourceResult<Self> {
// Fast path for just two arrays. // Fast path for just two arrays.
let mut args = args;
if args.remaining() <= 1 { if args.remaining() <= 1 {
let other = args.expect::<Array>("others")?;
args.finish()?;
return Ok(self return Ok(self
.iter() .iter()
.zip(args.expect::<Array>("others")?) .zip(other)
.map(|(first, second)| array![first.clone(), second].into_value()) .map(|(first, second)| array![first.clone(), second].into_value())
.collect()); .collect());
} }
@ -339,6 +487,7 @@ impl Array {
.into_iter() .into_iter()
.map(|i| i.into_iter()) .map(|i| i.into_iter())
.collect::<Vec<_>>(); .collect::<Vec<_>>();
args.finish()?;
for this in self.iter() { for this in self.iter() {
let mut row = Self::with_capacity(1 + iterators.len()); let mut row = Self::with_capacity(1 + iterators.len());
@ -358,16 +507,213 @@ impl Array {
Ok(out) Ok(out)
} }
/// Return a sorted version of this array, optionally by a given key function. /// Folds all items into a single value using an accumulator function.
#[func]
pub fn fold(
&self,
/// The virtual machine.
vm: &mut Vm,
/// The initial value to start with.
init: Value,
/// The folding function. Must have two parameters: One for the
/// accumulated value and one for an item.
folder: Func,
) -> SourceResult<Value> {
let mut acc = init;
for item in self.iter() {
let args = Args::new(folder.span(), [acc, item.clone()]);
acc = folder.call_vm(vm, args)?;
}
Ok(acc)
}
/// Sums all items (works for all types that can be added).
#[func]
pub fn sum(
&self,
/// What to return if the array is empty. Must be set if the array can
/// be empty.
#[named]
default: Option<Value>,
) -> StrResult<Value> {
let mut acc = self
.0
.first()
.cloned()
.or(default)
.ok_or("cannot calculate sum of empty array with no default")?;
for i in self.iter().skip(1) {
acc = add(acc, i.clone())?;
}
Ok(acc)
}
/// Calculates the product all items (works for all types that can be
/// multiplied).
#[func]
pub fn product(
&self,
/// What to return if the array is empty. Must be set if the array can
/// be empty.
#[named]
default: Option<Value>,
) -> StrResult<Value> {
let mut acc = self
.0
.first()
.cloned()
.or(default)
.ok_or("cannot calculate product of empty array with no default")?;
for i in self.iter().skip(1) {
acc = mul(acc, i.clone())?;
}
Ok(acc)
}
/// Whether the given function returns `{true}` for any item in the array.
#[func]
pub fn any(
&self,
/// The virtual machine.
vm: &mut Vm,
/// The function to apply to each item. Must return a boolean.
test: Func,
) -> SourceResult<bool> {
for item in self.iter() {
let args = Args::new(test.span(), [item.clone()]);
if test.call_vm(vm, args)?.cast::<bool>().at(test.span())? {
return Ok(true);
}
}
Ok(false)
}
/// Whether the given function returns `{true}` for all items in the array.
#[func]
pub fn all(
&self,
/// The virtual machine.
vm: &mut Vm,
/// The function to apply to each item. Must return a boolean.
test: Func,
) -> SourceResult<bool> {
for item in self.iter() {
let args = Args::new(test.span(), [item.clone()]);
if !test.call_vm(vm, args)?.cast::<bool>().at(test.span())? {
return Ok(false);
}
}
Ok(true)
}
/// Combine all nested arrays into a single flat one.
#[func]
pub fn flatten(&self) -> Array {
let mut flat = EcoVec::with_capacity(self.0.len());
for item in self.iter() {
if let Value::Array(nested) = item {
flat.extend(nested.flatten().into_iter());
} else {
flat.push(item.clone());
}
}
flat.into()
}
/// Return a new array with the same items, but in reverse order.
#[func(title = "Reverse")]
pub fn rev(&self) -> Array {
self.0.iter().cloned().rev().collect()
}
/// Split the array at occurrences of the specified value.
#[func]
pub fn split(
&self,
/// The value to split at.
at: Value,
) -> Array {
self.as_slice()
.split(|value| *value == at)
.map(|subslice| Value::Array(subslice.iter().cloned().collect()))
.collect()
}
/// Combine all items in the array into one.
#[func]
pub fn join(
&self,
/// A value to insert between each item of the array.
#[default]
separator: Option<Value>,
/// An alternative separator between the last two items
#[named]
last: Option<Value>,
) -> StrResult<Value> {
let len = self.0.len();
let separator = separator.unwrap_or(Value::None);
let mut last = last;
let mut result = Value::None;
for (i, value) in self.iter().cloned().enumerate() {
if i > 0 {
if i + 1 == len && last.is_some() {
result = ops::join(result, last.take().unwrap())?;
} else {
result = ops::join(result, separator.clone())?;
}
}
result = ops::join(result, value)?;
}
Ok(result)
}
/// Returns an array with a copy of the separator value placed between
/// adjacent elements.
#[func]
pub fn intersperse(&self, sep: Value) -> Array {
// TODO: Use once stabilized:
// https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.intersperse
let size = match self.len() {
0 => return Array::new(),
n => (2 * n) - 1,
};
let mut vec = EcoVec::with_capacity(size);
let mut iter = self.iter().cloned();
if let Some(first) = iter.next() {
vec.push(first);
}
for value in iter {
vec.push(sep.clone());
vec.push(value);
}
Array(vec)
}
/// Return a sorted version of this array, optionally by a given key
/// function.
/// ///
/// Returns an error if two values could not be compared or if the key function (if given) /// Returns an error if two values could not be compared or if the key
/// yields an error. /// function (if given) yields an error.
#[func]
pub fn sorted( pub fn sorted(
&self, &self,
/// The virtual machine.
vm: &mut Vm, vm: &mut Vm,
/// The callsite span.
span: Span, span: Span,
/// If given, applies this function to the elements in the array to
/// determine the keys to sort by.
#[named]
key: Option<Func>, key: Option<Func>,
) -> SourceResult<Self> { ) -> SourceResult<Array> {
let mut result = Ok(()); let mut result = Ok(());
let mut vec = self.0.clone(); let mut vec = self.0.clone();
let mut key_of = |x: Value| match &key { let mut key_of = |x: Value| match &key {
@ -398,34 +744,24 @@ impl Array {
result.map(|_| vec.into()) result.map(|_| vec.into())
} }
/// Repeat this array `n` times.
pub fn repeat(&self, n: i64) -> StrResult<Self> {
let count = usize::try_from(n)
.ok()
.and_then(|n| self.0.len().checked_mul(n))
.ok_or_else(|| format!("cannot repeat this array {} times", n))?;
Ok(self.iter().cloned().cycle().take(count).collect())
}
/// Enumerate all items in the array.
pub fn enumerate(&self, start: i64) -> StrResult<Self> {
self.iter()
.enumerate()
.map(|(i, value)| {
Ok(array![
start
.checked_add_unsigned(i as u64)
.ok_or_else(|| "array index is too large".to_string())?,
value.clone()
]
.into_value())
})
.collect()
}
/// Deduplicates all items in the array. /// Deduplicates all items in the array.
pub fn dedup(&self, vm: &mut Vm, key: Option<Func>) -> SourceResult<Self> { ///
/// Returns a new array with all duplicate items removed. Only the first
/// element of each duplicate is kept.
///
/// ```example
/// #(1, 1, 2, 3, 1).dedup()
/// ```
#[func(title = "Deduplicate")]
pub fn dedup(
&self,
/// The virtual machine.
vm: &mut Vm,
/// If given, applies this function to the elements in the array to
/// determine the keys to deduplicate by.
#[named]
key: Option<Func>,
) -> SourceResult<Array> {
let mut out = EcoVec::with_capacity(self.0.len()); let mut out = EcoVec::with_capacity(self.0.len());
let mut key_of = |x: Value| match &key { let mut key_of = |x: Value| match &key {
// NOTE: We are relying on `comemo`'s memoization of function // NOTE: We are relying on `comemo`'s memoization of function
@ -455,34 +791,15 @@ impl Array {
Ok(Self(out)) Ok(Self(out))
} }
/// Extract a slice of the whole array.
pub fn as_slice(&self) -> &[Value] {
self.0.as_slice()
} }
/// Iterate over references to the contained values. /// A value that can be cast to bytes.
pub fn iter(&self) -> std::slice::Iter<Value> { pub struct ToArray(Array);
self.0.iter()
}
/// Resolve an index or throw an out of bounds error. cast! {
fn locate(&self, index: i64, end_ok: bool) -> StrResult<usize> { ToArray,
self.locate_opt(index, end_ok) v: Bytes => Self(v.iter().map(|&b| Value::Int(b.into())).collect()),
.ok_or_else(|| out_of_bounds(index, self.len())) v: Array => Self(v),
}
/// Resolve an index, if it is within bounds.
///
/// `index == len` is considered in bounds if and only if `end_ok` is true.
fn locate_opt(&self, index: i64, end_ok: bool) -> Option<usize> {
let wrapped =
if index >= 0 { Some(index) } else { (self.len() as i64).checked_add(index) };
wrapped
.and_then(|v| usize::try_from(v).ok())
.filter(|&v| v < self.0.len() + end_ok as usize)
}
} }
impl Debug for Array { impl Debug for Array {
@ -555,8 +872,12 @@ impl From<&[Value]> for Array {
} }
impl<T> Reflect for Vec<T> { impl<T> Reflect for Vec<T> {
fn describe() -> CastInfo { fn input() -> CastInfo {
Array::describe() Array::input()
}
fn output() -> CastInfo {
Array::output()
} }
fn castable(value: &Value) -> bool { fn castable(value: &Value) -> bool {

18
crates/typst/src/eval/auto.rs
View File

@ -1,9 +1,17 @@
use std::fmt::{self, Debug, Formatter}; use std::fmt::{self, Debug, Formatter};
use super::{CastInfo, FromValue, IntoValue, Reflect, Value}; use super::{ty, CastInfo, FromValue, IntoValue, Reflect, Type, Value};
use crate::diag::StrResult; use crate::diag::StrResult;
/// A value that indicates a smart default. /// A value that indicates a smart default.
///
/// The auto type has exactly one value: `{auto}`.
///
/// Parameters that support the `{auto}` value have some smart default or
/// contextual behaviour. A good example is the [text direction]($text.dir)
/// parameter. Setting it to `{auto}` lets Typst automatically determine the
/// direction from the [text language]($text.lang).
#[ty(name = "auto")]
#[derive(Default, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)] #[derive(Default, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
pub struct AutoValue; pub struct AutoValue;
@ -23,8 +31,12 @@ impl FromValue for AutoValue {
} }
impl Reflect for AutoValue { impl Reflect for AutoValue {
fn describe() -> CastInfo { fn input() -> CastInfo {
CastInfo::Type("auto") CastInfo::Type(Type::of::<Self>())
}
fn output() -> CastInfo {
CastInfo::Type(Type::of::<Self>())
} }
fn castable(value: &Value) -> bool { fn castable(value: &Value) -> bool {

15
crates/typst/src/eval/bool.rs Normal file
View File

@ -0,0 +1,15 @@
use super::ty;
/// A type with two states.
///
/// The boolean type has two values: `{true}` and `{false}`. It denotes whether
/// something is active or enabled.
///
/// # Example
/// ```example
/// #false \
/// #true \
/// #(1 < 2)
/// ```
#[ty(title = "Boolean")]
type bool;

141
crates/typst/src/eval/bytes.rs
View File

@ -7,11 +7,37 @@ use comemo::Prehashed;
use ecow::{eco_format, EcoString}; use ecow::{eco_format, EcoString};
use serde::{Serialize, Serializer}; use serde::{Serialize, Serializer};
use crate::diag::StrResult; use super::{cast, func, scope, ty, Array, Reflect, Str, Value};
use crate::diag::{bail, StrResult};
use super::Value; /// A sequence of bytes.
///
/// A shared byte buffer that is cheap to clone and hash. /// This is conceptually similar to an array of [integers]($int) between `{0}`
/// and `{255}`, but represented much more efficiently.
///
/// You can convert
/// - a [string]($str) or an [array]($array) of integers to bytes with the
/// [`bytes`]($bytes) constructor
/// - bytes to a string with the [`str`]($str) constructor
/// - bytes to an array of integers with the [`array`]($array) constructor
///
/// When [reading]($read) data from a file, you can decide whether to load it
/// as a string or as raw bytes.
///
/// ```example
/// #bytes((123, 160, 22, 0)) \
/// #bytes("Hello 😃")
///
/// #let data = read(
/// "rhino.png",
/// encoding: none,
/// )
///
/// // Magic bytes.
/// #array(data.slice(0, 4)) \
/// #str(data.slice(1, 4))
/// ```
#[ty(scope)]
#[derive(Clone, Hash, Eq, PartialEq)] #[derive(Clone, Hash, Eq, PartialEq)]
pub struct Bytes(Arc<Prehashed<Cow<'static, [u8]>>>); pub struct Bytes(Arc<Prehashed<Cow<'static, [u8]>>>);
@ -21,19 +47,9 @@ impl Bytes {
Self(Arc::new(Prehashed::new(Cow::Borrowed(slice)))) Self(Arc::new(Prehashed::new(Cow::Borrowed(slice))))
} }
/// Get the byte at the given index. /// Return `true` if the length is 0.
pub fn at(&self, index: i64, default: Option<Value>) -> StrResult<Value> { pub fn is_empty(&self) -> bool {
self.locate_opt(index) self.0.is_empty()
.and_then(|i| self.0.get(i).map(|&b| Value::Int(b as i64)))
.or(default)
.ok_or_else(|| out_of_bounds_no_default(index, self.len()))
}
/// Extract a contiguous subregion of the bytes.
pub fn slice(&self, start: i64, end: Option<i64>) -> StrResult<Self> {
let start = self.locate(start)?;
let end = self.locate(end.unwrap_or(self.len() as i64))?.max(start);
Ok(self.0[start..end].into())
} }
/// Return a view into the buffer. /// Return a view into the buffer.
@ -64,6 +80,79 @@ impl Bytes {
} }
} }
#[scope]
impl Bytes {
/// Converts a value to bytes.
///
/// - Strings are encoded in UTF-8.
/// - Arrays of integers between `{0}` and `{255}` are converted directly. The
/// dedicated byte representation is much more efficient than the array
/// representation and thus typically used for large byte buffers (e.g. image
/// data).
///
/// ```example
/// #bytes("Hello 😃") \
/// #bytes((123, 160, 22, 0))
/// ```
#[func(constructor)]
pub fn construct(
/// The value that should be converted to bytes.
value: ToBytes,
) -> Bytes {
value.0
}
/// The length in bytes.
#[func(title = "Length")]
pub fn len(&self) -> usize {
self.0.len()
}
/// Returns the byte at the specified index. Returns the default value if
/// the index is out of bounds or fails with an error if no default value
/// was specified.
#[func]
pub fn at(
&self,
/// The index at which to retrieve the byte.
index: i64,
/// A default value to return if the index is out of bounds.
#[named]
default: Option<Value>,
) -> StrResult<Value> {
self.locate_opt(index)
.and_then(|i| self.0.get(i).map(|&b| Value::Int(b.into())))
.or(default)
.ok_or_else(|| out_of_bounds_no_default(index, self.len()))
}
/// Extracts a subslice of the bytes. Fails with an error if the start or
/// index is out of bounds.
#[func]
pub fn slice(
&self,
/// The start index (inclusive).
start: i64,
/// The end index (exclusive). If omitted, the whole slice until the end
/// is extracted.
#[default]
end: Option<i64>,
/// The number of items to extract. This is equivalent to passing
/// `start + count` as the `end` position. Mutually exclusive with
/// `end`.
#[named]
count: Option<i64>,
) -> StrResult<Bytes> {
let mut end = end;
if end.is_none() {
end = count.map(|c: i64| start + c);
}
let start = self.locate(start)?;
let end = self.locate(end.unwrap_or(self.len() as i64))?.max(start);
Ok(self.0[start..end].into())
}
}
impl From<&[u8]> for Bytes { impl From<&[u8]> for Bytes {
fn from(slice: &[u8]) -> Self { fn from(slice: &[u8]) -> Self {
Self(Arc::new(Prehashed::new(slice.to_vec().into()))) Self(Arc::new(Prehashed::new(slice.to_vec().into())))
@ -134,6 +223,24 @@ impl Serialize for Bytes {
} }
} }
/// A value that can be cast to bytes.
pub struct ToBytes(Bytes);
cast! {
ToBytes,
v: Str => Self(v.as_bytes().into()),
v: Array => Self(v.iter()
.map(|item| match item {
Value::Int(byte @ 0..=255) => Ok(*byte as u8),
Value::Int(_) => bail!("number must be between 0 and 255"),
value => Err(<u8 as Reflect>::error(value)),
})
.collect::<Result<Vec<u8>, _>>()?
.into()
),
v: Bytes => Self(v),
}
/// The out of bounds access error message. /// The out of bounds access error message.
#[cold] #[cold]
fn out_of_bounds(index: i64, len: usize) -> EcoString { fn out_of_bounds(index: i64, len: usize) -> EcoString {

120
crates/typst/src/eval/cast.rs
View File

@ -4,9 +4,9 @@ use unicode_math_class::MathClass;
use std::fmt::Write; use std::fmt::Write;
use std::ops::Add; use std::ops::Add;
use ecow::EcoString; use ecow::{eco_format, EcoString};
use super::Value; use super::{Type, Value};
use crate::diag::{At, SourceResult, StrResult}; use crate::diag::{At, SourceResult, StrResult};
use crate::syntax::{Span, Spanned}; use crate::syntax::{Span, Spanned};
use crate::util::separated_list; use crate::util::separated_list;
@ -25,8 +25,11 @@ use crate::util::separated_list;
/// `From<T> for Value`, but that inverses the impl and leads to tons of /// `From<T> for Value`, but that inverses the impl and leads to tons of
/// `.into()` all over the place that become hard to decipher. /// `.into()` all over the place that become hard to decipher.
pub trait Reflect { pub trait Reflect {
/// Describe the acceptable values for this type. /// Describe what can be cast into this value.
fn describe() -> CastInfo; fn input() -> CastInfo;
/// Describe what this value can be cast into.
fn output() -> CastInfo;
/// Whether the given value can be converted to `T`. /// Whether the given value can be converted to `T`.
/// ///
@ -45,12 +48,16 @@ pub trait Reflect {
/// ); /// );
/// ``` /// ```
fn error(found: &Value) -> EcoString { fn error(found: &Value) -> EcoString {
Self::describe().error(found) Self::input().error(found)
} }
} }
impl Reflect for Value { impl Reflect for Value {
fn describe() -> CastInfo { fn input() -> CastInfo {
CastInfo::Any
}
fn output() -> CastInfo {
CastInfo::Any CastInfo::Any
} }
@ -60,8 +67,12 @@ impl Reflect for Value {
} }
impl<T: Reflect> Reflect for Spanned<T> { impl<T: Reflect> Reflect for Spanned<T> {
fn describe() -> CastInfo { fn input() -> CastInfo {
T::describe() T::input()
}
fn output() -> CastInfo {
T::output()
} }
fn castable(value: &Value) -> bool { fn castable(value: &Value) -> bool {
@ -70,8 +81,12 @@ impl<T: Reflect> Reflect for Spanned<T> {
} }
impl<T: Reflect> Reflect for StrResult<T> { impl<T: Reflect> Reflect for StrResult<T> {
fn describe() -> CastInfo { fn input() -> CastInfo {
T::describe() T::input()
}
fn output() -> CastInfo {
T::output()
} }
fn castable(value: &Value) -> bool { fn castable(value: &Value) -> bool {
@ -80,8 +95,12 @@ impl<T: Reflect> Reflect for StrResult<T> {
} }
impl<T: Reflect> Reflect for SourceResult<T> { impl<T: Reflect> Reflect for SourceResult<T> {
fn describe() -> CastInfo { fn input() -> CastInfo {
T::describe() T::input()
}
fn output() -> CastInfo {
T::output()
} }
fn castable(value: &Value) -> bool { fn castable(value: &Value) -> bool {
@ -90,8 +109,12 @@ impl<T: Reflect> Reflect for SourceResult<T> {
} }
impl<T: Reflect> Reflect for &T { impl<T: Reflect> Reflect for &T {
fn describe() -> CastInfo { fn input() -> CastInfo {
T::describe() T::input()
}
fn output() -> CastInfo {
T::output()
} }
fn castable(value: &Value) -> bool { fn castable(value: &Value) -> bool {
@ -100,8 +123,12 @@ impl<T: Reflect> Reflect for &T {
} }
impl<T: Reflect> Reflect for &mut T { impl<T: Reflect> Reflect for &mut T {
fn describe() -> CastInfo { fn input() -> CastInfo {
T::describe() T::input()
}
fn output() -> CastInfo {
T::output()
} }
fn castable(value: &Value) -> bool { fn castable(value: &Value) -> bool {
@ -191,7 +218,7 @@ pub enum CastInfo {
/// A specific value, plus short documentation for that value. /// A specific value, plus short documentation for that value.
Value(Value, &'static str), Value(Value, &'static str),
/// Any value of a type. /// Any value of a type.
Type(&'static str), Type(Type),
/// Multiple alternatives. /// Multiple alternatives.
Union(Vec<Self>), Union(Vec<Self>),
} }
@ -200,32 +227,20 @@ impl CastInfo {
/// Produce an error message describing what was expected and what was /// Produce an error message describing what was expected and what was
/// found. /// found.
pub fn error(&self, found: &Value) -> EcoString { pub fn error(&self, found: &Value) -> EcoString {
fn accumulate( let mut matching_type = false;
info: &CastInfo, let mut parts = vec![];
found: &Value,
parts: &mut Vec<EcoString>, self.walk(|info| match info {
matching_type: &mut bool,
) {
match info {
CastInfo::Any => parts.push("anything".into()), CastInfo::Any => parts.push("anything".into()),
CastInfo::Value(value, _) => { CastInfo::Value(value, _) => {
parts.push(value.repr().into()); parts.push(value.repr().into());
if value.type_name() == found.type_name() { if value.ty() == found.ty() {
*matching_type = true; matching_type = true;
} }
} }
CastInfo::Type(ty) => parts.push((*ty).into()), CastInfo::Type(ty) => parts.push(eco_format!("{ty}")),
CastInfo::Union(options) => { CastInfo::Union(_) => {}
for option in options { });
accumulate(option, found, parts, matching_type);
}
}
}
}
let mut matching_type = false;
let mut parts = vec![];
accumulate(self, found, &mut parts, &mut matching_type);
let mut msg = String::from("expected "); let mut msg = String::from("expected ");
if parts.is_empty() { if parts.is_empty() {
@ -236,7 +251,7 @@ impl CastInfo {
if !matching_type { if !matching_type {
msg.push_str(", found "); msg.push_str(", found ");
msg.push_str(found.type_name()); write!(msg, "{}", found.ty()).unwrap();
} }
if_chain::if_chain! { if_chain::if_chain! {
if let Value::Int(i) = found; if let Value::Int(i) = found;
@ -249,6 +264,27 @@ impl CastInfo {
msg.into() msg.into()
} }
/// Walk all contained non-union infos.
pub fn walk<F>(&self, mut f: F)
where
F: FnMut(&Self),
{
fn inner<F>(info: &CastInfo, f: &mut F)
where
F: FnMut(&CastInfo),
{
if let CastInfo::Union(infos) = info {
for child in infos {
inner(child, f);
}
} else {
f(info);
}
}
inner(self, &mut f)
}
} }
impl Add for CastInfo { impl Add for CastInfo {
@ -299,7 +335,11 @@ impl<T> Container for Vec<T> {
pub enum Never {} pub enum Never {}
impl Reflect for Never { impl Reflect for Never {
fn describe() -> CastInfo { fn input() -> CastInfo {
CastInfo::Union(vec![])
}
fn output() -> CastInfo {
CastInfo::Union(vec![]) CastInfo::Union(vec![])
} }

599
crates/typst/src/eval/datetime.rs
View File

@ -6,15 +6,114 @@ use std::ops::{Add, Sub};
use ecow::{eco_format, EcoString, EcoVec}; use ecow::{eco_format, EcoString, EcoVec};
use time::error::{Format, InvalidFormatDescription}; use time::error::{Format, InvalidFormatDescription};
use time::{format_description, PrimitiveDateTime}; use time::macros::format_description;
use time::{format_description, Month, PrimitiveDateTime};
use crate::diag::bail; use super::{cast, func, scope, ty, Dict, Duration, Str, Value, Vm};
use crate::eval::{Duration, StrResult}; use crate::diag::{bail, StrResult};
use crate::geom::Smart;
use crate::util::pretty_array_like; use crate::util::pretty_array_like;
use crate::World;
/// A datetime object that represents either a date, a time or a combination of /// Represents a date, a time, or a combination of both.
/// both. ///
#[derive(Copy, Clone, Eq, PartialEq, Hash)] /// Can be created by either specifying a custom datetime using this type's
/// constructor function or getting the current date with
/// [`datetime.today`]($datetime.today).
///
/// # Example
/// ```example
/// #let date = datetime(
/// year: 2020,
/// month: 10,
/// day: 4,
/// )
///
/// #date.display() \
/// #date.display(
/// "y:[year repr:last_two]"
/// )
///
/// #let time = datetime(
/// hour: 18,
/// minute: 2,
/// second: 23,
/// )
///
/// #time.display() \
/// #time.display(
/// "h:[hour repr:12][period]"
/// )
/// ```
///
/// # Format
/// You can specify a customized formatting using the
/// [`display`]($datetime.display) method. The format of a datetime is
/// specified by providing _components_ with a specified number of _modifiers_.
/// A component represents a certain part of the datetime that you want to
/// display, and with the help of modifiers you can define how you want to
/// display that component. In order to display a component, you wrap the name
/// of the component in square brackets (e.g. `[[year]]` will display the year).
/// In order to add modifiers, you add a space after the component name followed
/// by the name of the modifier, a colon and the value of the modifier (e.g.
/// `[[month repr:short]]` will display the short representation of the month).
///
/// The possible combination of components and their respective modifiers is as
/// follows:
///
/// - `year`: Displays the year of the datetime.
/// - `padding`: Can be either `zero`, `space` or `none`. Specifies how the
/// year is padded.
/// - `repr` Can be either `full` in which case the full year is displayed or
/// `last_two` in which case only the last two digits are displayed.
/// - `sign`: Can be either `automatic` or `mandatory`. Specifies when the
/// sign should be displayed.
/// - `month`: Displays the month of the datetime.
/// - `padding`: Can be either `zero`, `space` or `none`. Specifies how the
/// month is padded.
/// - `repr`: Can be either `numerical`, `long` or `short`. Specifies if the
/// month should be displayed as a number or a word. Unfortunately, when
/// choosing the word representation, it can currently only display the
/// English version. In the future, it is planned to support localization.
/// - `day`: Displays the day of the datetime.
/// - `padding`: Can be either `zero`, `space` or `none`. Specifies how the
/// day is padded.
/// - `week_number`: Displays the week number of the datetime.
/// - `padding`: Can be either `zero`, `space` or `none`. Specifies how the
/// week number is padded.
/// - `repr`: Can be either `ISO`, `sunday` or `monday`. In the case of `ISO`,
/// week numbers are between 1 and 53, while the other ones are between 0
/// and 53.
/// - `weekday`: Displays the weekday of the date.
/// - `repr` Can be either `long`, `short`, `sunday` or `monday`. In the case
/// of `long` and `short`, the corresponding English name will be displayed
/// (same as for the month, other languages are currently not supported). In
/// the case of `sunday` and `monday`, the numerical value will be displayed
/// (assuming Sunday and Monday as the first day of the week, respectively).
/// - `one_indexed`: Can be either `true` or `false`. Defines whether the
/// numerical representation of the week starts with 0 or 1.
/// - `hour`: Displays the hour of the date.
/// - `padding`: Can be either `zero`, `space` or `none`. Specifies how the
/// hour is padded.
/// - `repr`: Can be either `24` or `12`. Changes whether the hour is
/// displayed in the 24-hour or 12-hour format.
/// - `period`: The AM/PM part of the hour
/// - `case`: Can be `lower` to display it in lower case and `upper` to
/// display it in upper case.
/// - `minute`: Displays the minute of the date.
/// - `padding`: Can be either `zero`, `space` or `none`. Specifies how the
/// minute is padded.
/// - `second`: Displays the second of the date.
/// - `padding`: Can be either `zero`, `space` or `none`. Specifies how the
/// second is padded.
///
/// Keep in mind that not always all components can be used. For example, if you
/// create a new datetime with `{datetime(year: 2023, month: 10, day: 13)}`, it
/// will be stored as a plain date internally, meaning that you cannot use
/// components such as `hour` or `minute`, which would only work on datetimes
/// that have a specified time.
#[ty(scope)]
#[derive(Clone, Copy, PartialEq, Hash)]
pub enum Datetime { pub enum Datetime {
/// Representation as a date. /// Representation as a date.
Date(time::Date), Date(time::Date),
@ -25,108 +124,6 @@ pub enum Datetime {
} }
impl Datetime { impl Datetime {
/// Which kind of variant this datetime stores.
pub fn kind(&self) -> &'static str {
match self {
Datetime::Datetime(_) => "datetime",
Datetime::Date(_) => "date",
Datetime::Time(_) => "time",
}
}
/// Display the date and/or time in a certain format.
pub fn display(&self, pattern: Option<EcoString>) -> Result<EcoString, EcoString> {
let pattern = pattern.as_ref().map(EcoString::as_str).unwrap_or(match self {
Datetime::Date(_) => "[year]-[month]-[day]",
Datetime::Time(_) => "[hour]:[minute]:[second]",
Datetime::Datetime(_) => "[year]-[month]-[day] [hour]:[minute]:[second]",
});
let format = format_description::parse(pattern)
.map_err(format_time_invalid_format_description_error)?;
let formatted_result = match self {
Datetime::Date(date) => date.format(&format),
Datetime::Time(time) => time.format(&format),
Datetime::Datetime(datetime) => datetime.format(&format),
}
.map(EcoString::from);
formatted_result.map_err(format_time_format_error)
}
/// Return the year of the datetime, if existing.
pub fn year(&self) -> Option<i32> {
match self {
Datetime::Date(date) => Some(date.year()),
Datetime::Time(_) => None,
Datetime::Datetime(datetime) => Some(datetime.year()),
}
}
/// Return the month of the datetime, if existing.
pub fn month(&self) -> Option<u8> {
match self {
Datetime::Date(date) => Some(date.month().into()),
Datetime::Time(_) => None,
Datetime::Datetime(datetime) => Some(datetime.month().into()),
}
}
/// Return the weekday of the datetime, if existing.
pub fn weekday(&self) -> Option<u8> {
match self {
Datetime::Date(date) => Some(date.weekday().number_from_monday()),
Datetime::Time(_) => None,
Datetime::Datetime(datetime) => Some(datetime.weekday().number_from_monday()),
}
}
/// Return the day of the datetime, if existing.
pub fn day(&self) -> Option<u8> {
match self {
Datetime::Date(date) => Some(date.day()),
Datetime::Time(_) => None,
Datetime::Datetime(datetime) => Some(datetime.day()),
}
}
/// Return the hour of the datetime, if existing.
pub fn hour(&self) -> Option<u8> {
match self {
Datetime::Date(_) => None,
Datetime::Time(time) => Some(time.hour()),
Datetime::Datetime(datetime) => Some(datetime.hour()),
}
}
/// Return the minute of the datetime, if existing.
pub fn minute(&self) -> Option<u8> {
match self {
Datetime::Date(_) => None,
Datetime::Time(time) => Some(time.minute()),
Datetime::Datetime(datetime) => Some(datetime.minute()),
}
}
/// Return the second of the datetime, if existing.
pub fn second(&self) -> Option<u8> {
match self {
Datetime::Date(_) => None,
Datetime::Time(time) => Some(time.second()),
Datetime::Datetime(datetime) => Some(datetime.second()),
}
}
/// Return the ordinal (day of the year), if existing.
pub fn ordinal(&self) -> Option<u16> {
match self {
Datetime::Datetime(datetime) => Some(datetime.ordinal()),
Datetime::Date(date) => Some(date.ordinal()),
Datetime::Time(_) => None,
}
}
/// Create a datetime from year, month, and day. /// Create a datetime from year, month, and day.
pub fn from_ymd(year: i32, month: u8, day: u8) -> Option<Self> { pub fn from_ymd(year: i32, month: u8, day: u8) -> Option<Self> {
Some(Datetime::Date( Some(Datetime::Date(
@ -155,54 +152,276 @@ impl Datetime {
let time = time::Time::from_hms(hour, minute, second).ok()?; let time = time::Time::from_hms(hour, minute, second).ok()?;
Some(Datetime::Datetime(PrimitiveDateTime::new(date, time))) Some(Datetime::Datetime(PrimitiveDateTime::new(date, time)))
} }
/// Try to parse a dictionary as a TOML date.
pub fn from_toml_dict(dict: &Dict) -> Option<Self> {
if dict.len() != 1 {
return None;
} }
impl PartialOrd for Datetime { let Ok(Value::Str(string)) = dict.get("$__toml_private_datetime") else {
fn partial_cmp(&self, other: &Self) -> Option<Ordering> { return None;
match (self, other) { };
(Datetime::Datetime(a), Datetime::Datetime(b)) => a.partial_cmp(b),
(Datetime::Date(a), Datetime::Date(b)) => a.partial_cmp(b), if let Ok(d) = time::PrimitiveDateTime::parse(
(Datetime::Time(a), Datetime::Time(b)) => a.partial_cmp(b), string,
_ => None, &format_description!("[year]-[month]-[day]T[hour]:[minute]:[second]Z"),
} ) {
Self::from_ymd_hms(
d.year(),
d.month() as u8,
d.day(),
d.hour(),
d.minute(),
d.second(),
)
} else if let Ok(d) = time::PrimitiveDateTime::parse(
string,
&format_description!("[year]-[month]-[day]T[hour]:[minute]:[second]"),
) {
Self::from_ymd_hms(
d.year(),
d.month() as u8,
d.day(),
d.hour(),
d.minute(),
d.second(),
)
} else if let Ok(d) =
time::Date::parse(string, &format_description!("[year]-[month]-[day]"))
{
Self::from_ymd(d.year(), d.month() as u8, d.day())
} else if let Ok(d) =
time::Time::parse(string, &format_description!("[hour]:[minute]:[second]"))
{
Self::from_hms(d.hour(), d.minute(), d.second())
} else {
None
} }
} }
impl Add<Duration> for Datetime { /// Which kind of variant this datetime stores.
type Output = Datetime; pub fn kind(&self) -> &'static str {
fn add(self, rhs: Duration) -> Self::Output {
let rhs: time::Duration = rhs.into();
match self { match self {
Datetime::Datetime(datetime) => Self::Datetime(datetime + rhs), Datetime::Datetime(_) => "datetime",
Datetime::Date(date) => Self::Date(date + rhs), Datetime::Date(_) => "date",
Datetime::Time(time) => Self::Time(time + rhs), Datetime::Time(_) => "time",
} }
} }
} }
impl Sub<Duration> for Datetime { #[scope]
type Output = Datetime; impl Datetime {
/// Creates a new datetime.
///
/// You can specify the [datetime]($datetime) using a year, month, day,
/// hour, minute, and second.
///
/// _Note_: Depending on which components of the datetime you specify, Typst
/// will store it in one of the following three ways:
/// * If you specify year, month and day, Typst will store just a date.
/// * If you specify hour, minute and second, Typst will store just a time.
/// * If you specify all of year, month, day, hour, minute and second, Typst
/// will store a full datetime.
///
/// Depending on how it is stored, the [`display`]($datetime.display) method
/// will choose a different formatting by default.
///
/// ```example
/// #datetime(
/// year: 2012,
/// month: 8,
/// day: 3,
/// ).display()
/// ```
#[func(constructor)]
pub fn construct(
/// The year of the datetime.
#[named]
year: Option<YearComponent>,
/// The month of the datetime.
#[named]
month: Option<MonthComponent>,
/// The day of the datetime.
#[named]
day: Option<DayComponent>,
/// The hour of the datetime.
#[named]
hour: Option<HourComponent>,
/// The minute of the datetime.
#[named]
minute: Option<MinuteComponent>,
/// The second of the datetime.
#[named]
second: Option<SecondComponent>,
) -> StrResult<Datetime> {
let time = match (hour, minute, second) {
(Some(hour), Some(minute), Some(second)) => {
match time::Time::from_hms(hour.0, minute.0, second.0) {
Ok(time) => Some(time),
Err(_) => bail!("time is invalid"),
}
}
(None, None, None) => None,
_ => bail!("time is incomplete"),
};
fn sub(self, rhs: Duration) -> Self::Output { let date = match (year, month, day) {
let rhs: time::Duration = rhs.into(); (Some(year), Some(month), Some(day)) => {
match time::Date::from_calendar_date(year.0, month.0, day.0) {
Ok(date) => Some(date),
Err(_) => bail!("date is invalid"),
}
}
(None, None, None) => None,
_ => bail!("date is incomplete"),
};
Ok(match (date, time) {
(Some(date), Some(time)) => {
Datetime::Datetime(PrimitiveDateTime::new(date, time))
}
(Some(date), None) => Datetime::Date(date),
(None, Some(time)) => Datetime::Time(time),
(None, None) => {
bail!("at least one of date or time must be fully specified")
}
})
}
/// Returns the current date.
///
/// ```example
/// Today's date is
/// #datetime.today().display().
/// ```
#[func]
pub fn today(
/// The virtual machine.
vm: &mut Vm,
/// An offset to apply to the current UTC date. If set to `{auto}`, the
/// offset will be the local offset.
#[named]
#[default]
offset: Smart<i64>,
) -> StrResult<Datetime> {
Ok(vm
.vt
.world
.today(offset.as_custom())
.ok_or("unable to get the current date")?)
}
/// Displays the datetime in a specified format.
///
/// Depending on whether you have defined just a date, a time or both, the
/// default format will be different. If you specified a date, it will be
/// `[[year]-[month]-[day]]`. If you specified a time, it will be
/// `[[hour]:[minute]:[second]]`. In the case of a datetime, it will be
/// `[[year]-[month]-[day] [hour]:[minute]:[second]]`.
#[func]
pub fn display(
&self,
/// The format used to display the datetime.
#[default]
pattern: Smart<DisplayPattern>,
) -> StrResult<EcoString> {
let pat = |s| format_description::parse_borrowed::<2>(s).unwrap();
let result = match pattern {
Smart::Auto => match self {
Self::Date(date) => date.format(&pat("[year]-[month]-[day]")),
Self::Time(time) => time.format(&pat("[hour]:[minute]:[second]")),
Self::Datetime(datetime) => {
datetime.format(&pat("[year]-[month]-[day] [hour]:[minute]:[second]"))
}
},
Smart::Custom(DisplayPattern(_, format)) => match self {
Self::Date(date) => date.format(&format),
Self::Time(time) => time.format(&format),
Self::Datetime(datetime) => datetime.format(&format),
},
};
result.map(EcoString::from).map_err(format_time_format_error)
}
/// The year if it was specified or `{none}`, otherwise.
#[func]
pub fn year(&self) -> Option<i32> {
match self { match self {
Datetime::Datetime(datetime) => Self::Datetime(datetime - rhs), Self::Date(date) => Some(date.year()),
Datetime::Date(date) => Self::Date(date - rhs), Self::Time(_) => None,
Datetime::Time(time) => Self::Time(time - rhs), Self::Datetime(datetime) => Some(datetime.year()),
}
} }
} }
impl Sub for Datetime { /// The month if it was specified or `{none}`, otherwise.
type Output = StrResult<Duration>; #[func]
pub fn month(&self) -> Option<u8> {
match self {
Self::Date(date) => Some(date.month().into()),
Self::Time(_) => None,
Self::Datetime(datetime) => Some(datetime.month().into()),
}
}
fn sub(self, rhs: Self) -> Self::Output { /// The weekday if it was specified or `{none}`, otherwise.
match (self, rhs) { #[func]
(Datetime::Datetime(a), Datetime::Datetime(b)) => Ok((a - b).into()), pub fn weekday(&self) -> Option<u8> {
(Datetime::Date(a), Datetime::Date(b)) => Ok((a - b).into()), match self {
(Datetime::Time(a), Datetime::Time(b)) => Ok((a - b).into()), Self::Date(date) => Some(date.weekday().number_from_monday()),
(a, b) => bail!("cannot subtract {} from {}", b.kind(), a.kind()), Self::Time(_) => None,
Self::Datetime(datetime) => Some(datetime.weekday().number_from_monday()),
}
}
/// The day if it was specified or `{none}`, otherwise.
#[func]
pub fn day(&self) -> Option<u8> {
match self {
Self::Date(date) => Some(date.day()),
Self::Time(_) => None,
Self::Datetime(datetime) => Some(datetime.day()),
}
}
/// The hour if it was specified or `{none}`, otherwise.
#[func]
pub fn hour(&self) -> Option<u8> {
match self {
Self::Date(_) => None,
Self::Time(time) => Some(time.hour()),
Self::Datetime(datetime) => Some(datetime.hour()),
}
}
/// The minute if it was specified or `{none}`, otherwise.
#[func]
pub fn minute(&self) -> Option<u8> {
match self {
Self::Date(_) => None,
Self::Time(time) => Some(time.minute()),
Self::Datetime(datetime) => Some(datetime.minute()),
}
}
/// The second if it was specified or `{none}`, otherwise.
#[func]
pub fn second(&self) -> Option<u8> {
match self {
Datetime::Date(_) => None,
Self::Time(time) => Some(time.second()),
Self::Datetime(datetime) => Some(datetime.second()),
}
}
/// The ordinal (day of the year), if it exists.
#[func]
pub fn ordinal(&self) -> Option<u16> {
match self {
Self::Datetime(datetime) => Some(datetime.ordinal()),
Self::Date(date) => Some(date.ordinal()),
Self::Time(_) => None,
} }
} }
} }
@ -224,6 +443,106 @@ impl Debug for Datetime {
} }
} }
impl PartialOrd for Datetime {
fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
match (self, other) {
(Self::Datetime(a), Self::Datetime(b)) => a.partial_cmp(b),
(Self::Date(a), Self::Date(b)) => a.partial_cmp(b),
(Self::Time(a), Self::Time(b)) => a.partial_cmp(b),
_ => None,
}
}
}
impl Add<Duration> for Datetime {
type Output = Self;
fn add(self, rhs: Duration) -> Self::Output {
let rhs: time::Duration = rhs.into();
match self {
Self::Datetime(datetime) => Self::Datetime(datetime + rhs),
Self::Date(date) => Self::Date(date + rhs),
Self::Time(time) => Self::Time(time + rhs),
}
}
}
impl Sub<Duration> for Datetime {
type Output = Self;
fn sub(self, rhs: Duration) -> Self::Output {
let rhs: time::Duration = rhs.into();
match self {
Self::Datetime(datetime) => Self::Datetime(datetime - rhs),
Self::Date(date) => Self::Date(date - rhs),
Self::Time(time) => Self::Time(time - rhs),
}
}
}
impl Sub for Datetime {
type Output = StrResult<Duration>;
fn sub(self, rhs: Self) -> Self::Output {
match (self, rhs) {
(Self::Datetime(a), Self::Datetime(b)) => Ok((a - b).into()),
(Self::Date(a), Self::Date(b)) => Ok((a - b).into()),
(Self::Time(a), Self::Time(b)) => Ok((a - b).into()),
(a, b) => bail!("cannot subtract {} from {}", b.kind(), a.kind()),
}
}
}
pub struct YearComponent(i32);
pub struct MonthComponent(Month);
pub struct DayComponent(u8);
pub struct HourComponent(u8);
pub struct MinuteComponent(u8);
pub struct SecondComponent(u8);
cast! {
YearComponent,
v: i32 => Self(v),
}
cast! {
MonthComponent,
v: u8 => Self(Month::try_from(v).map_err(|_| "month is invalid")?)
}
cast! {
DayComponent,
v: u8 => Self(v),
}
cast! {
HourComponent,
v: u8 => Self(v),
}
cast! {
MinuteComponent,
v: u8 => Self(v),
}
cast! {
SecondComponent,
v: u8 => Self(v),
}
/// A format in which a datetime can be displayed.
pub struct DisplayPattern(Str, format_description::OwnedFormatItem);
cast! {
DisplayPattern,
self => self.0.into_value(),
v: Str => {
let item = format_description::parse_owned::<2>(&v)
.map_err(format_time_invalid_format_description_error)?;
Self(v, item)
}
}
/// Format the `Format` error of the time crate in an appropriate way. /// Format the `Format` error of the time crate in an appropriate way.
fn format_time_format_error(error: Format) -> EcoString { fn format_time_format_error(error: Format) -> EcoString {
match error { match error {

172
crates/typst/src/eval/dict.rs
View File

@ -4,9 +4,10 @@ use std::ops::{Add, AddAssign};
use std::sync::Arc; use std::sync::Arc;
use ecow::{eco_format, EcoString}; use ecow::{eco_format, EcoString};
use indexmap::IndexMap;
use serde::{Deserialize, Deserializer, Serialize, Serializer}; use serde::{Deserialize, Deserializer, Serialize, Serializer};
use super::{array, Array, Str, Value}; use super::{array, func, scope, ty, Array, Str, Value};
use crate::diag::StrResult; use crate::diag::StrResult;
use crate::syntax::is_ident; use crate::syntax::is_ident;
use crate::util::{pretty_array_like, separated_list, ArcExt}; use crate::util::{pretty_array_like, separated_list, ArcExt};
@ -26,10 +27,42 @@ macro_rules! __dict {
#[doc(inline)] #[doc(inline)]
pub use crate::__dict as dict; pub use crate::__dict as dict;
#[doc(inline)] /// A map from string keys to values.
pub use indexmap::IndexMap; ///
/// You can construct a dictionary by enclosing comma-separated `key: value`
/// A reference-counted dictionary with value semantics. /// pairs in parentheses. The values do not have to be of the same type. Since
/// empty parentheses already yield an empty array, you have to use the special
/// `(:)` syntax to create an empty dictionary.
///
/// A dictionary is conceptually similar to an array, but it is indexed by
/// strings instead of integers. You can access and create dictionary entries
/// with the `.at()` method. If you know the key statically, you can
/// alternatively use [field access notation]($scripting/#fields) (`.key`) to
/// access the value. Dictionaries can be added with the `+` operator and
/// [joined together]($scripting/#blocks). To check whether a key is present in
/// the dictionary, use the `in` keyword.
///
/// You can iterate over the pairs in a dictionary using a [for
/// loop]($scripting/#loops). This will iterate in the order the pairs were
/// inserted / declared.
///
/// # Example
/// ```example
/// #let dict = (
/// name: "Typst",
/// born: 2019,
/// )
///
/// #dict.name \
/// #(dict.launch = 20)
/// #dict.len() \
/// #dict.keys() \
/// #dict.values() \
/// #dict.at("born") \
/// #dict.insert("city", "Berlin ")
/// #("name" in dict)
/// ```
#[ty(scope, name = "dictionary")]
#[derive(Default, Clone, PartialEq)] #[derive(Default, Clone, PartialEq)]
pub struct Dict(Arc<IndexMap<Str, Value>>); pub struct Dict(Arc<IndexMap<Str, Value>>);
@ -44,18 +77,14 @@ impl Dict {
self.0.is_empty() self.0.is_empty()
} }
/// The number of pairs in the dictionary. /// Borrow the value at the given key.
pub fn len(&self) -> usize { pub fn get(&self, key: &str) -> StrResult<&Value> {
self.0.len() self.0.get(key).ok_or_else(|| missing_key(key))
} }
/// Borrow the value the given `key` maps to, /// Remove the value if the dictionary contains the given key.
pub fn at(&self, key: &str, default: Option<Value>) -> StrResult<Value> { pub fn take(&mut self, key: &str) -> StrResult<Value> {
self.0 Arc::make_mut(&mut self.0).remove(key).ok_or_else(|| missing_key(key))
.get(key)
.cloned()
.or(default)
.ok_or_else(|| missing_key_no_default(key))
} }
/// Mutably borrow the value the given `key` maps to. /// Mutably borrow the value the given `key` maps to.
@ -65,31 +94,11 @@ impl Dict {
.ok_or_else(|| missing_key_no_default(key)) .ok_or_else(|| missing_key_no_default(key))
} }
/// Remove the value if the dictionary contains the given key.
pub fn take(&mut self, key: &str) -> StrResult<Value> {
Arc::make_mut(&mut self.0)
.remove(key)
.ok_or_else(|| eco_format!("missing key: {:?}", Str::from(key)))
}
/// Whether the dictionary contains a specific key. /// Whether the dictionary contains a specific key.
pub fn contains(&self, key: &str) -> bool { pub fn contains(&self, key: &str) -> bool {
self.0.contains_key(key) self.0.contains_key(key)
} }
/// Insert a mapping from the given `key` to the given `value`.
pub fn insert(&mut self, key: Str, value: Value) {
Arc::make_mut(&mut self.0).insert(key, value);
}
/// Remove a mapping by `key` and return the value.
pub fn remove(&mut self, key: &str) -> StrResult<Value> {
match Arc::make_mut(&mut self.0).shift_remove(key) {
Some(value) => Ok(value),
None => Err(missing_key(key)),
}
}
/// Clear the dictionary. /// Clear the dictionary.
pub fn clear(&mut self) { pub fn clear(&mut self) {
if Arc::strong_count(&self.0) == 1 { if Arc::strong_count(&self.0) == 1 {
@ -99,25 +108,6 @@ impl Dict {
} }
} }
/// Return the keys of the dictionary as an array.
pub fn keys(&self) -> Array {
self.0.keys().cloned().map(Value::Str).collect()
}
/// Return the values of the dictionary as an array.
pub fn values(&self) -> Array {
self.0.values().cloned().collect()
}
/// Return the values of the dictionary as an array of pairs (arrays of
/// length two).
pub fn pairs(&self) -> Array {
self.0
.iter()
.map(|(k, v)| Value::Array(array![k.clone(), v.clone()]))
.collect()
}
/// Iterate over pairs of references to the contained keys and values. /// Iterate over pairs of references to the contained keys and values.
pub fn iter(&self) -> indexmap::map::Iter<Str, Value> { pub fn iter(&self) -> indexmap::map::Iter<Str, Value> {
self.0.iter() self.0.iter()
@ -135,6 +125,80 @@ impl Dict {
} }
} }
#[scope]
impl Dict {
/// The number of pairs in the dictionary.
#[func(title = "Length")]
pub fn len(&self) -> usize {
self.0.len()
}
/// Returns the value associated with the specified key in the dictionary.
/// May be used on the left-hand side of an assignment if the key is already
/// present in the dictionary. Returns the default value if the key is not
/// part of the dictionary or fails with an error if no default value was
/// specified.
#[func]
pub fn at(
&self,
/// The key at which to retrieve the item.
key: Str,
/// A default value to return if the key is not part of the dictionary.
#[named]
default: Option<Value>,
) -> StrResult<Value> {
self.0
.get(&key)
.cloned()
.or(default)
.ok_or_else(|| missing_key_no_default(&key))
}
/// Insert a new pair into the dictionary and return the value. If the
/// dictionary already contains this key, the value is updated.
#[func]
pub fn insert(
&mut self,
/// The key of the pair that should be inserted.
key: Str,
/// The value of the pair that should be inserted.
value: Value,
) {
Arc::make_mut(&mut self.0).insert(key, value);
}
/// Remove a pair from the dictionary by key and return the value.
#[func]
pub fn remove(&mut self, key: Str) -> StrResult<Value> {
match Arc::make_mut(&mut self.0).shift_remove(&key) {
Some(value) => Ok(value),
None => Err(missing_key(&key)),
}
}
/// Returns the keys of the dictionary as an array in insertion order.
#[func]
pub fn keys(&self) -> Array {
self.0.keys().cloned().map(Value::Str).collect()
}
/// Returns the values of the dictionary as an array in insertion order.
#[func]
pub fn values(&self) -> Array {
self.0.values().cloned().collect()
}
/// Returns the keys and values of the dictionary as an array of pairs. Each
/// pair is represented as an array of length two.
#[func]
pub fn pairs(&self) -> Array {
self.0
.iter()
.map(|(k, v)| Value::Array(array![k.clone(), v.clone()]))
.collect()
}
}
impl Debug for Dict { impl Debug for Dict {
fn fmt(&self, f: &mut Formatter) -> fmt::Result { fn fmt(&self, f: &mut Formatter) -> fmt::Result {
if self.is_empty() { if self.is_empty() {

84
crates/typst/src/eval/duration.rs
View File

@ -1,11 +1,14 @@
use crate::util::pretty_array_like;
use ecow::eco_format; use ecow::eco_format;
use std::fmt; use std::fmt;
use std::fmt::{Debug, Formatter}; use std::fmt::{Debug, Formatter};
use std::ops::{Add, Div, Mul, Neg, Sub}; use std::ops::{Add, Div, Mul, Neg, Sub};
use time::ext::NumericalDuration; use time::ext::NumericalDuration;
use super::{func, scope, ty};
use crate::util::pretty_array_like;
/// Represents a positive or negative span of time. /// Represents a positive or negative span of time.
#[ty(scope)]
#[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)] #[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
pub struct Duration(time::Duration); pub struct Duration(time::Duration);
@ -14,39 +17,100 @@ impl Duration {
pub fn is_zero(&self) -> bool { pub fn is_zero(&self) -> bool {
self.0.is_zero() self.0.is_zero()
} }
}
#[scope]
impl Duration {
/// Creates a new duration.
///
/// You can specify the [duration]($duration) using weeks, days, hours,
/// minutes and seconds. You can also get a duration by subtracting two
/// [datetimes]($datetime).
///
/// ```example
/// #duration(
/// days: 3,
/// hours: 12,
/// ).hours()
/// ```
#[func(constructor)]
pub fn construct(
/// The number of seconds.
#[named]
#[default(0)]
seconds: i64,
/// The number of minutes.
#[named]
#[default(0)]
minutes: i64,
/// The number of hours.
#[named]
#[default(0)]
hours: i64,
/// The number of days.
#[named]
#[default(0)]
days: i64,
/// The number of weeks.
#[named]
#[default(0)]
weeks: i64,
) -> Duration {
Duration::from(
time::Duration::seconds(seconds)
+ time::Duration::minutes(minutes)
+ time::Duration::hours(hours)
+ time::Duration::days(days)
+ time::Duration::weeks(weeks),
)
}
/// The duration expressed in seconds. /// The duration expressed in seconds.
///
/// This function returns the total duration represented in seconds as a
/// floating-point number rather than the second component of the duration.
#[func]
pub fn seconds(&self) -> f64 { pub fn seconds(&self) -> f64 {
self.0.as_seconds_f64() self.0.as_seconds_f64()
} }
/// The duration expressed in minutes. /// The duration expressed in minutes.
///
/// This function returns the total duration represented in minutes as a
/// floating-point number rather than the second component of the duration.
#[func]
pub fn minutes(&self) -> f64 { pub fn minutes(&self) -> f64 {
self.seconds() / 60.0 self.seconds() / 60.0
} }
/// The duration expressed in hours. /// The duration expressed in hours.
///
/// This function returns the total duration represented in hours as a
/// floating-point number rather than the second component of the duration.
#[func]
pub fn hours(&self) -> f64 { pub fn hours(&self) -> f64 {
self.seconds() / 3_600.0 self.seconds() / 3_600.0
} }
/// The duration expressed in days. /// The duration expressed in days.
///
/// This function returns the total duration represented in days as a
/// floating-point number rather than the second component of the duration.
#[func]
pub fn days(&self) -> f64 { pub fn days(&self) -> f64 {
self.seconds() / 86_400.0 self.seconds() / 86_400.0
} }
/// The duration expressed in weeks. /// The duration expressed in weeks.
///
/// This function returns the total duration represented in weeks as a
/// floating-point number rather than the second component of the duration.
#[func]
pub fn weeks(&self) -> f64 { pub fn weeks(&self) -> f64 {
self.seconds() / 604_800.0 self.seconds() / 604_800.0
} }
} }
impl From<time::Duration> for Duration {
fn from(value: time::Duration) -> Self {
Self(value)
}
}
impl Debug for Duration { impl Debug for Duration {
fn fmt(&self, f: &mut Formatter) -> fmt::Result { fn fmt(&self, f: &mut Formatter) -> fmt::Result {
let mut tmp = self.0; let mut tmp = self.0;
@ -85,6 +149,12 @@ impl Debug for Duration {
} }
} }
impl From<time::Duration> for Duration {
fn from(value: time::Duration) -> Self {
Self(value)
}
}
impl From<Duration> for time::Duration { impl From<Duration> for time::Duration {
fn from(value: Duration) -> Self { fn from(value: Duration) -> Self {
value.0 value.0

84
crates/typst/src/eval/fields.rs
View File

@ -1,22 +1,23 @@
use ecow::{eco_format, EcoString}; use ecow::{eco_format, EcoString};
use crate::diag::StrResult; use crate::diag::StrResult;
use crate::geom::{Axes, GenAlign, PartialStroke, Stroke}; use crate::geom::{Align, Length, Rel, Stroke};
use super::{IntoValue, Value}; use super::{IntoValue, Type, Value};
/// Try to access a field on a value. /// Try to access a field on a value.
/// This function is exclusively for types which have ///
/// predefined fields, such as stroke and length. /// This function is exclusively for types which have predefined fields, such as
/// stroke and length.
pub(crate) fn field(value: &Value, field: &str) -> StrResult<Value> { pub(crate) fn field(value: &Value, field: &str) -> StrResult<Value> {
let name = value.type_name(); let ty = value.ty();
let not_supported = || Err(no_fields(name)); let nope = || Err(no_fields(ty));
let missing = || Err(missing_field(name, field)); let missing = || Err(missing_field(ty, field));
// Special cases, such as module and dict, are handled by Value itself // Special cases, such as module and dict, are handled by Value itself
let result = match value { let result = match value {
Value::Length(length) => match field { Value::Length(length) => match field {
"em" => length.em.into_value(), "em" => length.em.get().into_value(),
"abs" => length.abs.into_value(), "abs" => length.abs.into_value(),
_ => return missing(), _ => return missing(),
}, },
@ -26,44 +27,27 @@ pub(crate) fn field(value: &Value, field: &str) -> StrResult<Value> {
_ => return missing(), _ => return missing(),
}, },
Value::Dyn(dynamic) => { Value::Dyn(dynamic) => {
if let Some(stroke) = dynamic.downcast::<PartialStroke>() { if let Some(stroke) = dynamic.downcast::<Stroke>() {
match field { match field {
"paint" => stroke "paint" => stroke.paint.clone().into_value(),
.paint "thickness" => stroke.thickness.into_value(),
.clone() "cap" => stroke.line_cap.into_value(),
.unwrap_or_else(|| Stroke::default().paint) "join" => stroke.line_join.into_value(),
.into_value(), "dash" => stroke.dash_pattern.clone().into_value(),
"thickness" => stroke "miter-limit" => stroke.miter_limit.map(|limit| limit.0).into_value(),
.thickness
.unwrap_or_else(|| Stroke::default().thickness.into())
.into_value(),
"cap" => stroke
.line_cap
.unwrap_or_else(|| Stroke::default().line_cap)
.into_value(),
"join" => stroke
.line_join
.unwrap_or_else(|| Stroke::default().line_join)
.into_value(),
"dash" => stroke.dash_pattern.clone().unwrap_or(None).into_value(),
"miter-limit" => stroke
.miter_limit
.unwrap_or_else(|| Stroke::default().miter_limit)
.0
.into_value(),
_ => return missing(), _ => return missing(),
} }
} else if let Some(align2d) = dynamic.downcast::<Axes<GenAlign>>() { } else if let Some(align) = dynamic.downcast::<Align>() {
match field { match field {
"x" => align2d.x.into_value(), "x" => align.x().into_value(),
"y" => align2d.y.into_value(), "y" => align.y().into_value(),
_ => return missing(), _ => return missing(),
} }
} else { } else {
return not_supported(); return nope();
} }
} }
_ => return not_supported(), _ => return nope(),
}; };
Ok(result) Ok(result)
@ -71,23 +55,27 @@ pub(crate) fn field(value: &Value, field: &str) -> StrResult<Value> {
/// The error message for a type not supporting field access. /// The error message for a type not supporting field access.
#[cold] #[cold]
fn no_fields(type_name: &str) -> EcoString { fn no_fields(ty: Type) -> EcoString {
eco_format!("cannot access fields on type {type_name}") eco_format!("cannot access fields on type {ty}")
} }
/// The missing field error message. /// The missing field error message.
#[cold] #[cold]
fn missing_field(type_name: &str, field: &str) -> EcoString { fn missing_field(ty: Type, field: &str) -> EcoString {
eco_format!("{type_name} does not contain field \"{field}\"") eco_format!("{ty} does not contain field \"{field}\"")
} }
/// List the available fields for a type. /// List the available fields for a type.
pub fn fields_on(type_name: &str) -> &[&'static str] { pub fn fields_on(ty: Type) -> &'static [&'static str] {
match type_name { if ty == Type::of::<Length>() {
"length" => &["em", "abs"], &["em", "abs"]
"relative length" => &["ratio", "length"], } else if ty == Type::of::<Rel>() {
"stroke" => &["paint", "thickness", "cap", "join", "dash", "miter-limit"], &["ratio", "length"]
"2d alignment" => &["x", "y"], } else if ty == Type::of::<Stroke>() {
_ => &[], &["paint", "thickness", "cap", "join", "dash", "miter-limit"]
} else if ty == Type::of::<Align>() {
&["x", "y"]
} else {
&[]
} }
} }

60
crates/typst/src/eval/float.rs Normal file
View File

@ -0,0 +1,60 @@
use ecow::eco_format;
use super::{cast, func, scope, ty, Str};
use crate::geom::Ratio;
/// A floating-point number.
///
/// A limited-precision representation of a real number. Typst uses 64 bits to
/// store floats. Wherever a float is expected, you can also pass an
/// [integer]($int).
///
/// You can convert a value to a float with this type's constructor.
///
/// # Example
/// ```example
/// #3.14 \
/// #1e4 \
/// #(10 / 4)
/// ```
#[ty(scope, name = "float")]
type f64;
#[scope]
impl f64 {
/// Converts a value to a float.
///
/// - Booleans are converted to `0.0` or `1.0`.
/// - Integers are converted to the closest 64-bit float.
/// - Ratios are divided by 100%.
/// - Strings are parsed in base 10 to the closest 64-bit float.
/// Exponential notation is supported.
///
/// ```example
/// #float(false) \
/// #float(true) \
/// #float(4) \
/// #float(40%) \
/// #float("2.7") \
/// #float("1e5")
/// ```
#[func(constructor)]
pub fn construct(
/// The value that should be converted to a float.
value: ToFloat,
) -> f64 {
value.0
}
}
/// A value that can be cast to a float.
pub struct ToFloat(f64);
cast! {
ToFloat,
v: bool => Self(v as i64 as f64),
v: i64 => Self(v as f64),
v: Ratio => Self(v.get()),
v: Str => Self(v.parse().map_err(|_| eco_format!("invalid float: {}", v))?),
v: f64 => Self(v),
}

392
crates/typst/src/eval/func.rs
View File

@ -1,22 +1,123 @@
use std::fmt::{self, Debug, Formatter}; use std::fmt::{self, Debug, Formatter};
use std::hash::{Hash, Hasher};
use std::sync::Arc; use std::sync::Arc;
use comemo::{Prehashed, Tracked, TrackedMut}; use comemo::{Prehashed, Tracked, TrackedMut};
use ecow::eco_format;
use once_cell::sync::Lazy; use once_cell::sync::Lazy;
use super::{ use super::{
cast, Args, CastInfo, Eval, FlowEvent, IntoValue, Route, Scope, Scopes, Tracer, cast, scope, ty, Args, CastInfo, Eval, FlowEvent, IntoValue, Route, Scope, Scopes,
Value, Vm, Tracer, Type, Value, Vm,
}; };
use crate::diag::{bail, SourceResult, StrResult}; use crate::diag::{bail, SourceResult, StrResult};
use crate::model::{DelayedErrors, ElemFunc, Introspector, Locator, Vt}; use crate::model::{
Content, DelayedErrors, Element, Introspector, Locator, Selector, Vt,
};
use crate::syntax::ast::{self, AstNode}; use crate::syntax::ast::{self, AstNode};
use crate::syntax::{FileId, Span, SyntaxNode}; use crate::syntax::{FileId, Span, SyntaxNode};
use crate::util::Static;
use crate::World; use crate::World;
/// An evaluatable function. #[doc(inline)]
pub use typst_macros::func;
/// A mapping from argument values to a return value.
///
/// You can call a function by writing a comma-separated list of function
/// _arguments_ enclosed in parentheses directly after the function name.
/// Additionally, you can pass any number of trailing content blocks arguments
/// to a function _after_ the normal argument list. If the normal argument list
/// would become empty, it can be omitted. Typst supports positional and named
/// arguments. The former are identified by position and type, while the later
/// are written as `name: value`.
///
/// Within math mode, function calls have special behaviour. See the
/// [math documentation]($category/math) for more details.
///
/// # Example
/// ```example
/// // Call a function.
/// #list([A], [B])
///
/// // Named arguments and trailing
/// // content blocks.
/// #enum(start: 2)[A][B]
///
/// // Version without parentheses.
/// #list[A][B]
/// ```
///
/// Functions are a fundamental building block of Typst. Typst provides
/// functions for a variety of typesetting tasks. Moreover, the markup you write
/// is backed by functions and all styling happens through functions. This
/// reference lists all available functions and how you can use them. Please
/// also refer to the documentation about [set]($styling/#set-rules) and
/// [show]($styling/#show-rules) rules to learn about additional ways you can
/// work with functions in Typst.
///
/// # Element functions
/// Some functions are associated with _elements_ like [headings]($heading) or
/// [tables]($table). When called, these create an element of their respective
/// kind. In contrast to normal functions, they can further be used in [set
/// rules]($styling/#set-rules), [show rules]($styling/#show-rules), and
/// [selectors]($selector).
///
/// # Function scopes
/// Functions can hold related definitions in their own scope, similar to a
/// [module]($scripting/#modules). Examples of this are
/// [`assert.eq`]($assert.eq) or [`list.item`]($list.item). However, this
/// feature is currently only available for built-in functions.
///
/// # Defining functions
/// You can define your own function with a [let binding]($scripting/#bindings)
/// that has a parameter list after the binding's name. The parameter list can
/// contain positional parameters, named parameters with default values and
/// [argument sinks]($arguments). The right-hand side of the binding can be a
/// block or any other expression. It defines the function's return value and
/// can depend on the parameters.
///
/// ```example
/// #let alert(body, fill: red) = {
/// set text(white)
/// set align(center)
/// rect(
/// fill: fill,
/// inset: 8pt,
/// radius: 4pt,
/// [*Warning:\ #body*],
/// )
/// }
///
/// #alert[
/// Danger is imminent!
/// ]
///
/// #alert(fill: blue)[
/// KEEP OFF TRACKS
/// ]
/// ```
///
/// # Unnamed functions { #unnamed }
/// You can also created an unnamed function without creating a binding by
/// specifying a parameter list followed by `=>` and the function body. If your
/// function has just one parameter, the parentheses around the parameter list
/// are optional. Unnamed functions are mainly useful for show rules, but also
/// for settable properties that take functions like the page function's
/// [`footer`]($page.footer) property.
///
/// ```example
/// #show "once?": it => [#it #it]
/// once?
/// ```
///
/// # Notable fact
/// In Typst, all functions are _pure._ This means that for the same
/// arguments, they always return the same result. They cannot "remember" things to
/// produce another value when they are called a second time.
///
/// The only exception are built-in methods like
/// [`array.push(value)`]($array.push). These can modify the values they are
/// called on.
#[ty(scope, name = "function")]
#[derive(Clone, Hash)] #[derive(Clone, Hash)]
#[allow(clippy::derived_hash_with_manual_eq)] #[allow(clippy::derived_hash_with_manual_eq)]
pub struct Func { pub struct Func {
@ -30,9 +131,9 @@ pub struct Func {
#[derive(Clone, PartialEq, Hash)] #[derive(Clone, PartialEq, Hash)]
enum Repr { enum Repr {
/// A native Rust function. /// A native Rust function.
Native(&'static NativeFunc), Native(Static<NativeFuncData>),
/// A function for an element. /// A function for an element.
Elem(ElemFunc), Element(Element),
/// A user-defined closure. /// A user-defined closure.
Closure(Arc<Prehashed<Closure>>), Closure(Arc<Prehashed<Closure>>),
/// A nested function with pre-applied arguments. /// A nested function with pre-applied arguments.
@ -40,37 +141,106 @@ enum Repr {
} }
impl Func { impl Func {
/// The name of the function. /// The function's name (e.g. `min`).
///
/// Returns `None` if this is an anonymous closure.
pub fn name(&self) -> Option<&str> { pub fn name(&self) -> Option<&str> {
match &self.repr { match &self.repr {
Repr::Native(native) => Some(native.info.name), Repr::Native(native) => Some(native.name),
Repr::Elem(func) => Some(func.info().name), Repr::Element(elem) => Some(elem.name()),
Repr::Closure(closure) => closure.name(), Repr::Closure(closure) => closure.name(),
Repr::With(arc) => arc.0.name(), Repr::With(with) => with.0.name(),
} }
} }
/// Extract details the function. /// The function's title case name, for use in documentation (e.g. `Minimum`).
pub fn info(&self) -> Option<&FuncInfo> { ///
/// Returns `None` if this is a closure.
pub fn title(&self) -> Option<&'static str> {
match &self.repr { match &self.repr {
Repr::Native(native) => Some(&native.info), Repr::Native(native) => Some(native.title),
Repr::Elem(func) => Some(func.info()), Repr::Element(elem) => Some(elem.title()),
Repr::Closure(_) => None, Repr::Closure(_) => None,
Repr::With(arc) => arc.0.info(), Repr::With(with) => with.0.title(),
} }
} }
/// The function's span. /// Documentation for the function (as Markdown).
pub fn span(&self) -> Span { pub fn docs(&self) -> Option<&'static str> {
self.span match &self.repr {
Repr::Native(native) => Some(native.docs),
Repr::Element(elem) => Some(elem.docs()),
Repr::Closure(_) => None,
Repr::With(with) => with.0.docs(),
}
} }
/// Attach a span to this function if it doesn't already have one. /// Get details about this function's parameters if available.
pub fn spanned(mut self, span: Span) -> Self { pub fn params(&self) -> Option<&'static [ParamInfo]> {
if self.span.is_detached() { match &self.repr {
self.span = span; Repr::Native(native) => Some(&native.0.params),
Repr::Element(elem) => Some(elem.params()),
Repr::Closure(_) => None,
Repr::With(with) => with.0.params(),
}
}
/// Get the parameter info for a parameter with the given name if it exist.
pub fn param(&self, name: &str) -> Option<&'static ParamInfo> {
self.params()?.iter().find(|param| param.name == name)
}
/// Get details about the function's return type.
pub fn returns(&self) -> Option<&'static CastInfo> {
static CONTENT: Lazy<CastInfo> =
Lazy::new(|| CastInfo::Type(Type::of::<Content>()));
match &self.repr {
Repr::Native(native) => Some(&native.0.returns),
Repr::Element(_) => Some(&CONTENT),
Repr::Closure(_) => None,
Repr::With(with) => with.0.returns(),
}
}
/// Search keywords for the function.
pub fn keywords(&self) -> &'static [&'static str] {
match &self.repr {
Repr::Native(native) => native.keywords,
Repr::Element(elem) => elem.keywords(),
Repr::Closure(_) => &[],
Repr::With(with) => with.0.keywords(),
}
}
/// The function's associated scope of sub-definition.
pub fn scope(&self) -> Option<&'static Scope> {
match &self.repr {
Repr::Native(native) => Some(&native.0.scope),
Repr::Element(elem) => Some(elem.scope()),
Repr::Closure(_) => None,
Repr::With(with) => with.0.scope(),
}
}
/// Get a field from this function's scope, if possible.
pub fn field(&self, field: &str) -> StrResult<&'static Value> {
let scope =
self.scope().ok_or("cannot access fields on user-defined functions")?;
match scope.get(field) {
Some(field) => Ok(field),
None => match self.name() {
Some(name) => bail!("function `{name}` does not contain field `{field}`"),
None => bail!("function does not contain field `{field}`"),
},
}
}
/// Extract the element function, if it is one.
pub fn element(&self) -> Option<Element> {
match self.repr {
Repr::Element(func) => Some(func),
_ => None,
} }
self
} }
/// Call the function with the given arguments. /// Call the function with the given arguments.
@ -83,11 +253,11 @@ impl Func {
match &self.repr { match &self.repr {
Repr::Native(native) => { Repr::Native(native) => {
let value = (native.func)(vm, &mut args)?; let value = (native.function)(vm, &mut args)?;
args.finish()?; args.finish()?;
Ok(value) Ok(value)
} }
Repr::Elem(func) => { Repr::Element(func) => {
let value = func.construct(vm, &mut args)?; let value = func.construct(vm, &mut args)?;
args.finish()?; args.finish()?;
Ok(Value::Content(value)) Ok(Value::Content(value))
@ -109,9 +279,9 @@ impl Func {
args, args,
) )
} }
Repr::With(arc) => { Repr::With(with) => {
args.items = arc.1.items.iter().cloned().chain(args.items).collect(); args.items = with.1.items.iter().cloned().chain(args.items).collect();
arc.0.call_vm(vm, args) with.0.call_vm(vm, args)
} }
} }
} }
@ -138,42 +308,56 @@ impl Func {
self.call_vm(&mut vm, args) self.call_vm(&mut vm, args)
} }
/// Apply the given arguments to the function. /// The function's span.
pub fn with(self, args: Args) -> Self { pub fn span(&self) -> Span {
self.span
}
/// Attach a span to this function if it doesn't already have one.
pub fn spanned(mut self, span: Span) -> Self {
if self.span.is_detached() {
self.span = span;
}
self
}
}
#[scope]
impl Func {
/// Returns a new function that has the given arguments pre-applied.
#[func]
pub fn with(
self,
/// The real arguments (the other argument is just for the docs).
/// The docs argument cannot be called `args`.
args: Args,
/// The arguments to apply to the function.
#[external]
arguments: Args,
) -> Func {
let span = self.span; let span = self.span;
Self { repr: Repr::With(Arc::new((self, args))), span } Self { repr: Repr::With(Arc::new((self, args))), span }
} }
/// Extract the element function, if it is one. /// Returns a selector that filters for elements belonging to this function
pub fn element(&self) -> Option<ElemFunc> { /// whose fields have the values of the given arguments.
match self.repr { #[func]
Repr::Elem(func) => Some(func), pub fn where_(
_ => None, self,
} /// The real arguments (the other argument is just for the docs).
} /// The docs argument cannot be called `args`.
args: Args,
/// Get a field from this function's scope, if possible. /// The fields to filter for.
pub fn get(&self, field: &str) -> StrResult<&Value> { #[external]
match &self.repr { fields: Args,
Repr::Native(func) => func.info.scope.get(field).ok_or_else(|| { ) -> StrResult<Selector> {
eco_format!( let mut args = args;
"function `{}` does not contain field `{}`", let fields = args.to_named();
func.info.name, args.items.retain(|arg| arg.name.is_none());
field Ok(self
) .element()
}), .ok_or("`where()` can only be called on element functions")?
Repr::Elem(func) => func.info().scope.get(field).ok_or_else(|| { .where_(fields))
eco_format!(
"function `{}` does not contain field `{}`",
func.name(),
field
)
}),
Repr::Closure(_) => {
Err(eco_format!("cannot access fields on user-defined functions"))
}
Repr::With(arc) => arc.0.get(field),
}
} }
} }
@ -198,82 +382,56 @@ impl From<Repr> for Func {
} }
} }
impl From<ElemFunc> for Func { impl From<Element> for Func {
fn from(func: ElemFunc) -> Self { fn from(func: Element) -> Self {
Repr::Elem(func).into() Repr::Element(func).into()
} }
} }
/// A Typst function defined by a native Rust function. /// A Typst function that is defined by a native Rust type that shadows a
pub struct NativeFunc { /// native Rust function.
/// The function's implementation. pub trait NativeFunc {
pub func: fn(&mut Vm, &mut Args) -> SourceResult<Value>, /// Get the function for the native Rust type.
/// Details about the function. fn func() -> Func {
pub info: Lazy<FuncInfo>, Func::from(Self::data())
} }
impl PartialEq for NativeFunc { /// Get the function data for the native Rust type.
fn eq(&self, other: &Self) -> bool { fn data() -> &'static NativeFuncData;
self.func as usize == other.func as usize
}
} }
impl Eq for NativeFunc {} /// Defines a native function.
pub struct NativeFuncData {
impl Hash for NativeFunc { pub function: fn(&mut Vm, &mut Args) -> SourceResult<Value>,
fn hash<H: Hasher>(&self, state: &mut H) { pub name: &'static str,
(self.func as usize).hash(state); pub title: &'static str,
} pub docs: &'static str,
pub keywords: &'static [&'static str],
pub scope: Lazy<Scope>,
pub params: Lazy<Vec<ParamInfo>>,
pub returns: Lazy<CastInfo>,
} }
impl From<&'static NativeFunc> for Func { impl From<&'static NativeFuncData> for Func {
fn from(native: &'static NativeFunc) -> Self { fn from(data: &'static NativeFuncData) -> Self {
Repr::Native(native).into() Repr::Native(Static(data)).into()
} }
} }
cast! { cast! {
&'static NativeFunc, &'static NativeFuncData,
self => Value::Func(self.into()), self => Func::from(self).into_value(),
} }
/// Details about a function. /// Describes a function parameter.
#[derive(Debug, Clone)]
pub struct FuncInfo {
/// The function's name.
pub name: &'static str,
/// The display name of the function.
pub display: &'static str,
/// A string of search keywords.
pub keywords: Option<&'static str>,
/// Which category the function is part of.
pub category: &'static str,
/// Documentation for the function.
pub docs: &'static str,
/// Details about the function's parameters.
pub params: Vec<ParamInfo>,
/// Valid values for the return value.
pub returns: CastInfo,
/// The function's own scope of fields and sub-functions.
pub scope: Scope,
}
impl FuncInfo {
/// Get the parameter info for a parameter with the given name
pub fn param(&self, name: &str) -> Option<&ParamInfo> {
self.params.iter().find(|param| param.name == name)
}
}
/// Describes a named parameter.
#[derive(Debug, Clone)] #[derive(Debug, Clone)]
pub struct ParamInfo { pub struct ParamInfo {
/// The parameter's name. /// The parameter's name.
pub name: &'static str, pub name: &'static str,
/// Documentation for the parameter. /// Documentation for the parameter.
pub docs: &'static str, pub docs: &'static str,
/// Valid values for the parameter. /// Describe what values this parameter accepts.
pub cast: CastInfo, pub input: CastInfo,
/// Creates an instance of the parameter's default value. /// Creates an instance of the parameter's default value.
pub default: Option<fn() -> Value>, pub default: Option<fn() -> Value>,
/// Is the parameter positional? /// Is the parameter positional?

139
crates/typst/src/eval/int.rs
View File

@ -1,12 +1,72 @@
use std::num::{NonZeroI64, NonZeroIsize, NonZeroU64, NonZeroUsize}; use std::num::{NonZeroI64, NonZeroIsize, NonZeroU64, NonZeroUsize};
use super::{cast, Value}; use ecow::eco_format;
use super::{cast, func, scope, ty, Str, Value};
/// A whole number.
///
/// The number can be negative, zero, or positive. As Typst uses 64 bits to
/// store integers, integers cannot be smaller than `{-9223372036854775808}` or
/// larger than `{9223372036854775807}`.
///
/// The number can also be specified as hexadecimal, octal, or binary by
/// starting it with a zero followed by either `x`, `o`, or `b`.
///
/// You can convert a value to an integer with this type's constructor.
///
/// # Example
/// ```example
/// #(1 + 2) \
/// #(2 - 5) \
/// #(3 + 4 < 8)
///
/// #0xff \
/// #0o10 \
/// #0b1001
/// ```
#[ty(scope, name = "int", title = "Integer")]
type i64;
#[scope]
impl i64 {
/// Converts a value to an integer.
///
/// - Booleans are converted to `0` or `1`.
/// - Floats are floored to the next 64-bit integer.
/// - Strings are parsed in base 10.
///
/// ```example
/// #int(false) \
/// #int(true) \
/// #int(2.7) \
/// #(int("27") + int("4"))
/// ```
#[func(constructor)]
pub fn construct(
/// The value that should be converted to an integer.
value: ToInt,
) -> i64 {
value.0
}
}
/// A value that can be cast to an integer.
pub struct ToInt(i64);
cast! {
ToInt,
v: bool => Self(v as i64),
v: f64 => Self(v as i64),
v: Str => Self(v.parse().map_err(|_| eco_format!("invalid integer: {}", v))?),
v: i64 => Self(v),
}
macro_rules! signed_int { macro_rules! signed_int {
($($ty:ty)*) => { ($($ty:ty)*) => {
$(cast! { $(cast! {
$ty, $ty,
self => Value::Int(self as i64), self => Value::Int(self as _),
v: i64 => v.try_into().map_err(|_| "number too large")?, v: i64 => v.try_into().map_err(|_| "number too large")?,
})* })*
} }
@ -16,7 +76,7 @@ macro_rules! unsigned_int {
($($ty:ty)*) => { ($($ty:ty)*) => {
$(cast! { $(cast! {
$ty, $ty,
self => Value::Int(self as i64), self => Value::Int(self as _),
v: i64 => v.try_into().map_err(|_| { v: i64 => v.try_into().map_err(|_| {
if v < 0 { if v < 0 {
"number must be at least zero" "number must be at least zero"
@ -28,54 +88,55 @@ macro_rules! unsigned_int {
} }
} }
macro_rules! signed_nonzero { signed_int! { i8 i16 i32 isize }
($($ty:ty)*) => { unsigned_int! { u8 u16 u32 u64 usize }
$(cast! {
$ty, cast! {
self => Value::Int(self.get() as i64), NonZeroI64,
v: i64 => v self => Value::Int(self.get() as _),
.try_into() v: i64 => v.try_into()
.ok() .map_err(|_| if v == 0 {
.and_then($ty::new)
.ok_or_else(|| if v == 0 {
"number must not be zero" "number must not be zero"
} else { } else {
"number too large" "number too large"
})?, })?,
})*
}
} }
macro_rules! unsigned_nonzero { cast! {
($($ty:ty)*) => { NonZeroIsize,
$(cast! { self => Value::Int(self.get() as _),
$ty,
self => Value::Int(self.get() as i64),
v: i64 => v v: i64 => v
.try_into() .try_into()
.ok() .and_then(|v: isize| v.try_into())
.and_then($ty::new) .map_err(|_| if v == 0 {
.ok_or_else(|| if v <= 0 { "number must not be zero"
} else {
"number too large"
})?,
}
cast! {
NonZeroU64,
self => Value::Int(self.get() as _),
v: i64 => v
.try_into()
.and_then(|v: u64| v.try_into())
.map_err(|_| if v <= 0 {
"number must be positive" "number must be positive"
} else { } else {
"number too large" "number too large"
})?, })?,
})*
}
} }
signed_int! { cast! {
i8 i16 i32 isize NonZeroUsize,
} self => Value::Int(self.get() as _),
v: i64 => v
unsigned_int! { .try_into()
u8 u16 u32 u64 usize .and_then(|v: usize| v.try_into())
} .map_err(|_| if v <= 0 {
"number must be positive"
signed_nonzero! { } else {
NonZeroI64 NonZeroIsize "number too large"
} })?,
unsigned_nonzero! {
NonZeroU64 NonZeroUsize
} }

35
crates/typst/src/eval/library.rs
View File

@ -6,12 +6,11 @@ use comemo::Tracked;
use ecow::EcoString; use ecow::EcoString;
use std::sync::OnceLock; use std::sync::OnceLock;
use super::{Args, Dynamic, Module, NativeFunc, Value, Vm}; use super::Module;
use crate::diag::SourceResult; use crate::diag::SourceResult;
use crate::doc::Document; use crate::doc::Document;
use crate::geom::{Abs, Dir}; use crate::geom::{Abs, Dir};
use crate::model::{Content, ElemFunc, Introspector, Label, StyleChain, Styles, Vt}; use crate::model::{Content, Element, Introspector, Label, StyleChain, Styles, Vt};
use crate::syntax::Span;
use crate::util::hash128; use crate::util::hash128;
/// Definition of Typst's standard library. /// Definition of Typst's standard library.
@ -43,8 +42,8 @@ pub struct LangItems {
pub linebreak: fn() -> Content, pub linebreak: fn() -> Content,
/// Plain text without markup. /// Plain text without markup.
pub text: fn(text: EcoString) -> Content, pub text: fn(text: EcoString) -> Content,
/// The text function. /// The text element.
pub text_func: ElemFunc, pub text_elem: Element,
/// Get the string if this is a text element. /// Get the string if this is a text element.
pub text_str: fn(&Content) -> Option<EcoString>, pub text_str: fn(&Content) -> Option<EcoString>,
/// A smart quote: `'` or `"`. /// A smart quote: `'` or `"`.
@ -69,20 +68,14 @@ pub struct LangItems {
fn(introspector: Tracked<Introspector>) -> Vec<(EcoString, Option<EcoString>)>, fn(introspector: Tracked<Introspector>) -> Vec<(EcoString, Option<EcoString>)>,
/// A section heading: `= Introduction`. /// A section heading: `= Introduction`.
pub heading: fn(level: NonZeroUsize, body: Content) -> Content, pub heading: fn(level: NonZeroUsize, body: Content) -> Content,
/// The heading function. /// The heading element.
pub heading_func: ElemFunc, pub heading_elem: Element,
/// An item in a bullet list: `- ...`. /// An item in a bullet list: `- ...`.
pub list_item: fn(body: Content) -> Content, pub list_item: fn(body: Content) -> Content,
/// An item in an enumeration (numbered list): `+ ...` or `1. ...`. /// An item in an enumeration (numbered list): `+ ...` or `1. ...`.
pub enum_item: fn(number: Option<usize>, body: Content) -> Content, pub enum_item: fn(number: Option<usize>, body: Content) -> Content,
/// An item in a term list: `/ Term: Details`. /// An item in a term list: `/ Term: Details`.
pub term_item: fn(term: Content, description: Content) -> Content, pub term_item: fn(term: Content, description: Content) -> Content,
/// The constructor for the 'rgba' color kind.
pub rgb_func: &'static NativeFunc,
/// The constructor for the 'cmyk' color kind.
pub cmyk_func: &'static NativeFunc,
/// The constructor for the 'luma' color kind.
pub luma_func: &'static NativeFunc,
/// A mathematical equation: `$x$`, `$ x^2 $`. /// A mathematical equation: `$x$`, `$ x^2 $`.
pub equation: fn(body: Content, block: bool) -> Content, pub equation: fn(body: Content, block: bool) -> Content,
/// An alignment point in math: `&`. /// An alignment point in math: `&`.
@ -110,14 +103,6 @@ pub struct LangItems {
pub math_frac: fn(num: Content, denom: Content) -> Content, pub math_frac: fn(num: Content, denom: Content) -> Content,
/// A root in math: `√x`, `∛x` or `∜x`. /// A root in math: `√x`, `∛x` or `∜x`.
pub math_root: fn(index: Option<Content>, radicand: Content) -> Content, pub math_root: fn(index: Option<Content>, radicand: Content) -> Content,
/// Dispatch a method on a library value.
pub library_method: fn(
vm: &mut Vm,
dynamic: &Dynamic,
method: &str,
args: Args,
span: Span,
) -> SourceResult<Value>,
} }
impl Debug for LangItems { impl Debug for LangItems {
@ -134,7 +119,7 @@ impl Hash for LangItems {
self.space.hash(state); self.space.hash(state);
self.linebreak.hash(state); self.linebreak.hash(state);
self.text.hash(state); self.text.hash(state);
self.text_func.hash(state); self.text_elem.hash(state);
(self.text_str as usize).hash(state); (self.text_str as usize).hash(state);
self.smart_quote.hash(state); self.smart_quote.hash(state);
self.parbreak.hash(state); self.parbreak.hash(state);
@ -146,13 +131,10 @@ impl Hash for LangItems {
self.reference.hash(state); self.reference.hash(state);
(self.bibliography_keys as usize).hash(state); (self.bibliography_keys as usize).hash(state);
self.heading.hash(state); self.heading.hash(state);
self.heading_func.hash(state); self.heading_elem.hash(state);
self.list_item.hash(state); self.list_item.hash(state);
self.enum_item.hash(state); self.enum_item.hash(state);
self.term_item.hash(state); self.term_item.hash(state);
self.rgb_func.hash(state);
self.cmyk_func.hash(state);
self.luma_func.hash(state);
self.equation.hash(state); self.equation.hash(state);
self.math_align_point.hash(state); self.math_align_point.hash(state);
self.math_delimited.hash(state); self.math_delimited.hash(state);
@ -160,7 +142,6 @@ impl Hash for LangItems {
self.math_accent.hash(state); self.math_accent.hash(state);
self.math_frac.hash(state); self.math_frac.hash(state);
self.math_root.hash(state); self.math_root.hash(state);
(self.library_method as usize).hash(state);
} }
} }

479
crates/typst/src/eval/methods.rs
View File

@ -1,324 +1,37 @@
//! Methods on values. //! Handles special built-in methods on values.
use ecow::{eco_format, EcoString}; use super::{Args, Array, Dict, Str, Type, Value};
use crate::diag::{At, SourceResult};
use super::{Args, Bytes, IntoValue, Plugin, Str, Value, Vm};
use crate::diag::{At, Hint, SourceResult};
use crate::eval::bail;
use crate::geom::{Align, Axes, Color, Dir, Em, GenAlign};
use crate::model::{Location, Selector};
use crate::syntax::Span; use crate::syntax::Span;
/// Call a method on a value. /// Whether a specific method is mutating.
pub fn call( pub fn is_mutating(method: &str) -> bool {
vm: &mut Vm, matches!(method, "push" | "pop" | "insert" | "remove")
value: Value, }
method: &str,
mut args: Args,
span: Span,
) -> SourceResult<Value> {
let name = value.type_name();
let missing = || Err(missing_method(name, method)).at(span);
let output = match value { /// Whether a specific method is an accessor.
Value::Color(color) => match method { pub fn is_accessor(method: &str) -> bool {
"lighten" => color.lighten(args.expect("amount")?).into_value(), matches!(method, "first" | "last" | "at")
"darken" => color.darken(args.expect("amount")?).into_value(),
"negate" => color.negate().into_value(),
"kind" => match color {
Color::Luma(_) => vm.items.luma_func.into_value(),
Color::Rgba(_) => vm.items.rgb_func.into_value(),
Color::Cmyk(_) => vm.items.cmyk_func.into_value(),
},
"hex" => color.to_rgba().to_hex().into_value(),
"rgba" => color.to_rgba().to_array().into_value(),
"cmyk" => match color {
Color::Luma(luma) => luma.to_cmyk().to_array().into_value(),
Color::Rgba(_) => {
bail!(span, "cannot obtain cmyk values from rgba color")
} }
Color::Cmyk(cmyk) => cmyk.to_array().into_value(),
},
"luma" => match color {
Color::Luma(luma) => luma.0.into_value(),
Color::Rgba(_) => {
bail!(span, "cannot obtain the luma value of rgba color")
}
Color::Cmyk(_) => {
bail!(span, "cannot obtain the luma value of cmyk color")
}
},
_ => return missing(),
},
Value::Str(string) => match method { /// List the available methods for a type and whether they take arguments.
"len" => string.len().into_value(), pub fn mutable_methods_on(ty: Type) -> &'static [(&'static str, bool)] {
"first" => string.first().at(span)?.into_value(), if ty == Type::of::<Array>() {
"last" => string.last().at(span)?.into_value(), &[
"at" => string ("first", false),
.at(args.expect("index")?, args.named("default")?) ("last", false),
.at(span)? ("at", true),
.into_value(), ("pop", false),
"slice" => { ("push", true),
let start = args.expect("start")?; ("insert", true),
let mut end = args.eat()?; ("remove", true),
if end.is_none() { ]
end = args.named("count")?.map(|c: i64| start + c); } else if ty == Type::of::<Dict>() {
} &[("at", true), ("insert", true), ("remove", true)]
string.slice(start, end).at(span)?.into_value()
}
"clusters" => string.clusters().into_value(),
"codepoints" => string.codepoints().into_value(),
"contains" => string.contains(args.expect("pattern")?).into_value(),
"starts-with" => string.starts_with(args.expect("pattern")?).into_value(),
"ends-with" => string.ends_with(args.expect("pattern")?).into_value(),
"find" => string.find(args.expect("pattern")?).into_value(),
"position" => string.position(args.expect("pattern")?).into_value(),
"match" => string.match_(args.expect("pattern")?).into_value(),
"matches" => string.matches(args.expect("pattern")?).into_value(),
"replace" => {
let pattern = args.expect("pattern")?;
let with = args.expect("string or function")?;
let count = args.named("count")?;
string.replace(vm, pattern, with, count)?.into_value()
}
"rev" => string.rev().into_value(),
"trim" => {
let pattern = args.eat()?;
let at = args.named("at")?;
let repeat = args.named("repeat")?.unwrap_or(true);
string.trim(pattern, at, repeat).into_value()
}
"split" => string.split(args.eat()?).into_value(),
_ => return missing(),
},
Value::Bytes(bytes) => match method {
"len" => bytes.len().into_value(),
"at" => bytes.at(args.expect("index")?, args.named("default")?).at(span)?,
"slice" => {
let start = args.expect("start")?;
let mut end = args.eat()?;
if end.is_none() {
end = args.named("count")?.map(|c: i64| start + c);
}
bytes.slice(start, end).at(span)?.into_value()
}
_ => return missing(),
},
Value::Datetime(datetime) => match method {
"display" => datetime.display(args.eat()?).at(args.span)?.into_value(),
"year" => datetime.year().into_value(),
"month" => datetime.month().into_value(),
"weekday" => datetime.weekday().into_value(),
"day" => datetime.day().into_value(),
"hour" => datetime.hour().into_value(),
"minute" => datetime.minute().into_value(),
"second" => datetime.second().into_value(),
"ordinal" => datetime.ordinal().into_value(),
_ => return missing(),
},
Value::Duration(duration) => match method {
"seconds" => duration.seconds().into_value(),
"minutes" => duration.minutes().into_value(),
"hours" => duration.hours().into_value(),
"days" => duration.days().into_value(),
"weeks" => duration.weeks().into_value(),
_ => return missing(),
},
Value::Content(content) => match method {
"func" => content.func().into_value(),
"has" => content.has(&args.expect::<EcoString>("field")?).into_value(),
"at" => content
.at(&args.expect::<Str>("field")?, args.named("default")?)
.at(span)?,
"fields" => content.dict().into_value(),
"location" => content
.location()
.ok_or("this method can only be called on content returned by query(..)")
.at(span)?
.into_value(),
_ => return missing(),
},
Value::Array(array) => match method {
"len" => array.len().into_value(),
"first" => array.first().at(span)?.clone(),
"last" => array.last().at(span)?.clone(),
"at" => array.at(args.expect("index")?, args.named("default")?).at(span)?,
"slice" => {
let start = args.expect("start")?;
let mut end = args.eat()?;
if end.is_none() {
end = args.named("count")?.map(|c: i64| start + c);
}
array.slice(start, end).at(span)?.into_value()
}
"contains" => array.contains(&args.expect("value")?).into_value(),
"find" => array.find(vm, args.expect("function")?)?.into_value(),
"position" => array.position(vm, args.expect("function")?)?.into_value(),
"filter" => array.filter(vm, args.expect("function")?)?.into_value(),
"map" => array.map(vm, args.expect("function")?)?.into_value(),
"fold" => {
array.fold(vm, args.expect("initial value")?, args.expect("function")?)?
}
"sum" => array.sum(args.named("default")?, span)?,
"product" => array.product(args.named("default")?, span)?,
"any" => array.any(vm, args.expect("function")?)?.into_value(),
"all" => array.all(vm, args.expect("function")?)?.into_value(),
"flatten" => array.flatten().into_value(),
"rev" => array.rev().into_value(),
"split" => array.split(args.expect("separator")?).into_value(),
"join" => {
let sep = args.eat()?;
let last = args.named("last")?;
array.join(sep, last).at(span)?
}
"intersperse" => array.intersperse(args.expect("separator")?).into_value(),
"sorted" => array.sorted(vm, span, args.named("key")?)?.into_value(),
"zip" => array.zip(&mut args)?.into_value(),
"enumerate" => array
.enumerate(args.named("start")?.unwrap_or(0))
.at(span)?
.into_value(),
"dedup" => array.dedup(vm, args.named("key")?)?.into_value(),
_ => return missing(),
},
Value::Dict(dict) => match method {
"len" => dict.len().into_value(),
"at" => dict
.at(&args.expect::<Str>("key")?, args.named("default")?)
.at(span)?,
"keys" => dict.keys().into_value(),
"values" => dict.values().into_value(),
"pairs" => dict.pairs().into_value(),
_ => {
return if matches!(dict.at(method, None), Ok(Value::Func(_))) {
Err(missing_method(name, method))
.hint(eco_format!(
"to call the function stored in the dictionary, surround the field access with parentheses"
))
.at(span)
} else { } else {
missing() &[]
} }
} }
},
Value::Func(func) => match method {
"with" => func.with(args.take()).into_value(),
"where" => {
let fields = args.to_named();
args.items.retain(|arg| arg.name.is_none());
func.element()
.ok_or("`where()` can only be called on element functions")
.at(span)?
.where_(fields)
.into_value()
}
_ => return missing(),
},
Value::Length(length) => match method {
unit @ ("pt" | "cm" | "mm" | "inches") => {
if length.em != Em::zero() {
return Err(eco_format!("cannot convert a length with non-zero em units ({length:?}) to {unit}"))
.hint(eco_format!("use 'length.abs.{unit}()' instead to ignore its em component"))
.at(span);
}
match unit {
"pt" => length.abs.to_pt().into_value(),
"cm" => length.abs.to_cm().into_value(),
"mm" => length.abs.to_mm().into_value(),
"inches" => length.abs.to_inches().into_value(),
_ => unreachable!(),
}
}
_ => return missing(),
},
Value::Angle(angle) => match method {
"deg" => angle.to_deg().into_value(),
"rad" => angle.to_rad().into_value(),
_ => return missing(),
},
Value::Args(args) => match method {
"pos" => args.to_pos().into_value(),
"named" => args.to_named().into_value(),
_ => return missing(),
},
Value::Dyn(dynamic) => {
if let Some(location) = dynamic.downcast::<Location>() {
match method {
"page" => vm.vt.introspector.page(*location).into_value(),
"position" => vm.vt.introspector.position(*location).into_value(),
"page-numbering" => vm.vt.introspector.page_numbering(*location),
_ => return missing(),
}
} else if let Some(selector) = dynamic.downcast::<Selector>() {
match method {
"or" => selector.clone().or(args.all::<Selector>()?).into_value(),
"and" => selector.clone().and(args.all::<Selector>()?).into_value(),
"before" => {
let location = args.expect::<Selector>("selector")?;
let inclusive =
args.named_or_find::<bool>("inclusive")?.unwrap_or(true);
selector.clone().before(location, inclusive).into_value()
}
"after" => {
let location = args.expect::<Selector>("selector")?;
let inclusive =
args.named_or_find::<bool>("inclusive")?.unwrap_or(true);
selector.clone().after(location, inclusive).into_value()
}
_ => return missing(),
}
} else if let Some(direction) = dynamic.downcast::<Dir>() {
match method {
"axis" => direction.axis().description().into_value(),
"start" => {
GenAlign::from(Align::from(direction.start())).into_value()
}
"end" => GenAlign::from(Align::from(direction.end())).into_value(),
"inv" => direction.inv().into_value(),
_ => return missing(),
}
} else if let Some(align) = dynamic.downcast::<GenAlign>() {
match method {
"axis" => align.axis().description().into_value(),
"inv" => align.inv().into_value(),
_ => return missing(),
}
} else if let Some(align2d) = dynamic.downcast::<Axes<GenAlign>>() {
match method {
"inv" => align2d.map(GenAlign::inv).into_value(),
_ => return missing(),
}
} else if let Some(plugin) = dynamic.downcast::<Plugin>() {
if plugin.iter().any(|func_name| func_name == method) {
let bytes = args.all::<Bytes>()?;
args.take().finish()?;
plugin.call(method, bytes).at(span)?.into_value()
} else {
return missing();
}
} else {
return (vm.items.library_method)(vm, &dynamic, method, args, span);
}
}
_ => return missing(),
};
args.finish()?;
Ok(output)
}
/// Call a mutating method on a value. /// Call a mutating method on a value.
pub fn call_mut( pub fn call_mut(
@ -327,8 +40,8 @@ pub fn call_mut(
mut args: Args, mut args: Args,
span: Span, span: Span,
) -> SourceResult<Value> { ) -> SourceResult<Value> {
let name = value.type_name(); let ty = value.ty();
let missing = || Err(missing_method(name, method)).at(span); let missing = || Err(missing_method(ty, method)).at(span);
let mut output = Value::None; let mut output = Value::None;
match value { match value {
@ -344,9 +57,7 @@ pub fn call_mut(
Value::Dict(dict) => match method { Value::Dict(dict) => match method {
"insert" => dict.insert(args.expect::<Str>("key")?, args.expect("value")?), "insert" => dict.insert(args.expect::<Str>("key")?, args.expect("value")?),
"remove" => { "remove" => output = dict.remove(args.expect::<Str>("key")?).at(span)?,
output = dict.remove(&args.expect::<EcoString>("key")?).at(span)?
}
_ => return missing(), _ => return missing(),
}, },
@ -364,8 +75,8 @@ pub fn call_access<'a>(
mut args: Args, mut args: Args,
span: Span, span: Span,
) -> SourceResult<&'a mut Value> { ) -> SourceResult<&'a mut Value> {
let name = value.type_name(); let ty = value.ty();
let missing = || Err(missing_method(name, method)).at(span); let missing = || Err(missing_method(ty, method)).at(span);
let slot = match value { let slot = match value {
Value::Array(array) => match method { Value::Array(array) => match method {
@ -385,134 +96,8 @@ pub fn call_access<'a>(
Ok(slot) Ok(slot)
} }
/// Whether a specific method is mutating.
pub fn is_mutating(method: &str) -> bool {
matches!(method, "push" | "pop" | "insert" | "remove")
}
/// Whether a specific method is an accessor.
pub fn is_accessor(method: &str) -> bool {
matches!(method, "first" | "last" | "at")
}
/// The missing method error message. /// The missing method error message.
#[cold] #[cold]
fn missing_method(type_name: &str, method: &str) -> String { fn missing_method(ty: Type, method: &str) -> String {
format!("type {type_name} has no method `{method}`") format!("type {ty} has no method `{method}`")
}
/// List the available methods for a type and whether they take arguments.
pub fn methods_on(type_name: &str) -> &[(&'static str, bool)] {
match type_name {
"color" => &[
("lighten", true),
("darken", true),
("negate", false),
("kind", false),
("hex", false),
("rgba", false),
("cmyk", false),
("luma", false),
],
"string" => &[
("len", false),
("at", true),
("clusters", false),
("codepoints", false),
("contains", true),
("ends-with", true),
("find", true),
("first", false),
("last", false),
("match", true),
("matches", true),
("position", true),
("replace", true),
("slice", true),
("split", true),
("starts-with", true),
("trim", true),
],
"bytes" => &[("len", false), ("at", true), ("slice", true)],
"datetime" => &[
("display", true),
("year", false),
("month", false),
("weekday", false),
("day", false),
("hour", false),
("minute", false),
("second", false),
("ordinal", false),
],
"duration" => &[
("seconds", false),
("minutes", false),
("hours", false),
("days", false),
("weeks", false),
],
"content" => &[
("func", false),
("has", true),
("at", true),
("fields", false),
("location", false),
],
"array" => &[
("all", true),
("any", true),
("at", true),
("contains", true),
("filter", true),
("find", true),
("first", false),
("flatten", false),
("fold", true),
("insert", true),
("split", true),
("join", true),
("last", false),
("len", false),
("map", true),
("pop", false),
("position", true),
("push", true),
("remove", true),
("rev", false),
("slice", true),
("sorted", false),
("enumerate", false),
("zip", true),
],
"dictionary" => &[
("at", true),
("insert", true),
("keys", false),
("len", false),
("pairs", false),
("remove", true),
("values", false),
],
"function" => &[("where", true), ("with", true)],
"length" => &[("pt", false), ("cm", false), ("mm", false), ("inches", false)],
"angle" => &[("deg", false), ("rad", false)],
"arguments" => &[("named", false), ("pos", false)],
"location" => &[("page", false), ("position", false), ("page-numbering", false)],
"selector" => &[("or", true), ("and", true), ("before", true), ("after", true)],
"direction" => {
&[("axis", false), ("start", false), ("end", false), ("inv", false)]
}
"alignment" => &[("axis", false), ("inv", false)],
"2d alignment" => &[("inv", false)],
"counter" => &[
("display", true),
("at", true),
("final", true),
("step", true),
("update", true),
],
"state" => &[("display", true), ("at", true), ("final", true), ("update", true)],
_ => &[],
}
} }

191
crates/typst/src/eval/mod.rs
View File

@ -14,10 +14,12 @@ mod str;
mod value; mod value;
mod args; mod args;
mod auto; mod auto;
mod bool;
mod bytes; mod bytes;
mod datetime; mod datetime;
mod duration; mod duration;
mod fields; mod fields;
mod float;
mod func; mod func;
mod int; mod int;
mod methods; mod methods;
@ -28,6 +30,7 @@ mod plugin;
mod scope; mod scope;
mod symbol; mod symbol;
mod tracer; mod tracer;
mod ty;
#[doc(hidden)] #[doc(hidden)]
pub use { pub use {
@ -37,9 +40,6 @@ pub use {
once_cell::sync::Lazy, once_cell::sync::Lazy,
}; };
#[doc(inline)]
pub use typst_macros::{func, symbols};
pub use self::args::{Arg, Args}; pub use self::args::{Arg, Args};
pub use self::array::{array, Array}; pub use self::array::{array, Array};
pub use self::auto::AutoValue; pub use self::auto::AutoValue;
@ -50,18 +50,20 @@ pub use self::cast::{
pub use self::datetime::Datetime; pub use self::datetime::Datetime;
pub use self::dict::{dict, Dict}; pub use self::dict::{dict, Dict};
pub use self::duration::Duration; pub use self::duration::Duration;
pub use self::fields::fields_on; pub use self::func::{func, Func, NativeFunc, NativeFuncData, ParamInfo};
pub use self::func::{Func, FuncInfo, NativeFunc, ParamInfo};
pub use self::library::{set_lang_items, LangItems, Library}; pub use self::library::{set_lang_items, LangItems, Library};
pub use self::methods::methods_on;
pub use self::module::Module; pub use self::module::Module;
pub use self::none::NoneValue; pub use self::none::NoneValue;
pub use self::plugin::Plugin; pub use self::plugin::Plugin;
pub use self::scope::{Scope, Scopes}; pub use self::scope::{NativeScope, Scope, Scopes};
pub use self::str::{format_str, Regex, Str}; pub use self::str::{format_str, Regex, Str};
pub use self::symbol::Symbol; pub use self::symbol::{symbols, Symbol};
pub use self::tracer::Tracer; pub use self::tracer::Tracer;
pub use self::value::{Dynamic, Type, Value}; pub use self::ty::{scope, ty, NativeType, NativeTypeData, Type};
pub use self::value::{Dynamic, Value};
pub(crate) use self::fields::fields_on;
pub(crate) use self::methods::mutable_methods_on;
use std::collections::HashSet; use std::collections::HashSet;
use std::mem; use std::mem;
@ -150,7 +152,7 @@ pub fn eval(
.unwrap_or_default() .unwrap_or_default()
.to_string_lossy(); .to_string_lossy();
Ok(Module::new(name).with_scope(vm.scopes.top).with_content(output)) Ok(Module::new(name, vm.scopes.top).with_content(output))
} }
/// Evaluate a string as code and return the resulting value. /// Evaluate a string as code and return the resulting value.
@ -575,7 +577,7 @@ impl Eval for ast::Escape<'_> {
#[tracing::instrument(name = "Escape::eval", skip_all)] #[tracing::instrument(name = "Escape::eval", skip_all)]
fn eval(self, _: &mut Vm) -> SourceResult<Self::Output> { fn eval(self, _: &mut Vm) -> SourceResult<Self::Output> {
Ok(Value::Symbol(Symbol::new(self.get()))) Ok(Value::Symbol(Symbol::single(self.get())))
} }
} }
@ -584,7 +586,7 @@ impl Eval for ast::Shorthand<'_> {
#[tracing::instrument(name = "Shorthand::eval", skip_all)] #[tracing::instrument(name = "Shorthand::eval", skip_all)]
fn eval(self, _: &mut Vm) -> SourceResult<Self::Output> { fn eval(self, _: &mut Vm) -> SourceResult<Self::Output> {
Ok(Value::Symbol(Symbol::new(self.get()))) Ok(Value::Symbol(Symbol::single(self.get())))
} }
} }
@ -992,7 +994,7 @@ impl Eval for ast::Array<'_> {
ast::ArrayItem::Spread(expr) => match expr.eval(vm)? { ast::ArrayItem::Spread(expr) => match expr.eval(vm)? {
Value::None => {} Value::None => {}
Value::Array(array) => vec.extend(array.into_iter()), Value::Array(array) => vec.extend(array.into_iter()),
v => bail!(expr.span(), "cannot spread {} into array", v.type_name()), v => bail!(expr.span(), "cannot spread {} into array", v.ty()),
}, },
} }
} }
@ -1019,11 +1021,7 @@ impl Eval for ast::Dict<'_> {
ast::DictItem::Spread(expr) => match expr.eval(vm)? { ast::DictItem::Spread(expr) => match expr.eval(vm)? {
Value::None => {} Value::None => {}
Value::Dict(dict) => map.extend(dict.into_iter()), Value::Dict(dict) => map.extend(dict.into_iter()),
v => bail!( v => bail!(expr.span(), "cannot spread {} into dictionary", v.ty()),
expr.span(),
"cannot spread {} into dictionary",
v.type_name()
),
}, },
} }
} }
@ -1085,8 +1083,8 @@ fn apply_binary_expr(
let lhs = binary.lhs().eval(vm)?; let lhs = binary.lhs().eval(vm)?;
// Short-circuit boolean operations. // Short-circuit boolean operations.
if (binary.op() == ast::BinOp::And && lhs == Value::Bool(false)) if (binary.op() == ast::BinOp::And && lhs == false.into_value())
|| (binary.op() == ast::BinOp::Or && lhs == Value::Bool(true)) || (binary.op() == ast::BinOp::Or && lhs == true.into_value())
{ {
return Ok(lhs); return Ok(lhs);
} }
@ -1146,49 +1144,83 @@ impl Eval for ast::FuncCall<'_> {
let callee_span = callee.span(); let callee_span = callee.span();
let args = self.args(); let args = self.args();
// Try to evaluate as a method call. This is possible if the callee is a // Try to evaluate as a call to an associated function or field.
// field access and does not evaluate to a module.
let (callee, mut args) = if let ast::Expr::FieldAccess(access) = callee { let (callee, mut args) = if let ast::Expr::FieldAccess(access) = callee {
let target = access.target(); let target = access.target();
let target_span = target.span();
let field = access.field(); let field = access.field();
let point = || Tracepoint::Call(Some(field.get().clone())); let field_span = field.span();
if methods::is_mutating(&field) {
let args = args.eval(vm)?; let target = if methods::is_mutating(&field) {
let mut args = args.eval(vm)?;
let target = target.access(vm)?; let target = target.access(vm)?;
// Prioritize a function's own methods (with, where) over its // Only arrays and dictionaries have mutable methods.
// fields. This is fine as we define each field of a function, if matches!(target, Value::Array(_) | Value::Dict(_)) {
// if it has any. args.span = span;
// ('methods_on' will be empty for Symbol and Module - their let point = || Tracepoint::Call(Some(field.get().clone()));
// method calls always refer to their fields.)
if !matches!(target, Value::Symbol(_) | Value::Module(_) | Value::Func(_))
|| methods_on(target.type_name())
.iter()
.any(|&(m, _)| m == field.as_str())
{
return methods::call_mut(target, &field, args, span).trace( return methods::call_mut(target, &field, args, span).trace(
vm.world(), vm.world(),
point, point,
span, span,
); );
} }
(target.field(&field).at(field.span())?, args)
} else {
let target = target.eval(vm)?;
let args = args.eval(vm)?;
if !matches!(target, Value::Symbol(_) | Value::Module(_) | Value::Func(_)) target.clone()
|| methods_on(target.type_name()) } else {
.iter() access.target().eval(vm)?
.any(|&(m, _)| m == field.as_str()) };
{
return methods::call(vm, target, &field, args, span).trace( let mut args = args.eval(vm)?;
vm.world(),
point, // Handle plugins.
span, if let Value::Plugin(plugin) = &target {
let bytes = args.all::<Bytes>()?;
args.finish()?;
return Ok(plugin.call(&field, bytes).at(span)?.into_value());
}
// Prioritize associated functions on the value's type (i.e.,
// methods) over its fields. A function call on a field is only
// allowed for functions, types, modules (because they are scopes),
// and symbols (because they have modifiers).
//
// For dictionaries, it is not allowed because it would be ambigious
// (prioritizing associated functions would make an addition of a
// new associated function a breaking change and prioritizing fields
// would break associated functions for certain dictionaries).
if let Some(callee) = target.ty().scope().get(&field) {
let this = Arg {
span: target_span,
name: None,
value: Spanned::new(target, target_span),
};
args.span = span;
args.items.insert(0, this);
(callee.clone(), args)
} else if matches!(
target,
Value::Symbol(_) | Value::Func(_) | Value::Type(_) | Value::Module(_)
) {
(target.field(&field).at(field_span)?, args)
} else {
let mut error = error!(
field_span,
"type {} has no method `{}`",
target.ty(),
field.as_str()
);
if let Value::Dict(dict) = target {
if matches!(dict.get(&field), Ok(Value::Func(_))) {
error.hint(
"to call the function stored in the dictionary, \
surround the field access with parentheses",
); );
} }
(target.field(&field).at(field.span())?, args) }
bail!(error);
} }
} else { } else {
(callee.eval(vm)?, args.eval(vm)?) (callee.eval(vm)?, args.eval(vm)?)
@ -1284,7 +1316,7 @@ impl Eval for ast::Args<'_> {
})); }));
} }
Value::Args(args) => items.extend(args.items), Value::Args(args) => items.extend(args.items),
v => bail!(expr.span(), "cannot spread {}", v.type_name()), v => bail!(expr.span(), "cannot spread {}", v.ty()),
}, },
} }
} }
@ -1364,7 +1396,7 @@ where
ast::Pattern::Destructuring(destruct) => match value { ast::Pattern::Destructuring(destruct) => match value {
Value::Array(value) => destructure_array(vm, pattern, value, f, destruct)?, Value::Array(value) => destructure_array(vm, pattern, value, f, destruct)?,
Value::Dict(value) => destructure_dict(vm, value, f, destruct)?, Value::Dict(value) => destructure_dict(vm, value, f, destruct)?,
_ => bail!(pattern.span(), "cannot destructure {}", value.type_name()), _ => bail!(pattern.span(), "cannot destructure {}", value.ty()),
}, },
} }
Ok(()) Ok(())
@ -1436,21 +1468,15 @@ where
for p in destruct.bindings() { for p in destruct.bindings() {
match p { match p {
ast::DestructuringKind::Normal(ast::Expr::Ident(ident)) => { ast::DestructuringKind::Normal(ast::Expr::Ident(ident)) => {
let v = dict let v = dict.get(&ident).at(ident.span())?;
.at(&ident, None) f(vm, ast::Expr::Ident(ident), v.clone())?;
.map_err(|_| "destructuring key not found in dictionary")
.at(ident.span())?;
f(vm, ast::Expr::Ident(ident), v)?;
used.insert(ident.as_str()); used.insert(ident.as_str());
} }
ast::DestructuringKind::Sink(spread) => sink = spread.expr(), ast::DestructuringKind::Sink(spread) => sink = spread.expr(),
ast::DestructuringKind::Named(named) => { ast::DestructuringKind::Named(named) => {
let name = named.name(); let name = named.name();
let v = dict let v = dict.get(&name).at(name.span())?;
.at(&name, None) f(vm, named.expr(), v.clone())?;
.map_err(|_| "destructuring key not found in dictionary")
.at(name.span())?;
f(vm, named.expr(), v)?;
used.insert(name.as_str()); used.insert(name.as_str());
} }
ast::DestructuringKind::Placeholder(_) => {} ast::DestructuringKind::Placeholder(_) => {}
@ -1690,10 +1716,10 @@ impl Eval for ast::ForLoop<'_> {
iter!(for pattern in array); iter!(for pattern in array);
} }
(ast::Pattern::Normal(_), _) => { (ast::Pattern::Normal(_), _) => {
bail!(self.iter().span(), "cannot loop over {}", iter.type_name()); bail!(self.iter().span(), "cannot loop over {}", iter.ty());
} }
(_, _) => { (_, _) => {
bail!(pattern.span(), "cannot destructure values of {}", iter.type_name()) bail!(pattern.span(), "cannot destructure values of {}", iter.ty())
} }
} }
@ -1789,16 +1815,25 @@ impl Eval for ast::ModuleImport<'_> {
} }
} }
if let Value::Func(func) = source { if let Value::Func(func) = source {
if func.info().is_none() { let Some(scope) = func.scope() else {
bail!(span, "cannot import from user-defined functions"); bail!(span, "cannot import from user-defined functions");
} };
apply_imports( apply_imports(
self.imports(), self.imports(),
vm, vm,
func, func,
new_name, new_name,
|func| func.info().unwrap().name.into(), |func| func.name().unwrap_or_default().into(),
|func| &func.info().unwrap().scope, |_| scope,
)?;
} else if let Value::Type(ty) = source {
apply_imports(
self.imports(),
vm,
ty,
new_name,
|ty| ty.short_name().into(),
|ty| ty.scope(),
)?; )?;
} else { } else {
let module = import(vm, source, span, true)?; let module = import(vm, source, span, true)?;
@ -1833,16 +1868,16 @@ fn import(
vm: &mut Vm, vm: &mut Vm,
source: Value, source: Value,
span: Span, span: Span,
accept_functions: bool, allow_scopes: bool,
) -> SourceResult<Module> { ) -> SourceResult<Module> {
let path = match source { let path = match source {
Value::Str(path) => path, Value::Str(path) => path,
Value::Module(module) => return Ok(module), Value::Module(module) => return Ok(module),
v => { v => {
if accept_functions { if allow_scopes {
bail!(span, "expected path, module or function, found {}", v.type_name()) bail!(span, "expected path, module, function, or type, found {}", v.ty())
} else { } else {
bail!(span, "expected path or module, found {}", v.type_name()) bail!(span, "expected path or module, found {}", v.ty())
} }
} }
}; };
@ -2038,20 +2073,22 @@ fn access_dict<'a>(
match access.target().access(vm)? { match access.target().access(vm)? {
Value::Dict(dict) => Ok(dict), Value::Dict(dict) => Ok(dict),
value => { value => {
let type_name = value.type_name(); let ty = value.ty();
let span = access.target().span(); let span = access.target().span();
if matches!( if matches!(
value, // those types have their own field getters value, // those types have their own field getters
Value::Symbol(_) | Value::Content(_) | Value::Module(_) | Value::Func(_) Value::Symbol(_) | Value::Content(_) | Value::Module(_) | Value::Func(_)
) { ) {
bail!(span, "cannot mutate fields on {type_name}"); bail!(span, "cannot mutate fields on {ty}");
} else if fields::fields_on(type_name).is_empty() { } else if fields::fields_on(ty).is_empty() {
bail!(span, "{type_name} does not have accessible fields"); bail!(span, "{ty} does not have accessible fields");
} else { } else {
// type supports static fields, which don't yet have // type supports static fields, which don't yet have
// setters // setters
Err(eco_format!("fields on {type_name} are not yet mutable")) Err(eco_format!("fields on {ty} are not yet mutable"))
.hint(eco_format!("try creating a new {type_name} with the updated field value instead")) .hint(eco_format!(
"try creating a new {ty} with the updated field value instead"
))
.at(span) .at(span)
} }
} }

27
crates/typst/src/eval/module.rs
View File

@ -3,12 +3,27 @@ use std::sync::Arc;
use ecow::{eco_format, EcoString}; use ecow::{eco_format, EcoString};
use super::{Content, Scope, Value}; use super::{ty, Content, Scope, Value};
use crate::diag::StrResult; use crate::diag::StrResult;
/// An evaluated module, ready for importing or typesetting. /// An evaluated module, either built-in or resulting from a file.
/// ///
/// Values of this type are cheap to clone and hash. /// You can access definitions from the module using [field access
/// notation]($scripting/#fields) and interact with it using the [import and
/// include syntaxes]($scripting/#modules).
///
/// # Example
/// ```example
/// <<< #import "utils.typ"
/// <<< #utils.add(2, 5)
///
/// <<< #import utils: sub
/// <<< #sub(1, 4)
/// >>> #7
/// >>>
/// >>> #(-3)
/// ```
#[ty]
#[derive(Clone, Hash)] #[derive(Clone, Hash)]
#[allow(clippy::derived_hash_with_manual_eq)] #[allow(clippy::derived_hash_with_manual_eq)]
pub struct Module { pub struct Module {
@ -29,10 +44,10 @@ struct Repr {
impl Module { impl Module {
/// Create a new module. /// Create a new module.
pub fn new(name: impl Into<EcoString>) -> Self { pub fn new(name: impl Into<EcoString>, scope: Scope) -> Self {
Self { Self {
name: name.into(), name: name.into(),
inner: Arc::new(Repr { scope: Scope::new(), content: Content::empty() }), inner: Arc::new(Repr { scope, content: Content::empty() }),
} }
} }
@ -70,7 +85,7 @@ impl Module {
} }
/// Try to access a definition in the module. /// Try to access a definition in the module.
pub fn get(&self, name: &str) -> StrResult<&Value> { pub fn field(&self, name: &str) -> StrResult<&Value> {
self.scope().get(name).ok_or_else(|| { self.scope().get(name).ok_or_else(|| {
eco_format!("module `{}` does not contain `{name}`", self.name()) eco_format!("module `{}` does not contain `{name}`", self.name())
}) })

41
crates/typst/src/eval/none.rs
View File

@ -1,15 +1,33 @@
use std::fmt::{self, Debug, Formatter}; use std::fmt::{self, Debug, Formatter};
use super::{cast, CastInfo, FromValue, IntoValue, Reflect, Value}; use serde::{Serialize, Serializer};
use super::{cast, ty, CastInfo, FromValue, IntoValue, Reflect, Type, Value};
use crate::diag::StrResult; use crate::diag::StrResult;
/// A value that indicates the absence of any other value. /// A value that indicates the absence of any other value.
///
/// The none type has exactly one value: `{none}`.
///
/// When inserted into the document, it is not visible. This is also the value
/// that is produced by empty code blocks. It can be
/// [joined]($scripting/#blocks) with any value, yielding the other value.
///
/// # Example
/// ```example
/// Not visible: #none
/// ```
#[ty(name = "none")]
#[derive(Default, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)] #[derive(Default, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
pub struct NoneValue; pub struct NoneValue;
impl Reflect for NoneValue { impl Reflect for NoneValue {
fn describe() -> CastInfo { fn input() -> CastInfo {
CastInfo::Type("none") CastInfo::Type(Type::of::<Self>())
}
fn output() -> CastInfo {
CastInfo::Type(Type::of::<Self>())
} }
fn castable(value: &Value) -> bool { fn castable(value: &Value) -> bool {
@ -38,6 +56,15 @@ impl Debug for NoneValue {
} }
} }
impl Serialize for NoneValue {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
serializer.serialize_none()
}
}
cast! { cast! {
(), (),
self => Value::None, self => Value::None,
@ -45,8 +72,12 @@ cast! {
} }
impl<T: Reflect> Reflect for Option<T> { impl<T: Reflect> Reflect for Option<T> {
fn describe() -> CastInfo { fn input() -> CastInfo {
T::describe() + NoneValue::describe() T::input() + NoneValue::input()
}
fn output() -> CastInfo {
T::output() + NoneValue::output()
} }
fn castable(value: &Value) -> bool { fn castable(value: &Value) -> bool {

53
crates/typst/src/eval/ops.rs
View File

@ -5,15 +5,15 @@ use std::fmt::Debug;
use ecow::eco_format; use ecow::eco_format;
use super::{format_str, Regex, Value}; use super::{format_str, IntoValue, Regex, Value};
use crate::diag::{bail, StrResult}; use crate::diag::{bail, StrResult};
use crate::geom::{Axes, Axis, GenAlign, Length, Numeric, PartialStroke, Rel, Smart}; use crate::geom::{Align, Length, Numeric, Rel, Smart, Stroke};
use Value::*; use Value::*;
/// Bail with a type mismatch error. /// Bail with a type mismatch error.
macro_rules! mismatch { macro_rules! mismatch {
($fmt:expr, $($value:expr),* $(,)?) => { ($fmt:expr, $($value:expr),* $(,)?) => {
return Err(eco_format!($fmt, $($value.type_name()),*)) return Err(eco_format!($fmt, $($value.ty()),*))
}; };
} }
@ -55,7 +55,7 @@ pub fn pos(value: Value) -> StrResult<Value> {
/// Compute the negation of a value. /// Compute the negation of a value.
pub fn neg(value: Value) -> StrResult<Value> { pub fn neg(value: Value) -> StrResult<Value> {
Ok(match value { Ok(match value {
Int(v) => Int(v.checked_neg().ok_or("value is too large")?), Int(v) => Int(v.checked_neg().ok_or_else(too_large)?),
Float(v) => Float(-v), Float(v) => Float(-v),
Length(v) => Length(-v), Length(v) => Length(-v),
Angle(v) => Angle(-v), Angle(v) => Angle(-v),
@ -73,7 +73,7 @@ pub fn add(lhs: Value, rhs: Value) -> StrResult<Value> {
(a, None) => a, (a, None) => a,
(None, b) => b, (None, b) => b,
(Int(a), Int(b)) => Int(a.checked_add(b).ok_or("value is too large")?), (Int(a), Int(b)) => Int(a.checked_add(b).ok_or_else(too_large)?),
(Int(a), Float(b)) => Float(a as f64 + b), (Int(a), Float(b)) => Float(a as f64 + b),
(Float(a), Int(b)) => Float(a + b as f64), (Float(a), Int(b)) => Float(a + b as f64),
(Float(a), Float(b)) => Float(a + b), (Float(a), Float(b)) => Float(a + b),
@ -108,33 +108,23 @@ pub fn add(lhs: Value, rhs: Value) -> StrResult<Value> {
(Array(a), Array(b)) => Array(a + b), (Array(a), Array(b)) => Array(a + b),
(Dict(a), Dict(b)) => Dict(a + b), (Dict(a), Dict(b)) => Dict(a + b),
(Color(color), Length(thickness)) | (Length(thickness), Color(color)) => { (Color(color), Length(thickness)) | (Length(thickness), Color(color)) => Stroke {
Value::dynamic(PartialStroke {
paint: Smart::Custom(color.into()), paint: Smart::Custom(color.into()),
thickness: Smart::Custom(thickness), thickness: Smart::Custom(thickness),
..PartialStroke::default() ..Stroke::default()
})
} }
.into_value(),
(Duration(a), Duration(b)) => Duration(a + b), (Duration(a), Duration(b)) => Duration(a + b),
(Datetime(a), Duration(b)) => Datetime(a + b), (Datetime(a), Duration(b)) => Datetime(a + b),
(Duration(a), Datetime(b)) => Datetime(b + a), (Duration(a), Datetime(b)) => Datetime(b + a),
(Dyn(a), Dyn(b)) => { (Dyn(a), Dyn(b)) => {
// 1D alignments can be summed into 2D alignments. // Alignments can be summed.
if let (Some(&a), Some(&b)) = if let (Some(&a), Some(&b)) = (a.downcast::<Align>(), b.downcast::<Align>()) {
(a.downcast::<GenAlign>(), b.downcast::<GenAlign>()) return Ok((a + b)?.into_value());
{
if a.axis() == b.axis() {
return Err(eco_format!("cannot add two {:?} alignments", a.axis()));
} }
return Ok(Value::dynamic(match a.axis() {
Axis::X => Axes { x: a, y: b },
Axis::Y => Axes { x: b, y: a },
}));
};
mismatch!("cannot add {} and {}", a, b); mismatch!("cannot add {} and {}", a, b);
} }
@ -145,7 +135,7 @@ pub fn add(lhs: Value, rhs: Value) -> StrResult<Value> {
/// Compute the difference of two values. /// Compute the difference of two values.
pub fn sub(lhs: Value, rhs: Value) -> StrResult<Value> { pub fn sub(lhs: Value, rhs: Value) -> StrResult<Value> {
Ok(match (lhs, rhs) { Ok(match (lhs, rhs) {
(Int(a), Int(b)) => Int(a.checked_sub(b).ok_or("value is too large")?), (Int(a), Int(b)) => Int(a.checked_sub(b).ok_or_else(too_large)?),
(Int(a), Float(b)) => Float(a as f64 - b), (Int(a), Float(b)) => Float(a as f64 - b),
(Float(a), Int(b)) => Float(a - b as f64), (Float(a), Int(b)) => Float(a - b as f64),
(Float(a), Float(b)) => Float(a - b), (Float(a), Float(b)) => Float(a - b),
@ -177,7 +167,7 @@ pub fn sub(lhs: Value, rhs: Value) -> StrResult<Value> {
/// Compute the product of two values. /// Compute the product of two values.
pub fn mul(lhs: Value, rhs: Value) -> StrResult<Value> { pub fn mul(lhs: Value, rhs: Value) -> StrResult<Value> {
Ok(match (lhs, rhs) { Ok(match (lhs, rhs) {
(Int(a), Int(b)) => Int(a.checked_mul(b).ok_or("value is too large")?), (Int(a), Int(b)) => Int(a.checked_mul(b).ok_or_else(too_large)?),
(Int(a), Float(b)) => Float(a as f64 * b), (Int(a), Float(b)) => Float(a as f64 * b),
(Float(a), Int(b)) => Float(a * b as f64), (Float(a), Int(b)) => Float(a * b as f64),
(Float(a), Float(b)) => Float(a * b), (Float(a), Float(b)) => Float(a * b),
@ -216,10 +206,10 @@ pub fn mul(lhs: Value, rhs: Value) -> StrResult<Value> {
(Float(a), Fraction(b)) => Fraction(a * b), (Float(a), Fraction(b)) => Fraction(a * b),
(Ratio(a), Fraction(b)) => Fraction(a.get() * b), (Ratio(a), Fraction(b)) => Fraction(a.get() * b),
(Str(a), Int(b)) => Str(a.repeat(b)?), (Str(a), Int(b)) => Str(a.repeat(Value::Int(b).cast()?)?),
(Int(a), Str(b)) => Str(b.repeat(a)?), (Int(a), Str(b)) => Str(b.repeat(Value::Int(a).cast()?)?),
(Array(a), Int(b)) => Array(a.repeat(b)?), (Array(a), Int(b)) => Array(a.repeat(Value::Int(b).cast()?)?),
(Int(a), Array(b)) => Array(b.repeat(a)?), (Int(a), Array(b)) => Array(b.repeat(Value::Int(a).cast()?)?),
(Content(a), b @ Int(_)) => Content(a.repeat(b.cast()?)), (Content(a), b @ Int(_)) => Content(a.repeat(b.cast()?)),
(a @ Int(_), Content(b)) => Content(b.repeat(a.cast()?)), (a @ Int(_), Content(b)) => Content(b.repeat(a.cast()?)),
@ -375,7 +365,9 @@ pub fn equal(lhs: &Value, rhs: &Value) -> bool {
(Dict(a), Dict(b)) => a == b, (Dict(a), Dict(b)) => a == b,
(Func(a), Func(b)) => a == b, (Func(a), Func(b)) => a == b,
(Args(a), Args(b)) => a == b, (Args(a), Args(b)) => a == b,
(Type(a), Type(b)) => a == b,
(Module(a), Module(b)) => a == b, (Module(a), Module(b)) => a == b,
(Plugin(a), Plugin(b)) => a == b,
(Datetime(a), Datetime(b)) => a == b, (Datetime(a), Datetime(b)) => a == b,
(Duration(a), Duration(b)) => a == b, (Duration(a), Duration(b)) => a == b,
(Dyn(a), Dyn(b)) => a == b, (Dyn(a), Dyn(b)) => a == b,
@ -456,7 +448,12 @@ pub fn contains(lhs: &Value, rhs: &Value) -> Option<bool> {
(Str(a), Str(b)) => Some(b.as_str().contains(a.as_str())), (Str(a), Str(b)) => Some(b.as_str().contains(a.as_str())),
(Dyn(a), Str(b)) => a.downcast::<Regex>().map(|regex| regex.is_match(b)), (Dyn(a), Str(b)) => a.downcast::<Regex>().map(|regex| regex.is_match(b)),
(Str(a), Dict(b)) => Some(b.contains(a)), (Str(a), Dict(b)) => Some(b.contains(a)),
(a, Array(b)) => Some(b.contains(a)), (a, Array(b)) => Some(b.contains(a.clone())),
_ => Option::None, _ => Option::None,
} }
} }
#[cold]
fn too_large() -> &'static str {
"value is too large"
}

122
crates/typst/src/eval/plugin.rs
View File

@ -5,14 +5,105 @@ use ecow::{eco_format, EcoString};
use std::sync::{Arc, Mutex}; use std::sync::{Arc, Mutex};
use wasmi::{AsContext, AsContextMut, Caller, Engine, Linker, Module}; use wasmi::{AsContext, AsContextMut, Caller, Engine, Linker, Module};
use super::{cast, Bytes}; use super::{func, scope, ty, Bytes, Vm};
use crate::diag::{bail, StrResult}; use crate::diag::{bail, At, SourceResult, StrResult};
use crate::syntax::Spanned;
use crate::World;
/// A plugin loaded from WebAssembly code. /// A WebAssembly plugin.
/// ///
/// It can run external code conforming to its protocol. /// This is **advanced functionality** and not to be confused with
/// [Typst packages]($scripting/#packages).
/// ///
/// This type is cheap to clone and hash. /// Typst is capable of interfacing with plugins compiled to WebAssembly. Plugin
/// functions may accept multiple [byte buffers]($bytes) as arguments and return
/// a single byte buffer. They should typically be wrapped in idiomatic Typst
/// functions that perform the necessary conversions between native Typst types
/// and bytes.
///
/// Plugins run in isolation from your system, which means that printing,
/// reading files, or anything like that will not be supported for security
/// reasons. To run as a plugin, a program needs to be compiled to a 32-bit
/// shared WebAssembly library. Many compilers will use the
/// [WASI ABI](https://wasi.dev/) by default or as their only option (e.g.
/// emscripten), which allows printing, reading files, etc. This ABI will not
/// directly work with Typst. You will either need to compile to a different
/// target or [stub all functions](https://github.com/astrale-sharp/wasm-minimal-protocol/blob/master/wasi-stub).
///
/// # Example
/// ```example
/// #let myplugin = plugin("hello.wasm")
/// #let concat(a, b) = str(
/// myplugin.concatenate(
/// bytes(a),
/// bytes(b),
/// )
/// )
///
/// #concat("hello", "world")
/// ```
///
/// # Protocol
/// To be used as a plugin, a WebAssembly module must conform to the following
/// protocol:
///
/// ## Exports
/// A plugin module can export functions to make them callable from Typst. To
/// conform to the protocol, an exported function should:
///
/// - Take `n` 32-bit integer arguments `a_1`, `a_2`, ..., `a_n` (interpreted as
/// lengths, so `usize/size_t` may be preferable), and return one 32-bit
/// integer.
///
/// - The function should first allocate a buffer `buf` of length
/// `a_1 + a_2 + ... + a_n`, and then call
/// `wasm_minimal_protocol_write_args_to_buffer(buf.ptr)`.
///
/// - The `a_1` first bytes of the buffer now constitute the first argument, the
/// `a_2` next bytes the second argument, and so on.
///
/// - The function can now do its job with the arguments and produce an output
/// buffer. Before returning, it should call
/// `wasm_minimal_protocol_send_result_to_host` to send its result back to the
/// host.
///
/// - To signal success, the function should return `0`.
///
/// - To signal an error, the function should return `1`. The written buffer is
/// then interpreted as an UTF-8 encoded error message.
///
/// ## Imports
/// Plugin modules need to import two functions that are provided by the runtime.
/// (Types and functions are described using WAT syntax.)
///
/// - `(import "typst_env" "wasm_minimal_protocol_write_args_to_buffer" (func (param i32)))`
///
/// Writes the arguments for the current function into a plugin-allocated
/// buffer. When a plugin function is called, it
/// [receives the lengths](#exports) of its input buffers as arguments. It
/// should then allocate a buffer whose capacity is at least the sum of these
/// lengths. It should then call this function with a `ptr` to the buffer to
/// fill it with the arguments, one after another.
///
/// - `(import "typst_env" "wasm_minimal_protocol_send_result_to_host" (func (param i32 i32)))`
///
/// Sends the output of the current function to the host (Typst). The first
/// parameter shall be a pointer to a buffer (`ptr`), while the second is the
/// length of that buffer (`len`). The memory pointed at by `ptr` can be freed
/// immediately after this function returns. If the message should be
/// interpreted as an error message, it should be encoded as UTF-8.
///
/// # Resources
/// For more resources, check out the
/// [wasm-minimal-protocol repository](https://github.com/astrale-sharp/wasm-minimal-protocol).
/// It contains:
///
/// - A list of example plugin implementations and a test runner for these
/// examples
/// - Wrappers to help you write your plugin in Rust (Zig wrapper in
/// development)
/// - A stubber for WASI
#[ty(scope)]
#[derive(Clone)] #[derive(Clone)]
pub struct Plugin(Arc<Repr>); pub struct Plugin(Arc<Repr>);
@ -36,6 +127,23 @@ struct StoreData {
output: Vec<u8>, output: Vec<u8>,
} }
#[scope]
impl Plugin {
/// Creates a new plugin from a WebAssembly file.
#[func(constructor)]
pub fn construct(
/// The virtual machine.
vm: &mut Vm,
/// Path to a WebAssembly file.
path: Spanned<EcoString>,
) -> SourceResult<Plugin> {
let Spanned { v: path, span } = path;
let id = vm.resolve_path(&path).at(span)?;
let data = vm.world().file(id).at(span)?;
Plugin::new(data).at(span)
}
}
impl Plugin { impl Plugin {
/// Create a new plugin from raw WebAssembly bytes. /// Create a new plugin from raw WebAssembly bytes.
#[comemo::memoize] #[comemo::memoize]
@ -179,10 +287,6 @@ impl Hash for Plugin {
} }
} }
cast! {
type Plugin: "plugin",
}
/// Write the arguments to the plugin function into the plugin's memory. /// Write the arguments to the plugin function into the plugin's memory.
fn wasm_minimal_protocol_write_args_to_buffer(mut caller: Caller<StoreData>, ptr: u32) { fn wasm_minimal_protocol_write_args_to_buffer(mut caller: Caller<StoreData>, ptr: u32) {
let memory = caller.get_export("memory").unwrap().into_memory().unwrap(); let memory = caller.get_export("memory").unwrap().into_memory().unwrap();

104
crates/typst/src/eval/scope.rs
View File

@ -1,11 +1,14 @@
use std::collections::BTreeMap;
use std::fmt::{self, Debug, Formatter}; use std::fmt::{self, Debug, Formatter};
use std::hash::Hash; use std::hash::{Hash, Hasher};
use ecow::{eco_format, EcoString}; use ecow::{eco_format, EcoString};
use indexmap::IndexMap;
use super::{IntoValue, Library, Value}; use super::{
Func, IntoValue, Library, Module, NativeFunc, NativeFuncData, NativeType, Type, Value,
};
use crate::diag::{bail, StrResult}; use crate::diag::{bail, StrResult};
use crate::model::{Element, NativeElement};
/// A stack of scopes. /// A stack of scopes.
#[derive(Debug, Default, Clone)] #[derive(Debug, Default, Clone)]
@ -83,18 +86,27 @@ fn unknown_variable(var: &str) -> EcoString {
} }
/// A map from binding names to values. /// A map from binding names to values.
#[derive(Default, Clone, Hash)] #[derive(Default, Clone)]
pub struct Scope(BTreeMap<EcoString, Slot>, bool); pub struct Scope {
map: IndexMap<EcoString, Slot>,
deduplicate: bool,
category: Option<&'static str>,
}
impl Scope { impl Scope {
/// Create a new empty scope. /// Create a new empty scope.
pub fn new() -> Self { pub fn new() -> Self {
Self(BTreeMap::new(), false) Default::default()
} }
/// Create a new scope with duplication prevention. /// Create a new scope with duplication prevention.
pub fn deduplicating() -> Self { pub fn deduplicating() -> Self {
Self(BTreeMap::new(), true) Self { deduplicate: true, ..Default::default() }
}
/// Enter a new category.
pub fn category(&mut self, name: &'static str) {
self.category = Some(name);
} }
/// Bind a value to a name. /// Bind a value to a name.
@ -103,32 +115,68 @@ impl Scope {
let name = name.into(); let name = name.into();
#[cfg(debug_assertions)] #[cfg(debug_assertions)]
if self.1 && self.0.contains_key(&name) { if self.deduplicate && self.map.contains_key(&name) {
panic!("duplicate definition: {name}"); panic!("duplicate definition: {name}");
} }
self.0.insert(name, Slot::new(value.into_value(), Kind::Normal)); self.map
.insert(name, Slot::new(value.into_value(), Kind::Normal, self.category));
}
/// Define a native function through a Rust type that shadows the function.
pub fn define_func<T: NativeFunc>(&mut self) {
let data = T::data();
self.define(data.name, Func::from(data));
}
/// Define a native function with raw function data.
pub fn define_func_with_data(&mut self, data: &'static NativeFuncData) {
self.define(data.name, Func::from(data));
}
/// Define a native type.
pub fn define_type<T: NativeType>(&mut self) {
let data = T::data();
self.define(data.name, Type::from(data));
}
/// Define a native element.
pub fn define_elem<T: NativeElement>(&mut self) {
let data = T::data();
self.define(data.name, Element::from(data));
}
/// Define a module.
pub fn define_module(&mut self, module: Module) {
self.define(module.name().clone(), module);
} }
/// Define a captured, immutable binding. /// Define a captured, immutable binding.
pub fn define_captured(&mut self, var: impl Into<EcoString>, value: impl IntoValue) { pub fn define_captured(&mut self, var: impl Into<EcoString>, value: impl IntoValue) {
self.0 self.map.insert(
.insert(var.into(), Slot::new(value.into_value(), Kind::Captured)); var.into(),
Slot::new(value.into_value(), Kind::Captured, self.category),
);
} }
/// Try to access a variable immutably. /// Try to access a variable immutably.
pub fn get(&self, var: &str) -> Option<&Value> { pub fn get(&self, var: &str) -> Option<&Value> {
self.0.get(var).map(Slot::read) self.map.get(var).map(Slot::read)
} }
/// Try to access a variable mutably. /// Try to access a variable mutably.
pub fn get_mut(&mut self, var: &str) -> Option<StrResult<&mut Value>> { pub fn get_mut(&mut self, var: &str) -> Option<StrResult<&mut Value>> {
self.0.get_mut(var).map(Slot::write) self.map.get_mut(var).map(Slot::write)
}
/// Get the category of a definition.
pub fn get_category(&self, var: &str) -> Option<&'static str> {
self.map.get(var)?.category
} }
/// Iterate over all definitions. /// Iterate over all definitions.
pub fn iter(&self) -> impl Iterator<Item = (&EcoString, &Value)> { pub fn iter(&self) -> impl Iterator<Item = (&EcoString, &Value)> {
self.0.iter().map(|(k, v)| (k, v.read())) self.map.iter().map(|(k, v)| (k, v.read()))
} }
} }
@ -136,11 +184,22 @@ impl Debug for Scope {
fn fmt(&self, f: &mut Formatter) -> fmt::Result { fn fmt(&self, f: &mut Formatter) -> fmt::Result {
f.write_str("Scope ")?; f.write_str("Scope ")?;
f.debug_map() f.debug_map()
.entries(self.0.iter().map(|(k, v)| (k, v.read()))) .entries(self.map.iter().map(|(k, v)| (k, v.read())))
.finish() .finish()
} }
} }
impl Hash for Scope {
fn hash<H: Hasher>(&self, state: &mut H) {
state.write_usize(self.map.len());
for item in &self.map {
item.hash(state);
}
self.deduplicate.hash(state);
self.category.hash(state);
}
}
/// A slot where a value is stored. /// A slot where a value is stored.
#[derive(Clone, Hash)] #[derive(Clone, Hash)]
struct Slot { struct Slot {
@ -148,6 +207,8 @@ struct Slot {
value: Value, value: Value,
/// The kind of slot, determines how the value can be accessed. /// The kind of slot, determines how the value can be accessed.
kind: Kind, kind: Kind,
/// The category of the slot.
category: Option<&'static str>,
} }
/// The different kinds of slots. /// The different kinds of slots.
@ -161,8 +222,8 @@ enum Kind {
impl Slot { impl Slot {
/// Create a new slot. /// Create a new slot.
fn new(value: Value, kind: Kind) -> Self { fn new(value: Value, kind: Kind, category: Option<&'static str>) -> Self {
Self { value, kind } Self { value, kind, category }
} }
/// Read the value. /// Read the value.
@ -183,3 +244,12 @@ impl Slot {
} }
} }
} }
/// Defines the associated scope of a Rust type.
pub trait NativeScope {
/// The constructor function for the type, if any.
fn constructor() -> Option<&'static NativeFuncData>;
/// Get the associated scope for the type.
fn scope() -> Scope;
}

643
crates/typst/src/eval/str.rs
View File

@ -7,9 +7,14 @@ use ecow::EcoString;
use serde::{Deserialize, Serialize}; use serde::{Deserialize, Serialize};
use unicode_segmentation::UnicodeSegmentation; use unicode_segmentation::UnicodeSegmentation;
use super::{cast, dict, Args, Array, Dict, Func, IntoValue, Value, Vm}; use super::{
cast, dict, func, scope, ty, Args, Array, Bytes, Dict, Func, IntoValue, Type, Value,
Vm,
};
use crate::diag::{bail, At, SourceResult, StrResult}; use crate::diag::{bail, At, SourceResult, StrResult};
use crate::geom::GenAlign; use crate::geom::Align;
use crate::model::Label;
use crate::syntax::{Span, Spanned};
/// Create a new [`Str`] from a format string. /// Create a new [`Str`] from a format string.
#[macro_export] #[macro_export]
@ -22,10 +27,47 @@ macro_rules! __format_str {
#[doc(inline)] #[doc(inline)]
pub use crate::__format_str as format_str; pub use crate::__format_str as format_str;
#[doc(hidden)] #[doc(hidden)]
pub use ecow::eco_format; pub use ecow::eco_format;
/// An immutable reference counted string. /// A sequence of Unicode codepoints.
///
/// You can iterate over the grapheme clusters of the string using a [for
/// loop]($scripting/#loops). Grapheme clusters are basically characters but
/// keep together things that belong together, e.g. multiple codepoints that
/// together form a flag emoji. Strings can be added with the `+` operator,
/// [joined together]($scripting/#blocks) and multiplied with integers.
///
/// Typst provides utility methods for string manipulation. Many of these
/// methods (e.g., `split`, `trim` and `replace`) operate on _patterns:_ A
/// pattern can be either a string or a [regular expression]($regex). This makes
/// the methods quite versatile.
///
/// All lengths and indices are expressed in terms of UTF-8 bytes. Indices are
/// zero-based and negative indices wrap around to the end of the string.
///
/// You can convert a value to a string with this type's constructor.
///
/// # Example
/// ```example
/// #"hello world!" \
/// #"\"hello\n world\"!" \
/// #"1 2 3".split() \
/// #"1,2;3".split(regex("[,;]")) \
/// #(regex("\d+") in "ten euros") \
/// #(regex("\d+") in "10 euros")
/// ```
///
/// # Escape sequences { #escapes }
/// Just like in markup, you can escape a few symbols in strings:
/// - `[\\]` for a backslash
/// - `[\"]` for a quote
/// - `[\n]` for a newline
/// - `[\r]` for a carriage return
/// - `[\t]` for a tab
/// - `[\u{1f600}]` for a hexadecimal Unicode escape sequence
#[ty(scope, title = "String")]
#[derive(Default, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Serialize, Deserialize)] #[derive(Default, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Serialize, Deserialize)]
#[serde(transparent)] #[serde(transparent)]
pub struct Str(EcoString); pub struct Str(EcoString);
@ -38,12 +80,15 @@ impl Str {
/// Return `true` if the length is 0. /// Return `true` if the length is 0.
pub fn is_empty(&self) -> bool { pub fn is_empty(&self) -> bool {
self.0.len() == 0 self.0.is_empty()
} }
/// The length of the string in bytes. /// Repeat the string a number of times.
pub fn len(&self) -> usize { pub fn repeat(&self, n: usize) -> StrResult<Self> {
self.0.len() if self.0.len().checked_mul(n).is_none() {
return Err(eco_format!("cannot repeat this string {n} times"));
}
Ok(Self(self.0.repeat(n)))
} }
/// A string slice containing the entire string. /// A string slice containing the entire string.
@ -51,8 +96,87 @@ impl Str {
self self
} }
/// Extract the first grapheme cluster. /// Resolve an index or throw an out of bounds error.
pub fn first(&self) -> StrResult<Self> { fn locate(&self, index: i64) -> StrResult<usize> {
self.locate_opt(index)?
.ok_or_else(|| out_of_bounds(index, self.len()))
}
/// Resolve an index, if it is within bounds and on a valid char boundary.
///
/// `index == len` is considered in bounds.
fn locate_opt(&self, index: i64) -> StrResult<Option<usize>> {
let wrapped =
if index >= 0 { Some(index) } else { (self.len() as i64).checked_add(index) };
let resolved = wrapped
.and_then(|v| usize::try_from(v).ok())
.filter(|&v| v <= self.0.len());
if resolved.map_or(false, |i| !self.0.is_char_boundary(i)) {
return Err(not_a_char_boundary(index));
}
Ok(resolved)
}
}
#[scope]
impl Str {
/// Converts a value to a string.
///
/// - Integers are formatted in base 10. This can be overridden with the
/// optional `base` parameter.
/// - Floats are formatted in base 10 and never in exponential notation.
/// - From labels the name is extracted.
/// - Bytes are decoded as UTF-8.
///
/// If you wish to convert from and to Unicode code points, see the
/// [`to-unicode`]($str.to-unicode) and [`from-unicode`]($str.from-unicode)
/// functions.
///
/// ```example
/// #str(10) \
/// #str(4000, base: 16) \
/// #str(2.7) \
/// #str(1e8) \
/// #str(<intro>)
/// ```
#[func(constructor)]
pub fn construct(
/// The value that should be converted to a string.
value: ToStr,
/// The base (radix) to display integers in, between 2 and 36.
#[named]
#[default(Spanned::new(10, Span::detached()))]
base: Spanned<i64>,
) -> SourceResult<Str> {
Ok(match value {
ToStr::Str(s) => {
if base.v != 10 {
bail!(base.span, "base is only supported for integers");
}
s
}
ToStr::Int(n) => {
if base.v < 2 || base.v > 36 {
bail!(base.span, "base must be between 2 and 36");
}
format_int_with_base(n, base.v).into()
}
})
}
/// The length of the string in UTF-8 encoded bytes.
#[func(title = "Length")]
pub fn len(&self) -> usize {
self.0.len()
}
/// Extracts the first grapheme cluster of the string.
/// Fails with an error if the string is empty.
#[func]
pub fn first(&self) -> StrResult<Str> {
self.0 self.0
.graphemes(true) .graphemes(true)
.next() .next()
@ -60,8 +184,10 @@ impl Str {
.ok_or_else(string_is_empty) .ok_or_else(string_is_empty)
} }
/// Extract the last grapheme cluster. /// Extracts the last grapheme cluster of the string.
pub fn last(&self) -> StrResult<Self> { /// Fails with an error if the string is empty.
#[func]
pub fn last(&self) -> StrResult<Str> {
self.0 self.0
.graphemes(true) .graphemes(true)
.next_back() .next_back()
@ -69,8 +195,18 @@ impl Str {
.ok_or_else(string_is_empty) .ok_or_else(string_is_empty)
} }
/// Extract the grapheme cluster at the given index. /// Extracts the first grapheme cluster after the specified index. Returns
pub fn at(&self, index: i64, default: Option<Value>) -> StrResult<Value> { /// the default value if the index is out of bounds or fails with an error
/// if no default value was specified.
#[func]
pub fn at(
&self,
/// The byte index. If negative, indexes from the back.
index: i64,
/// A default value to return if the index is out of bounds.
#[named]
default: Option<Value>,
) -> StrResult<Value> {
let len = self.len(); let len = self.len();
self.locate_opt(index)? self.locate_opt(index)?
.and_then(|i| self.0[i..].graphemes(true).next().map(|s| s.into_value())) .and_then(|i| self.0[i..].graphemes(true).next().map(|s| s.into_value()))
@ -78,41 +214,110 @@ impl Str {
.ok_or_else(|| no_default_and_out_of_bounds(index, len)) .ok_or_else(|| no_default_and_out_of_bounds(index, len))
} }
/// Extract a contiguous substring. /// Extracts a substring of the string.
pub fn slice(&self, start: i64, end: Option<i64>) -> StrResult<Self> { /// Fails with an error if the start or end index is out of bounds.
#[func]
pub fn slice(
&self,
/// The start byte index (inclusive). If negative, indexes from the
/// back.
start: i64,
/// The end byte index (exclusive). If omitted, the whole slice until
/// the end of the string is extracted. If negative, indexes from the
/// back.
#[default]
end: Option<i64>,
/// The number of bytes to extract. This is equivalent to passing
/// `start + count` as the `end` position. Mutually exclusive with `end`.
#[named]
count: Option<i64>,
) -> StrResult<Str> {
let end = end.or(count.map(|c| start + c)).unwrap_or(self.len() as i64);
let start = self.locate(start)?; let start = self.locate(start)?;
let end = self.locate(end.unwrap_or(self.len() as i64))?.max(start); let end = self.locate(end)?.max(start);
Ok(self.0[start..end].into()) Ok(self.0[start..end].into())
} }
/// The grapheme clusters the string consists of. /// Returns the grapheme clusters of the string as an array of substrings.
#[func]
pub fn clusters(&self) -> Array { pub fn clusters(&self) -> Array {
self.as_str().graphemes(true).map(|s| Value::Str(s.into())).collect() self.as_str().graphemes(true).map(|s| Value::Str(s.into())).collect()
} }
/// The codepoints the string consists of. /// Returns the Unicode codepoints of the string as an array of substrings.
#[func]
pub fn codepoints(&self) -> Array { pub fn codepoints(&self) -> Array {
self.chars().map(|c| Value::Str(c.into())).collect() self.chars().map(|c| Value::Str(c.into())).collect()
} }
/// Whether the given pattern exists in this string. /// Converts a character into its corresponding code point.
pub fn contains(&self, pattern: StrPattern) -> bool { ///
/// ```example
/// #"a".to-unicode() \
/// #("a\u{0300}"
/// .codepoints()
/// .map(str.to-unicode))
/// ```
#[func]
pub fn to_unicode(
/// The character that should be converted.
character: char,
) -> u32 {
character as u32
}
/// Converts a unicode code point into its corresponding string.
///
/// ```example
/// #str.from-unicode(97)
/// ```
#[func]
pub fn from_unicode(
/// The code point that should be converted.
value: u32,
) -> StrResult<Str> {
let c: char = value
.try_into()
.map_err(|_| eco_format!("{value:#x} is not a valid codepoint"))?;
Ok(c.into())
}
/// Whether the string contains the specified pattern.
///
/// This method also has dedicated syntax: You can write `{"bc" in "abcd"}`
/// instead of `{"abcd".contains("bc")}`.
#[func]
pub fn contains(
&self,
/// The pattern to search for.
pattern: StrPattern,
) -> bool {
match pattern { match pattern {
StrPattern::Str(pat) => self.0.contains(pat.as_str()), StrPattern::Str(pat) => self.0.contains(pat.as_str()),
StrPattern::Regex(re) => re.is_match(self), StrPattern::Regex(re) => re.is_match(self),
} }
} }
/// Whether this string begins with the given pattern. /// Whether the string starts with the specified pattern.
pub fn starts_with(&self, pattern: StrPattern) -> bool { #[func]
pub fn starts_with(
&self,
/// The pattern the string might start with.
pattern: StrPattern,
) -> bool {
match pattern { match pattern {
StrPattern::Str(pat) => self.0.starts_with(pat.as_str()), StrPattern::Str(pat) => self.0.starts_with(pat.as_str()),
StrPattern::Regex(re) => re.find(self).map_or(false, |m| m.start() == 0), StrPattern::Regex(re) => re.find(self).map_or(false, |m| m.start() == 0),
} }
} }
/// Whether this string ends with the given pattern. /// Whether the string ends with the specified pattern.
pub fn ends_with(&self, pattern: StrPattern) -> bool { #[func]
pub fn ends_with(
&self,
/// The pattern the string might end with.
pattern: StrPattern,
) -> bool {
match pattern { match pattern {
StrPattern::Str(pat) => self.0.ends_with(pat.as_str()), StrPattern::Str(pat) => self.0.ends_with(pat.as_str()),
StrPattern::Regex(re) => { StrPattern::Regex(re) => {
@ -132,25 +337,52 @@ impl Str {
} }
} }
/// The text of the pattern's first match in this string. /// Searches for the specified pattern in the string and returns the first
pub fn find(&self, pattern: StrPattern) -> Option<Self> { /// match as a string or `{none}` if there is no match.
#[func]
pub fn find(
&self,
/// The pattern to search for.
pattern: StrPattern,
) -> Option<Str> {
match pattern { match pattern {
StrPattern::Str(pat) => self.0.contains(pat.as_str()).then_some(pat), StrPattern::Str(pat) => self.0.contains(pat.as_str()).then_some(pat),
StrPattern::Regex(re) => re.find(self).map(|m| m.as_str().into()), StrPattern::Regex(re) => re.find(self).map(|m| m.as_str().into()),
} }
} }
/// The position of the pattern's first match in this string. /// Searches for the specified pattern in the string and returns the index
pub fn position(&self, pattern: StrPattern) -> Option<i64> { /// of the first match as an integer or `{none}` if there is no match.
#[func]
pub fn position(
&self,
/// The pattern to search for.
pattern: StrPattern,
) -> Option<usize> {
match pattern { match pattern {
StrPattern::Str(pat) => self.0.find(pat.as_str()).map(|i| i as i64), StrPattern::Str(pat) => self.0.find(pat.as_str()),
StrPattern::Regex(re) => re.find(self).map(|m| m.start() as i64), StrPattern::Regex(re) => re.find(self).map(|m| m.start()),
} }
} }
/// The start and, text and capture groups (if any) of the first match of /// Searches for the specified pattern in the string and returns a
/// the pattern in this string. /// dictionary with details about the first match or `{none}` if there is no
pub fn match_(&self, pattern: StrPattern) -> Option<Dict> { /// match.
///
/// The returned dictionary has the following keys:
/// - `start`: The start offset of the match
/// - `end`: The end offset of the match
/// - `text`: The text that matched.
/// - `captures`: An array containing a string for each matched capturing
/// group. The first item of the array contains the first matched
/// capturing, not the whole match! This is empty unless the `pattern` was
/// a regex with capturing groups.
#[func]
pub fn match_(
&self,
/// The pattern to search for.
pattern: StrPattern,
) -> Option<Dict> {
match pattern { match pattern {
StrPattern::Str(pat) => { StrPattern::Str(pat) => {
self.0.match_indices(pat.as_str()).next().map(match_to_dict) self.0.match_indices(pat.as_str()).next().map(match_to_dict)
@ -159,9 +391,15 @@ impl Str {
} }
} }
/// The start, end, text and capture groups (if any) of all matches of the /// Searches for the specified pattern in the string and returns an array of
/// pattern in this string. /// dictionaries with details about all matches. For details about the
pub fn matches(&self, pattern: StrPattern) -> Array { /// returned dictionaries, see above.
#[func]
pub fn matches(
&self,
/// The pattern to search for.
pattern: StrPattern,
) -> Array {
match pattern { match pattern {
StrPattern::Str(pat) => self StrPattern::Str(pat) => self
.0 .0
@ -177,30 +415,89 @@ impl Str {
} }
} }
/// Split this string at whitespace or a specific pattern. /// Replace at most `count` occurrences of the given pattern with a
pub fn split(&self, pattern: Option<StrPattern>) -> Array { /// replacement string or function (beginning from the start). If no count
let s = self.as_str(); /// is given, all occurrences are replaced.
match pattern { #[func]
None => s.split_whitespace().map(|v| Value::Str(v.into())).collect(), pub fn replace(
Some(StrPattern::Str(pat)) => { &self,
s.split(pat.as_str()).map(|v| Value::Str(v.into())).collect() /// The virtual machine.
vm: &mut Vm,
/// The pattern to search for.
pattern: StrPattern,
/// The string to replace the matches with or a function that gets a
/// dictionary for each match and can return individual replacement
/// strings.
replacement: Replacement,
/// If given, only the first `count` matches of the pattern are placed.
#[named]
count: Option<usize>,
) -> SourceResult<Str> {
// Heuristic: Assume the new string is about the same length as
// the current string.
let mut output = EcoString::with_capacity(self.as_str().len());
// Replace one match of a pattern with the replacement.
let mut last_match = 0;
let mut handle_match = |range: Range<usize>, dict: Dict| -> SourceResult<()> {
// Push everything until the match.
output.push_str(&self[last_match..range.start]);
last_match = range.end;
// Determine and push the replacement.
match &replacement {
Replacement::Str(s) => output.push_str(s),
Replacement::Func(func) => {
let args = Args::new(func.span(), [dict.into_value()]);
let piece = func.call_vm(vm, args)?.cast::<Str>().at(func.span())?;
output.push_str(&piece);
} }
Some(StrPattern::Regex(re)) => { }
re.split(s).map(|v| Value::Str(v.into())).collect()
Ok(())
};
// Iterate over the matches of the `pattern`.
let count = count.unwrap_or(usize::MAX);
match &pattern {
StrPattern::Str(pat) => {
for m in self.match_indices(pat.as_str()).take(count) {
let (start, text) = m;
handle_match(start..start + text.len(), match_to_dict(m))?;
}
}
StrPattern::Regex(re) => {
for caps in re.captures_iter(self).take(count) {
// Extract the entire match over all capture groups.
let m = caps.get(0).unwrap();
handle_match(m.start()..m.end(), captures_to_dict(caps))?;
} }
} }
} }
/// Trim either whitespace or the given pattern at both or just one side of // Push the remainder.
/// the string. If `repeat` is true, the pattern is trimmed repeatedly output.push_str(&self[last_match..]);
/// instead of just once. Repeat must only be given in combination with a Ok(output.into())
/// pattern. }
/// Removes matches of a pattern from one or both sides of the string, once or
/// repeatedly and returns the resulting string.
#[func]
pub fn trim( pub fn trim(
&self, &self,
/// The pattern to search for.
#[default]
pattern: Option<StrPattern>, pattern: Option<StrPattern>,
/// Can be `start` or `end` to only trim the start or end of the string.
/// If omitted, both sides are trimmed.
#[named]
at: Option<StrSide>, at: Option<StrSide>,
/// Whether to repeatedly removes matches of the pattern or just once.
/// Defaults to `{true}`.
#[named]
#[default(true)]
repeat: bool, repeat: bool,
) -> Self { ) -> Str {
let mut start = matches!(at, Some(StrSide::Start) | None); let mut start = matches!(at, Some(StrSide::Start) | None);
let end = matches!(at, Some(StrSide::End) | None); let end = matches!(at, Some(StrSide::End) | None);
@ -268,101 +565,93 @@ impl Str {
trimmed.into() trimmed.into()
} }
/// Replace at most `count` occurrences of the given pattern with a /// Splits a string at matches of a specified pattern and returns an array
/// replacement string or function (beginning from the start). If no count /// of the resulting parts.
/// is given, all occurrences are replaced. #[func]
pub fn replace( pub fn split(
&self, &self,
vm: &mut Vm, /// The pattern to split at. Defaults to whitespace.
pattern: StrPattern, #[default]
with: Replacement, pattern: Option<StrPattern>,
count: Option<usize>, ) -> Array {
) -> SourceResult<Self> { let s = self.as_str();
// Heuristic: Assume the new string is about the same length as match pattern {
// the current string. None => s.split_whitespace().map(|v| Value::Str(v.into())).collect(),
let mut output = EcoString::with_capacity(self.as_str().len()); Some(StrPattern::Str(pat)) => {
s.split(pat.as_str()).map(|v| Value::Str(v.into())).collect()
// Replace one match of a pattern with the replacement. }
let mut last_match = 0; Some(StrPattern::Regex(re)) => {
let mut handle_match = |range: Range<usize>, dict: Dict| -> SourceResult<()> { re.split(s).map(|v| Value::Str(v.into())).collect()
// Push everything until the match.
output.push_str(&self[last_match..range.start]);
last_match = range.end;
// Determine and push the replacement.
match &with {
Replacement::Str(s) => output.push_str(s),
Replacement::Func(func) => {
let args = Args::new(func.span(), [dict]);
let piece = func.call_vm(vm, args)?.cast::<Str>().at(func.span())?;
output.push_str(&piece);
} }
} }
Ok(())
};
// Iterate over the matches of the `pattern`.
let count = count.unwrap_or(usize::MAX);
match &pattern {
StrPattern::Str(pat) => {
for m in self.match_indices(pat.as_str()).take(count) {
let (start, text) = m;
handle_match(start..start + text.len(), match_to_dict(m))?;
}
}
StrPattern::Regex(re) => {
for caps in re.captures_iter(self).take(count) {
// Extract the entire match over all capture groups.
let m = caps.get(0).unwrap();
handle_match(m.start()..m.end(), captures_to_dict(caps))?;
}
}
}
// Push the remainder.
output.push_str(&self[last_match..]);
Ok(output.into())
}
/// Repeat the string a number of times.
pub fn repeat(&self, n: i64) -> StrResult<Self> {
let n = usize::try_from(n)
.ok()
.and_then(|n| self.0.len().checked_mul(n).map(|_| n))
.ok_or_else(|| format!("cannot repeat this string {} times", n))?;
Ok(Self(self.0.repeat(n)))
} }
/// Reverse the string. /// Reverse the string.
pub fn rev(&self) -> Self { #[func(title = "Reverse")]
pub fn rev(&self) -> Str {
self.as_str().graphemes(true).rev().collect::<String>().into() self.as_str().graphemes(true).rev().collect::<String>().into()
} }
/// Resolve an index or throw an out of bounds error.
fn locate(&self, index: i64) -> StrResult<usize> {
self.locate_opt(index)?
.ok_or_else(|| out_of_bounds(index, self.len()))
} }
/// Resolve an index, if it is within bounds and on a valid char boundary. /// A value that can be cast to a string.
/// pub enum ToStr {
/// `index == len` is considered in bounds. /// A string value ready to be used as-is.
fn locate_opt(&self, index: i64) -> StrResult<Option<usize>> { Str(Str),
let wrapped = /// An integer about to be formatted in a given base.
if index >= 0 { Some(index) } else { (self.len() as i64).checked_add(index) }; Int(i64),
let resolved = wrapped
.and_then(|v| usize::try_from(v).ok())
.filter(|&v| v <= self.0.len());
if resolved.map_or(false, |i| !self.0.is_char_boundary(i)) {
return Err(not_a_char_boundary(index));
} }
Ok(resolved) cast! {
ToStr,
v: i64 => Self::Int(v),
v: f64 => Self::Str(format_str!("{}", v)),
v: Bytes => Self::Str(
std::str::from_utf8(&v)
.map_err(|_| "bytes are not valid utf-8")?
.into()
),
v: Label => Self::Str(v.0.into()),
v: Type => Self::Str(v.long_name().into()),
v: Str => Self::Str(v),
} }
/// Format an integer in a base.
fn format_int_with_base(mut n: i64, base: i64) -> EcoString {
if n == 0 {
return "0".into();
}
// In Rust, `format!("{:x}", -14i64)` is not `-e` but `fffffffffffffff2`.
// So we can only use the built-in for decimal, not bin/oct/hex.
if base == 10 {
return eco_format!("{n}");
}
// The largest output is `to_base(i64::MIN, 2)`, which is 65 chars long.
const SIZE: usize = 65;
let mut digits = [b'\0'; SIZE];
let mut i = SIZE;
// It's tempting to take the absolute value, but this will fail for i64::MIN.
// Instead, we turn n negative, as -i64::MAX is perfectly representable.
let negative = n < 0;
if n > 0 {
n = -n;
}
while n != 0 {
let digit = char::from_digit(-(n % base) as u32, base as u32);
i -= 1;
digits[i] = digit.unwrap_or('?') as u8;
n /= base;
}
if negative {
i -= 1;
digits[i] = b'-';
}
std::str::from_utf8(&digits[i..]).unwrap_or_default().into()
} }
/// The out of bounds access error message. /// The out of bounds access error message.
@ -547,6 +836,25 @@ cast! {
} }
/// A regular expression. /// A regular expression.
///
/// Can be used as a [show rule selector]($styling/#show-rules) and with
/// [string methods]($str) like `find`, `split`, and `replace`.
///
/// [See here](https://docs.rs/regex/latest/regex/#syntax) for a specification
/// of the supported syntax.
///
/// # Example
/// ```example
/// // Works with show rules.
/// #show regex("\d+"): set text(red)
///
/// The numbers 1 to 10.
///
/// // Works with string methods.
/// #("a,b;c"
/// .split(regex("[,;]")))
/// ```
#[ty(scope)]
#[derive(Clone)] #[derive(Clone)]
pub struct Regex(regex::Regex); pub struct Regex(regex::Regex);
@ -557,6 +865,27 @@ impl Regex {
} }
} }
#[scope]
impl Regex {
/// Create a regular expression from a string.
#[func(constructor)]
pub fn construct(
/// The regular expression as a string.
///
/// Most regex escape sequences just work because they are not valid Typst
/// escape sequences. To produce regex escape sequences that are also valid in
/// Typst (e.g. `[\\]`), you need to escape twice. Thus, to match a verbatim
/// backslash, you would need to write `{regex("\\\\")}`.
///
/// If you need many escape sequences, you can also create a raw element
/// and extract its text to use it for your regular expressions:
/// ```{regex(`\d+\.\d+\.\d+`.text)}```.
regex: Spanned<Str>,
) -> SourceResult<Regex> {
Self::new(&regex.v).at(regex.span)
}
}
impl Deref for Regex { impl Deref for Regex {
type Target = regex::Regex; type Target = regex::Regex;
@ -584,7 +913,7 @@ impl Hash for Regex {
} }
cast! { cast! {
type Regex: "regular expression", type Regex,
} }
/// A pattern which can be searched for in a string. /// A pattern which can be searched for in a string.
@ -598,8 +927,12 @@ pub enum StrPattern {
cast! { cast! {
StrPattern, StrPattern,
text: Str => Self::Str(text), self => match self {
regex: Regex => Self::Regex(regex), Self::Str(v) => v.into_value(),
Self::Regex(v) => v.into_value(),
},
v: Str => Self::Str(v),
v: Regex => Self::Regex(v),
} }
/// A side of a string. /// A side of a string.
@ -614,9 +947,9 @@ pub enum StrSide {
cast! { cast! {
StrSide, StrSide,
align: GenAlign => match align { v: Align => match v {
GenAlign::Start => Self::Start, Align::START => Self::Start,
GenAlign::End => Self::End, Align::END => Self::End,
_ => bail!("expected either `start` or `end`"), _ => bail!("expected either `start` or `end`"),
}, },
} }
@ -632,6 +965,36 @@ pub enum Replacement {
cast! { cast! {
Replacement, Replacement,
text: Str => Self::Str(text), self => match self {
func: Func => Self::Func(func) Self::Str(v) => v.into_value(),
Self::Func(v) => v.into_value(),
},
v: Str => Self::Str(v),
v: Func => Self::Func(v)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_to_base() {
assert_eq!(&format_int_with_base(0, 10), "0");
assert_eq!(&format_int_with_base(0, 16), "0");
assert_eq!(&format_int_with_base(0, 36), "0");
assert_eq!(
&format_int_with_base(i64::MAX, 2),
"111111111111111111111111111111111111111111111111111111111111111"
);
assert_eq!(
&format_int_with_base(i64::MIN, 2),
"-1000000000000000000000000000000000000000000000000000000000000000"
);
assert_eq!(&format_int_with_base(i64::MAX, 10), "9223372036854775807");
assert_eq!(&format_int_with_base(i64::MIN, 10), "-9223372036854775808");
assert_eq!(&format_int_with_base(i64::MAX, 16), "7fffffffffffffff");
assert_eq!(&format_int_with_base(i64::MIN, 16), "-8000000000000000");
assert_eq!(&format_int_with_base(i64::MAX, 36), "1y2p0ij32e8e7");
assert_eq!(&format_int_with_base(i64::MIN, 36), "-1y2p0ij32e8e8");
}
} }

Some files were not shown because too many files have changed in this diff Show More