metanorma-plugin-lutaml 0.4.8 → 0.4.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 202335c2a56ade17a5bdfedd489b6c39363b256ebbaa2e2cbfe812a6bb6995e5
-  data.tar.gz: 9637bc5a68bbbe8cda105e74a537ae7e41d5676f584e64e907ad26ba6cf50082
+  metadata.gz: 2a10016110c0403f8925e080c1f29cf8a4b81e9d2f52c1e986bf26c3d9754d0c
+  data.tar.gz: 81f3c21e207bde438c076f11aa7d2fc109732999351a99431785f4323c3d749c
 SHA512:
-  metadata.gz: 7e183219067f431d7b839d59ab3e5c8a8b3f54b335cb1e232297f1fa997e7f7abafa4a0858d5398a034c2a025d46feef240f3e71b14db7730fb1789b2dd11afb
-  data.tar.gz: 400132cae1b7b1b3f03414f4c4ab8b16edde68ab285cd192bd0894d913bee26985182aaf880c2a4ddac1935541bac62913679424e433d88bacc8242c7fcabede
+  metadata.gz: 0ba4c445dc6254628dd8184bddecf6dd5394496694ff6493572b8b30479c62e92275d4af33d6f5015862ec6dad39be0a438e2dd2d75353882b6820dffef613b5
+  data.tar.gz: c1258f09dd31d96424b2b63bb039c424042248e0cdd84b7215c48a817f25c326b0dc75a0f439db97716d1a1e8f712685c736d0c1ac9149a7a35c3dde66aaf17d

data/README.adoc

@@ -28,7 +28,7 @@ LutaML supports accessing EXPRESS models via the
 https://github.com/lutaml/expressir[Expressir] parser.
 
 
-=== Usage of the `lutaml_express` EXPRESS macro
+=== Usage of the `lutaml` macro
 
 Given an `example.exp` EXPRESS file with the content:
 
@@ -57,11 +57,11 @@ SCHEMA test_schema 'test';
 END_SCHEMA;
 ----
 
-And the `lutaml_express` macro block:
+And the `lutaml` macro block:
 
 [source,adoc]
 -----
-[lutaml_express,example.exp,my_context]
+[lutaml,example.exp,my_context]
 ----
 
 {% for schema in my_context.schemas %}
@@ -82,7 +82,7 @@ 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_express,example.exp,my_context]` is invoked in an `.adoc` file located at
+`[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`);
 
@@ -97,8 +97,7 @@ https://github.com/lutaml/expressir/blob/master/lib/expressir/model/schema.rb[sc
 
 Will produce this output:
 
-[source,adoc]
------
+____
 == test_schema
 
 === my_type1
@@ -106,9 +105,9 @@ Will produce this output:
 === my_type3
 === my_type4
 === my_type5
------
+____
 
-This macro also supports `.lutaml` files.
+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
@@ -137,19 +136,22 @@ Example of usage:
 -----
 = Document title
 Author
-:lutaml-express-index: my_custom_name; /path/to/express_files; cache=/path/to/cache_file.yaml
-[lutaml_express,my_custom_name,my_context]
+:lutaml-express-index: index_name; /path/to/express_files; cache=/path/to/cache_file.yaml
+[lutaml,index_name,context]
 ----
-{% for schema in my_context.schemas %}
+{% for schema in context.schemas %}
 == {{schema.id}}
 {% endfor %}
 ----
 -----
 
-=== Usage, `lutaml_diagram` macro
+== Usage with UML
 
-This macro allows to quickly render lutaml file as diagram image.
-Given `example.lutaml` file with the content:
+=== Rendering a LutaML view: `lutaml_diagram`
+
+This command allows to quickly render a LutaML view as an image file.
+
+Given a file `example.lutaml` file with content:
 
 [source,java]
 ----
@@ -173,16 +175,17 @@ diagram MyView {
 }
 ----
 
-And the `lutaml_diagram` macro:
+The `lutaml_diagram` command will add the image to the document.
 
 [source,adoc]
 -----
 lutaml_diagram::example.lutaml[]
 -----
 
-Will add diagram image to the document
+The `lutaml_diagram` command can also be used to denote a block with an embedded
+LutaML view.
 
-Also one can use `lutaml_diagram` block with embed lutaml code instead of block macro. Example:
+For example:
 
 [source,java]
 ----
@@ -193,9 +196,9 @@ diagram MyView {
 
   enum AddressClassProfile {
     imlicistAttributeProfile: CharacterString [0..1] {
-      definition
-        this is multiline with `ascidoc`
-      end definition
+      definition {
+        This is multiline AsciiDoc content.
+      }
     }
   }
 
@@ -210,9 +213,9 @@ diagram MyView {
 ----
 
 
-=== Usage of `lutaml_uml_attributes_table` macro
+=== `lutaml_uml_attributes_table`
 
-This macro allows to quickly render data model attributes/values tables.
+This command allows rendering definition tables for a UML model.
 
 Given `example.lutaml` file with the content:
 
@@ -247,21 +250,20 @@ And the `lutaml_uml_attributes_table` macro:
 
 Will produce this output:
 
-[source,adoc]
------
+____
 === AttributeProfile
 
-
 .AttributeProfile attributes
 |===
 |Name |Definition |Mandatory/ Optional/ Conditional |Max Occur |Data Type
 
-|addressClassProfile |TODO: enum 's definition |M |1 | `CharacterString`
+|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:
 
@@ -272,11 +274,9 @@ In case of "enumeration" (AddressClassProfile) entity:
 
 Will produce this output:
 
-[source,adoc]
------
+____
 === AddressClassProfile
 
-
 .AddressClassProfile values
 |===
 |Name |Definition
@@ -284,11 +284,11 @@ Will produce this output:
 |imlicistAttributeProfile |this is multiline with `asciidoc`
 
 |===
------
+____
 
 === Usage of `lutaml_uml_datamodel_description` macro
 
-This macro allows to quickly render data model packages and its dependent
+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:
@@ -349,13 +349,19 @@ 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, not that `literal` block style must be used in there(eg `....`)
+* `[.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]` - macro to add additional text after the rendered output, can be used only once, additional occurrences of macro will overwrite text
+* `[.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"]` - macro with text to be inserted before(after in case of `.before` name) the package
+* `[.after, package="Another"]` - block 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 diagram image. `format` is an optional attribute that tells what file extension to use when including diagram file. The logic is as follows:
+* `[.package_text, position="after", package="Another"]` - include custom adoc code into package rendered body, `position` is a arequired 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:
 [source,adoc]
 -----
 {% for diagram in package.diagrams %}
@@ -377,11 +383,30 @@ For instance, the script will take package diagrams supplied in the XMI file and
 
 * `[.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 macro called `lutaml_figure`. `lutaml_figure` is used to lookup and reference xmi package diagrams. The syntax is as follows:
+
+NOTE: .after, .before, package_text and include_block macroses all can be used with additional option - `liquid`, if this option is supplied then the code inside block will be interpolated in liquid context
+
+
+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:
 
 [source,adoc]
 -----
+// For lutaml_figure
 This is lutaml_figure::[package="Wrapper root package", name="Fig B1 Full model"] figure
+
+// For lutaml_table
+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"] enumeration
+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.
@@ -418,9 +443,9 @@ Content for CityGML package
 
 ==== Defining tables
 
-.<<tab-P-another-C-{XMI_ID}>> -- Elements of &#8220;Another::AbstractAtomicTimeseries&#8221; (class)
+.<<section-EAPK_9C96A88B_E98B_490b_8A9C_24AEDAC64293>> -- Elements of &#8220;Another::AbstractAtomicTimeseries&#8221; (class)
 
-[[tab-P-another-C-{XMI_ID}]]
+[[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"]
 |===
@@ -462,13 +487,20 @@ h|Constraints: 7+| (none)
 text after CityGML package
 -----
 
-In addition to just supplying an XMI file, this macro also supports a YAML
-configuration file.
+In addition to the XMI file, this macro also supports a YAML configuration file
+that specifies:
+
+* What packages to include in the render;
 
-The format for using YAML is this:
+* 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:
 
 [source,yaml]
------
+----
 ---
 packages:
   # includes these packages
@@ -477,21 +509,49 @@ packages:
   - three
   # skips these packages
   - skip: four
-render_style: entity_list|data_dictionary|default
+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`
+
+* `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`.
++
+[source,json]
+----
+[
+  {
+    name: 'One',
+    packages: [{ name: 'one-1' }, { name: 'one-2' }]
+  },
+  {
+    name: 'Two',
+    packages: [{ name: 'two-1' }, { name: 'two-2' }]
+  }
+]
+----
 
 Usage with macro:
 
@@ -505,10 +565,11 @@ Usage with macro:
 ----
 --
 
-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`
-will be skipped during render
+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.
 
 == Documentation
 
-Please refer to https://www.metanorma.com.
+Please refer to https://www.metanorma.oeg.

data/lib/metanorma/plugin/lutaml/liquid/custom_filters.rb

@@ -8,6 +8,15 @@ module Metanorma
           def html2adoc(input)
             ReverseAdoc.convert(input)
           end
+
+          def interpolate(input)
+            sub = ::Liquid::Template.parse(input)
+            sub.render(@context)
+          end
+
+          def identify(input)
+            input.split(/(?=[A-Z])/).map(&:downcase).join('-')
+          end
         end
       end
     end

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

@@ -2,7 +2,14 @@
 {% assign package_name = package.name | downcase | replace: ":", "" | replace: " ", "_" %}
 {% if additional_context.before and additional_context.before.size > 0 %}
 {% for before in additional_context.before %}
+{% if before.text %}
+
+{% if before.liquid %}
+{{ before.text | interpolate }}
+{% else %}
 {{ before.text }}
+{% endif %}
+{% endif %}
 {% endfor %}
 {% endif %}
 {% assign is_package_spare = package.name | slice: 0,5 %}
@@ -10,17 +17,56 @@
 {% elsif is_package_spare == 'Spare' %}{% continue %}
 {% endif %}
 
-{% capture equalsigns %}{% for count in (1..depth) %}={% endfor %}{% endcapture %}
+{% capture equalsigns %}{% for count in (1..depth) %}={% endfor %}{% endcapture %}{{equalsigns}} {{ package.name }} package
+[[section-{{ package.xmi_id }}]]
+{{equalsigns}}= {{ package.name }} overview
+
+{% if additional_context.all_macros.size > 0 %}
+{% assign sorted_all_macros = additional_context.all_macros | where: "position", "before" | sort: 'index' %}
+{% for block in sorted_all_macros %}
+{% case block.type %}
+{% when 'include_block' %}
+{% unless block.package and block.package != package.name %}
+{% 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 %}
 
-[[lutaml-section-{{ package_name }}]]
-{{equalsigns}} {{ package.name }} package
+{% if block.liquid %}
+{{ block.text | interpolate }}
+{% else %}
+{{ block.text }}
+{% endif %}
+{% endif %}
 
-{{equalsigns}}= {{ package.name }} overview
+{{ block_content }}
+{% endunless %}
+{% endunless %}
+{% when 'package_text' %}
+{% unless block.package and block.package != package.name %}
+
+{% if block.liquid %}
+{{ block.text | interpolate }}
+{% else %}
+{{ block.text }}
+{% endif %}
+{% endunless %}
+{% else %}
+{% endcase %}
+{% endfor %}
+{% endif %}
 
 {% 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] %}
+{% if before.text %}
+
+{% if before.liquid %}
+{{ before.text | interpolate }}
+{% else %}
 {{ before.text }}
+{% endif %}
+{% endif %}
 {% endfor %}
 {% endif %}
 {% if additional_context.diagram_include_block %}
@@ -54,8 +100,8 @@
 {% elsif is_klass_spare == 'Spare' %}{% continue %}
 {% endif %}
 {% assign klass_name = klass.name | downcase | replace: ':', '' | replace: ' ', '_' %}
-{% assign klass_xid = klass.xmi_id %}
-.<<tab-P-{{ package_name }}-C-{{ klass_xid }}>> -- Elements of "{{ package.name }}::{{ klass.name }}"
+[[section-{{ klass.xmi_id }}]]
+.Elements of &#8220;{{ package.name }}::{{ klass.name }}&#8221; ({{ klass.stereotype }})
 
 {% endfor %}
 {% for enum in package.enums %}
@@ -64,8 +110,8 @@
 {% elsif is_enum_spare == 'Spare' %}{% continue %}
 {% endif %}
 {% assign enum_name = enum.name | downcase | replace: ':', '' | replace: ' ', '_' %}
-{% assign enum_xid = enum.xmi_id %}
-.<<tab-P-{{ package_name }}-E-{{ enum_xid }}>> -- Elements of "{{ package.name }}::{{ enum.name }}"
+[[section-{{ enum.xmi_id }}]]
+.Elements of &#8220;{{ package.name }}::{{ enum.name }}&#8221; ({{ enum.stereotype }})
 
 {% endfor %}
 {% for data_type in package.data_types %}
@@ -74,8 +120,8 @@
 {% elsif is_data_type_spare == 'Spare' %}{% continue %}
 {% endif %}
 {% assign data_type_name = data_type.name | downcase | replace: ':', '' | replace: ' ', '_' %}
-{% assign data_type_xid = data_type.xmi_id %}
-.<<tab-P-{{ package_name }}-DT-{{ data_type_xid }}>> -- Elements of "{{ package.name }}::{{ data_type.name }}"
+[[section-{{ data_type.xmi_id }}]]
+.Elements of &#8220;{{ package.name }}::{{ data_type.name }}&#8221; ({{ data_type.stereotype }})
 
 {% endfor %}
 
@@ -113,18 +159,65 @@
 {% capture block_content %}{% include block_filename %}{% endcapture %}
 {% unless block_content contains "Liquid error" %}
 {% if block.text %}
+
+{% if block.liquid %}
+{{ block.text | interpolate }}
+{% else %}
 {{ block.text }}
 {% endif %}
+{% endif %}
 {{ block_content }}
 {% endunless %}
 {% endfor %}
 {% endif %}
 
+{% if additional_context.all_macros.size > 0 %}
+{% assign sorted_all_macros = additional_context.all_macros | where: "position", "after" | sort: 'index' %}
+{% for block in sorted_all_macros %}
+{% case block.type %}
+{% when 'include_block' %}
+{% unless block.package and block.package != package.name %}
+{% 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 %}
+
+{% if block.liquid %}
+{{ block.text | interpolate }}
+{% else %}
+{{ block.text }}
+{% endif %}
+{% endif %}
+
+{{ block_content }}
+{% endunless %}
+{% endunless %}
+{% when 'package_text' %}
+{% unless block.package and block.package != package.name %}
+
+{% if block.liquid %}
+{{ block.text | interpolate }}
+{% else %}
+{{ block.text }}
+{% endif %}
+{% endunless %}
+{% else %}
+{% endcase %}
+{% endfor %}
+{% endif %}
+
 {% assign after_package_key = 'after;' | append: package.name %}
 {% if additional_context[after_package_key] %}
 {{equalsigns}}= Additional information
 {% for after in additional_context[after_package_key] %}
+{% if after.text %}
+
+{% if after.liquid %}
+{{ after.text | interpolate }}
+{% else %}
 {{ after.text }}
+{% endif %}
+{% endif %}
 {% endfor %}
 {% endif %}
 {% if package.packages.size > 0 and render_nested_packages %}
@@ -134,6 +227,13 @@
 
 {% if additional_context.after and additional_context.after.size > 0 %}
 {% for after in additional_context.after %}
+{% if after.text %}
+
+{% if after.liquid %}
+{{ after.text | interpolate }}
+{% else %}
 {{ after.text }}
+{% endif %}
+{% endif %}
 {% endfor %}
 {% endif %}

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

@@ -3,9 +3,8 @@
 {% elsif is_klass_spare == 'Spare' %}{% continue %}
 {% endif %}
 {% assign klass_name = klass.name | downcase | replace: ':', '' | replace: ' ', '_' %}
-{% assign klass_xid = klass.xmi_id %}
-[[tab-P-{{ package_name }}-C-{{ klass_xid }}]]
-.Elements of "{{ package.name }}::{{ klass.name }}" (class)
+[[section-{{ klass.xmi_id }}]]
+.Elements of “{{ package.name }}::{{ klass.name }}” ({{ klass.stereotype }})
 [width="100%",cols="a,a,a,a,a,a,a,a"]
 |===
 
@@ -70,8 +69,8 @@ h| Public attributes:
 
 {% if klass.constraints.size > 0 %}
 .{{ klass.constraints.size }}+h| Constraints:
-{% for constr in klass.constraints %}
-7+| `{{ constr.body }}`
+{% for constraint in klass.constraints %}
+7+| `{{ constraint.body }}`: `{{ constraint.definition | replace: '|', '\|' }}`
 
 {% endfor %}
 {% else %}