metanorma-plugin-lutaml 0.4.2 → 0.4.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.adoc +312 -10
- data/lib/metanorma-plugin-lutaml.rb +3 -0
- data/lib/metanorma/plugin/lutaml/liquid/multiply_local_file_system.rb +53 -0
- data/lib/metanorma/plugin/lutaml/liquid_templates/_diagrams_block.liquid +11 -0
- data/lib/metanorma/plugin/lutaml/liquid_templates/_packages.liquid +133 -0
- data/lib/metanorma/plugin/lutaml/liquid_templates/_packages_class.liquid +81 -0
- data/lib/metanorma/plugin/lutaml/liquid_templates/_packages_data_dictionary.liquid +177 -0
- data/lib/metanorma/plugin/lutaml/liquid_templates/_packages_data_dictionary_classes.liquid +43 -0
- data/lib/metanorma/plugin/lutaml/liquid_templates/_packages_data_type.liquid +63 -0
- data/lib/metanorma/plugin/lutaml/liquid_templates/_packages_entity_list.liquid +113 -0
- data/lib/metanorma/plugin/lutaml/liquid_templates/_packages_enum.liquid +63 -0
- data/lib/metanorma/plugin/lutaml/lutaml_diagram_base.rb +81 -0
- data/lib/metanorma/plugin/lutaml/lutaml_diagram_block.rb +5 -60
- data/lib/metanorma/plugin/lutaml/lutaml_diagram_block_macro.rb +20 -0
- data/lib/metanorma/plugin/lutaml/lutaml_figure_inline_macro.rb +23 -0
- data/lib/metanorma/plugin/lutaml/lutaml_uml_attributes_table_preprocessor.rb +11 -10
- data/lib/metanorma/plugin/lutaml/lutaml_uml_datamodel_description_preprocessor.rb +188 -0
- data/lib/metanorma/plugin/lutaml/utils.rb +4 -2
- data/lib/metanorma/plugin/lutaml/version.rb +1 -1
- metadata +15 -2
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 636e4bec2488f6e9044ab15915f37485cf08ddcec31e2e852c9d381188b2d99e
|
4
|
+
data.tar.gz: c9c0e74be3a5d5856336f5202c7cb18e442d18548e1a29f476b72694d767eac5
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 0e15f9f636f56f0f110baaec844dde2691aefbc882d3be878abe4ccd57e917472847ceb7dcca32f41c1d713d202f4e5caed0530171aad7d368fdde16431fdaee
|
7
|
+
data.tar.gz: 623fb7a37ad8be5e2aac50bbb32be6f366c75abeb47226800af1ae3ec88e24e6c024b7f57016862791f3fa89f4e8181a5c55710f71ab557d25f13480e88e53d9
|
data/README.adoc
CHANGED
@@ -64,9 +64,19 @@ Where:
|
|
64
64
|
|
65
65
|
* content within the block is called the "`template`";
|
66
66
|
|
67
|
-
* `{example.exp}` is the location of the
|
68
|
-
|
69
|
-
|
67
|
+
* `{example.exp}` is the location of the EXPRESS schema file (`*.exp`) that
|
68
|
+
contains data to be loaded. Location of the file is computed relative to the
|
69
|
+
source directory that `[lutaml]` is used (e.g., if
|
70
|
+
`[lutaml,example.exp,my_context]` is invoked in an `.adoc` file located at
|
71
|
+
`/foo/bar/doc.adoc`, the data file is expected to be found at
|
72
|
+
`/foo/bar/example.exp`);
|
73
|
+
|
74
|
+
* `{my_context}` is the name where the EXPRESS Repository read from the .exp
|
75
|
+
file can be accessed with. Context object is a serialized
|
76
|
+
`Expressir::Model::Repository` object with all variable names available. See
|
77
|
+
https://github.com/lutaml/expressir[Expressir] docs for reference.
|
78
|
+
`{my_context}` has `schemas` method to access Expressir
|
79
|
+
https://github.com/lutaml/expressir/blob/master/lib/expressir/model/schema.rb[schemas]
|
70
80
|
|
71
81
|
Will produce this output:
|
72
82
|
|
@@ -83,7 +93,11 @@ Will produce this output:
|
|
83
93
|
|
84
94
|
This macro also supports `.lutaml` files.
|
85
95
|
|
86
|
-
Instead of using the direct path to the file one can use `lutaml-express-index`
|
96
|
+
Instead of using the direct path to the file one can use `lutaml-express-index`
|
97
|
+
document attribute to supply directory with express files or YAML index file to
|
98
|
+
parse as well as the cache file location.
|
99
|
+
|
100
|
+
The syntax is as follows:
|
87
101
|
|
88
102
|
[source,adoc]
|
89
103
|
-----
|
@@ -92,13 +106,15 @@ Instead of using the direct path to the file one can use `lutaml-express-index`
|
|
92
106
|
|
93
107
|
Where:
|
94
108
|
|
95
|
-
* `my_custom_name` - is name of the parsed
|
109
|
+
* `my_custom_name` - is name of the parsed EXPRESS files context for the later
|
110
|
+
use with lutaml macro
|
96
111
|
|
97
|
-
* `dir_or_index_path` - location of directory with
|
112
|
+
* `dir_or_index_path` - location of directory with EXPRESS files or path to the
|
113
|
+
YAML index file to parse
|
98
114
|
|
99
|
-
* `cache_path` - optional, location of the
|
115
|
+
* `cache_path` - optional, location of the Expressir cache file to use
|
100
116
|
|
101
|
-
Example of
|
117
|
+
Example of usage:
|
102
118
|
|
103
119
|
[source,adoc]
|
104
120
|
-----
|
@@ -113,9 +129,75 @@ Author
|
|
113
129
|
----
|
114
130
|
-----
|
115
131
|
|
132
|
+
=== Usage, `lutaml_diagram` macro
|
133
|
+
|
134
|
+
This macro allows to quickly render lutaml file as diagram image.
|
135
|
+
Given `example.lutaml` file with the content:
|
136
|
+
|
137
|
+
[source,java]
|
138
|
+
----
|
139
|
+
diagram MyView {
|
140
|
+
title "my diagram"
|
141
|
+
|
142
|
+
enum AddressClassProfile {
|
143
|
+
imlicistAttributeProfile: CharacterString [0..1] {
|
144
|
+
definition
|
145
|
+
this is multiline with `ascidoc`
|
146
|
+
end definition
|
147
|
+
}
|
148
|
+
}
|
149
|
+
|
150
|
+
class AttributeProfile {
|
151
|
+
+addressClassProfile: CharacterString [0..1]
|
152
|
+
imlicistAttributeProfile: CharacterString [0..1] {
|
153
|
+
definition this is attribute definition
|
154
|
+
}
|
155
|
+
}
|
156
|
+
}
|
157
|
+
----
|
158
|
+
|
159
|
+
And the `lutaml_diagram` macro:
|
160
|
+
|
161
|
+
[source,adoc]
|
162
|
+
-----
|
163
|
+
lutaml_diagram::example.lutaml[]
|
164
|
+
-----
|
165
|
+
|
166
|
+
Will add diagram image to the document
|
167
|
+
|
168
|
+
Also one can use `lutaml_diagram` block with embed lutaml code instead of block macro. Example:
|
169
|
+
|
170
|
+
[source,java]
|
171
|
+
----
|
172
|
+
[lutaml_diagram]
|
173
|
+
....
|
174
|
+
diagram MyView {
|
175
|
+
title "my diagram"
|
176
|
+
|
177
|
+
enum AddressClassProfile {
|
178
|
+
imlicistAttributeProfile: CharacterString [0..1] {
|
179
|
+
definition
|
180
|
+
this is multiline with `ascidoc`
|
181
|
+
end definition
|
182
|
+
}
|
183
|
+
}
|
184
|
+
|
185
|
+
class AttributeProfile {
|
186
|
+
+addressClassProfile: CharacterString [0..1]
|
187
|
+
imlicistAttributeProfile: CharacterString [0..1] {
|
188
|
+
definition this is attribute definition
|
189
|
+
}
|
190
|
+
}
|
191
|
+
}
|
192
|
+
....
|
193
|
+
----
|
194
|
+
|
195
|
+
|
116
196
|
=== Usage, `lutaml_uml_attributes_table` macro
|
117
197
|
|
118
|
-
This macro allows to quickly render
|
198
|
+
This macro allows to quickly render data model attributes/values tables.
|
199
|
+
|
200
|
+
Given `example.lutaml` file with the content:
|
119
201
|
|
120
202
|
[source,java]
|
121
203
|
----
|
@@ -187,6 +269,226 @@ Will produce this output:
|
|
187
269
|
|===
|
188
270
|
-----
|
189
271
|
|
272
|
+
=== Usage, `lutaml_uml_datamodel_description` macro
|
273
|
+
|
274
|
+
This macro allows to quickly render data model packages and its dependent
|
275
|
+
objects for supplied XMI file.
|
276
|
+
|
277
|
+
Given an Enterprise Architect `example.xmi` file with 2 packages:
|
278
|
+
|
279
|
+
* 'Another'
|
280
|
+
* 'CityGML'
|
281
|
+
|
282
|
+
The `lutaml_uml_datamodel_description` macro can be used:
|
283
|
+
|
284
|
+
[source,adoc]
|
285
|
+
-----
|
286
|
+
[lutaml_uml_datamodel_description, path/to/example.xmi]
|
287
|
+
--
|
288
|
+
[.before]
|
289
|
+
....
|
290
|
+
my text
|
291
|
+
....
|
292
|
+
|
293
|
+
[.diagram_include_block, base_path="requirements/"]
|
294
|
+
....
|
295
|
+
Diagram text
|
296
|
+
....
|
297
|
+
|
298
|
+
[.include_block, package="Another", base_path="spec/fixtures"]
|
299
|
+
....
|
300
|
+
my text
|
301
|
+
....
|
302
|
+
|
303
|
+
[.include_block, base_path="spec/fixtures"]
|
304
|
+
....
|
305
|
+
my text
|
306
|
+
....
|
307
|
+
|
308
|
+
[.before, package="Another"]
|
309
|
+
....
|
310
|
+
text before Another package
|
311
|
+
....
|
312
|
+
|
313
|
+
[.after, package="Another"]
|
314
|
+
....
|
315
|
+
text after Another package
|
316
|
+
....
|
317
|
+
|
318
|
+
[.after, package="CityGML"]
|
319
|
+
....
|
320
|
+
text after CityGML package
|
321
|
+
....
|
322
|
+
|
323
|
+
[.after]
|
324
|
+
....
|
325
|
+
footer text
|
326
|
+
....
|
327
|
+
--
|
328
|
+
--
|
329
|
+
-----
|
330
|
+
|
331
|
+
Where:
|
332
|
+
|
333
|
+
* `path/to/example.xmi` - required, path to the XMI file to render
|
334
|
+
|
335
|
+
* `[.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 `....`)
|
336
|
+
|
337
|
+
* `[.after]` - macro to add additional text after the rendered output, can be used only once, additional occurrences of macro will overwrite text
|
338
|
+
|
339
|
+
* `[.after, package="Another"]` - macro with text to be inserted before(after in case of `.before` name) the package
|
340
|
+
|
341
|
+
* `[.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:
|
342
|
+
[source,adoc]
|
343
|
+
-----
|
344
|
+
{% for diagram in package.diagrams %}
|
345
|
+
[[figure-{{ diagram.xmi_id }}]]
|
346
|
+
.{{ diagram.name }}
|
347
|
+
image::{{ image_base_path }}/{{ diagram.xmi_id }}.png[]
|
348
|
+
|
349
|
+
{% if diagram.definition %}
|
350
|
+
{{ diagram.definition | html2adoc }}
|
351
|
+
{% endif %}
|
352
|
+
{% endfor %}
|
353
|
+
-----
|
354
|
+
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.
|
355
|
+
|
356
|
+
* `[.diagram_include_block, package="Another"]` - same as above, but diagram will be included only for supplied package name
|
357
|
+
|
358
|
+
* `[.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`.
|
359
|
+
|
360
|
+
* `[.include_block, package="Another", base_path="spec/fixtures"]` - same as above, but include block will be included only for supplied package name
|
361
|
+
|
362
|
+
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:
|
363
|
+
|
364
|
+
[source,adoc]
|
365
|
+
-----
|
366
|
+
This is lutaml_figure::[package="Wrapper root package", name="Fig B1 Full model"] figure
|
367
|
+
-----
|
368
|
+
|
369
|
+
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.
|
370
|
+
|
371
|
+
Will produce this output:
|
372
|
+
|
373
|
+
[source,adoc]
|
374
|
+
-----
|
375
|
+
my text
|
376
|
+
== CityGML package
|
377
|
+
=== CityGML overview
|
378
|
+
|
379
|
+
Diagram text
|
380
|
+
|
381
|
+
[[figure-EAID_ACBB5EE3_3428_40f5_9C7C_E41923419F29]]
|
382
|
+
.CityGML Package Diagram
|
383
|
+
image::requirements//EAID_ACBB5EE3_3428_40f5_9C7C_E41923419F29.png[]
|
384
|
+
|
385
|
+
BuildingFurnitureFunctionValue is a code list that enumerates the different purposes of a BuildingFurniture.
|
386
|
+
|
387
|
+
[[figure-EAID_938AE961_1C57_4052_B964_997D1894A58D]]
|
388
|
+
.Use of ISO and OASIS standards in CityGML
|
389
|
+
image::requirements//EAID_938AE961_1C57_4052_B964_997D1894A58D.png[]
|
390
|
+
|
391
|
+
The CityGML package is organized into
|
392
|
+
2 packages with 1 modules:
|
393
|
+
|
394
|
+
[arabic]
|
395
|
+
. Another package
|
396
|
+
. CityTML package
|
397
|
+
|
398
|
+
my text
|
399
|
+
|
400
|
+
Content for CityGML package
|
401
|
+
|
402
|
+
==== Defining tables
|
403
|
+
|
404
|
+
[arabic]
|
405
|
+
.<<tab-P-another-C-abstractatomictimeseries>> -- Elements of Another::AbstractAtomicTimeseries
|
406
|
+
|
407
|
+
[[tab-P-another-C-abstractatomictimeseries]]
|
408
|
+
.Elements of Another::AbstractAtomicTimeseries
|
409
|
+
[width="100%",cols="a,a,a,a,a,a,a,a"]
|
410
|
+
|===
|
411
|
+
h|Name: 7+| AbstractAtomicTimeseries
|
412
|
+
h|Definition: 7+|
|
413
|
+
h|Stereotype: 7+| interface
|
414
|
+
h|Abstract: 7+|
|
415
|
+
.1+h|Associations: 7+| (none)
|
416
|
+
.4+h|Public attributes:
|
417
|
+
| _Name_
|
418
|
+
2+| _Definition_
|
419
|
+
| _Derived_
|
420
|
+
| _Obligation_
|
421
|
+
| _Maximum occurrence_
|
422
|
+
| _Data type_
|
423
|
+
| adeOfAbstractAtomicTimeseries
|
424
|
+
2+|
|
425
|
+
|
|
426
|
+
| C
|
427
|
+
| *
|
428
|
+
| ADEOfAbstractAtomicTimeseries
|
429
|
+
| observationProperty
|
430
|
+
2+|
|
431
|
+
|
|
432
|
+
| M
|
433
|
+
| 1
|
434
|
+
| CharacterString
|
435
|
+
| uom
|
436
|
+
2+|
|
437
|
+
|
|
438
|
+
| C
|
439
|
+
| 1
|
440
|
+
| CharacterString
|
441
|
+
h|Constraints: 7+| (none)
|
442
|
+
|===
|
443
|
+
|
444
|
+
=== Additional Information
|
445
|
+
|
446
|
+
text after CityGML package
|
447
|
+
-----
|
448
|
+
|
449
|
+
In addition to just supplying XMI file, this macro also supports YAML
|
450
|
+
configuration file.
|
451
|
+
|
452
|
+
The format for using YAML is this:
|
453
|
+
|
454
|
+
[source,yaml]
|
455
|
+
-----
|
456
|
+
---
|
457
|
+
packages:
|
458
|
+
# includes these packages
|
459
|
+
- "Package *"
|
460
|
+
- two*
|
461
|
+
- three
|
462
|
+
# skips these packages
|
463
|
+
- skip: four
|
464
|
+
render_style: entity_list|data_dictionary|default
|
465
|
+
section_depth: 2
|
466
|
+
-----
|
467
|
+
|
468
|
+
Where:
|
469
|
+
|
470
|
+
* `packages` - required, root element with the list of strings or objects
|
471
|
+
* `Package *` - pattern matching, specifies lookup condition for packages to
|
472
|
+
render.
|
473
|
+
+
|
474
|
+
NOTE: In this example, it is equal to the following regular expression: `/^Package.*$/`
|
475
|
+
|
476
|
+
* `skip: four` - object with package name to skip
|
477
|
+
* `render_style` - what template to use to render packages, can be: entity_list, data_dictionary or default
|
478
|
+
* `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`
|
479
|
+
|
480
|
+
Usage with macro:
|
481
|
+
|
482
|
+
[source,adoc]
|
483
|
+
-----
|
484
|
+
[lutaml_uml_datamodel_description, path/to/example.xmi, path/to/config.yml]
|
485
|
+
....
|
486
|
+
-----
|
487
|
+
|
488
|
+
The macro processor will read supplied YAML file and arrange packages according
|
489
|
+
to the order supplied in the config file, also all packages supplied as `skip`
|
490
|
+
will be skipped during render
|
491
|
+
|
190
492
|
== Documentation
|
191
493
|
|
192
|
-
|
494
|
+
Please refer to https://www.metanorma.com.
|
@@ -1,7 +1,10 @@
|
|
1
1
|
require "metanorma/plugin/lutaml/version"
|
2
2
|
require "metanorma/plugin/lutaml/lutaml_preprocessor"
|
3
3
|
require "metanorma/plugin/lutaml/lutaml_uml_attributes_table_preprocessor"
|
4
|
+
require "metanorma/plugin/lutaml/lutaml_uml_datamodel_description_preprocessor"
|
4
5
|
require "metanorma/plugin/lutaml/lutaml_diagram_block"
|
6
|
+
require "metanorma/plugin/lutaml/lutaml_diagram_block_macro"
|
7
|
+
require "metanorma/plugin/lutaml/lutaml_figure_inline_macro"
|
5
8
|
|
6
9
|
module Metanorma
|
7
10
|
module Plugin
|
@@ -0,0 +1,53 @@
|
|
1
|
+
module Metanorma
|
2
|
+
module Plugin
|
3
|
+
module Lutaml
|
4
|
+
module Liquid
|
5
|
+
class LocalFileSystem
|
6
|
+
attr_accessor :roots, :patterns
|
7
|
+
|
8
|
+
def initialize(roots, patterns = ["_%s.liquid"])
|
9
|
+
@roots = roots
|
10
|
+
@patterns = patterns
|
11
|
+
end
|
12
|
+
|
13
|
+
def read_template_file(template_path)
|
14
|
+
full_path = full_path(template_path)
|
15
|
+
raise FileSystemError, "No such template '#{template_path}'" unless File.exist?(full_path)
|
16
|
+
|
17
|
+
File.read(full_path)
|
18
|
+
end
|
19
|
+
|
20
|
+
def full_path(template_path)
|
21
|
+
raise ::Liquid::FileSystemError, "Illegal template name '#{template_path}'" unless %r{\A[^./][a-zA-Z0-9_/]+\z}.match?(template_path)
|
22
|
+
|
23
|
+
result_path = if template_path.include?('/')
|
24
|
+
roots
|
25
|
+
.map do |root|
|
26
|
+
patterns.map do |pattern|
|
27
|
+
File.join(root, File.dirname(template_path), pattern % File.basename(template_path))
|
28
|
+
end
|
29
|
+
end
|
30
|
+
.flatten
|
31
|
+
.find { |path| File.file?(path) }
|
32
|
+
else
|
33
|
+
roots
|
34
|
+
.map do |root|
|
35
|
+
patterns.map do |pattern|
|
36
|
+
File.join(root, pattern % template_path)
|
37
|
+
end
|
38
|
+
end
|
39
|
+
.flatten
|
40
|
+
.find { |path| File.file?(path) }
|
41
|
+
end
|
42
|
+
|
43
|
+
unless roots.any? { |root| File.expand_path(result_path).start_with?(File.expand_path(root)) }
|
44
|
+
raise ::Liquid::FileSystemError, "Illegal template path '#{File.expand_path(result_path)}'"
|
45
|
+
end
|
46
|
+
|
47
|
+
result_path
|
48
|
+
end
|
49
|
+
end
|
50
|
+
end
|
51
|
+
end
|
52
|
+
end
|
53
|
+
end
|
@@ -0,0 +1,11 @@
|
|
1
|
+
{{ text }}
|
2
|
+
|
3
|
+
{% for diagram in package.diagrams %}
|
4
|
+
[[figure-{{ diagram.xmi_id }}]]
|
5
|
+
.{{ diagram.name }}
|
6
|
+
image::{{ image_base_path }}/{{ diagram.xmi_id }}.png[]
|
7
|
+
|
8
|
+
{% if diagram.definition %}
|
9
|
+
{{ diagram.definition | html2adoc }}
|
10
|
+
{% endif %}
|
11
|
+
{% endfor %}
|