Repository: typst/typst
File: crates/typst-library/src/loading/toml.rs (Rust)

Code before:
/// to be encoded or decoded.
///
/// | TOML value | Converted into Typst |
/// | ---------- | -------------------- |
/// | string     | [`str`]              |
/// | integer    | [`int`]              |
/// | float      | [`float`]            |
/// | boolean    | [`bool`]             |
/// | datetime   | [`datetime`]         |
/// | array      | [`array`]            |
/// | table      | [`dictionary`]       |
///
/// Be aware that **TOML integers** larger than 2<sup>63</sup>-1 or smaller than
/// -2<sup>63</sup> cannot be represented losslessly in Typst, and an error will
/// be thrown according to the [spec](https://toml.io/en/v1.0.0#integer).
///
/// | Typst value                           | Converted into TOML            |
/// | ------------------------------------- | ------------------------------ |
/// | types that can be converted from TOML | corresponding TOML value       |
/// | `{none}`                              | ignored                        |
/// | [`bytes`]                             | string via [`repr`]            |
/// | [`symbol`]                            | string                         |
/// | [`content`]                           | a table describing the content |
/// | other types ([`length`], etc.)        | string via [`repr`]            |
///
/// - **Bytes** are not encoded as TOML arrays for performance reasons.
///   Consider using [`cbor.encode`] for binary data.
///
/// - The **`repr`** function is [for debugging purposes only]($repr/#debugging-only),
///   and its output is not guaranteed to be stable across typst versions.
#[func(scope, title = "TOML")]
pub fn toml(
    engine: &mut Engine,
    /// A [path]($syntax/#paths) to a TOML file or raw TOML bytes.
    source: Spanned<DataSource>,
) -> SourceResult<Dict> {
    let loaded = source.load(engine.world)?;
    let raw = loaded.data.as_str().within(&loaded)?;
    ::toml::from_str(raw).map_err(format_toml_error).within(&loaded)
}

#[scope]
impl toml {
    /// Reads structured data from a TOML string/bytes.
    #[func(title = "Decode TOML")]
    #[deprecated(
        message = "`toml.decode` is deprecated, directly pass bytes to `toml` instead",
        until = "0.15.0"
    )]
    pub fn decode(
        engine: &mut Engine,

Review comment (performance):
Not just performance reasons, but also UX reasons as simple queries for e.g.a figure would turn into huge output. Not sure whether that's worth mentioning, but this statement could feel better motivated.

Code after:
/// to be encoded or decoded.
///
/// | TOML value | Converted into Typst |
/// | ---------- | -------------------- |
/// | string     | [`str`]              |
/// | integer    | [`int`]              |
/// | float      | [`float`]            |
/// | boolean    | [`bool`]             |
/// | datetime   | [`datetime`]         |
/// | array      | [`array`]            |
/// | table      | [`dictionary`]       |
///
/// | Typst value                           | Converted into TOML            |
/// | ------------------------------------- | ------------------------------ |
/// | types that can be converted from TOML | corresponding TOML value       |
/// | `{none}`                              | ignored                        |
/// | [`bytes`]                             | string via [`repr`]            |
/// | [`symbol`]                            | string                         |
/// | [`content`]                           | a table describing the content |
/// | other types ([`length`], etc.)        | string via [`repr`]            |
///
/// ## Notes
/// - Be aware that TOML integers larger than 2<sup>63</sup>-1 or smaller
///   than -2<sup>63</sup> cannot be represented losslessly in Typst, and an
///   error will be thrown according to the
///   [specification](https://toml.io/en/v1.0.0#integer).
///
/// - Bytes are not encoded as TOML arrays for performance and readability
///   reasons. Consider using [`cbor.encode`] for binary data.
///
/// - The `repr` function is [for debugging purposes only]($repr/#debugging-only),
///   and its output is not guaranteed to be stable across Typst versions.
#[func(scope, title = "TOML")]
pub fn toml(
    engine: &mut Engine,
    /// A [path]($syntax/#paths) to a TOML file or raw TOML bytes.
    source: Spanned<DataSource>,
) -> SourceResult<Dict> {
    let loaded = source.load(engine.world)?;
    let raw = loaded.data.as_str().within(&loaded)?;
    ::toml::from_str(raw).map_err(format_toml_error).within(&loaded)
}

#[scope]
impl toml {
    /// Reads structured data from a TOML string/bytes.
    #[func(title = "Decode TOML")]
    #[deprecated(
        message = "`toml.decode` is deprecated, directly pass bytes to `toml` instead",
        until = "0.15.0"
    )]