= metanorma-plugin-lutaml image:https://github.com/metanorma/metanorma-plugin-lutaml/workflows/rake/badge.svg["Build Status", link="https://github.com/metanorma/metanorma-plugin-lutaml/actions?workflow=rake"] == Functionality Metanorma plugin that allows you to access lutaml objects from a Metanorma document === Installation [source,console] ---- $ gem install metanorma-plugin-lutaml ---- === Usage, `lutaml` macro Given `example.exp` file with the content: [source,exp] ---- SCHEMA test_schema 'test'; (* Need select elements for measure_value *) REFERENCE FROM measure_schema (measure_value); TYPE my_type1 = EXTENSIBLE SELECT; END_TYPE; TYPE my_type2 = EXTENSIBLE ENUMERATION; END_TYPE; TYPE my_type3 = EXTENSIBLE ENUMERATION; END_TYPE; TYPE my_type4 = EXTENSIBLE ENUMERATION; END_TYPE; TYPE my_type5 = EXTENSIBLE ENUMERATION; END_TYPE; END_SCHEMA; ---- And the `lutaml` macro block: [source,adoc] ----- [lutaml,example.exp,my_context] ---- {% for schema in my_context.schemas %} == {{schema.id}} {% for entity in schema.entities %} === {{entity.id}} {% endfor %} {% endfor %} ---- ----- Where: * content within the block is called the "`template`"; * `{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: [source,adoc] ----- == test_schema === my_type1 === my_type2 === my_type3 === my_type4 === my_type5 ----- 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: [source,adoc] ----- :lutaml-express-index: my_custom_name; dir_or_index_path[; cache=cache_path] ----- Where: * `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 the YAML index file to parse * `cache_path` - optional, location of the Expressir cache file to use Example of usage: [source,adoc] ----- = Document title Author :lutaml-express-index: my_custom_name; /path/to/express_files; cache=/path/to/cache_file.yaml [lutaml,my_custom_name,my_context] ---- {% for schema in my_context.schemas %} == {{schema.id}} {% endfor %} ---- ----- === 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 data model attributes/values tables. 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_uml_attributes_table` macro: [source,adoc] ----- [lutaml_uml_attributes_table, example.lutaml, AttributeProfile] ----- 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` |imlicistAttributeProfile |this is attribute definition with multiply lines |M |1 | `CharacterString` |=== ----- In case of "enumeration"(AddressClassProfile) entity: [source,adoc] ----- [lutaml_uml_attributes_table, example.lutaml, AddressClassProfile] ----- Will produce this output: [source,adoc] ----- === AddressClassProfile .AddressClassProfile values |=== |Name |Definition |imlicistAttributeProfile |this is multiline with `ascidoc` |=== ----- === 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 --- [.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 * `[.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 Will produce this output: [source,adoc] ----- = preface my text text before Another package === Another [[rc_another-model_section]] ==== Another ==== Requirements ==== Class Definitions .Classes used in Another [cols="2a,6a",options="header"] |=== |Class |Description |<> «» | |<> «» | .... |=== .Data Types used in Another [cols="2,6",options="header"] |=== |Name |Description |<> | |<> | .... |=== .Enumerated Classes used in Another [cols="2a,6a",options="header"] |=== |Name |Description |<> | |=== ==== Additional Information text after Another package === CityGML [[rc_citygml-model_section]] ==== CityGML ==== Requirements ==== Class Definitions ==== Additional Information text after CityGML package = footer footer text ----- 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 ----- 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 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 Please refer to https://www.metanorma.com.