Transformer#

Qualified name: rsm.transformer.Transformer

class rsm.transformer.Transformer[source]#

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 = """
... :manuscript:
... 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_keywords_to_constructs

add_necessary_subproofs

autonumber_nodes

collect_labels

Find all nodes with labels.

make_toc

resolve_pending_references

transform

Transform a manuscript tree.

collect_labels()[source]#

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.

transform(tree)[source]#

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.