►V Reference
On this page:
58.10.1 Source-Addressable Formulas
source-span
source-occurrence
source-part
source-selector?
formula-source-match?
visual-selection
58.10.1.1 Querying Retained Source
formula-source
formula-find
formula-source-select
formula-source-select-one
58.10.1.2 Planning String Correspondences
plan-matching-strings
string-match
formula-string-copy
string-match?
formula-string-copy?
string-match-plan?
string-match-plan->datum
transform-matching-strings
58.10.1.3 Part Routes and Copies
formula-part-path
formula-part-copy
formula-part-path?
formula-part-copy?
formula-route?
formula-arc
formula-relative-path
58.10.1.4 Generated SVG Fragments
tagged-formula-fragment-visual?
tagged-formula-fragment-visual-svg-source
58.10.1.5 Part and Glyph Transitions
transform-matching-parts
transform-matching-glyphs
58.10.1.6 Anchored Rewrites
rewrite-formula
58.10.1.7 Derivation Steps
formula-step
formula-derivation-step?
formula-derivation
9.3

58.10 Formula Source Selection and Matching🔗ℹ

Source queries address retained TeX character ranges, named matches address formula parts, and glyph matching addresses rendered outlines. None of these APIs proves algebraic equivalence. Use selectors for lookup, a plan for inspection, and a transition request for animation; the sections below keep those roles separate.

See also Formula Construction and Layout, Formula Assemblies and Named Parts.

    58.10.1 Source-Addressable Formulas

      58.10.1.1 Querying Retained Source

      58.10.1.2 Planning String Correspondences

      58.10.1.3 Part Routes and Copies

      58.10.1.4 Generated SVG Fragments

      58.10.1.5 Part and Glyph Transitions

      58.10.1.6 Anchored Rewrites

      58.10.1.7 Derivation Steps

58.10.1 Source-Addressable Formulas🔗ℹ

Source selectors address character ranges in the canonical TeX source retained by math-tex. They complement named formula fragments; they do not recognize algebraic roles or prove mathematical equivalence. Source indices are Racket string-character indices in half-open ranges, so (source-span 2 5) selects characters 2 through 4.

struct

(struct source-span (start end))

  start : exact-nonnegative-integer?
  end : exact-nonnegative-integer?
Represents one half-open source range. It is checked against the formula’s canonical source when used.

struct

(struct source-occurrence (selector index))

  selector : source-selector?
  index : exact-nonnegative-integer?
Selects the zero-based occurrence of a literal-string, regexp, or source-span selector.

struct

(struct source-part (name selector))

  name : symbol?
  selector : source-selector?
Gives a declared source selector one stable author-facing name. This is used by math-tex with #:source-map 'declared.

procedure

(source-selector? value) → boolean?

  value : any/c
Recognizes a literal string, regexp, source-span, source-occurrence, or declared source-part selector.

Selector descriptions are model data; they do not typeset a formula.

Examples:

procedure

(formula-source-match? value) → boolean?

  value : any/c
Recognizes one immutable source-map unit. Its source span, canonical text, stable name, and mapped leaf paths can be inspected with the corresponding accessors.

struct

(struct visual-selection (root paths)
    #:transparent)
  root : visual-path?
  paths : (listof list?)
An immutable root-relative selection of existing Visual leaves. Each member of paths is a relative path of symbols below root. Selections describe semantic paths; they are not synthetic group Visuals.

58.10.1.1 Querying Retained Source🔗ℹ

procedure

(formula-source formula) → string?

  formula : formula-assembly-visual?
Returns the immutable canonical source string retained by a source-mapped formula. For several math-tex source arguments, arguments are joined by one literal space; that separator is part of the documented coordinate system. A formula constructed with #:source-map 'none raises an error.

procedure

(formula-find formula selector) → (listof formula-source-match?)

  formula : formula-assembly-visual?
  selector : source-selector?
Returns every mapped source occurrence in source order. A string matches non-overlapping occurrences from left to right; a regexp may not match an empty range. An unmatched query produces the empty list.

procedure

(formula-source-select formula selector) → visual-selection?

  formula : formula-assembly-visual?
  selector : source-selector?
Returns the immutable selection of all leaves mapped by selector. The selection is a query result, not a new scene Visual. It may therefore be used for read-only selection operations and formula styling, but not as a target for replacement, removal, or arbitrary movement. It raises an error when no mapped rendered leaf is selected.

procedure

(formula-source-select-one formula    
  selector) → visual-selection?
  formula : formula-assembly-visual?
  selector : source-selector?
Like formula-source-select, but requires exactly one matched source occurrence.

58.10.1.2 Planning String Correspondences🔗ℹ

procedure

(plan-matching-strings source    
  destination    
  [#:matches matches    
  #:copies copies]) → string-match-plan?
  source : formula-assembly-visual?
  destination : formula-assembly-visual?
  matches : (listof string-match?) = '()
  copies : (listof formula-string-copy?) = '()
Plans a deterministic source-addressed correspondence without rendering it. Explicit string-match declarations take precedence; remaining equal normalized source material is matched in source order. The resulting plan can be inspected with string-match-plan->datum, then animated with transform-matching-strings. Changed material uses the requested fade or fade-transform policy; unmatched material fades. This is syntactic matching, not symbolic algebra or a general TeX parser.

procedure

(string-match 
  source 
  destination 
  [#:route route 
  #:mode mode 
  #:appearance-complete-at-x appearance-complete-at-x 
  #:appearance-duration appearance-duration]) 
 → string-match?
  source : source-selector?
  destination : source-selector?
  route : (or/c #f formula-route?) = #f
  mode : (or/c 'auto 'rigid 'glyphwise 'cross-fade) = 'auto
  appearance-complete-at-x : (or/c #f source-selector?) = #f
  appearance-duration : (or/c #f (and/c finite-real? positive? (<=/c 1)))
   = #f
Declares one source-addressed correspondence. Explicit declarations take priority over automatic normalized-source matching.

When both appearance keywords are supplied, the part keeps its ordinary route, but its changed appearance completes when that route first reaches the current x-coordinate of appearance-complete-at-x. The duration is a fraction of the enclosing transition: the old and new appearances cross-fade only in the interval immediately preceding that deadline. This is useful for a moving + that should become - exactly as it passes an equality sign.

procedure

(formula-string-copy source    
  destination    
  [#:route route    
  #:mode mode]) → formula-string-copy?
  source : source-selector?
  destination : source-selector?
  route : (or/c #f formula-route?) = #f
  mode : (or/c 'auto 'rigid 'glyphwise 'cross-fade) = 'auto
Declares a moving copy: the source remains present while an otherwise unmatched destination is introduced. Its formula- prefix avoids colliding with racket/base’s string-copy.

procedure

(string-match? value) → boolean?

  value : any/c
Recognizes an explicit string correspondence.

procedure

(formula-string-copy? value) → boolean?

  value : any/c
Recognizes an explicit source-addressed formula string copy.

procedure

(string-match-plan? value) → boolean?

  value : any/c
Recognizes an immutable deterministic match plan.

procedure

(string-match-plan->datum plan) → immutable-hash?

  plan : string-match-plan?
Returns a transparent diagnostic representation of the planner’s matches, unmatched material, routes, and decision reasons.

procedure

(transform-matching-strings 
  source 
  destination 
  [#:matches matches 
  #:key-map key-map 
  #:protect-source protect-source 
  #:protect-destination protect-destination 
  #:copies copies 
  #:on-ambiguity on-ambiguity 
  #:path-arc path-arc 
  #:mismatch-mode mismatch-mode]) 
 → transform-formula-parts-request?
  source : formula-assembly-visual?
  destination : formula-assembly-visual?
  matches : (listof string-match?) = '()
  key-map : (listof string-match?) = '()
  protect-source : (listof source-selector?) = '()
  protect-destination : (listof source-selector?) = '()
  copies : (listof formula-string-copy?) = '()
  on-ambiguity : (or/c 'left-to-right 'error) = 'left-to-right
  path-arc : finite-real? = 0
  mismatch-mode : (or/c 'fade 'fade-transform) = 'fade
Plans source-addressed formula correspondences then compiles them into the normal deterministic formula transition. It matches source structure, not algebraic meaning or arbitrary rendered glyph similarity. The compiled plan is retained for the preview String matching inspector.

58.10.1.3 Part Routes and Copies🔗ℹ

procedure

(formula-part-path source-name    
  destination-name    
  route) → formula-part-path?
  source-name : symbol?
  destination-name : symbol?
  route : formula-route?
Declares an explicit route for one named formula-part correspondence.

procedure

(formula-part-copy source-name    
  destination-name    
  route) → formula-part-copy?
  source-name : symbol?
  destination-name : symbol?
  route : formula-route?
Declares a copy from one source part to an otherwise unmatched destination part.

procedure

(formula-part-path? value) → boolean?

  value : any/c
Recognizes a formula-part route declaration.

procedure

(formula-part-copy? value) → boolean?

  value : any/c
Recognizes a formula-part copy declaration.

procedure

(formula-route? value) → boolean?

  value : any/c
Recognizes a supported formula-motion route such as a circular formula-arc or a unit-chord formula-relative-path.

procedure

(formula-arc #:angle angle) → formula-route?

  angle : finite-real?
Creates a circular formula-motion route. Positive angles travel counter-clockwise in the formula’s local coordinate system; zero is straight.

procedure

(formula-relative-path geometry) → formula-route?

  geometry : path-geometry?
Creates a custom route in unit-chord coordinates. The path must start at (vec2 0 0) and end at (vec2 1 0).

58.10.1.4 Generated SVG Fragments🔗ℹ

procedure

(tagged-formula-fragment-visual? value) → boolean?

  value : any/c
Returns #t for a generated fragment Visual inside a tagged formula. The subtype is also a formula-visual?.

Returns the immutable SVG source used to render one generated tagged fragment. This is provided for inspection and renderer integration; construct fragments through tagged-formula, not by manufacturing this renderer detail.

58.10.1.5 Part and Glyph Transitions🔗ℹ

procedure

(transform-matching-parts source 
  destination 
  [#:matches matches]) 
 → transform-formula-parts-request?
  source : formula-assembly-visual?
  destination : formula-assembly-visual?
  matches : (listof formula-part-match?) = '()
Builds a correspondence transform in the style of Manim’s matching formula transitions. Explicit matches have priority. Animate then automatically pairs every remaining source fragment with the first still-unmatched destination fragment that has exactly the same formula source and typesetting options, in source order.

Exact matches render as one rigid SVG group that moves with its local transform. Changed explicit matches are moving cross-fades, and unmatched fragments use the normal fade-out/fade-in behavior. This operation does not infer algebraic equivalence, parse TeX tokens, choose paths/arcs for the movement, or morph glyph outlines.

procedure

(transform-matching-glyphs source 
  destination 
  [#:matches matches 
  #:path-arc path-arc 
  #:part-paths part-paths 
  #:copies copies 
  #:mismatch-mode mismatch-mode 
  #:changed-mode changed-mode]) 
 → transform-formula-parts-request?
  source : formula-assembly-visual?
  destination : formula-assembly-visual?
  matches : (listof formula-part-match?) = '()
  path-arc : finite-real? = 0
  part-paths : (listof formula-part-path?) = '()
  copies : (listof formula-part-copy?) = '()
  mismatch-mode : (or/c 'fade 'fade-transform) = 'fade
  changed-mode : (or/c 'fade 'morph) = 'fade
Builds the glyph-level counterpart to transform-matching-parts. Both assemblies must have been produced by glyph-tex. Exact dvisvgm path outlines pair automatically in source order; use matches for a deliberate changed glyph, such as mapping the generated plus-sign part to the destination minus-sign part. The remaining keywords have the same meanings as for transform-matching-parts.

This matches and moves whole rendered glyph leaves. 'fade is the default: changed matches use the ordinary moving cross-fade. With #:changed-mode 'morph, a changed matched pair instead interpolates its outline only when both cropped dvisvgm SVG fragments expand to one identically painted path whose positive-length contours are all closed and compatible in count. Animate globally pairs those destination contours with the source, phase-aligns them without reversing their traversal, normalizes the resulting paths to compatible cubic segments, and uses that path geometry only for interior frames; the ordinary tagged SVG fragments remain exact endpoints. Glyphs with multiple independently painted paths, open contours, incompatible contour topology, changed paint, or unsupported geometry safely fall back to the moving cross-fade.

This operation does not derive a mathematical operation, identify TeX characters or terms, perform semantic grouping, or infer which changed glyphs should be paired.

58.10.1.6 Anchored Rewrites🔗ℹ

procedure

(rewrite-formula source 
  destination 
  #:anchor anchor 
  [#:matches matches 
  #:stationary stationary 
  #:path-arc path-arc 
  #:part-paths part-paths 
  #:copies copies 
  #:mismatch-mode mismatch-mode]) 
 → transform-formula-parts-request?
  source : formula-assembly-visual?
  destination : formula-assembly-visual?
  anchor : (or/c symbol? formula-part-match?)
  matches : (listof formula-part-match?) = '()
  stationary : (listof (or/c symbol? formula-part-match?)) = '()
  path-arc : finite-real? = 0
  part-paths : (listof formula-part-path?) = '()
  copies : (listof formula-part-copy?) = '()
  mismatch-mode : (or/c 'fade 'fade-transform) = 'fade
Builds a matching formula transition with one fixed named anchor. Pass a symbol such as 'equals when the part has the same name at both endpoints, or a formula-part-match when its names differ. The anchor is made an explicit match; a conflicting value in matches raises an error.

When scene-play compiles the request, Animate translates the complete destination layout so the destination anchor coincides with the corresponding part in the current source formula. Consequently, a sequence of rewrites keeps the anchor fixed even when the formula values passed as earlier templates were constructed at their own default positions. The translation preserves the target formula’s TeX spacing and baselines.

Each stationary entry names an additional matched pair: a symbol means the same source and destination part name, while a formula-part-match permits different names. The pair is made explicit, and at clip compilation the destination fragment receives the current source fragment’s exact affine transform. Thus several selected terms can remain fixed even if the rest of the destination layout moves or reflows. This is an explicit presentation choice; it does not infer which terms should remain still or maintain a general layout constraint between them.

The remaining keywords have the same meaning as in transform-matching-parts: explicit matches take priority, routes and copies select intentional term motion, and 'fade-transform cross-fades remaining unmatched parts while moving them. Like the lower-level operation, this is whole-fragment correspondence rather than TeX parsing or glyph-outline morphing.

58.10.1.7 Derivation Steps🔗ℹ

procedure

(formula-step destination 
  [#:anchor anchor 
  #:stationary stationary 
  #:matches matches 
  #:path-arc path-arc 
  #:part-paths part-paths 
  #:copies copies 
  #:mismatch-mode mismatch-mode 
  #:duration duration 
  #:pause pause 
  #:explanation explanation]) 
 → formula-derivation-step?
  destination : formula-assembly-visual?
  anchor : (or/c false/c symbol? formula-part-match?) = #f
  stationary : (listof (or/c symbol? formula-part-match?)) = '()
  matches : (listof formula-part-match?) = '()
  path-arc : finite-real? = 0
  part-paths : (listof formula-part-path?) = '()
  copies : (listof formula-part-copy?) = '()
  mismatch-mode : (or/c 'fade 'fade-transform) = 'fade
  duration : (and/c finite-real? positive?) = 1
  pause : (and/c finite-real? (>=/c 0)) = 1/2
  explanation : (or/c false/c string?) = #f
Describes one explicit rewrite endpoint for formula-derivation. The destination and rewrite keywords have the same meanings as rewrite-formula. pause is the amount of time to hold the optional explanation before this step’s transition begins. An explanation must be one line of plain text.

anchor defaults to #f, which means that the derivation’s shared anchor is used. A step can override it with a same-name symbol or an explicit formula-part-match. stationary has the same meaning as in rewrite-formula and makes additional matched parts fixed for this one step. This data does not claim that the rewrite is algebraically valid; it records the author’s chosen presentation.

procedure

(formula-derivation-step? value) → boolean?

  value : any/c
Returns #t when value was created by formula-step.

procedure

(formula-derivation 
  scene 
  initial 
  #:anchor anchor 
  #:steps steps 
  [#:explanation-position explanation-position 
  #:explanation-id explanation-id 
  #:explanation-font-size explanation-font-size 
  #:explanation-color explanation-color]) 
 → scene?
  scene : scene?
  initial : formula-assembly-visual?
  anchor : (or/c symbol? formula-part-match?)
  steps : (listof formula-derivation-step?)
  explanation-position : (or/c false/c vec2?) = #f
  explanation-id : symbol? = 'derivation-note
  explanation-font-size : (and/c finite-real? positive?) = 1/4
  explanation-color : any/c = "darkslategray"
Appends an ordered derivation to scene. initial must already be present in the scene under its formula identity. For each steps entry, the builder first replaces its own optional explanation label, waits for that step’s pause, and then appends a rewrite-formula clip with the requested duration and correspondence options. The resulting endpoint becomes the construction template for the next step, while every rewrite still resolves its anchor from the current sampled scene formula.

When any step has an explanation, supply explanation-position. The builder creates plain text with explanation-id, which must be absent from the initial scene. Later explanations replace only that generated Visual. The final explanation remains visible unless a later step omits it.

This is immutable convenience syntax over existing scene and formula APIs. It does not parse TeX, infer operations, prove a derivation, choose matches/routes, or automatically lay out the explanation.