Transformer

Qualified name: rsm.transformer.Transformer

class rsm.transformer.Transformer(root_dir=None, src_file=None, strict=False)

Bases: None

Apply transformations to the abstract syntax tree.

A transformation is any operation on the manuscript tree that modifies its structure. This class keeps a register of transformations and applies them in sequence. Order of application is of the utmost importance since each transform modifies the tree in some way.

Notes

If an operation is being carried out not to transform the tree, but merely to check it in some way, consider implementing it as a linter operation instead.

Examples

Consider the following manuscript.

>>> src = """
... Here comes a :span:{:label:lbl} word :: with a label,
... and a reference to the :ref:lbl,word::.
... """

The transform step comes after the parsing step. After parsing, the manuscript looks as follows.

>>> parser = rsm.tsparser.TSParser()
>>> sans_transform = parser.parse(src)
>>> print(sans_transform.sexp())
(Manuscript
  (Paragraph
    (Text)
    (Span
      (Text))
    (Text)
    (PendingReference)
    (Text)))

The rsm.nodes.PendingReference node is created as a placeholder. One can inspect its desired target.

>>> sans_transform.children[0].children[3].target
'lbl'

The target is the string 'lbl'. Note this is the label of the target node.

After the transform step, the tree is modified and the reference is resolved.

>>> tform = rsm.transformer.Transformer()
>>> with_transform = tform.transform(sans_transform)
>>> print(with_transform.sexp())
(Manuscript
  (Paragraph
    (Text)
    (Span
      (Text))
    (Text)
    (Reference)
    (Text)))

Accordingly, its target is now no longer a string, but the actual node.

>>> with_transform.children[0].children[3].target
Span(label=lbl, parent=Paragraph, [Text])

Methods

add_handrail_depth
add_keywords_to_constructs
add_necessary_subproofs
assign_author_affiliations	Deduplicate affiliations and assign superscript numbers to authors.
assign_author_note_symbols	Assign symbols (*, †, ‡, §, ¶, ‖, **, ††, ...) to author notes.
assign_node_ids
autonumber_nodes
check_for_cst_errors	Check for CST errors in the transformed tree.
collect_labels	Find all nodes with labels.
make_toc
mark_author_visibility	Mark which authors should be hidden in collapsed mode (>5 authors).
resolve_pending_references
transform	Transform a manuscript tree.

assign_author_affiliations()

Deduplicate affiliations and assign superscript numbers to authors.

This transform iterates through all Author nodes and: 1. Collects unique affiliations in order of first appearance 2. Assigns a number (1, 2, 3, …) to each unique affiliation 3. Sets the affiliation_number attribute on each Author node 4. Stores the total count of unique affiliations on the Manuscript node

Authors with the same affiliation text get the same number. Authors without an affiliation get affiliation_number = None.

Examples

Two authors with the same affiliation get the same number:

>>> from rsm import nodes
>>> from rsm.transformer import Transformer
>>> tree = nodes.Manuscript()
>>> a1 = nodes.Author(name="Alice", affiliation="MIT")
>>> a2 = nodes.Author(name="Bob", affiliation="MIT")
>>> _ = tree.append(a1).append(a2)
>>> tform = Transformer()
>>> tform.tree = tree
>>> tform.assign_author_affiliations()
>>> a1.affiliation_number
1
>>> a2.affiliation_number
1

assign_author_note_symbols()

Assign symbols (*, †, ‡, §, ¶, ‖, **, ††, …) to author notes.

This transform iterates through all Author nodes and: 1. Collects unique note texts in order of first appearance 2. Assigns a symbol to each unique note 3. Sets the note_symbol attribute on each Author node 4. Stores the total count of unique notes on the Manuscript node

Symbol progression: *, †, ‡, §, ¶, ‖, **, ††, ‡‡, §§, ¶¶, ‖‖, ***, †††, …

Authors with the same note text get the same symbol. Authors without a note get note_symbol = “”.

Examples

Two authors with the same note get the same symbol:

>>> from rsm import nodes
>>> from rsm.transformer import Transformer
>>> tree = nodes.Manuscript()
>>> a1 = nodes.Author(name="Alice", author_note="Equal contribution")
>>> a2 = nodes.Author(name="Bob", author_note="Equal contribution")
>>> _ = tree.append(a1).append(a2)
>>> tform = Transformer()
>>> tform.tree = tree
>>> tform.assign_author_note_symbols()
>>> a1.note_symbol
'*'
>>> a2.note_symbol
'*'

check_for_cst_errors()

Check for CST errors in the transformed tree.

If strict mode is enabled and Error nodes are found in the tree, raise an exception. This transform runs last to ensure all other transformations have completed.

Raises:

RSMTransformerError – If strict mode is enabled and Error nodes are present in the tree.

Notes

This transform does not modify the tree. It only checks for errors and optionally raises an exception.

collect_labels()

Find all nodes with labels.

Find all nodes with a non-empty label attribute and build a label-to-node mapping. This mapping is later used by other transforms.

Warning

If two nodes with the same label are found, only the first node is assigned the label and the second (and later, if any) nodes’ labels are erased and ignored.

Notes

This transform does not actually modify the tree, but is necessary for the execution of other transforms that may modify it. Therefore, this must be executed before all other ones.

mark_author_visibility()

Mark which authors should be hidden in collapsed mode (>5 authors).

When there are >5 authors: - Show first 3 authors - Hide middle authors (positions 4 to N-2) - Show last 2 authors - Add container and toggle button

transform(tree)

Transform a manuscript tree.

For examples see class docstring.

Parameters:

tree (Manuscript) – Manuscript tree to be transformed.

Returns:

tree – The transformed tree. All transformations occur in place.

Return type:

Manuscript

Notes

tree is stored as self.tree.