Nothing
## -----------------------------------------------------------------------
## typstTranslate: translate arbitrary character strings (variable
## labels, titles, etc.) so they display correctly as literal text in
## Typst markup, with optional math-mode handling for superscripts and
## Greek letter names -- the Typst analog of latexTranslate().
##
## Deliberately simpler than latexTranslate() in several ways:
##
## - Built entirely on vectorized base gsub() calls, not sedit()/
## replace.substring.wild(); the Greek-letter pass in particular
## collapses latexTranslate's 39-iteration loop into one regex
## alternation.
##
## - Several characters latexTranslate escapes (|, %, &, >, the pound
## sign) have NO special meaning in Typst markup and are simply left
## alone here -- carrying over LaTeX's escaping list unchanged would
## have added noise, not correctness.
##
## - Where LaTeX requires math mode for symbols like \leq/\geq (they
## don't exist in text mode at all), Typst can just use the literal
## Unicode character in ordinary text -- no $...$ wrapping needed,
## so <= and >= translate directly to unicode rather than opening a
## math span the way latexTranslate must.
##
## - Superscripts are always parenthesized ($^(2)$, not $^2$) -- valid
## for both single- and multi-character exponents, so there's no need
## for latexTranslate's length-conditional/math-mode-tracking logic.
##
## - $ protection uses an actual unlikely-collision control character
## (\u0001) as the placeholder rather than a text token like
## latexTranslate's "DOLLARS", which could in principle already
## appear verbatim in real input text.
##
## Characters that ARE escaped, because they're syntactically meaningful
## in Typst markup mode and could otherwise corrupt output or (in the
## case of '<') cause an outright compile error: # < _ @ ` * ~ and \
## itself. '<' specifically needs this because Typst reads a bare '<' as
## the start of label-reference syntax (<name>) -- confirmed directly:
## an unescaped P-value formatted as "<0.001" breaks Typst compilation
## with "unclosed label" if not escaped.
##
## A second confirmed compile-breaking case, now handled: when a Greek
## substitution and a superscript substitution land immediately next to
## each other with no text between them (e.g. "chi^2" -> naively
## "$chi$$^(2)$"), Typst reads the touching $$ as an EMPTY math block
## followed by bare (invalid, out-of-math-mode) text -- a real
## "unexpected hat" compile error, not just a cosmetic double-span. The
## cleanup pass near the end of this function merges any such touching
## spans into one continuous span before they can cause this.
##
## Not carried over from latexTranslate: the `pb` argument (auto-sizing
## \left/\right delimiters) and the `inn`/`out` extension arguments --
## Typst doesn't need LaTeX's delimiter-sizing workaround for ordinary
## text-mode brackets, and the extension hooks weren't asked for. Add
## back if a concrete need for either turns up.
## -----------------------------------------------------------------------
#' Translate a Character String for Typst Markup
#'
#' Translates arbitrary character strings -- variable labels, titles,
#' captions, and similar free text -- so they display correctly as
#' literal text in Typst markup, with optional math-mode handling for
#' superscripts and Greek letter names. This is the Typst analog of
#' \code{\link{latexTranslate}} and \code{\link{htmlTranslate}}.
#'
#' \code{typstTranslate} is built entirely from vectorized base
#' \code{\link{gsub}} calls rather than \code{\link{sedit}}, and is
#' deliberately simpler than \code{latexTranslate} in several respects:
#'
#' \itemize{
#' \item Several characters \code{latexTranslate} escapes (\code{|},
#' \code{\%}, \code{&}, \code{>}, the pound sign) have no special
#' meaning in Typst markup and are left untouched here -- carrying
#' over LaTeX's escaping list unchanged would add noise, not
#' correctness.
#' \item Where LaTeX requires math mode for symbols such as
#' \code{\\leq}/\code{\\geq} (they do not exist in text mode at
#' all), Typst can use the literal Unicode character directly in
#' ordinary text, so \code{<=} and \code{>=} translate straight to
#' Unicode rather than opening a math span.
#' \item Superscripts (\verb{^digits}) are rendered with Typst's
#' text-mode \verb{#super[]} function rather than a bare math-mode
#' span. A bare \verb{$^(3)$} span with no base inside the same
#' span is invalid Typst syntax ("unexpected hat") unless something
#' happens to merge a base into it, and even when made syntactically
#' valid, pulling an ordinary word into math mode causes Typst to
#' auto-italicize/treat it as bare variable letters rather than
#' showing plain upright text. \verb{#super[]} avoids both problems:
#' it is valid immediately after any preceding content (or none),
#' and does not restyle whatever precedes it.
#' \item Greek letter names are recognized as whole words (via a
#' single vectorized regex alternation, not a per-letter loop) and
#' wrapped in \verb{$...$} so they render as the actual Greek
#' glyph.
#' }
#'
#' Characters that \emph{are} escaped, because they are syntactically
#' meaningful in Typst markup mode and could otherwise corrupt output or
#' (in the case of \verb{<}) cause an outright compile error, are
#' \verb{# < _ @ `} \verb{*} \verb{~} and the backslash itself.
#' \verb{<} specifically needs this because Typst reads a bare \verb{<}
#' as the start of label-reference syntax (\verb{<name>}); an unescaped
#' value such as a P-value formatted as \verb{"<0.001"} will otherwise
#' break Typst compilation with an "unclosed label" error.
#' \verb{_} and \verb{*} are escaped unconditionally (not only where
#' they would definitely cause trouble) because ordinary variable names
#' and labels routinely contain underscores or asterisks, and Typst's
#' emphasis/strong-text shorthand can trigger across unrelated stretches
#' of text if these are left unescaped.
#'
#' Math spans that end up touching with no text between them (which can
#' happen, for example, when a Greek-letter substitution lands
#' immediately next to another math-producing substitution) are merged
#' into one continuous span. Typst reads two adjacent \verb{$...$$...$}
#' spans as an \emph{empty} math block followed by bare text -- a real
#' compile error ("unexpected hat"), not merely a cosmetic issue -- so
#' this merge is applied unconditionally wherever it is safe to do so.
#'
#' Not carried over from \code{latexTranslate}: the \code{pb} argument
#' (auto-sizing \verb{\\left}/\verb{\\right} delimiters) and the
#' \code{inn}/\code{out} extension arguments -- Typst does not need
#' LaTeX's delimiter-sizing workaround for ordinary text-mode brackets,
#' and the extension hooks were not needed for current use cases.
#'
#' @param object A character vector, or an object coercible to one via
#' \code{\link{as.character}}, to be translated for display in Typst
#' markup.
#' @param greek Logical. If \code{TRUE}, whole-word matches of Greek
#' letter names (\code{alpha}, \code{beta}, \code{Gamma}, etc.) are
#' wrapped in Typst math mode so they render as the actual Greek
#' glyph rather than the literal English name. Default is
#' \code{FALSE}.
#' @param na Character string to substitute for \code{NA} elements of
#' \code{object} before translation. Default is \code{''}.
#' @param ... Currently unused; present for signature compatibility
#' with \code{\link{latexTranslate}}/\code{\link{htmlTranslate}}.
#'
#' @return A character vector of the same length as \code{object},
#' containing valid Typst markup safe for direct insertion into Typst
#' source (for example, inside a \verb{```{=typst}} raw block, or as
#' the content of a native \verb{#table()} cell).
#'
#' @seealso \code{\link{latexTranslate}}, \code{\link{htmlTranslate}},
#' \code{\link{typstAsis}}
#'
#' @examples
#' typstTranslate("P<0.001") # escapes the literal <
#' typstTranslate("Volume (cm^3)") # #super[] superscript
#' typstTranslate("rho coefficient", greek=TRUE) # real Greek rho glyph
#' typstTranslate("chi^2 statistic", greek=TRUE) # merged math span
#'
#' @export
typstTranslate <- function(object, greek = FALSE, na = '', ...)
{
text <- ifelse(is.na(object), na, as.character(object))
## Protect literal $ before any of the steps below insert their own
## math-mode $ delimiters
text <- gsub('$', '\u0001', text, fixed = TRUE)
## Multi-character sequences with no Typst syntax of their own -- just
## become their literal Unicode characters, no math mode required
text <- gsub('<=', '\u2264', text, fixed = TRUE)
text <- gsub('>=', '\u2265', text, fixed = TRUE)
## Escape existing backslashes first, so the escaping below doesn't
## double up on backslashes it just inserted
text <- gsub('\\', '\\\\', text, fixed = TRUE)
## Characters syntactically special in Typst markup mode
specials <- c('#', '<', '_', '@', '`', '*', '~')
for (ch in specials)
text <- gsub(ch, paste0('\\', ch), text, fixed = TRUE)
## ^digits -> Typst text-mode superscript via #super[], NOT math mode.
## Math mode ($^(...)$) was tried first but has two real problems:
## (1) a bare "$^(3)$" math span with no preceding base INSIDE that
## same span is invalid Typst syntax ("unexpected hat") unless
## something happens to merge a base into it -- this only accidentally
## worked for a Greek-letter base (via the $$-merge step below), never
## for an ordinary word like "cm" in "cm^3"; (2) even made valid,
## pulling a word like "cm" into math mode makes Typst auto-italicize/
## treat it as bare variable letters (read as c times m) rather than
## showing plain upright unit text. #super[] sidesteps both: it's a
## text-mode function, valid after any preceding content or none, and
## doesn't restyle whatever precedes it.
text <- gsub('\\^(-?[0-9]+)', '#super[\\1]', text, perl = TRUE)
if (greek) {
gl <- c('alpha','beta','gamma','delta','epsilon','varepsilon','zeta',
'eta','theta','vartheta','iota','kappa','lambda','mu','nu',
'xi','pi','varpi','rho','varrho','sigma','varsigma','tau',
'upsilon','phi','varphi','chi','psi','omega','Gamma','Delta',
'Theta','Lambda','Xi','Pi','Sigma','Upsilon','Phi','Psi','Omega')
pat <- paste0('\\b(', paste(gl, collapse = '|'), ')\\b')
text <- gsub(pat, '$\\1$', text, perl = TRUE)
}
## Merge math spans our own substitutions could still leave touching
## with no text between them into one continuous span. With
## superscripts now using #super[] instead of math mode (see above),
## the only remaining source of $...$ spans is the Greek-word pass,
## and two separate Greek-word matches can never end up touching (a
## word boundary always separates them) -- so this is now a defensive
## fallback rather than something load-bearing for a known case, kept
## in place since it's cheap and harmless if it never fires. Safe to
## collapse unconditionally: literal user $ characters are still
## behind the \u0001 placeholder at this point.
text <- gsub('$$', '', text, fixed = TRUE)
gsub('\u0001', '\\$', text, fixed = TRUE)
}
##' Typst Utility Function Definitions
##'
##' A named list of Typst utility function definitions, stored as R
##' character strings, for use by `typst.*` print/render methods in
##' place of requiring users to install a local Typst package (such as
##' `htypstmisc`). Each element is emitted once per document via
##' `typstAsis(typstFunctions$name)` before any calls to that function
##' are emitted, the same way `htypstmisc`'s `spikehist()` was
##' compile-tested.
##'
##' @details
##' Usage from a `typst.*` method:
##' ```
##' typstAsis(typstFunctions$spikehist) # define, once per document
##' typstAsis(paste0("#spikehist((", paste(heights, collapse=", "), "))"))
##' ```
##'
##' Current elements:
##' \describe{
##' \item{`spikehist`}{Spike histogram, the Typst analog of the LaTeX
##' `picture` environment used by `latex.describe.single`. Takes
##' `heights`, an array of non-negative numbers (one per bin; zero
##' height is legal and draws nothing, since `describe()` output
##' routinely has sparse bins at the tails of a distribution), plus
##' `width`, `height`, and `stroke-width` controlling the bounding box
##' and spike thickness. `baseline-shift` defaults to `auto`, resolved
##' inside the function body to `-height` -- confirmed by compile
##' error that Typst does not allow a parameter default to reference a
##' sibling parameter directly, hence the `auto`-sentinel-plus-body-
##' resolution pattern rather than `baseline-shift: -height` written
##' directly into the parameter list. This seats the spikes on the
##' baseline of the current text line when placed inline next to
##' running text, confirmed by compile-testing, and is the intended
##' use in `typst.describe.single`.}
##' \item{`justifiedText`}{Places `body` at position `(x, y)` with
##' left/center/right justification via `justify`, using Typst's
##' `measure()` to size the placement before positioning it.}
##' }
##'
##' @format A named list of character strings, each a complete Typst
##' `#let` function definition.
##' @keywords internal
typstFunctions <- list(
## spikehist: spike histogram, the Typst analog of the LaTeX `picture`
## environment used by latex.describe.single. Confirmed by
## compile-testing: height=0.2cm / baseline-shift=auto (resolving to
## -height) seats the spikes on the baseline of the current text line
## when placed inline next to running text -- the intended use in
## typst.describe.single.
##
## heights: array of non-negative numbers, one per bin. Zero-height
## bins are legal (drawn as nothing) -- describe() output
## routinely has sparse bins at the tails of a distribution.
## width, height: overall bounding box (Typst length, e.g. 3cm, 30pt).
## stroke-width: thickness of each spike.
## baseline-shift: defaults to auto, resolved in the function body to
## -height (Typst doesn't allow a parameter default to
## reference a sibling parameter directly -- confirmed by
## compile error -- hence the auto-sentinel + body-resolution
## pattern rather than `baseline-shift: -height` directly in
## the parameter list).
spikehist = '
#let spikehist(
heights,
width: 3cm,
height: 0.2cm,
stroke-width: 0.5pt,
baseline-shift: auto
) = {
let bshift = if baseline-shift == auto { -height } else { baseline-shift }
let n = heights.len()
let max-h = calc.max(..heights)
box(width: width, height: height, baseline: height + bshift)[
#for (i, h) in heights.enumerate() {
if h > 0 {
let x = width * (i + 0.5) / n
let h-scaled = height * h / max-h
place(dx: x, dy: height - h-scaled,
line(length: h-scaled, angle: 90deg, stroke: stroke-width))
}
}
]
}
',
justifiedText = '
#let justified-text(x, y, body, justify: "l") = {
context {
let sz = measure(body)
let dx = if justify == "r" { x - sz.width }
else if justify == "c" { x - sz.width / 2 }
else { x }
let dy = y - sz.height / 2
place(dx: dx, dy: dy, body)
}
}
'
## Additional typstFunctions elements go here as they're written, one
## per Typst utility function, following the same pattern.
)
## -----------------------------------------------------------------------
## typstAsis: canonical helper for emitting raw Typst markup from any
## typst.X print/render method (typst.describe, typst.describe.single,
## a future typst branch in prModFit, etc.).
##
## Wraps x in a Pandoc raw-block fence and marks it for knitr's asis
## treatment when running under Quarto/knitr, so no chunk-level
## `results='asis'` option is ever needed at the call site. Falls back to
## plain console output (cat()) when not running under knitr, so typst.X
## functions remain usable interactively while developing/testing.
##
## No knit_print method registration is required anywhere for this to
## work correctly -- confirmed empirically: print.describe (and any
## other print.X method) can call typst.describe(x), which returns
## typstAsis(...), and this renders correctly as real typeset Typst
## content with print.describe's existing prType()-based dispatch shape
## completely unchanged.
##
## This is deliberately NOT a markupSpecs$typst list entry -- it's
## format-agnostic plumbing (the fenced-raw-block/asis_output mechanism
## itself), not a per-format translation like the rest of
## markupSpecs$typst (varlabel, hfill, chisq, etc.).
## -----------------------------------------------------------------------
#' Emit Raw Typst Markup Without Requiring \code{results='asis'}
#'
#' Marks a character string as raw Typst source so that Quarto/knitr
#' renders it directly -- as real typeset Typst content -- rather than
#' displaying it as literal escaped text. This lets \code{print}/render
#' methods that build Typst output (for example \code{typst_describe},
#' \code{typst_describe_single}, or the Typst branch of a
#' \code{print.X}/\code{latex.X} method) return their result normally,
#' with no \code{results='asis'} chunk option required anywhere in the
#' calling document.
#'
#' \code{typstAsis} wraps \code{x} in a Pandoc raw-block fence
#' (\verb{````{=typst}} ... \verb{````}) and, when running inside a
#' knitr/Quarto render, returns the result via
#' \code{\link[knitr]{asis_output}}. Returning an \code{asis_output}
#' object as the visible top-level value of a chunk is what knitr's own
#' \code{knit_print} dispatch recognizes as content to insert verbatim
#' rather than escape -- this is the mechanism, confirmed empirically,
#' that requires no new \code{knit_print} method to be registered for
#' any particular class: any function that ultimately returns
#' \code{typstAsis(...)} as its result renders correctly, regardless of
#' how deeply the string was built up inside helper functions.
#'
#' The fence uses \strong{four} backticks, not the usual three. This is
#' deliberate: if \code{x} itself contains a triple-backtick sequence
#' (for example, output from a helper that wraps captured
#' \code{\link{print}} output in its own raw block, such as
#' \code{typst_verbatim}), an ordinary three-backtick outer fence would
#' be closed prematurely by that inner sequence, silently corrupting
#' everything in the document that follows -- confirmed directly as the
#' cause of a real rendering failure during development. Pandoc's
#' fenced-block matching only closes a fence with another fence of at
#' least the same length, so a four-backtick outer fence cannot be
#' broken by an inner three-backtick one.
#'
#' When not running inside a knitr render (for example, when called
#' interactively at the R console while developing or testing a
#' \code{typst_*} function), \code{typstAsis} falls back to printing
#' \code{x} via \code{\link{cat}} and returning it invisibly, so
#' \code{typst_*} functions remain directly usable outside Quarto
#' documents.
#'
#' \strong{Important:} \code{x} must already be genuine, complete Typst
#' syntax. \code{typstAsis} does not translate or interpret its
#' argument in any way -- it only marks already-finished Typst markup
#' so Pandoc passes it through untouched. This means \code{typstAsis}
#' must \emph{not} be used to wrap LaTeX-syntax math content that is
#' meant to be parsed by Pandoc's own markdown reader and translated to
#' Typst via texmath (for example, the equation content built by
#' \code{latexrms} and its calling \code{latex.X} methods) -- wrapping
#' such content in a \verb{{=typst}} raw block prevents Pandoc from ever
#' recognizing it as math to translate, and it will be inserted
#' unchanged, as literal LaTeX syntax, into a Typst document. That kind
#' of content should instead be returned via a bare
#' \code{\link[knitr]{asis_output}} call, with no raw-block fence, so
#' Pandoc's markdown/math parsing sees it directly.
#'
#' @param x A character string (or vector, coerced via
#' \code{\link{paste0}}) containing complete, valid Typst markup.
#'
#' @return If called during a knitr/Quarto render, an object of class
#' \code{knit_asis} (see \code{\link[knitr]{asis_output}}), which
#' knitr inserts into the rendered document verbatim. Otherwise, the
#' fenced string is printed to the console via \code{\link{cat}} and
#' returned invisibly.
#'
#' @seealso \code{\link{typstTranslate}}, \code{\link[knitr]{asis_output}}
#'
#' @examples
#' \dontrun{
#' # Inside a print/render method's typst branch:
#' typst_describe <- function(object, ...) {
#' R <- c(typstFunctions$spikehist, ...) # build up Typst content
#' typstAsis(paste(R, collapse = '\n\n'))
#' }
#'
#' # NOT appropriate: LaTeX-syntax math meant for texmath translation
#' # should use bare knitr::asis_output(), never typstAsis()
#' }
#'
#' @export
typstAsis <- function(x) {
x <- paste0("````{=typst}\n", x, "\n````\n")
if (length(getOption('knitr.in.progress')))
knitr::asis_output(x)
else {
cat(x)
invisible(x)
}
}
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.