Metanorma LutaML plugin (metanorma-plugin-lutaml)

LutaML supports accessing EXPRESS models via the Expressir parser.

Given an example.exp EXPRESS file with content:

And the lutaml block:

Where:

• content within the block is called the “template”;

• {example.exp} is the location of the EXPRESS schema file (*.exp) that contains data to be loaded. Location of the file is computed relative to the source directory that [lutaml] is used (e.g., if [lutaml,example.exp,my_context] is invoked in an .adoc file located at /foo/bar/doc.adoc, the data file is expected to be found at /foo/bar/example.exp);

• {my_context} is the name where the EXPRESS Repository read from the .exp file can be accessed with.

  • The context object is a serialized Expressir::Model::Repository object with all variable names available. See Expressir docs for reference. {my_context} has schemas method to access Expressir schemas

Will produce this output:

== test_schema

=== my_type1 === my_type2 === my_type3 === my_type4 === my_type5

This command also supports .lutaml files.

Instead of using the direct path to the file one can use lutaml-express-index document attribute to supply directory with express files or YAML index file to parse as well as the cache file location.

The syntax is as follows:

Where:

• my_custom_name - is name of the parsed EXPRESS files context for the later use with lutaml macro

• dir_or_index_path - location of directory with EXPRESS files or path to the YAML index file to parse

• cache_path - optional, location of the Expressir cache file to use

Example of usage:

This functionality allows [lutaml_express] blocks to load a full set of EXPRESS schemas in one index, and then provide a select ("filter") option per-block via a separate YAML file.

Where schemas_all.yml provides all schemas:

And schemas.yaml only selects 2 schemas:

The resulting block adds the select attribute to every schema of the the "context" object, which allows you to filter those out for complex operations via Liquid:

This command allows to quickly render a LutaML view as an image file.

Given a file example.lutaml file with content:

The lutaml_diagram command will add the image to the document.

The lutaml_diagram command can also be used to denote a block with an embedded LutaML view.

For example:

This command allows to quickly render a LutaML diagram as an image file by specifying the name of diagram.

The code will search the diagram with name name_of_diagram and then render it as:

This command allows to render a LutaML GML Dictionary by using Liquid Drop.

GmlDictionaryDrop has the following attributes:

• name

• file_name

• dictionary_entry

Each dictionary_entry has the following attributes:

• name

• description

The command accepts the options listed below:

• /path/to/dictionary.xml specifies the path of xml file of the GML Dictionary.

• template="/path/to/template.liquid" specifies the liquid template. For example, you can create a liquid template and link it by template.

• context=dict define the context in the template.

In spite of specifying the path of the template, you can also define an inline template within a block by [lutaml_gml_dictionary,"/path/to/dictionary.xml",context=dict].

This command allows to render a LutaML table of a class by using Liquid Drop.

The table will show:

• Class Name

• Class Definition

• Inherited Properties

• Self-defined Properties

• Properties Inherited from Association

• Properties Defined in Association

The command accepts the options listed below:

• /path/to/example.xmi specifies the path of xmi file.

• name option only, name option with package option or path option. One of 3 forms of options can be used to specify the name of the class.

  • name="NameOfClass" specifies the name of the class. (e.g. name="Building") If there are multiple classes with the same name, other form of options are recommended to specify the class.

  • package="NameOfPackage"name="NameOfClass" specifies the name of the class (specified by name option) inside the package (specified by package option). The package option must be used with the name option. (e.g. package="uro",name="_BoundarySurface")

  • path="PathOfClass" specifies the absolute path of the class which is started with :: (e.g. path="::EA_Model::Conceptual Models::i-UR::Urban Planning ADE 3. 1::uro::_BoundarySurface") or relative path of the class which is not started with :: (e.g. path="uro::_BoundarySurface"). The last part of the path separated by :: is the name of the class. The other parts of the path are the names of the packages.

• template="/path/to/templates/_my_klass_table.liquid" specifies the path of the liquid template. (Optional) By default, it will look for the template _klass_table.liquid defined in lib/metanorma/plugin/lutaml/templates. This template can be customized by changing the template path in the template option.

• guidance="/path/to/my_guidance.yml" specifies the path of the yaml file of the guidance. (Optional)

The guidance file should be in the following format:

If you want to define the guidance, you can define the name of the class under classes. Then define which attributes you want to add guidance by the name. Set used to show the attribute is used or not. Drop the message of guidance in guidance.

This command allows rendering a definition clause for a UML class.

Given example.lutaml with this content:

The command:

Will produce this output:

== Register

A register of information.

=== Attributes

==== identifier

Unique identifier of the register.

Table 1. Specification of Register.identifier

Value type and multiplicity	String [1]

==== concepts

Concepts.

Table 2. Specification of Register.concepts

Value type and multiplicity	Concepts [0..*]

The command accepts two options:

• skip_headers=true (or just skip_headers). The initial heading (the UML class name) will not be generated. This is useful if additional content is to be supplied to the clause, such as diagrams that are defined outside the UML model.

• depth={n}. (default: 2) This determines the depth of the generated headings. A depth of 2 means the initial heading will have 2 equal signs, and so forth. The heading depth of the attributes are in relation to the initial depth, so a depth of 2 will have the "Attributes" section at depth 3.

This command allows rendering definition tables for a UML model.

Given example.lutaml file with the content:

And the lutaml_uml_attributes_table macro:

Will produce this output:

=== AttributeProfile

Table 3. AttributeProfile attributes

Name	Definition	Mandatory/ Optional/ Conditional	Max Occur	Data Type
addressClassProfile	TODO: enum’s definition	M	1	CharacterString
imlicistAttributeProfile	this is attribute definition with multiply lines	M	1	CharacterString

In case of "enumeration" (AddressClassProfile) entity:

Will produce this output:

=== AddressClassProfile

Table 4. AddressClassProfile values

Name	Definition
imlicistAttributeProfile	this is multiline with asciidoc

This command allows to quickly render data model packages and its dependent objects for supplied XMI file.

Given an Enterprise Architect example.xmi file with 2 packages:

• 'Another'

• 'CityGML'

The lutaml_uml_datamodel_description macro can be used:

Where:

• path/to/example.xmi - required, path to the XMI file to render

• [.before] - block text that adds additional text before the rendered output, can be used only once, additional occurrences of macro will overwrite text, not that literal block style must be used in there(eg …​.)

• [.after] - block text that adds additional text after the rendered output, can be used only once, additional occurrences of macro will overwrite text

• [.after, package="Another"] - block text to be inserted before(after in case of .before name) the package

• [.package_text, position="after", package="Another"] - include custom adoc code into package rendered body, position is a a required attribute which tells where to insert the code.

• [.package_text, package="Another"] - same as above, but include block will be included only for supplied package name

• [.diagram_include_block] - block text to automatically include diagram images. Attribute base_path is a required attribute to supply path prefix where to look for a diagram image. format is an optional attribute that tells what file extension to use when including diagram file.

  The logic is as follows:

For instance, the script will take package diagrams supplied in the XMI file and will try to include image with the name equal to diagram' xmi_id attribute plus .png. Also one can add any text to the macro text, it will be added as paragraph before each image include.

• [.diagram_include_block, package="Another"] - same as above, but diagram will be included only for supplied package name

• [.include_block, base_path="spec/fixtures"] - macro to include files (.adoc or .liquid) for each package name. Attribute base_path is a required attribute to supply path prefix where to look for file to include. Macro will look for a file called base_path + / package_name(downcase, replace : → '', ' ' → '') + .adoc[.liquid], eg for package 'My Package name' and base_path eq to my/path, macro will look for the following file path: my/path/_my_package_name.adoc.

• [.include_block, package="Another", base_path="spec/fixtures"] - same as above, but include block will be included only for supplied package name

There are two other commands that are used to refer to LutaML generated document elements:

• lutaml_figure. Provides a reference anchor to a figure defined in the XMI file, using its XMI ID for reference.

• lutaml_table. Provides a reference anchor to the definition tables of a particular package, class, enumeration or data type object in the XMI.

The syntax is as follows:

This code will be transformed into [figure-{diagram.xmi_id}] and will point to diagram figure. One can only use this macro when document rendered lutaml_uml_datamodel_description macro as it needs diagram lookup table in order to reference package diagram.

Will produce this output:

In addition to the XMI file, this macro also supports a YAML configuration file that specifies:

• What packages to include in the render;

• What render style is desired;

• Location of the root package (which package should the iterative process start at).

The format for using the YAML configuration file:

Where:

• packages - required, root element with the list of strings or objects

• Package * - pattern matching, specifies lookup condition for packages to render.

  Note	In this example, it is equal to the following regular expression: /^Package.*$/

• skip: four - object with package name to skip

• render_style - what template to use to render packages, can be one of:

  • entity_list

  • data_dictionary; or

  • default

• section_depth - what package to use as root package for render. e.g., a section_depth equal to 2 tells the processor to use the first nested package of the first root packages in XMI file.

  EXAMPLE: If the XMI file has this package structure, and we have section_depth equal to 2, root package will be one-1.

  [
    {
      name: 'One',
      packages: [{ name: 'one-1' }, { name: 'one-2' }]
    },
    {
      name: 'Two',
      packages: [{ name: 'two-1' }, { name: 'two-2' }]
    }
  ]

Usage with macro:

The processor will read the supplied YAML config file (path/to/config.yml), and iterate through packages according to the order supplied in the file. All packages that matches skip in the YAML config file will be skipped during render.

This command is a replacement for lutaml_uml_datamodel_description to perform the same functionalities of lutaml_uml_datamodel_description, which is to render data model packages and its dependent objects for supplied XMI file, by using Liquid Drop. The performance of lutaml_ea_xmi can be improved by 10~20 times. (Tested with a 10.6MB XMI file with 120000+ lines)

To use this macro, you only need to replace lutaml_uml_datamodel_description by lutaml_ea_xmi.

Replace:

By:

You can define guidance in the configuration file as well. The configuration file will looks like:

The guidance file should be in the following format:

If you want to define the guidance, you can define the name of the class under classes. Then define which attributes you want to add guidance by the name. Set used to show the attribute is used or not. Drop the message of guidance in guidance.

The name of class can be defined in the following ways:

• name: "NameOfClass" specifies the name of the class. (e.g. name: "Building") If there are multiple classes with the same name, it is recommended to specify the class by absolute path.

• name: "::NameOfPackage::NameOfClass" specifies the name of the class in absolute path. (e.g. name: "::EA_Model::Conceptual Models::CityGML2.0::bldg::Building")