Code Quickstart

The following sections roughly outline the structure of pymunge.

Document Tree

The most important thing you need to know about pymunge is that almost every building block of the mod files can be referenced as node inside a big tree of documents and folders. A node can have none to one parent and none to multiple children. Nodes can also reference other nodes. Figure Fig. 1 provides a simple examples of how files and their content is represented in pymunge.

Document treeDocument tree

Fig. 1 Sample representation of folders and files in pymunge. Each colored node describes a different content type. For example a folder (green) points to another folder by a reference (blue). Documents (red) contain the AST of the respective format.

In the case of ODF files the root node of the document contains the section nodes as children. Each section node contains several key child nodes. A key node has exactly one value node.

Diagnostics

Error handling is done via the central component Diagnostic. The class is implemented as a singleton and initialized by the Munger. Therefore, it can be accessed anywhere in the code via the MungeEnvironment.

A DiagnosticMessage is made up of a scope, severity, code, and text:

  • The scope determines the module, class, or topic from which the diagnostic message occurred. Examples would be “ODF” or “MSH”. Scopes are defined during implementation.

  • Based on the severity (Error, Warning, Info) a diagnostic message might be reported during the munge process. A short summary is given at the end of the munge process how many diagnostic messages with different severity levels have occurred.

  • The diagnostic code is generated automatically during definition time. One drawback is that diagnostic numbers may change over time. But the big advantage is that diagnostic numbers remain up-to-date with the documentation

  • The text property is the only dynamic component of the diagnostic message. It can be defined during runtime to pin down the problem and tell the user, what went wrong.

An example from the code is given in Listing Lst. 1.

Lst. 1 Sample of how to report a diagnostic message.
1class Section(LexicalNode):
2
3    def __init__(self, tokens: list[Token], parent: Node = None):
4        LexicalNode.__init__(self, tokens, parent)
5
6        self.name: str = self.raw().strip()
7
8        if self.name not in OdfParser.Section:
9            MungeEnvironment.Diagnostic.report(OdfParserWarning(f'Section name "{self.name}" is not known.'))