metanorma-plugin-lutaml 0.4.2 → 0.4.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bfe1f241f558def33ef0fc13446d842d50aac1b1003cade580fa3b62e730b722
-  data.tar.gz: 2d12efe1688915194f16cd857e6ca4deaf9852b98407112363bf106dcf3e60a9
+  metadata.gz: 636e4bec2488f6e9044ab15915f37485cf08ddcec31e2e852c9d381188b2d99e
+  data.tar.gz: c9c0e74be3a5d5856336f5202c7cb18e442d18548e1a29f476b72694d767eac5
 SHA512:
-  metadata.gz: d6c46b1d885bc2cb06ea76c4dd5ff057e2b2944579403c8582b43e8a66fe5cb67046b49c1d00526410aba63c0f1614900d3a65e681d67e5f75a3d9b66fc18fd9
-  data.tar.gz: 3da558c2e348387e60bdc1d0b079150c032e11dcf60731b8083b766dc129b10322c9e3f06892bfc06b8524df1ad453ed1d519153b19f55c7b34734ed20e4f614
+  metadata.gz: 0e15f9f636f56f0f110baaec844dde2691aefbc882d3be878abe4ccd57e917472847ceb7dcca32f41c1d713d202f4e5caed0530171aad7d368fdde16431fdaee
+  data.tar.gz: 623fb7a37ad8be5e2aac50bbb32be6f366c75abeb47226800af1ae3ec88e24e6c024b7f57016862791f3fa89f4e8181a5c55710f71ab557d25f13480e88e53d9

data/README.adoc

@@ -64,9 +64,19 @@ Where:
 
 * content within the block is called the "`template`";
 
-* `{example.exp}` is the location of the exp schema file 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,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`);
-
-* `{my_context}` is the name where the EXPRESS Repository read from the .exp file can be accessed with. Context object is a serialized  Expressir::Model::Repository object with all variable names available. See https://github.com/lutaml/expressir[Expressir] docs for reference. `{my_context}` has `schemas` method to access Expressir https://github.com/lutaml/expressir/blob/master/lib/expressir/model/schema.rb[schemas]
+* `{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,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`);
+
+* `{my_context}` is the name where the EXPRESS Repository read from the .exp
+file can be accessed with. Context object is a serialized
+`Expressir::Model::Repository` object with all variable names available. See
+https://github.com/lutaml/expressir[Expressir] docs for reference.
+`{my_context}` has `schemas` method to access Expressir
+https://github.com/lutaml/expressir/blob/master/lib/expressir/model/schema.rb[schemas]
 
 Will produce this output:
 
@@ -83,7 +93,11 @@ Will produce this output:
 
 This macro 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 parse as well as the cache file location. The syntax is as follows:
+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
+parse as well as the cache file location.
+
+The syntax is as follows:
 
 [source,adoc]
 -----
@@ -92,13 +106,15 @@ Instead of using the direct path to the file one can use `lutaml-express-index`
 
 Where:
 
-* `my_custom_name` - is name of the parsed express files context for the later use with lutaml macro
+* `my_custom_name` - is name of the parsed EXPRESS files context for the later
+use with lutaml macro
 
-* `dir_or_index_path` - location of directory with express files or path to yaml index file to parse
+* `dir_or_index_path` - location of directory with EXPRESS files or path to the
+YAML index file to parse
 
-* `cache_path` - optional, location of the expressir cache file to use
+* `cache_path` - optional, location of the Expressir cache file to use
 
-Example of real usage:
+Example of usage:
 
 [source,adoc]
 -----
@@ -113,9 +129,75 @@ Author
 ----
 -----
 
+=== Usage, `lutaml_diagram` macro
+
+This macro allows to quickly render lutaml file as diagram image.
+Given `example.lutaml` file with the content:
+
+[source,java]
+----
+diagram MyView {
+  title "my diagram"
+
+  enum AddressClassProfile {
+    imlicistAttributeProfile: CharacterString [0..1] {
+      definition
+        this is multiline with `ascidoc`
+      end definition
+    }
+  }
+
+  class AttributeProfile {
+    +addressClassProfile: CharacterString [0..1]
+    imlicistAttributeProfile: CharacterString [0..1] {
+      definition this is attribute definition
+    }
+  }
+}
+----
+
+And the `lutaml_diagram` macro:
+
+[source,adoc]
+-----
+lutaml_diagram::example.lutaml[]
+-----
+
+Will add diagram image to the document
+
+Also one can use `lutaml_diagram` block with embed lutaml code instead of block macro. Example:
+
+[source,java]
+----
+[lutaml_diagram]
+....
+diagram MyView {
+  title "my diagram"
+
+  enum AddressClassProfile {
+    imlicistAttributeProfile: CharacterString [0..1] {
+      definition
+        this is multiline with `ascidoc`
+      end definition
+    }
+  }
+
+  class AttributeProfile {
+    +addressClassProfile: CharacterString [0..1]
+    imlicistAttributeProfile: CharacterString [0..1] {
+      definition this is attribute definition
+    }
+  }
+}
+....
+----
+
+
 === Usage, `lutaml_uml_attributes_table` macro
 
-This macro allows to quickly render datamodel attributes/values tables. Given `example.lutaml` file with the content:
+This macro allows to quickly render data model attributes/values tables.
+
+Given `example.lutaml` file with the content:
 
 [source,java]
 ----
@@ -187,6 +269,226 @@ Will produce this output:
 |===
 -----
 
+=== Usage, `lutaml_uml_datamodel_description` macro
+
+This macro 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:
+
+* 'Another'
+* 'CityGML'
+
+The `lutaml_uml_datamodel_description` macro can be used:
+
+[source,adoc]
+-----
+[lutaml_uml_datamodel_description, path/to/example.xmi]
+--
+[.before]
+....
+my text
+....
+
+[.diagram_include_block, base_path="requirements/"]
+....
+Diagram text
+....
+
+[.include_block, package="Another", base_path="spec/fixtures"]
+....
+my text
+....
+
+[.include_block, base_path="spec/fixtures"]
+....
+my text
+....
+
+[.before, package="Another"]
+....
+text before Another package
+....
+
+[.after, package="Another"]
+....
+text after Another package
+....
+
+[.after, package="CityGML"]
+....
+text after CityGML package
+....
+
+[.after]
+....
+footer text
+....
+--
+--
+-----
+
+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 `....`)
+
+* `[.after]` - macro to add 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
+
+* `[.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 digram image. The logic is as follows:
+[source,adoc]
+-----
+{% for diagram in package.diagrams %}
+[[figure-{{ diagram.xmi_id }}]]
+.{{ diagram.name }}
+image::{{ image_base_path }}/{{ diagram.xmi_id }}.png[]
+
+{% if diagram.definition %}
+{{ diagram.definition | html2adoc }}
+{% endif %}
+{% endfor %}
+-----
+Eg: script will take package diagrams supplied in 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 macro 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
+
+* `[.include_block, base_path="spec/fixtures"]` - macro to inlude files(adoc/liquid) for each package name. Attribute `base_path` is a required attribute to supply path prefix where to look for file to include. Macro 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`, macro 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
+
+In addition to macroses 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:
+
+[source,adoc]
+-----
+This is lutaml_figure::[package="Wrapper root package", name="Fig B1 Full model"] figure
+-----
+
+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 refernce package diagram.
+
+Will produce this output:
+
+[source,adoc]
+-----
+my text
+== CityGML package
+=== CityGML overview
+
+Diagram text
+
+[[figure-EAID_ACBB5EE3_3428_40f5_9C7C_E41923419F29]]
+.CityGML Package Diagram
+image::requirements//EAID_ACBB5EE3_3428_40f5_9C7C_E41923419F29.png[]
+
+BuildingFurnitureFunctionValue is a code list that enumerates the different purposes of a BuildingFurniture.
+
+[[figure-EAID_938AE961_1C57_4052_B964_997D1894A58D]]
+.Use of ISO and OASIS standards in CityGML
+image::requirements//EAID_938AE961_1C57_4052_B964_997D1894A58D.png[]
+
+The CityGML package is organized into
+2 packages with 1 modules:
+
+[arabic]
+. Another package
+. CityTML package
+
+my text
+
+Content for CityGML package
+
+==== Defining tables
+
+[arabic]
+.<<tab-P-another-C-abstractatomictimeseries>> -- Elements of Another::AbstractAtomicTimeseries
+
+[[tab-P-another-C-abstractatomictimeseries]]
+.Elements of Another::AbstractAtomicTimeseries
+[width="100%",cols="a,a,a,a,a,a,a,a"]
+|===
+h|Name: 7+| AbstractAtomicTimeseries
+h|Definition: 7+|
+h|Stereotype: 7+| interface
+h|Abstract: 7+|
+.1+h|Associations: 7+| (none)
+.4+h|Public attributes:
+| _Name_
+2+| _Definition_
+| _Derived_
+| _Obligation_
+| _Maximum occurrence_
+| _Data type_
+| adeOfAbstractAtomicTimeseries
+2+|
+|
+| C
+| *
+| ADEOfAbstractAtomicTimeseries
+| observationProperty
+2+|
+|
+| M
+| 1
+| CharacterString
+| uom
+2+|
+|
+| C
+| 1
+| CharacterString
+h|Constraints: 7+| (none)
+|===
+
+=== Additional Information
+
+text after CityGML package
+-----
+
+In addition to just supplying XMI file, this macro also supports YAML
+configuration file.
+
+The format for using YAML is this:
+
+[source,yaml]
+-----
+---
+packages:
+  # includes these packages
+  - "Package *"
+  - two*
+  - three
+  # skips these packages
+  - skip: four
+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`
+
+Usage with macro:
+
+[source,adoc]
+-----
+[lutaml_uml_datamodel_description, path/to/example.xmi, path/to/config.yml]
+....
+-----
+
+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
+
 == Documentation
 
-See https://www.metanorma.com.
+Please refer to https://www.metanorma.com.

data/lib/metanorma-plugin-lutaml.rb

@@ -1,7 +1,10 @@
 require "metanorma/plugin/lutaml/version"
 require "metanorma/plugin/lutaml/lutaml_preprocessor"
 require "metanorma/plugin/lutaml/lutaml_uml_attributes_table_preprocessor"
+require "metanorma/plugin/lutaml/lutaml_uml_datamodel_description_preprocessor"
 require "metanorma/plugin/lutaml/lutaml_diagram_block"
+require "metanorma/plugin/lutaml/lutaml_diagram_block_macro"
+require "metanorma/plugin/lutaml/lutaml_figure_inline_macro"
 
 module Metanorma
   module Plugin

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

@@ -0,0 +1,53 @@
+module Metanorma
+  module Plugin
+    module Lutaml
+      module Liquid
+        class LocalFileSystem
+          attr_accessor :roots, :patterns
+
+          def initialize(roots, patterns = ["_%s.liquid"])
+            @roots    = roots
+            @patterns = patterns
+          end
+
+          def read_template_file(template_path)
+            full_path = full_path(template_path)
+            raise FileSystemError, "No such template '#{template_path}'" unless File.exist?(full_path)
+
+            File.read(full_path)
+          end
+
+          def full_path(template_path)
+            raise ::Liquid::FileSystemError, "Illegal template name '#{template_path}'" unless %r{\A[^./][a-zA-Z0-9_/]+\z}.match?(template_path)
+
+            result_path = if template_path.include?('/')
+              roots
+                .map do |root|
+                  patterns.map do |pattern|
+                    File.join(root, File.dirname(template_path), pattern % File.basename(template_path))
+                  end
+                end
+                .flatten
+                .find { |path| File.file?(path) }
+            else
+              roots
+                .map do |root|
+                  patterns.map do |pattern|
+                    File.join(root, pattern % template_path)
+                  end
+                end
+                .flatten
+                .find { |path| File.file?(path) }
+            end
+
+            unless roots.any? { |root| File.expand_path(result_path).start_with?(File.expand_path(root)) }
+              raise ::Liquid::FileSystemError, "Illegal template path '#{File.expand_path(result_path)}'"
+            end
+
+            result_path
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+{{ text }}
+
+{% for diagram in package.diagrams %}
+[[figure-{{ diagram.xmi_id }}]]
+.{{ diagram.name }}
+image::{{ image_base_path }}/{{ diagram.xmi_id }}.png[]
+
+{% if diagram.definition %}
+{{ diagram.definition | html2adoc }}
+{% endif %}
+{% endfor %}