metanorma-plugin-lutaml 0.7.46 → 0.7.49

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a35215ee0b1f56e7a7b8896e512da9fb7aa190244988efa0b173bf72ed84202c
-  data.tar.gz: ee445b71760e111e26896f30559e35d4b8ea86a03cc20c0c000aebd7c43debb7
+  metadata.gz: 7f35e27d23b6509b4a0ddb778d7e5706782a8f6b3a8a3d08de0488b2ff74aea6
+  data.tar.gz: 9d72a1aa1bc17a5375e15fa9d1575e21409714a28d6a5a2ca3516426a510ad95
 SHA512:
-  metadata.gz: 9ff29f6c04bd2483e359b5bb3bc3e0e9bfbb1254df12aed87453ab05b7e6f329583d80be38113dedc9aa6e18e71871a1869fc74e85c0b236bf069176e81de886
-  data.tar.gz: 9027e9b86616da94c0cd7144858f6ae01de440fc20a18aeb4d2e2a600a19ac37464d1d8fae2a1244e398e96f0502a876e9e306334e0598c0b0e3d53160cc40b5
+  metadata.gz: 1eea2b10a5361287562e4c082fa96b2f94cafc97e54dcdb47e758ff4b0973fae4270a2d6099720eb7d98d85dd8da92b74f4137891924fa39ef89737ce702ffab
+  data.tar.gz: ffb1271076d8dab3211f552d123aad3bb76e908230fdcacb40b28e1ded86075f0b1f7b744d8ec3769030c8f2f04094f6c0f5687ba4dbfbb165261792bf194cbf

data/.github/workflows/release.yml

@@ -19,6 +19,9 @@ jobs:
     uses: metanorma/ci/.github/workflows/rubygems-release.yml@main
     with:
       next_version: ${{ github.event.inputs.next_version }}
+      release_command: |
+        bundle install
+        bundle exec rake release
     secrets:
       rubygems-api-key: ${{ secrets.METANORMA_CI_RUBYGEMS_API_KEY }}
       pat_token: ${{ secrets.METANORMA_CI_PAT_TOKEN }}

data/README.adoc

@@ -12,6 +12,8 @@ within a Metanorma document:
 * EXPRESS files (`*.exp`)
 * LutaML-UML files (`*.lutaml`)
 * Enterprise Architect exported UML files in XMI format (`*.xmi`)
+* Enterprise Architect QEA files (`*.qea`)
+* Enterprise Architect LUR files (`*.lur`)
 * LutaML GML Dictionary files (`*.xml`)
 * JSON or YAML files (`*.json|*.yml|*.yaml`)
 * XML Schema files (`*.xsd`)
@@ -31,6 +33,8 @@ link:docs/usages/lutaml-uml.adoc[Usage with LutaML files by lutaml_diagram]
 
 link:docs/usages/enterprise_architect.adoc[Usage with Enterprise Architect XMI files by lutaml_ea_xmi, lutaml_ea_diagram, lutaml_klass_table or lutaml_enum_table]
 
+link:docs/usages/enterprise_architect_uml.adoc[Usage with Enterprise Architect UML files (XMI, QEA, LUR) by lutaml_ea_uml]
+
 link:docs/usages/lutaml-gml.adoc[Usage with LutaML GML Dictionary by lutaml_gml_dictionary]
 
 link:docs/usages/json_yaml.adoc[Usage with JSON or YAML files by data2text, yaml2text or json2text]

data/docs/usages/enterprise_architect_uml.adoc

@@ -0,0 +1,173 @@
+
+== Usage with Enterprise Architect UML files (XMI, QEA, LUR) by lutaml_ea_uml
+
+=== General
+
+The `lutaml_ea_uml` command renders UML data models from Enterprise Architect
+files using custom Liquid templates. It supports three file formats:
+
+* XMI (`*.xmi`) -- Enterprise Architect XML Metadata Interchange export
+* QEA (`*.qea`) -- Enterprise Architect native database format
+* LUR (`*.lur`) -- Enterprise Architect model exchange format
+
+The command parses the file into a Liquid template context, allowing full
+control over the rendered output through custom Liquid templates.
+
+
+=== Basic usage
+
+[source,adoc]
+----
+[lutaml_ea_uml,path/to/example.xmi]
+--
+Name of the Lutaml UML Document: {{ context.name }}
+
+Number of packages: {{ context.packages | size }}
+--
+----
+
+Where:
+
+* `path/to/example.xmi` -- path to the XMI, QEA, or LUR file to render.
+
+The content between `--` delimiters is a Liquid template. The parsed UML
+document is available as `context` by default.
+
+
+=== Usage with a configuration file
+
+[source,adoc]
+----
+[lutaml_ea_uml,path/to/example.xmi,path/to/config.yml]
+--
+Name of the Lutaml UML Document: {{ my_uml_document.name }}
+
+Number of packages: {{ my_uml_document.packages | size }}
+
+{% render "package", package: my_uml_document.packages.first %}
+--
+----
+
+Where:
+
+* `path/to/example.xmi` -- path to the XMI, QEA, or LUR file.
+* `path/to/config.yml` -- path to the YAML configuration file.
+
+
+=== Configuration file format
+
+[source,yaml]
+----
+---
+ea_extension:
+  - "CityGML_MDG_Technology.xml"
+  - "ISO19103MDG v1.0.0-beta.xml"
+context_name: my_uml_document
+template_path: "path/to/liquid/templates"
+guidance: "path/to/guidance.yml"
+----
+
+Where:
+
+* `ea_extension` -- optional, list of EA extension XML files to load. Some
+  XMI/QEA/LUR files contain elements that cannot be resolved by default (e.g.
+  CityGML elements). Load their definitions here. Paths are relative to the
+  config YAML file.
+
+* `context_name` -- optional, the Liquid context variable name for the parsed
+  document. Defaults to `context`. When set, the document is accessible as
+  `{{ my_uml_document }}` instead of `{{ context }}`.
+
+* `template_path` -- optional, path to a directory containing custom Liquid
+  templates. When specified, `render` tags in the block content will use
+  templates from this directory.
+
+* `guidance` -- optional, path to a YAML guidance file for adding annotations
+  to rendered output.
+
+
+=== Usage with document index
+
+You can define an XMI/QEA/LUR file index at the document level and reference
+it by name:
+
+[source,adoc]
+----
+:lutaml-xmi-index: my-model; /path/to/example.qea
+
+[lutaml_ea_uml,index=my-model]
+--
+Name: {{ context.name }}
+--
+----
+
+Syntax for the index attribute:
+
+[source,adoc]
+----
+:lutaml-xmi-index: index_name; file_path[; config=config_path]
+----
+
+Where:
+
+* `index_name` -- name to reference later with `index=`.
+* `file_path` -- path to the XMI, QEA, or LUR file.
+* `config_path` -- optional, path to the configuration YAML file.
+
+
+=== Liquid template context
+
+The parsed UML document is exposed to Liquid templates with the following
+structure:
+
+* `context.name` -- name of the root UML model.
+* `context.packages` -- array of packages in the model.
+* `context.packages.first.name` -- name of a package.
+* `context.packages.first.packages` -- nested sub-packages.
+* `context.packages.first.classes` -- array of classes in a package.
+* `context.packages.first.classes.first.name` -- name of a class.
+* `context.packages.first.classes.first.attributes` -- array of attributes.
+* `context.packages.first.classes.first.associations` -- array of associations.
+
+When `context_name` is set in the configuration, replace `context` with the
+configured name (e.g. `my_uml_document`).
+
+
+=== Example: rendering class tables with a custom template
+
+Given a custom template at `templates/_klass.liquid`:
+
+[source,liquid]
+----
+{% for package in context.packages %}
+== {{ package.name }}
+
+{% for klass in package.classes %}
+=== {{ klass.name }}
+
+{{ klass.definition | html2adoc }}
+
+[cols="a,a"]
+|===
+| Attribute | Type
+
+{% for attr in klass.owned_props %}
+| {{ attr.name }} | {{ attr.type }}
+{% endfor %}
+
+|===
+{% endfor %}
+{% endfor %}
+----
+
+The AsciiDoc block would be:
+
+[source,adoc]
+----
+[lutaml_ea_uml,path/to/example.xmi,path/to/config.yml]
+--
+{% render "klass", context: context %}
+--
+----
+
+Where the config specifies `template_path` pointing to the templates directory.

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

@@ -171,7 +171,7 @@ module Metanorma
             )
             parsed_template.assigns["schemas_order"] =
               options["selected_schemas"]
-            parsed_template.render.split("\n", -1)
+            parsed_template.render
           end.flatten
         rescue StandardError => e
           ::Metanorma::Util.log(

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

@@ -33,7 +33,7 @@ module Metanorma
           )
         end
 
-        def get_original_document(parent, index = nil)
+        def get_original_document(parent, index = nil) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity
           path = get_path_from_index(parent, index) if index
 
           if index && path
@@ -43,11 +43,27 @@ module Metanorma
             )
           end
 
-          first_path = parent.document.attributes["lutaml_xmi_paths"]&.first
-          return unless first_path
+          # get the first document from lutaml_xmi_cache
+          first_path = parent
+            .document.attributes["lutaml_xmi_cache"]&.keys&.first
+          if first_path
+            return lutaml_document_from_file_or_cache(
+              parent.document, first_path,
+              Metanorma::Plugin::Lutaml::Config::Root.new
+            )
+          end
+
+          # get the first document from the first lutaml_xmi_index
+          first_index = parent
+            .document.attributes["lutaml_xmi_index"]&.keys&.first
+
+          return unless first_index
+
+          path_from_index = get_path_from_index(parent, first_index)
+          return unless path_from_index
 
           lutaml_document_from_file_or_cache(
-            parent.document, first_path,
+            parent.document, path_from_index,
             Metanorma::Plugin::Lutaml::Config::Root.new
           )
         end

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "liquid"
+require "asciidoctor"
+require "asciidoctor/reader"
+require "lutaml"
+require_relative "utils"
+require "metanorma/plugin/lutaml/asciidoctor/preprocessor"
+require "metanorma/plugin/lutaml/lutaml_ea_xmi_base"
+
+module Metanorma
+  module Plugin
+    module Lutaml
+      #  Macro for rendering Lutaml::Uml models which are parsing from
+      #  XMI/QEA/LUR file
+      class LutamlEaUmlPreprocessor < ::Asciidoctor::Extensions::Preprocessor
+        include LutamlEaXmiBase
+
+        MACRO_REGEXP = /\[lutaml_ea_uml,([^,]+),?(.+)?\]/
+
+        private
+
+        def parse_result_document(full_path, _guidance)
+          case File.extname(full_path).downcase
+          when ".xmi"
+            ::Lutaml::Xmi::Parsers::Xml.parse(full_path)
+          when ".qea"
+            ::Lutaml::Qea.parse(full_path)
+          when ".lur"
+            repo = ::Lutaml::UmlRepository::Repository.from_file(full_path)
+            repo.document
+          end
+        end
+
+        def process_text_blocks(document, input_lines) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+          line = input_lines.next
+
+          process_xmi_index_lines(document, line)
+          block_match = line.match(get_macro_regexp)
+
+          return [line] if block_match.nil?
+
+          config_yaml_path = block_match[2]&.strip
+          filepath_or_index = block_match[1]&.strip
+
+          lutaml_document, yaml_config = load_lutaml_doc_and_config(
+            document,
+            filepath_or_index,
+            config_yaml_path,
+          )
+
+          block_lines = collect_block_lines(input_lines, input_lines.next)
+
+          render_result, errors = Utils.render_liquid_string(
+            template_string: block_lines.join("\n"),
+            contexts: create_default_context_object(
+              lutaml_document, yaml_config
+            ),
+            document: document,
+            include_path: template_path(document, yaml_config.template_path),
+          )
+          Utils.notify_render_errors(document, errors)
+
+          render_result.split("\n")
+        end
+
+        def create_default_context_object(uml_document, options)
+          context_name = "context"
+          if options.context_name
+            context_name = options.context_name
+          end
+          contexts = {}
+          contexts[context_name] = uml_document.to_liquid
+          contexts
+        end
+      end
+    end
+  end
+end

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

@@ -39,6 +39,61 @@ module Metanorma
 
         private
 
+        def lutaml_document_from_file_or_cache(document, file_path, yaml_config, yaml_config_path = nil) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength,Metrics/CyclomaticComplexity,Layout/LineLength,Metrics/PerceivedComplexity
+          full_path = Utils.relative_file_path(document, file_path)
+          if document.attributes["lutaml_xmi_cache"] &&
+              document.attributes["lutaml_xmi_cache"][full_path]
+            return document.attributes["lutaml_xmi_cache"][full_path]
+          end
+
+          guidance = get_guidance(document, yaml_config.guidance)
+          result_document = parse_result_document(full_path, guidance)
+
+          # load EA extensions for Xmi::EaRoot
+          yaml_config.ea_extension&.each do |ea_extension_path|
+            # resolve paths of ea extensions based on the location of
+            # config yaml file
+            ea_extension_full_path = File.expand_path(
+              ea_extension_path, File.dirname(yaml_config_path)
+            )
+
+            # unload the extension if it is already loaded
+            xmi_doc = Nokogiri::XML(File.read(ea_extension_full_path))
+            extension_id = Xmi::EaRoot.get_module_name(xmi_doc)
+            if Xmi::EaRoot.extension_loaded?(extension_id)
+              Xmi::EaRoot.unload_extension(extension_id)
+            end
+
+            Xmi::EaRoot.load_extension(ea_extension_full_path)
+          end
+
+          # store in document.attributes as cache
+          document.attributes["lutaml_xmi_cache"] ||= {}
+          document.attributes["lutaml_xmi_cache"][full_path] = result_document
+
+          result_document
+        end
+
+        def get_guidance(document, guidance_config)
+          return unless guidance_config
+
+          guidance_yaml = Utils.relative_file_path(document, guidance_config)
+          guidance = Metanorma::Plugin::Lutaml::Config::Guidance.from_yaml(
+            File.read(guidance_yaml, encoding: "UTF-8"),
+          )
+          guidance.to_yaml_hash
+        end
+
+        def parse_yaml_config_file(document, file_path)
+          return Metanorma::Plugin::Lutaml::Config::Root.new if file_path.nil?
+
+          relative_file_path = Utils.relative_file_path(document, file_path)
+
+          Metanorma::Plugin::Lutaml::Config::Root.from_yaml(
+            File.read(relative_file_path, encoding: "UTF-8"),
+          )
+        end
+
         def get_xmi_path(parent, target, attrs)
           return get_path_from_index(parent, attrs["index"]) if attrs["index"]
 
@@ -106,8 +161,8 @@ module Metanorma
           )
         end
 
-        def load_lutaml_doc_and_config(document, xmi_or_index, config_yaml_path) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
-          index = xmi_or_index.match(/index=(.*)/)
+        def load_lutaml_doc_and_config(document, filepath_or_index, config_yaml_path) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength,Layout/LineLength
+          index = filepath_or_index.match(/index=(.*)/)
 
           if index
             index_name = index[1]
@@ -121,7 +176,7 @@ module Metanorma
               )
             end
 
-            xmi_or_index = document
+            filepath_or_index = document
               .attributes["lutaml_xmi_index"][index_name][:path]
             config_yaml_path = document
               .attributes["lutaml_xmi_index"][index_name][:config]
@@ -130,7 +185,7 @@ module Metanorma
           yaml_config = parse_yaml_config_file(document, config_yaml_path)
           lutaml_document = lutaml_document_from_file_or_cache(
             document,
-            xmi_or_index,
+            filepath_or_index,
             yaml_config,
             Utils.relative_file_path(document, config_yaml_path),
           )

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

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

data/lib/metanorma-plugin-lutaml.rb

@@ -55,6 +55,8 @@ module Metanorma
                "lutaml_uml_datamodel_description_preprocessor"
       autoload :LutamlXmiUmlPreprocessor,
                "metanorma/plugin/lutaml/lutaml_xmi_uml_preprocessor"
+      autoload :LutamlEaUmlPreprocessor,
+               "metanorma/plugin/lutaml/lutaml_ea_uml_preprocessor"
       autoload :LutamlXsdPreprocessor,
                "metanorma/plugin/lutaml/lutaml_xsd_preprocessor"
       autoload :ParseError, "metanorma/plugin/lutaml/parse_error"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: metanorma-plugin-lutaml
 version: !ruby/object:Gem::Version
-  version: 0.7.46
+  version: 0.7.49
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-20 00:00:00.000000000 Z
+date: 2026-06-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor
@@ -170,6 +170,7 @@ files:
 - bin/console
 - bin/setup
 - docs/usages/enterprise_architect.adoc
+- docs/usages/enterprise_architect_uml.adoc
 - docs/usages/express.adoc
 - docs/usages/json_yaml.adoc
 - docs/usages/lutaml-gml.adoc
@@ -225,6 +226,7 @@ files:
 - lib/metanorma/plugin/lutaml/lutaml_diagram_block.rb
 - lib/metanorma/plugin/lutaml/lutaml_diagram_block_macro.rb
 - lib/metanorma/plugin/lutaml/lutaml_ea_diagram_block_macro.rb
+- lib/metanorma/plugin/lutaml/lutaml_ea_uml_preprocessor.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