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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: bfe1f241f558def33ef0fc13446d842d50aac1b1003cade580fa3b62e730b722
4
- data.tar.gz: 2d12efe1688915194f16cd857e6ca4deaf9852b98407112363bf106dcf3e60a9
3
+ metadata.gz: 636e4bec2488f6e9044ab15915f37485cf08ddcec31e2e852c9d381188b2d99e
4
+ data.tar.gz: c9c0e74be3a5d5856336f5202c7cb18e442d18548e1a29f476b72694d767eac5
5
5
  SHA512:
6
- metadata.gz: d6c46b1d885bc2cb06ea76c4dd5ff057e2b2944579403c8582b43e8a66fe5cb67046b49c1d00526410aba63c0f1614900d3a65e681d67e5f75a3d9b66fc18fd9
7
- data.tar.gz: 3da558c2e348387e60bdc1d0b079150c032e11dcf60731b8083b766dc129b10322c9e3f06892bfc06b8524df1ad453ed1d519153b19f55c7b34734ed20e4f614
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 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`);
68
-
69
- * `{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]
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` 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:
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 express files context for the later use with lutaml macro
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 express files or path to yaml index file to parse
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 expressir cache file to use
115
+ * `cache_path` - optional, location of the Expressir cache file to use
100
116
 
101
- Example of real usage:
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 datamodel attributes/values tables. Given `example.lutaml` file with the content:
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
- See https://www.metanorma.com.
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 %}