vxml_pipeline/delimiter_pipelines
Pipeline fragments for converting delimited text into VXML elements.
Each function returns a Pipeline that can be inserted into an application
pipeline. The outside argument follows the package’s __outside
convention: delimiters inside subtrees whose tags occur in that list are
left untouched. unbridgeable prevents an opening delimiter from pairing
with a closing delimiter across an intervening element whose tag occurs in
that list.
Delimiters are normally not paired across paragraph boundaries. Before
paragraphs have been wrapped in their own elements, those boundaries should
therefore be represented by explicit elements and included in
unbridgeable. Writerly-derived pipelines typically operate on VXML of
this form:
<> root
<>
'first paragraph with _an opening delimiter'
<> WriterlyBlankLine
<>
'second paragraph with a closing delimiter_'
With "WriterlyBlankLine" included in unbridgeable, the two
underscores cannot form a pair. Distinct paragraphs should not instead be
represented as adjacent sibling text nodes: no element would then exist for
the pairing machinery to recognize as a boundary. Once paragraphs have
been wrapped in separate elements, their parent-child structure provides
the boundary and the explicit blank-line elements may be removed.
Values
pub fn annotated_backtick_pipeline(
output_tag: String,
annotation_key: String,
unbridgeable: List(String),
outside: List(String),
) -> List(core.Desugarer)Returns a pipeline that converts annotated backtick spans into VXML elements.
For example, with output_tag set to "span" and annotation_key set to
"class", `marked`{manual-color} becomes a span whose class
attribute is manual-color and whose text is marked. Unpaired syntax is
restored as text.
pub fn asymmetric_delimiter_pipeline(
opening_pattern: String,
closing_pattern: String,
opening_text: String,
closing_text: String,
output_tag: String,
unbridgeable: List(String),
outside: List(String),
) -> List(core.Desugarer)Returns a boundary-aware pipeline for distinct opening and closing delimiters.
opening_pattern and closing_pattern are regular-expression patterns.
Matched pairs become elements named output_tag; unmatched delimiter
elements are restored as opening_text and closing_text.
pub fn boundary_aware_symmetric_delimiter_pipeline(
delimiter_pattern: String,
delimiter_text: String,
output_tag: String,
outside: List(String),
) -> List(core.Desugarer)Returns a boundary-aware pipeline for symmetric inline delimiters.
delimiter_pattern is a regular-expression pattern. Opening and closing
occurrences are classified using their neighboring whitespace and
punctuation. Paired occurrences become an element named output_tag;
unmatched occurrences are restored as delimiter_text.
pub fn delimiter_cleanup_pipeline() -> List(core.Desugarer)Returns a cleanup pipeline for use after one or more delimiter pipelines.
Delimiter recognition splits text around every recognized delimiter. Once the temporary delimiter elements have been paired and folded, empty text nodes can remain at the boundaries between generated elements. For example, running italic, bold, and Markdown-link pipelines over:
_one_*two*[three](target) tail _
produces the following intermediate VXML. The final unmatched underscore is ordinary text, while the empty text nodes are splitting artifacts:
<> root
<>
''
<> i
<>
'one'
<>
''
<> b
<>
'two'
<>
''
<> a
href=target
<>
'three'
<>
' tail _'
This cleanup pipeline concatenates adjacent text nodes and removes text nodes containing exactly one empty line. The result is:
<> root
<> i
<>
'one'
<> b
<>
'two'
<> a
href=target
<>
'three'
<>
' tail _'
Cleanup can run once after a consecutive group of delimiter pipelines; it does not need to follow each one individually. As described in the module documentation, significant text boundaries must still be represented by intervening elements or by separate parent elements. Otherwise, concatenating adjacent text nodes could erase a boundary that exists only in the caller’s interpretation of the tree.
pub fn inline_math_pipeline(
recognized_delimiters: List(core.LatexDelimiterPair),
output_delimiter: core.LatexDelimiterPair,
fallback_output_delimiter: core.LatexDelimiterPair,
unbridgeable: List(String),
outside: List(String),
) -> List(core.Desugarer)Returns a pipeline that converts the recognized LaTeX inline delimiters
into Math elements.
Existing and newly created Math elements have recognized delimiters
removed and their contents trimmed. They are wrapped in output_delimiter
unless that delimiter already occurs in their text, in which case
fallback_output_delimiter is used.
pub fn markdown_link_pipeline(
unbridgeable: List(String),
outside: List(String),
) -> List(core.Desugarer)Returns a pipeline that converts Markdown-style [text](target) links into
a elements having target as their href attribute.
Unmatched opening and closing syntax is restored as text.
pub fn math_block_pipeline(
recognized_delimiters: List(core.LatexDelimiterPair),
output_delimiter: core.LatexDelimiterPair,
unbridgeable: List(String),
outside: List(String),
) -> List(core.Desugarer)Returns a pipeline that converts the recognized LaTeX display delimiters
into MathBlock elements.
Existing and newly created MathBlock elements have recognized delimiters
removed, their contents trimmed, and output_delimiter inserted on its own
opening and closing lines. Delimiters belonging to named LaTeX environments
remain inside the resulting MathBlock for MathJax to interpret.
pub fn permissive_symmetric_delimiter_pipeline(
delimiter_pattern: String,
delimiter_text: String,
output_tag: String,
unbridgeable: List(String),
outside: List(String),
) -> List(core.Desugarer)Returns a pipeline that treats every unescaped match of a symmetric delimiter as a possible opening or closing delimiter.
Unlike boundary_aware_symmetric_delimiter_pipeline, this function imposes
no neighboring whitespace or punctuation rules. delimiter_pattern is a
regular-expression pattern. Paired occurrences become an element named
output_tag; unmatched occurrences are restored as delimiter_text.