metanorma-plugin-lutaml 0.4.9 → 0.4.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7be44107e7c1d3c9a4471ead7d39630d49cdced1e3996b6bea8b3c64be4fd03f
-  data.tar.gz: b99ff8fa3069c0fb0f983de14a984c06db12ecc595e0b876ed83e83926c6eeba
+  metadata.gz: 241b12b07d457ea48176e22ce2cacc4a533c2ffc5435465637d51d37d6da1e80
+  data.tar.gz: 2a2bd1fe63f4febdae9ce40679f525cfe476f2a773ab15c5de9622145dbdbd7f
 SHA512:
-  metadata.gz: 2e6d79ef550cecde85e2e0d49717259f6e9016ef7e3935fdb938d13173361daf404e586a1d1319b05a1ab4a393213086625399d5d3e1090a4afd902c0bfc3f82
-  data.tar.gz: 454fe356b82f983a2a4ed9b2a1fa81de19ea8dcb6ac0c10243f1afc8db8e2eed8b8600658c7f0e37040224401dae077a0f93e433227b31c9dd63c7119c59db5f
+  metadata.gz: 33ef546ecbc2929104ccda434021ef50afbd067d5f466b7d07181aea92415a15aaad67fdf3848b4bd0cf93878e032b007b437a630b1d5ea87398396b446b622f
+  data.tar.gz: 7373d126f78af6063dbfea6076018712f4185a6c0e75e50309befc23bf1e34beeec86ab80d8b36f9c73eb7e5ae238b0522e85ec307ee434538222790cc05d8c3

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,15 +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 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:
+
+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"] enum
-This is lutaml_table::[package="Wrapper root package", data_type="my name"] data_type
+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.
@@ -466,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
@@ -481,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:
 
@@ -509,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 %}
@@ -14,10 +21,52 @@
 [[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 %}
+
+{% 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 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 %}
@@ -51,7 +100,8 @@
 {% elsif is_klass_spare == 'Spare' %}{% continue %}
 {% endif %}
 {% assign klass_name = klass.name | downcase | replace: ':', '' | replace: ' ', '_' %}
-.<<section-{{ klass.xmi_id }}>> -- &#8220;Elements of {{ package.name }}::{{ klass.name }}&#8221; (class)
+[[section-{{ klass.xmi_id }}]]
+.Elements of &#8220;{{ package.name }}::{{ klass.name }}&#8221; ({{ klass.stereotype }})
 
 {% endfor %}
 {% for enum in package.enums %}
@@ -60,7 +110,8 @@
 {% elsif is_enum_spare == 'Spare' %}{% continue %}
 {% endif %}
 {% assign enum_name = enum.name | downcase | replace: ':', '' | replace: ' ', '_' %}
-.<<section-{{ enum.xmi_id }}>> -- &#8220;Elements of {{ package.name }}::{{ enum.name }}&#8221; (enum)
+[[section-{{ enum.xmi_id }}]]
+.Elements of &#8220;{{ package.name }}::{{ enum.name }}&#8221; ({{ enum.stereotype }})
 
 {% endfor %}
 {% for data_type in package.data_types %}
@@ -69,7 +120,8 @@
 {% elsif is_data_type_spare == 'Spare' %}{% continue %}
 {% endif %}
 {% assign data_type_name = data_type.name | downcase | replace: ':', '' | replace: ' ', '_' %}
-.<<section-{{ data_type.xmi_id }}>> -- &#8220;Elements of {{ package.name }}::{{ data_type.name }}&#8221; (data_type)
+[[section-{{ data_type.xmi_id }}]]
+.Elements of &#8220;{{ package.name }}::{{ data_type.name }}&#8221; ({{ data_type.stereotype }})
 
 {% endfor %}
 
@@ -107,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 %}
@@ -128,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 %}