drawio2py/docs/formalisms/create.rst

How To Create Custom Formalisms?
================================
Each formalism represents a "block diagram", where components are connected
via edges. Each edge is defined from a source "port class" to a target
"port class". Ports usually have unique names to allow for identification and
are located **inside** the blocks they connect.

New components can be defined by a 1-level hierarchical composition of the
model. I.e. a set of connected blocks that are "grouped" together.

.. warning::
    If the target for the code generation of a custom formalism does not
    comply to the above description, this tool cannot be used.
    :code:`DrawioConvert` currently only supports the described block diagram
    structure.

Structure
---------
Each formalism corresponds to a package in the :code:`./formalisms` directory.
There, all additional (re)sources can be added. In the required
:code:`__init__.py` file, the :code:`setup` variable bust be defined as a
dictionary, with the following structure (names followed by an asterisk are
required fields):

* :code:`parser`: All components required for parsing drawio files.
    * :code:`input class`: The class name used to identify input port in the
      generated code. Defaults to :code:`"InputPort"`.
    * :code:`output class`: The class name used to identify output ports in
      the generated code. Defaults to :code:`"OutputPort"`.
    * :code:`class object xpath`: The `xpath <https://www.w3.org/TR/xpath/>`_
      definition of a path which identifies a "class object" in the drawio
      XML-structure. More specifically, all elements that correspond to that
      structure will be seen as custom classes. Defaults to:
      :code:`".//object/mxCell/mxGeometry/mxRectangle/../../..[@class_name]"`.
    * :code:`class special xpath`: The `xpath <https://www.w3.org/TR/xpath/>`_
      definition of a path which identifies a "special object" in the drawio
      XML-structure. More specifically, all elements that correspond to that
      structure will be seen as elements with additional information for
      the code generation. For instance, custom imports can be defined this
      way. Defaults to: :code:`".//object/mxCell/mxGeometry/../..[@role]"`.
* :code:`generator`: The setup information for the file generation.
    * :code:`verify`: List of dictionaries that allow for simple assertion
      checking. Each dictionary has the following elements:

        - :code:`function`\*: A function that takes a single argument (the list
          of :class:`parser.Node` objects generated from drawio) and returns
          :code:`False` when the nodes are invalid.
        - :code:`error`\*: The error message to display when :code:`function`
          returns :code:`False`.
    * :code:`ignore`: List of attribute names to ignore.
    * :code:`environment`: List of allowed environment variables. These will
      be defined with the :code:`-E`/:code:`--environment` flag.
    * :code:`templates`: List of template files to be generated. These files
      are defined by their own dictionaries with the following keys:

        - :code:`filename`\*: The filename of the generated file. The template
          file name is this value, appended with :code:`.jinja`, located in the
          same directory as the :code:`__init__.py` file.
        - :code:`overwrite`: When :code:`True`, this file may be overwritten
          whenever a generation is called. Defaults to :code:`True`.
        - :code:`auto`: When :code:`True`, this file will automatically be
          generated by the script. Otherwise, the :code:`-a`/:code:`--all`
          flag is required. Defaults to :code:`True`.
        - :code:`entry`: Boolean value, indicative of whether or not the
          :code:`-e`/:code:`--entry` flag must be set in order to generate this
          file. Defaults to :code:`False`.