metanorma-plugin-lutaml 0.7.36 → 0.7.37

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d43aaa8c6ecdc67372b3aad6b2f7544132233255012209cb0ed58fbd47385959
-  data.tar.gz: 3b2a90461dcd3d1790bbfc7742102c6f5c337eeb7f03dcdfd24a6308f6ffb408
+  metadata.gz: 2322a39b5dc29e981cf64a1c383c7d53aee9e1b132412ea79fc91dfac88485aa
+  data.tar.gz: b1199f54f2e895a3938b1711c1b36184fbb0bc68fd79e56a6bc9acac12979c2e
 SHA512:
-  metadata.gz: b89e3f6357f35059bb73ff892e113b371ed362deda4317259be50c0ced969e9b90dafbed4eda435180c4b85ed58a4b12ea031211e53c4766f825d8acf61f53ee
-  data.tar.gz: 1182223b096793ab132ac4bfb6c55bf419086a4958eba4a46b1b0ee70f314f4cf883708c40fa437ee06e87f079a4c6ef52bf6eb5767a0dbc07b22cdbc3915488
+  metadata.gz: a11578fe6890dbf07994ba86d55ae9eee7d7eac605907b0dde761570c48d1871de497418ca1adff80091fdd931b520dcedf68ff1fc20f0cedac1f26bc78062a0
+  data.tar.gz: a7f983789b4b1afd9d4b1b01b1b2546218d1530e9c6ff4cdb8f0ffab0d7f6af83d1f2611fdda609d038c0616dfe1ea50e91b0a61b053000602d3f1685f61a5e1

data/.github/workflows/rake.yml

@@ -10,6 +10,6 @@ on:
 
 jobs:
   rake:
-    uses: metanorma/ci/.github/workflows/plantuml-rake.yml@main
+    uses: metanorma/ci/.github/workflows/graphviz-rake.yml@main
     secrets:
       pat_token: ${{ secrets.METANORMA_CI_PAT_TOKEN }}

data/README.adoc

@@ -24,15 +24,15 @@ $ gem install metanorma-plugin-lutaml
 
 == Usages
 
-link:docs/usages/express.adoc[Usage with EXPRESS]
+link:docs/usages/express.adoc[Usage with EXPRESS files by lutaml_express]
 
-link:docs/usages/lutaml-uml.adoc[Usage with LutaML-UML]
+link:docs/usages/lutaml-uml.adoc[Usage with LutaML files by lutaml_diagram]
 
-link:docs/usages/enterprise_architect.adoc[Usage with Enterprise Architect (UML in XMI)]
+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/lutaml-gml.adoc[Usage with LutaML GML Dictionary]
+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]
+link:docs/usages/json_yaml.adoc[Usage with JSON or YAML files by data2text, yaml2text or json2text]
 
 == Documentation
 

data/docs/usages/enterprise_architect.adoc

@@ -1,5 +1,5 @@
 
-== Usage with Enterprise Architect (UML in XMI)
+== Usage with Enterprise Architect XMI files by lutaml_ea_xmi, lutaml_ea_diagram, lutaml_klass_table or lutaml_enum_table
 
 === General
 

data/docs/usages/express.adoc

@@ -1,5 +1,5 @@
 
-== Usage with EXPRESS
+== Usage with EXPRESS files by lutaml_express
 
 === General
 

data/docs/usages/json_yaml.adoc

@@ -1,5 +1,5 @@
 
-== Usage with JSON or YAML files
+== Usage with JSON or YAML files by data2text, yaml2text or json2text
 
 === General
 

data/docs/usages/lutaml-gml.adoc

@@ -1,5 +1,5 @@
 
-== Usage with LutaML GML Dictionary
+== Usage with LutaML GML Dictionary by lutaml_gml_dictionary
 
 === Rendering a LutaML GML Dictionary: `lutaml_gml_dictionary`
 

data/docs/usages/lutaml-uml.adoc

@@ -1,5 +1,5 @@
 
-== Usage with Lutaml-UML
+== Usage with LutaML files by lutaml_diagram
 
 === General
 

data/docs/usages/xmi_to_uml.adoc

@@ -0,0 +1,213 @@
+
+== Usage with Enterprise Architect XMI files by lutaml_xmi_uml
+
+=== General
+
+The LutaML plugin supports working with Enterprise Architect exported XMI files
+to render them as LutaML UML documents.
+
+The command is prefixed as `lutaml_xmi_uml` to denote their specific use.
+
+=== Usage of `lutaml_xmi_uml` command
+
+The `lutaml_xmi_uml` command renders Lutaml UML document and its dependent
+objects for the supplied XMI file.
+
+[example]
+.Specify the path of a XMI file by `lutaml_xmi_uml` command
+====
+[source,adoc]
+----
+[lutaml_xmi_uml,/path/to/first.xmi]
+--
+Name of the Lutaml UML Document: {{ context.name }}
+
+Number of packages: {{ context.packages | size }}
+--
+----
+
+By default, the command will parse the XMI file and render it as a
+Lutaml::Uml::Document via `context`.
+====
+
+=== Usage of `lutaml_xmi_uml` command with configuration file
+
+You can use the `lutaml_xmi_uml` command with a configuration file.
+The configuration file is a YAML file that looks like:
+
+[example]
+.Configuration file for `lutaml_xmi_uml` command
+====
+[source,yaml]
+----
+ea_extension:
+  - "ISO19103MDG v1.0.0-beta.xml"
+  - "CityGML_MDG_Technology.xml"
+context_name: my_uml_document
+template_path: "path/to/liquid_templates"
+----
+
+where:
+
+`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
+in XML format (`CityGML_MDG_Technology.xml`) in order to resolve them.  The
+location of the xml files is relative to the config YAML file.
+
+`context_name`:: optional, name of the context for the rendered output.
+This can be used to customize the output further by providing a specific
+context name.
+
+`template_path`:: optional, path to custom Liquid templates directory for
+rendering the output. When specified, the processor will use custom templates
+from this directory. This allows for complete customization of the rendered
+output format and structure.
+
+To use the configuration file, you can specify it in the command:
+
+[source,adoc]
+----
+[lutaml_xmi_uml,/path/to/first.xmi,path/to/config.yml]
+--
+Name of the Lutaml UML Document: {{ context.name }}
+
+Number of packages: {{ context.packages | size }}
+--
+----
+====
+
+=== Document attribute `:lutaml-xmi-index:`
+
+This attribute allows specifying one or more XMI files to define names
+for later use with `lutaml_xmi_uml` commands.
+
+Syntax:
+
+[source,adoc]
+----
+:lutaml-xmi-index: index_name; index_path[; config=config_path]
+----
+
+where:
+
+`index_name`:: name of index
+`index_path`:: path to XMI file for the later use with `lutaml_xmi_uml` command
+`config_path`:: optional, location of YAML configuration file that specifies
+what packages to include in the render, what render style is desired and
+location of the root package.
+
+[example]
+.Define an index in the document and use it in the `lutaml_xmi_uml` command
+====
+[source,adoc]
+----
+:lutaml-xmi-index: first-xmi-index; /path/to/first.xmi
+
+[lutaml_xmi_uml,index=first-xmi-index]
+--
+...
+--
+----
+
+The command `lutaml_xmi_uml` will load the XMI file from the path
+`/path/to/first.xmi` which is specified by the `index`: `first-xmi-index`.
+====
+
+=== Advanced example usage of `lutaml_xmi_uml` command
+
+The following is an advanced example of using the `lutaml_xmi_uml` command
+with a configuration file and custom Liquid templates to render a UML class
+table.
+
+[example]
+.Advanced example usage of `lutaml_xmi_uml` command
+====
+
+Assume you have the following configuration file `config.yml`:
+
+[source,yaml]
+----
+ea_extension:
+  - "ISO19103MDG v1.0.0-beta.xml"
+  - "CityGML_MDG_Technology.xml"
+context_name: my_uml_document
+template_path: "path/to/my_liquid_templates"
+----
+
+And the following Liquid template `_klass.liquid` in the directory
+`path/to/my_liquid_templates`:
+
+[source,liquid]
+----
+[cols="1a,1a,1a,2a"]
+|===
+| Name of Class 3+| {{ klass.name }}
+| Definition 3+| {{ klass.definition }}
+|===
+
+{% render "attributes", attributes: klass.attributes %}
+----
+
+And the following Liquid template `_attributes.liquid` in the directory
+`path/to/my_liquid_templates`:
+
+[source,liquid]
+----
+[cols="1a,1a,1a,2a"]
+|===
+4+| Attributes
+| Name | Type | Multiplicity | Definition
+{% for attr in attributes %}
+| {{ attr.name }}
+| {{ attr.type }}
+| {{ attr.cardinality.min }}..{{ attr.cardinality.max }}
+| {{ attr.definition }}
+{% endfor %}
+|===
+----
+
+You can use the command to render a specific class
+`RootPackage::MySubPackage::MyClass` by liquid filters:
+
+[source,adoc]
+----
+[lutaml_xmi_uml,example.xmi,config.yml]
+--
+Name of the Lutaml UML Document: {{ my_uml_document.name }}
+
+{% assign root_package = my_uml_document.packages.first %}
+
+{% assign sub_package = root_package.packages | where: "name", "MySubPackage" | first %}
+
+{% assign klass = sub_package.classes | where: "name", "MyClass" | first %}
+
+{% render "klass", klass: klass %}
+----
+
+The output will be a formatted table of the class `MyClass` with its attributes
+looks like:
+
+[source]
+----
+Name of the Lutaml UML Document: `My document`
+
+--------------------------------------------------
+| Name of Class | MyClass                        |
+--------------------------------------------------
+| Definition    | My class definition            |
+--------------------------------------------------
+
+--------------------------------------------------
+| Attributes                                     |
+--------------------------------------------------
+| Name       | Type  | Multiplicity | Definition |
+--------------------------------------------------
+| Attribute1 | Type1 | 0..*         | Def1       |
+--------------------------------------------------
+| Attribute2 | Type2 | 0..1         | Def2       |
+--------------------------------------------------
+| Attribute3 | Type3 | 1..*         | Def3       |
+--------------------------------------------------
+----
+====

data/lib/metanorma/plugin/lutaml/config/root.rb

@@ -17,6 +17,7 @@ module Metanorma
           attribute :render_nested_packages, :boolean
           attribute :external_classes, :hash
           attribute :skip_unrecognized_connector, :boolean
+          attribute :context_name, :string
 
           yaml do
             map "packages", to: :packages,
@@ -34,6 +35,7 @@ module Metanorma
             map "render_nested_packages", to: :render_nested_packages
             map "external_classes", to: :external_classes
             map "skip_unrecognized_connector", to: :skip_unrecognized_connector
+            map "context_name", to: :context_name
           end
 
           def packages_from_yaml(model, values) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity

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

@@ -244,15 +244,21 @@ module Metanorma
             .merge(children_pks_diags)
         end
 
-        def collect_additional_context(document, input_lines, end_mark) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
-          additional_context = Hash.new { |hash, key| hash[key] = [] }
-          additional_context["all_macros"] = []
+        def collect_block_lines(input_lines, end_mark)
           block_lines = []
 
           while (block_line = input_lines.next) != end_mark
             block_lines.push(block_line)
           end
 
+          block_lines
+        end
+
+        def collect_additional_context(document, input_lines, end_mark) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+          additional_context = Hash.new { |hash, key| hash[key] = [] }
+          additional_context["all_macros"] = []
+          block_lines = collect_block_lines(input_lines, end_mark)
+
           processed_lines = process(
             document,
             ::Asciidoctor::PreprocessorReader.new(document, block_lines),

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

@@ -0,0 +1,71 @@
+# 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 file
+      class LutamlXmiUmlPreprocessor < ::Asciidoctor::Extensions::Preprocessor
+        include LutamlEaXmiBase
+
+        MACRO_REGEXP = /\[lutaml_xmi_uml,([^,]+),?(.+)?\]/.freeze
+
+        private
+
+        def parse_result_document(full_path, _guidance)
+          ::Lutaml::XMI::Parsers::XML.parse(
+            File.new(full_path, encoding: "UTF-8"),
+          )
+        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
+          xmi_or_index = block_match[1]&.strip
+
+          lutaml_document, yaml_config = load_lutaml_doc_and_config(
+            document,
+            xmi_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/utils.rb

@@ -39,8 +39,8 @@ module Metanorma
         end
 
         def render_liquid_string( # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
-          template_string:, contexts:, document:,
-          include_path: nil, template_path: nil
+          contexts:, document:,
+          template_string: nil, include_path: nil, template_path: nil
         )
           # Allow includes for the template
           include_paths = [

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

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

data/lib/metanorma-plugin-lutaml.rb

@@ -6,6 +6,7 @@ require "metanorma/plugin/lutaml/data2_text_preprocessor"
 require "metanorma/plugin/lutaml/lutaml_preprocessor"
 require "metanorma/plugin/lutaml/lutaml_uml_datamodel_description_preprocessor"
 require "metanorma/plugin/lutaml/lutaml_ea_xmi_preprocessor"
+require "metanorma/plugin/lutaml/lutaml_xmi_uml_preprocessor"
 require "metanorma/plugin/lutaml/lutaml_diagram_block"
 require "metanorma/plugin/lutaml/lutaml_diagram_block_macro"
 require "metanorma/plugin/lutaml/lutaml_figure_inline_macro"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: metanorma-plugin-lutaml
 version: !ruby/object:Gem::Version
-  version: 0.7.36
+  version: 0.7.37
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-15 00:00:00.000000000 Z
+date: 2025-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor
@@ -146,6 +146,7 @@ files:
 - docs/usages/json_yaml.adoc
 - docs/usages/lutaml-gml.adoc
 - docs/usages/lutaml-uml.adoc
+- docs/usages/xmi_to_uml.adoc
 - lib/metanorma-plugin-lutaml.rb
 - lib/metanorma/plugin/lutaml/asciidoctor/preprocessor.rb
 - lib/metanorma/plugin/lutaml/base_structured_text_preprocessor.rb
@@ -197,6 +198,7 @@ files:
 - lib/metanorma/plugin/lutaml/lutaml_preprocessor.rb
 - lib/metanorma/plugin/lutaml/lutaml_table_inline_macro.rb
 - lib/metanorma/plugin/lutaml/lutaml_uml_datamodel_description_preprocessor.rb
+- lib/metanorma/plugin/lutaml/lutaml_xmi_uml_preprocessor.rb
 - lib/metanorma/plugin/lutaml/parse_error.rb
 - lib/metanorma/plugin/lutaml/source_extractor.rb
 - lib/metanorma/plugin/lutaml/utils.rb