metanorma-plugin-lutaml 0.7.34 → 0.7.35

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bdcd6f308c7b6b9aedf946aaf6c83524cc53fe0d861376b2f27488bdc66f03ea
-  data.tar.gz: 950763731a5d2712b15ae1f98fd06f173ffbab4e520243a8474ef652839455b5
+  metadata.gz: 0bfc071fedc2ba0801f8c50024ffd3e4370b356b0d78991cb9ae776b749ee4fc
+  data.tar.gz: 1badb8034821908be57039d87755a3937a8b93bc63c22f9b99d87344c57a4ed9
 SHA512:
-  metadata.gz: c7f843aa5286d1b952437b330749ade1854e510a33f2ec100e7a384c3049838f60fb099339c23c66ef54cad12c862ca29c7e5138eca3a8306ed326ba9e55e615
-  data.tar.gz: fbb5cbe113944fb2106143b8ad653dd39daca164df59b99b2564292132cd3b29c634c939589c4ce8de303aad30d9316b9e943ef6c3b90d3a71ff3258b60745fd
+  metadata.gz: ed2e7d2becf9296bff55b12a2c29aae7d7875ab4b1972ec76b6aa364aefb5b836bbc80fe1e201bb6f5eec3347b530c555cc8e9c70f7a6ed7e6bd5ef4e649a2fe
+  data.tar.gz: 2632e92cc22255166f2e32fb8492244f75b85582dc35919ac0deff75c360a4f6d5316de2cb68f9b683505dae9034c2d029b37f87cb730c6c6327a0407b5a6f06

data/docs/usages/enterprise_architect.adoc

@@ -12,7 +12,7 @@ Enterprise Architect XMI files.
 
 === Document attribute `:lutaml-xmi-index:`
 
-This attribute allows specifying one or more XMI files to defined names
+This attribute allows specifying one or more XMI files to define names
 for later use with `lutaml_ea_*` commands.
 
 Syntax:
@@ -56,10 +56,10 @@ The command `lutaml_ea_diagram` will load the XMI file from the path
 ====
 
 
-=== Rendering a Enterprise Architect diagram from XMI: `lutaml_ea_diagram`
+=== Rendering an Enterprise Architect diagram from XMI: `lutaml_ea_diagram`
 
-This command allows to quickly render a LutaML diagram as an image file by
-specifying the name of diagram.
+This command allows you to quickly render a LutaML diagram as an image file by
+specifying the name of the diagram.
 
 Syntax:
 
@@ -110,7 +110,7 @@ where the EA images exported with the XMI file are at `/path/to/xmi-images`.
 lutaml_ea_diagram::[name="DiagramName",package="PackageA",base_path="/path/to/xmi-images"]
 ----
 
-The search wil be restricted to the diagrams named `DiagramName` in the
+The search will be restricted to the diagrams named `DiagramName` in the
 `PackageA` package.
 ====
 
@@ -135,7 +135,7 @@ the XMI file defined in the index `index_name`.
 
 === Generating a class definition table for a class: `lutaml_klass_table`
 
-This command allows to render a LutaML table of a class by using Liquid Drop.
+This command allows you to render a LutaML table of a class by using Liquid Drop.
 
 The table will show:
 
@@ -153,27 +153,27 @@ lutaml_klass_table::/path/to/example.xmi[name="NameOfClass",template="/path/to/t
 
 The command accepts the options listed below:
 
-* `/path/to/example.xmi` specifies the path of xmi file.
+* `/path/to/example.xmi` specifies the path of the 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
+   If there are multiple classes with the same name, other forms of options
    are recommended to specify the class.
 
-** `package="NameOfPackage"name="NameOfClass"` specifies the name of the
+** `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 `::`
+   which starts 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 `::`
+   or `relative` path of the `class` which does not start 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`.
@@ -208,19 +208,50 @@ under `classes`.  Then define which `attributes` you want to add guidance by the
 guidance in `guidance`.
 
 
+=== Generating a definition table for an enumeration: `lutaml_enum_table`
+
+This command allows you to render a LutaML table of a class by using Liquid Drop.
+
+The table will show:
+
+* Enumeration Name
+* Enumeration Definition
+* Subtype of superclass
+* Enumeration Stereotype
+* Enumeration Values
+** Code
+** Value
+** Definition
+
+[source,adoc]
+----
+lutaml_enum_table::/path/to/example.xmi[name="NameOfEnum",template="/path/to/templates/_my_enum_table.liquid"]
+----
+
+The command accepts the options listed below:
+
+* `/path/to/example.xmi` specifies the path of the XMI file.
+
+* `name` of the name of the enumeration.
+
+* `template="/path/to/templates/_my_enum_table.liquid"` specifies the path of
+  the liquid template. (Optional)
+  By default, it will look for the template `_enum_table.liquid` defined in
+  `lib/metanorma/plugin/lutaml/templates`.  This template can be customized by
+  changing the template path in the `template` option.
 
 
 === Usage of `lutaml_ea_xmi` command
 
-The `lutaml_ea_xmi` command supersedes the `lutaml_uml_datamodel_description`
-command which it is functionally equivalent to.
+The `lutaml_ea_xmi` command performs the same function as the
+`lutaml_uml_datamodel_description` command starting from version 0.7.21.
 
-This command renders data model packages and its dependent objects for supplied
+This command renders data model packages and their dependent objects for the supplied
 XMI file, by using Liquid Drop objects.
 
 NOTE: The performance of `lutaml_ea_xmi` exceeds
-`lutaml_uml_datamodel_description` by 10~20 times (Tested with a 10.6MB XMI file
-with 120,000+ lines).
+`lutaml_uml_datamodel_description` by 10~20 times when tested with a 10.6MB XMI
+file with 120,000+ lines using version 0.7.20 of the plugin.
 
 NOTE: To migrate to this command from `lutaml_uml_datamodel_description`, just
 replace the command `lutaml_uml_datamodel_description` by `lutaml_ea_xmi`.
@@ -242,7 +273,7 @@ By:
 ----
 
 You can define guidance in the configuration file as well. The configuration
-file will looks like:
+file will look like:
 
 [source,yaml]
 ----
@@ -271,7 +302,7 @@ 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:
+The `name` of the class can be defined in the following ways:
 
 * `name: "NameOfClass"` specifies the name of the `class`.
   (e.g. `name: "Building"`)
@@ -285,8 +316,8 @@ The `name` of class can be defined in the following ways:
 
 === Usage of `lutaml_uml_datamodel_description` command
 
-This command allows to quickly render data model packages and its dependent
-objects for supplied XMI file.
+This command allows you to quickly render data model packages and their dependent
+objects for the supplied XMI file.
 
 Given an Enterprise Architect `example.xmi` file with 2 packages:
 
@@ -346,17 +377,17 @@ 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 command 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 the command will overwrite text, note that `literal` block style must be used there (e.g. `....`)
 
-* `[.after]` - block text that adds additional text after the rendered output, can be used only once, additional occurrences of command will overwrite text
+* `[.after]` - block text that adds additional text after the rendered output, can be used only once, additional occurrences of the command will overwrite text
 
-* `[.after, package="Another"]` - block text to be inserted before(after in case of `.before` name) the package
+* `[.after, package="Another"]` - block text to be inserted after the package (before in case of `.before` name)
 
-* `[.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, position="after", package="Another"]` - include custom adoc code into the package rendered body, `position` is 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
+* `[.package_text, package="Another"]` - same as above, but the include block will be included only for the 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.
+* `[.diagram_include_block]` - block text to automatically include diagram images. Attribute `base_path` is a required attribute to supply the path prefix where to look for a diagram image. `format` is an optional attribute that tells what file extension to use when including the diagram file.
 +
 The logic is as follows:
 [source,adoc]
@@ -372,16 +403,16 @@ image::{{ image_base_path }}/{{ diagram.xmi_id }}.{{ format | default: 'png' }}[
 {% endfor %}
 ----
 
-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 command 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 the diagram's xmi_id attribute plus `.png`. Also one can add any text to the command 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
+* `[.diagram_include_block, package="Another"]` - same as above, but the diagram will be included only for the supplied package name
 
-* `[.include_block, base_path="spec/fixtures"]` - command 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. command 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`, command will look for the following file path: `my/path/_my_package_name.adoc`.
+* `[.include_block, base_path="spec/fixtures"]` - command to include files (`*.adoc` or `*.liquid`) for each package name. Attribute `base_path` is a required attribute to supply the path prefix where to look for file to include. The command will look for a file called `base_path` + `/` `_package_name`(downcase, replace : -> '', ' ' -> '_') + `.adoc`[`.liquid`], e.g. for package 'My Package name' and `base_path` eq to `my/path`, the command 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
+* `[.include_block, package="Another", base_path="spec/fixtures"]` - same as above, but the include block will be included only for the supplied package name
 
 
-NOTE: .after, .before, package_text and include_block commandses all can be used with additional option - `liquid`, if this option is supplied then the code inside block will be interpolated in liquid context
+NOTE: .after, .before, package_text and include_block commands all can be used with additional option - `liquid`, if this option is supplied then the code inside block will be interpolated in liquid context
 
 
 === Referencing objects generated by LutaML
@@ -410,7 +441,7 @@ This is lutaml_table::[package="Wrapper root package", enum="my name"] enumerati
 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 command when document rendered `lutaml_uml_datamodel_description` command as it needs diagram lookup table in order to reference package diagram.
+This code will be transformed into `<<figure-{diagram.xmi_id}>>` and will point to diagram figure. One can only use this command when the document has rendered `lutaml_uml_datamodel_description` command as it needs diagram lookup table in order to reference package diagram.
 
 Will produce this output:
 
@@ -514,6 +545,8 @@ packages:
   - skip: four
 render_style: entity_list | data_dictionary | default
 section_depth: 2
+template_path: "path/to/custom/liquid/templates"
+skip_unrecognized_connector: true
 ea_extension:
   - "CityGML_MDG_Technology.xml"
   - "xmi_definition_for_some_standard.xml"
@@ -559,6 +592,32 @@ equal to 2, root package will be `one-1`.
 ]
 ----
 
+* `template_path` - optional, path to custom Liquid templates directory for
+rendering the output. When specified, the processor will use custom templates
+from this directory instead of the default built-in templates. This allows for
+complete customization of the rendered output format and structure.
+
+* `skip_unrecognized_connector` - optional, boolean flag that shows in liquid
+templates as context variable `context.skip_unrecognized_connector`, which
+allows to control whether the associations with unrecognized connectors should
+be included in the output.  By making use of this context variable and
+`association.connector.recognized?` in the liquid templates, you can
+conditionally skip rendering of associations that have unrecognized connectors.
++
+EXAMPLE: Given that `associations` is a list of association objects of a class
+named `klass`, if you want to skip rendering of associations that have
+unrecognized connectors when `skip_unrecognized_connector` is set to `true`,
+then in the liquid template you can use:
++
+[source,liquid]
+----
+{% for assoc in klass.associations %}
+{% if context.skip_unrecognized_connector != true or assoc.connector.recognized? == true %}
+...do something with association that has recognized connector...
+{% endif %}
+{% endfor %}
+----
+
 * `ea_extension` - optional, list of EA extensions to load. Some XMI files may
 contain elements that cannot be resolved by default, for example CityGML
 elements.  You can use `ea_extension` to load the definition of these elements
@@ -579,5 +638,5 @@ Usage with command:
 
 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
+packages that match `skip` in the YAML config file will be skipped during
 render.

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

@@ -0,0 +1,24 @@
+{% capture enum_stereotype -%}«{{ enum.stereotype }}»{%- endcapture -%}
+{%- if enum_stereotype == "«»" -%}
+  {%- assign enum_stereotype = " " -%}
+{%- endif %}
+
+[cols="29,195,535"]
+|===
+3+^h| Enumeration: {{ enum.name }}
+3+| Definition: {{ enum.definition }}
+3+| Subtype of: {{ enum.upper_packaged_element }}
+3+| Stereotypes: {{ enum_stereotype }}
+
+{% if enum.values.size > 0 %}
+{% assign code_num = 0 %}
+
+h| Code h| Value h| Definition
+
+{% for value in enum.values %}
+{% assign code_num = code_num | plus: 1 %}
+| {{ code_num }} | {{ value.name }} | {{ value.definition }}
+{% endfor %}
+
+{% endif %}
+|===

data/lib/metanorma/plugin/lutaml/lutaml_enum_table_block_macro.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Plugin
+    module Lutaml
+      class LutamlEnumTableBlockMacro <
+        ::Asciidoctor::Extensions::BlockMacroProcessor
+        include LutamlEaXmiBase
+
+        DEFAULT_TEMPLATE = File.join(
+          Gem::Specification.find_by_name("metanorma-plugin-lutaml").gem_dir,
+          "lib", "metanorma", "plugin", "lutaml", "liquid_templates",
+          "_enum_table.liquid"
+        )
+
+        use_dsl
+        named :lutaml_enum_table
+
+        def process(parent, target, attrs) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+          xmi_path = get_xmi_path(parent, target, attrs)
+
+          if attrs["template"]
+            attrs["template"] = Utils.relative_file_path(
+              parent.document, attrs["template"]
+            )
+          end
+
+          path = if !attrs["path"].nil?
+                   attrs["path"]
+                 elsif !attrs["package"].nil? && !attrs["name"].nil?
+                   "#{attrs['package']}::#{attrs['name']}"
+                 else
+                   attrs["name"]
+                 end
+
+          enum = ::Lutaml::XMI::Parsers::XML.serialize_enumeration_by_name(
+            xmi_path, path
+          )
+
+          render(enum, parent, attrs)
+        end
+
+        private
+
+        def render(enum, parent, attrs)
+          rendered_table = render_table(enum, parent, attrs)
+
+          block = create_open_block(parent, "", attrs)
+          parse_content(block, rendered_table, attrs)
+        end
+
+        def render_table(enum, parent, attrs)
+          table_tmpl = get_template(parent.document, attrs)
+          table_tmpl.assigns["enum"] = enum
+          table_tmpl.render
+        end
+
+        def get_template(document, attrs)
+          template = DEFAULT_TEMPLATE
+          if attrs["template"]
+            template = attrs["template"]
+          end
+
+          rel_tmpl_path = Utils.relative_file_path(
+            document, template
+          )
+
+          ::Liquid::Template.parse(File.read(rel_tmpl_path))
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/plugin/lutaml/version.rb

@@ -1,7 +1,7 @@
 module Metanorma
   module Plugin
     module Lutaml
-      VERSION = "0.7.34".freeze
+      VERSION = "0.7.35".freeze
     end
   end
 end

data/lib/metanorma-plugin-lutaml.rb

@@ -15,6 +15,7 @@ require "metanorma/plugin/lutaml/lutaml_gml_dictionary_base"
 require "metanorma/plugin/lutaml/lutaml_gml_dictionary_block_macro"
 require "metanorma/plugin/lutaml/lutaml_gml_dictionary_block"
 require "metanorma/plugin/lutaml/lutaml_klass_table_block_macro"
+require "metanorma/plugin/lutaml/lutaml_enum_table_block_macro"
 
 module Metanorma
   module Plugin

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: metanorma-plugin-lutaml
 version: !ruby/object:Gem::Version
-  version: 0.7.34
+  version: 0.7.35
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-07-02 00:00:00.000000000 Z
+date: 2025-08-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor
@@ -170,6 +170,7 @@ files:
 - lib/metanorma/plugin/lutaml/liquid_drops/gml_dictionary_drop.rb
 - lib/metanorma/plugin/lutaml/liquid_drops/gml_dictionary_entry_drop.rb
 - lib/metanorma/plugin/lutaml/liquid_templates/_diagrams_block.liquid
+- lib/metanorma/plugin/lutaml/liquid_templates/_enum_table.liquid
 - lib/metanorma/plugin/lutaml/liquid_templates/_klass_table.liquid
 - lib/metanorma/plugin/lutaml/liquid_templates/_packages.liquid
 - lib/metanorma/plugin/lutaml/liquid_templates/_packages_class.liquid
@@ -187,6 +188,7 @@ files:
 - lib/metanorma/plugin/lutaml/lutaml_ea_diagram_block_macro.rb
 - lib/metanorma/plugin/lutaml/lutaml_ea_xmi_base.rb
 - lib/metanorma/plugin/lutaml/lutaml_ea_xmi_preprocessor.rb
+- lib/metanorma/plugin/lutaml/lutaml_enum_table_block_macro.rb
 - lib/metanorma/plugin/lutaml/lutaml_figure_inline_macro.rb
 - lib/metanorma/plugin/lutaml/lutaml_gml_dictionary_base.rb
 - lib/metanorma/plugin/lutaml/lutaml_gml_dictionary_block.rb