metanorma-plugin-lutaml 0.4.5 → 0.4.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a510a5a23684dee91557fb6047267ca6ac87be25cbe11e0bcad8e4c0d0812b9
-  data.tar.gz: 5d6e5cfc99c66b42ed50b7f6c6b1346fd2887ee9bba4436cacd5fbc56121dde6
+  metadata.gz: 7be44107e7c1d3c9a4471ead7d39630d49cdced1e3996b6bea8b3c64be4fd03f
+  data.tar.gz: b99ff8fa3069c0fb0f983de14a984c06db12ecc595e0b876ed83e83926c6eeba
 SHA512:
-  metadata.gz: ea2e863ee349fb9bc5e60c43802569b0592b3437f2aad58f5bdb5591ecd430388566aff7ad8ff6d6c187e64868df9f1f303917afa94e73396e5c6d6564d0571a
-  data.tar.gz: dc8d9a72fbea070f7aec02fa576c59859ce34abf6375e307ef18685cdbd70130edcc3958839e7b82e9e7155befc8b51657c685d5f42cef96e900de0fd4a50532
+  metadata.gz: 2e6d79ef550cecde85e2e0d49717259f6e9016ef7e3935fdb938d13173361daf404e586a1d1319b05a1ab4a393213086625399d5d3e1090a4afd902c0bfc3f82
+  data.tar.gz: 454fe356b82f983a2a4ed9b2a1fa81de19ea8dcb6ac0c10243f1afc8db8e2eed8b8600658c7f0e37040224401dae077a0f93e433227b31c9dd63c7119c59db5f

data/README.adoc

@@ -1,21 +1,36 @@
-= metanorma-plugin-lutaml
+= Metanorma LutaML plugin (metanorma-plugin-lutaml)
 
 image:https://github.com/metanorma/metanorma-plugin-lutaml/workflows/rake/badge.svg["Build Status", link="https://github.com/metanorma/metanorma-plugin-lutaml/actions?workflow=rake"]
 
-== Functionality
+== Purpose
 
-Metanorma plugin that allows you to access lutaml objects from a Metanorma document
+LutaML is a data model accessor that supports various data model formats,
+including:
 
-=== Installation
+* EXPRESS (`*.exp` files)
+* OMG UML in XMI format (`*.xmi` files)
+
+This plugin allows you to access LutaML models from within a Metanorma document.
+
+== Installation
 
 [source,console]
 ----
 $ gem install metanorma-plugin-lutaml
 ----
 
-=== Usage, `lutaml` macro
 
-Given `example.exp` file with the content:
+== Usage with EXPRESS
+
+=== General
+
+LutaML supports accessing EXPRESS models via the
+https://github.com/lutaml/expressir[Expressir] parser.
+
+
+=== Usage of the `lutaml_express` EXPRESS macro
+
+Given an `example.exp` EXPRESS file with the content:
 
 [source,exp]
 ----
@@ -42,11 +57,11 @@ SCHEMA test_schema 'test';
 END_SCHEMA;
 ----
 
-And the `lutaml` macro block:
+And the `lutaml_express` macro block:
 
 [source,adoc]
 -----
-[lutaml,example.exp,my_context]
+[lutaml_express,example.exp,my_context]
 ----
 
 {% for schema in my_context.schemas %}
@@ -67,13 +82,15 @@ Where:
 * `{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
+`[lutaml_express,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. Context object is a serialized
-`Expressir::Model::Repository` object with all variable names available. See
+* `{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
 https://github.com/lutaml/expressir[Expressir] docs for reference.
 `{my_context}` has `schemas` method to access Expressir
 https://github.com/lutaml/expressir/blob/master/lib/expressir/model/schema.rb[schemas]
@@ -121,7 +138,7 @@ Example of usage:
 = Document title
 Author
 :lutaml-express-index: my_custom_name; /path/to/express_files; cache=/path/to/cache_file.yaml
-[lutaml,my_custom_name,my_context]
+[lutaml_express,my_custom_name,my_context]
 ----
 {% for schema in my_context.schemas %}
 == {{schema.id}}
@@ -142,7 +159,7 @@ diagram MyView {
   enum AddressClassProfile {
     imlicistAttributeProfile: CharacterString [0..1] {
       definition
-        this is multiline with `ascidoc`
+        this is multiline with `asciidoc`
       end definition
     }
   }
@@ -193,7 +210,7 @@ diagram MyView {
 ----
 
 
-=== Usage, `lutaml_uml_attributes_table` macro
+=== Usage of `lutaml_uml_attributes_table` macro
 
 This macro allows to quickly render data model attributes/values tables.
 
@@ -246,7 +263,7 @@ Will produce this output:
 |===
 -----
 
-In case of "enumeration"(AddressClassProfile) entity:
+In case of "enumeration" (AddressClassProfile) entity:
 
 [source,adoc]
 -----
@@ -264,12 +281,12 @@ Will produce this output:
 |===
 |Name |Definition
 
-|imlicistAttributeProfile |this is multiline with `ascidoc`
+|imlicistAttributeProfile |this is multiline with `asciidoc`
 
 |===
 -----
 
-=== Usage, `lutaml_uml_datamodel_description` macro
+=== Usage of `lutaml_uml_datamodel_description` macro
 
 This macro allows to quickly render data model packages and its dependent
 objects for supplied XMI file.
@@ -286,44 +303,44 @@ The `lutaml_uml_datamodel_description` macro can be used:
 [lutaml_uml_datamodel_description, path/to/example.xmi]
 --
 [.before]
-...
+....
 my text
-...
+....
 
-[.diagram_include_block, base_path="requirements/"]
-...
+[.diagram_include_block, base_path="requirements/", format="emf"]
+....
 Diagram text
-...
+....
 
 [.include_block, package="Another", base_path="spec/fixtures"]
-...
+....
 my text
-...
+....
 
 [.include_block, base_path="spec/fixtures"]
-...
+....
 my text
-...
+....
 
 [.before, package="Another"]
-...
+....
 text before Another package
-...
+....
 
 [.after, package="Another"]
-...
+....
 text after Another package
-...
+....
 
 [.after, package="CityGML"]
-...
+....
 text after CityGML package
-...
+....
 
 [.after]
-...
+....
 footer text
-...
+....
 --
 --
 -----
@@ -332,33 +349,46 @@ Where:
 
 * `path/to/example.xmi` - required, path to the XMI file to render
 
-* `[.before]` - macro to add additional text before the rendered output, can be used only once, additional occurrences of macro will overwrite text
+* `[.before]` - macro to add 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]` - macro to add additional text after the rendered output, can be used only once, additional occurrences of macro will overwrite text
 
 * `[.after, package="Another"]` - macro with text to be inserted before(after in case of `.before` name) the package
 
-* `[.diagram_include_block]` - macro to automatically include diagram images. Attribute `base_path` is a required attribute to supply path prefix where to look for a digram image. The logic is as follows:
+* `[.diagram_include_block]` - macro 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:
 [source,adoc]
 -----
 {% for diagram in package.diagrams %}
 [[figure-{{ diagram.xmi_id }}]]
 .{{ diagram.name }}
-image::{{ image_base_path }}/{{ diagram.xmi_id }}.png[]
+image::{{ image_base_path }}/{{ diagram.xmi_id }}.{{ format | default: 'png' }}[]
 
 {% if diagram.definition %}
 {{ diagram.definition | html2adoc }}
 {% endif %}
 {% endfor %}
 -----
-Eg: script will take package diagrams supplied in 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.
+
+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 inlude files(adoc/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, 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
 
+In addition to the macros listed above that can be used only inside `lutaml_uml_datamodel_description` macro there is another macroses called `lutaml_figure` and `lutaml_table`. `lutaml_figure` is used to lookup and reference xmi package diagrams. `lutaml_table` is used to lookup rendered xmi entries. The syntax is as follows:
+
+[source,adoc]
+-----
+This is lutaml_figure::[package="Wrapper root package", name="Fig B1 Full model"] figure
+This is lutaml_table::[package="Wrapper root package"] package
+This is lutaml_table::[package="Wrapper root package", class="my name"] class
+This is lutaml_table::[package="Wrapper root package", enum="my name"] enum
+This is lutaml_table::[package="Wrapper root package", data_type="my name"] data_type
+-----
+
+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:
 
@@ -372,18 +402,17 @@ Diagram text
 
 [[figure-EAID_ACBB5EE3_3428_40f5_9C7C_E41923419F29]]
 .CityGML Package Diagram
-image::requirements//EAID_ACBB5EE3_3428_40f5_9C7C_E41923419F29.png[]
+image::requirements/EAID_ACBB5EE3_3428_40f5_9C7C_E41923419F29.png[]
 
 BuildingFurnitureFunctionValue is a code list that enumerates the different purposes of a BuildingFurniture.
 
 [[figure-EAID_938AE961_1C57_4052_B964_997D1894A58D]]
 .Use of ISO and OASIS standards in CityGML
-image::requirements//EAID_938AE961_1C57_4052_B964_997D1894A58D.png[]
+image::requirements/EAID_938AE961_1C57_4052_B964_997D1894A58D.png[]
 
 The CityGML package is organized into
 2 packages with 1 modules:
 
-[arabic]
 . Another package
 . CityTML package
 
@@ -393,18 +422,17 @@ Content for CityGML package
 
 ==== Defining tables
 
-[arabic]
-.<<tab-P-another-C-abstractatomictimeseries>> -- Elements of Another::AbstractAtomicTimeseries
+.<<section-EAPK_9C96A88B_E98B_490b_8A9C_24AEDAC64293>> -- Elements of &#8220;Another::AbstractAtomicTimeseries&#8221; (class)
 
-[[tab-P-another-C-abstractatomictimeseries]]
-.Elements of Another::AbstractAtomicTimeseries
+[[section-EAPK_9C96A88B_E98B_490b_8A9C_24AEDAC64293]]
+.Elements of &#8220;Another::AbstractAtomicTimeseries&#8221; (class)
 [width="100%",cols="a,a,a,a,a,a,a,a"]
 |===
 h|Name: 7+| AbstractAtomicTimeseries
 h|Definition: 7+|
 h|Stereotype: 7+| interface
 h|Abstract: 7+|
-.1+h|Associations: 7+| (none)
+h|Associations: 7+| (none)
 .4+h|Public attributes:
 | _Name_
 2+| _Definition_
@@ -438,7 +466,7 @@ h|Constraints: 7+| (none)
 text after CityGML package
 -----
 
-In addition to just supplying XMI file, this macro also supports YAML
+In addition to just supplying an XMI file, this macro also supports a YAML
 configuration file.
 
 The format for using YAML is this:
@@ -453,26 +481,33 @@ packages:
   - three
   # skips these packages
   - skip: four
+render_style: entity_list|data_dictionary|default
+section_depth: 2
 -----
 
 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: entity_list, data_dictionary or default
+* `section_depth` - what package to use as root package for render, eg `section_depth` equal to 2 tells processor to use first nested package of the first root packages in xmi file. Example: if xmi file has this package structure: [{ name: 'One', packages: [{ name: 'one-1' }, { name: 'one-2' }] }, { name: 'Two', packages: [{ name: 'two-1' }, { name: 'two-2' }] }] and we have `section_depth` equal to 2, root package will be `one-1`
 
 Usage with macro:
 
 [source,adoc]
------
+--
 [lutaml_uml_datamodel_description, path/to/example.xmi, path/to/config.yml]
-....
------
+----
+[.diagram_include_block, base_path="models/Images", format="png"]
+...
+...
+----
+--
 
 The macro processor will read supplied YAML file and arrange packages according
 to the order supplied in the config file, also all packages supplied as `skip`

data/lib/metanorma/plugin/lutaml/liquid_templates/_diagrams_block.liquid

@@ -3,7 +3,7 @@
 {% for diagram in package.diagrams %}
 [[figure-{{ diagram.xmi_id }}]]
 .{{ diagram.name }}
-image::{{ image_base_path }}/{{ diagram.xmi_id }}.png[]
+image::{{ image_base_path }}/{{ diagram.xmi_id }}.{{ format | default: 'png' }}[]
 
 {% if diagram.definition %}
 {{ diagram.definition | html2adoc }}

data/lib/metanorma/plugin/lutaml/liquid_templates/_packages.liquid

@@ -1,11 +1,9 @@
 {% for package in context.packages %}
 {% assign package_name = package.name | downcase | replace: ":", "" | replace: " ", "_" %}
-{% if additional_context.before %}
-{{ additional_context.before.text }}
-{% endif %}
-{% assign before_package_key = 'before;' | append: package.name %}
-{% if additional_context[before_package_key] %}
-{{ additional_context[before_package_key].text }}
+{% if additional_context.before and additional_context.before.size > 0 %}
+{% for before in additional_context.before %}
+{{ before.text }}
+{% endfor %}
 {% endif %}
 {% assign is_package_spare = package.name | slice: 0,5 %}
 {% if is_package_spare == 'old: ' %}{% continue %}
@@ -13,16 +11,25 @@
 {% endif %}
 
 {% capture equalsigns %}{% for count in (1..depth) %}={% endfor %}{% endcapture %}{{equalsigns}} {{ package.name }} package
+[[section-{{ package.xmi_id }}]]
 {{equalsigns}}= {{ package.name }} overview
 
+{% assign before_package_key = 'before;' | append: package.name %}
+{% if additional_context[before_package_key] and additional_context[before_package_key].size > 0 %}
+{% for before in additional_context[before_package_key] %}
+{{ before.text }}
+{% endfor %}
+{% endif %}
 {% if additional_context.diagram_include_block %}
-{% include "diagrams_block", package_name: package_name, image_base_path: additional_context.diagram_include_block.base_path, text: additional_context.diagram_include_block.text %}
+{% for diagram_include_block in additional_context.diagram_include_block %}
+{% include "diagrams_block", package_name: package_name, image_base_path: diagram_include_block.base_path, text: diagram_include_block.text, format: diagram_include_block.format %}
+{% endfor %}
 {% endif %}
 
 {% if package.packages.size > 0 %}The {{ package.name }} package is organized into
 {{ package.packages.size }} packages{% assign modules_nested_size = 0 %}{% for module in package.packages %}{% assign modules_nested_size = modules_nested_size | plus: module.packages.size %}{% endfor %}{% if modules_nested_size > 0 %} with {{modules_nested_size}} modules{% endif %}:
 {% endif %}
-[arabic]
+
 {% for module in package.packages %}
 {% if module.packages.length > 0 %}
 . {{ module.name }} package comprises:
@@ -38,14 +45,13 @@
 
 {{equalsigns}}= Defining tables
 
-[arabic]
 {% for klass in package.classes %}
 {% assign is_klass_spare = klass.name | slice: 0,5 %}
 {% if is_klass_spare == 'old: ' %}{% continue %}
 {% elsif is_klass_spare == 'Spare' %}{% continue %}
 {% endif %}
 {% assign klass_name = klass.name | downcase | replace: ':', '' | replace: ' ', '_' %}
-.<<tab-P-{{ package_name }}-C-{{ klass_name }}>> -- Elements of {{ package.name }}::{{ klass.name }}
+.<<section-{{ klass.xmi_id }}>> -- &#8220;Elements of {{ package.name }}::{{ klass.name }}&#8221; (class)
 
 {% endfor %}
 {% for enum in package.enums %}
@@ -54,7 +60,7 @@
 {% elsif is_enum_spare == 'Spare' %}{% continue %}
 {% endif %}
 {% assign enum_name = enum.name | downcase | replace: ':', '' | replace: ' ', '_' %}
-.<<tab-P-{{ package_name }}-E-{{ enum_name }}>> -- Elements of {{ package.name }}::{{ enum.name }}
+.<<section-{{ enum.xmi_id }}>> -- &#8220;Elements of {{ package.name }}::{{ enum.name }}&#8221; (enum)
 
 {% endfor %}
 {% for data_type in package.data_types %}
@@ -63,7 +69,7 @@
 {% elsif is_data_type_spare == 'Spare' %}{% continue %}
 {% endif %}
 {% assign data_type_name = data_type.name | downcase | replace: ':', '' | replace: ' ', '_' %}
-.<<tab-P-{{ package_name }}-DT-{{ data_type_name }}>> -- Elements of {{ package.name }}::{{ data_type.name }}
+.<<section-{{ data_type.xmi_id }}>> -- &#8220;Elements of {{ package.name }}::{{ data_type.name }}&#8221; (data_type)
 
 {% endfor %}
 
@@ -81,9 +87,9 @@
 
 {% endif %}
 
-{% if additional_context.include_block %}
-{% assign block = additional_context.include_block %}
-{% capture block_filename %}{{ block.base_path }}/{{ package_name }}{% endcapture %}
+{% if additional_context.include_block and additional_context.include_block.size > 0 %}
+{% for block in additional_context.include_block %}
+{% capture block_filename %}{{ block.base_path }}{{ package_name }}{% endcapture %}
 {% capture block_content %}{% include block_filename %}{% endcapture %}
 {% unless block_content contains "Liquid error" %}
 {% if block.text %}
@@ -91,12 +97,13 @@
 {% endif %}
 {{ block_content }}
 {% endunless %}
+{% endfor %}
 {% endif %}
 
 {% assign include_block_package_key = 'include_block;' | append: package.name %}
-{% assign block = additional_context[include_block_package_key] %}
-{% if block %}
-{% capture block_filename %}{{ block.base_path }}/{{ package_name }}{% endcapture %}
+{% if additional_context[include_block_package_key] and additional_context[include_block_package_key].size > 0 %}
+{% for block in additional_context[include_block_package_key] %}
+{% capture block_filename %}{{ block.base_path }}{{ package_name }}{% endcapture %}
 {% capture block_content %}{% include block_filename %}{% endcapture %}
 {% unless block_content contains "Liquid error" %}
 {% if block.text %}
@@ -104,16 +111,23 @@
 {% endif %}
 {{ block_content }}
 {% endunless %}
+{% endfor %}
 {% endif %}
 
 {% assign after_package_key = 'after;' | append: package.name %}
-{{equalsigns}}= Additional Information
 {% if additional_context[after_package_key] %}
-{{ additional_context[after_package_key].text }}
+{{equalsigns}}= Additional information
+{% for after in additional_context[after_package_key] %}
+{{ after.text }}
+{% endfor %}
+{% endif %}
+{% if package.packages.size > 0 and render_nested_packages %}
+{% assign nested_depth = depth | plus: 1 %}{% include "packages", depth: nested_depth, context: package %}
 {% endif %}
-{% if package.packages.size > 0 and render_nested_packages %}{% assign nested_depth = depth | plus: 1 %}{% include "packages", depth: nested_depth, context: package %}{% endif %}
 {% endfor %}
 
-{% if additional_context.after %}
-{{ additional_context.after.text }}
+{% if additional_context.after and additional_context.after.size > 0 %}
+{% for after in additional_context.after %}
+{{ after.text }}
+{% endfor %}
 {% endif %}