lutaml 0.11.4 → 0.11.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.
Files changed (52) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/docs.yml +28 -5
  3. data/.github/workflows/links.yml +14 -0
  4. data/README.adoc +6 -43
  5. data/docs/_config.yml +1 -1
  6. data/docs/_guides/cli-usage.adoc +43 -0
  7. data/docs/_guides/diagram-generation.adoc +3 -3
  8. data/docs/_guides/index.adoc +21 -20
  9. data/docs/_guides/parsing/index.adoc +9 -8
  10. data/docs/_guides/parsing/qea-parsing.adoc +47 -0
  11. data/docs/_guides/repository-management.adoc +44 -0
  12. data/docs/_guides/sysml-modeling.adoc +2 -2
  13. data/docs/_guides/uml-modeling.adoc +3 -5
  14. data/docs/_pages/concepts/diagram-generation.adoc +4 -4
  15. data/docs/_pages/concepts/lur-format.adoc +4 -4
  16. data/docs/_pages/concepts/qea-parsing.adoc +4 -4
  17. data/docs/_pages/concepts/uml-models.adoc +43 -0
  18. data/docs/_pages/core/architecture.adoc +4 -4
  19. data/docs/_pages/core/installation.adoc +7 -7
  20. data/docs/_pages/core/overview.adoc +10 -10
  21. data/docs/_pages/index.adoc +11 -10
  22. data/docs/_pages/uml-syntax.adoc +41 -25
  23. data/docs/_references/api/parsers.adoc +61 -0
  24. data/docs/_references/api/presenters.adoc +43 -0
  25. data/docs/_references/api/repository.adoc +67 -0
  26. data/docs/_references/cli/commands.adoc +72 -0
  27. data/docs/_references/configuration/diagram-styles.adoc +3 -3
  28. data/docs/_references/configuration/index.adoc +5 -4
  29. data/docs/_references/configuration/package-metadata.adoc +4 -4
  30. data/docs/_references/formats/index.adoc +5 -4
  31. data/docs/_references/formats/lur-format.adoc +39 -0
  32. data/docs/_references/formats/qea-structure.adoc +4 -4
  33. data/docs/_references/index.adoc +26 -25
  34. data/docs/_tutorials/documentation-site.adoc +47 -0
  35. data/docs/_tutorials/first-lur-package.adoc +45 -0
  36. data/docs/_tutorials/generating-diagrams.adoc +42 -0
  37. data/docs/_tutorials/getting-started.adoc +45 -0
  38. data/docs/_tutorials/index.adoc +28 -37
  39. data/docs/_tutorials/querying-models.adoc +44 -0
  40. data/docs/examples/build_package.rb +12 -0
  41. data/docs/examples/build_site.rb +12 -0
  42. data/docs/examples/city_model.rb +21 -0
  43. data/docs/examples/present_class.rb +10 -0
  44. data/docs/examples/query_model.rb +12 -0
  45. data/docs/examples/render_diagram.rb +11 -0
  46. data/docs/index.adoc +12 -12
  47. data/docs/lychee.toml +24 -57
  48. data/lib/lutaml/version.rb +1 -1
  49. data/lutaml.gemspec +1 -1
  50. data/scripts/check-site-urls.rb +54 -0
  51. data/scripts/check-vendor-link.py +64 -0
  52. metadata +26 -4
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 801bd028c5c0adbb4f66c7025f6c3a958d57d7f8d9beff937d803f3735792dde
4
- data.tar.gz: 0ec4e7d17155aa3194c850aa31cb3f11d4494aeb92414b403c65e7cc27d96b5e
3
+ metadata.gz: 4df99c138c7cc44cbcaf087c4619b509ad25b92bc98ccc4eba5dbc8285bc5b64
4
+ data.tar.gz: 187bc0dd33e4d506dfaeadb1864cfdf3a6184811be76710c43e7430c4f1bb20f
5
5
  SHA512:
6
- metadata.gz: 8d9af90a66fc40bd2415b7ab1120e2d231b89e7db35845e966e9e3138d1ec4e80d79e56b66d37ff9457dbb29ca363f312a5228b455f5746454f7ea82f121f845
7
- data.tar.gz: f080df35bfdfa37691d74acec208d5863a9aa1fd423f5d750d5cf640fdc89daecb5c9ec6be07cb98f313ae12dadb4eeee106235b1c7a5c714d2bd843ef8ccb83
6
+ metadata.gz: 10e1fed22426ada38466d8c660cf7847c423cb4aef3de5870ae8c0d8516befd4d1ec74012c635ffc83a2cafd8173858e27821ef45fee6a0203a958a5ede54008
7
+ data.tar.gz: c721020920f5e751f657edb145e1551fdf824c56bb19c6f6db1c9e9e0ce83cc21373befeac95e139edcf1cc5a53ad46b05a558192ddb53f86e5037f97fc09c9c
@@ -5,9 +5,11 @@ on:
5
5
  branches: [main]
6
6
  paths:
7
7
  - 'docs/**'
8
+ - '.github/workflows/docs.yml'
8
9
  pull_request:
9
10
  paths:
10
11
  - 'docs/**'
12
+ - '.github/workflows/docs.yml'
11
13
  repository_dispatch:
12
14
  workflow_dispatch:
13
15
 
@@ -21,7 +23,29 @@ concurrency:
21
23
  cancel-in-progress: false
22
24
 
23
25
  jobs:
26
+ examples:
27
+ runs-on: ubuntu-latest
28
+ steps:
29
+ - uses: actions/checkout@v6
30
+
31
+ - uses: ruby/setup-ruby@v1
32
+ with:
33
+ ruby-version: '3.3'
34
+ bundler-cache: true
35
+
36
+ - name: Run the documented Ruby examples
37
+ run: |
38
+ task_examples_dir="$PWD/docs/examples"
39
+ export BUNDLE_GEMFILE="$PWD/Gemfile"
40
+ task_output_dir="$(mktemp -d "${RUNNER_TEMP}/lutaml-docs.XXXXXX")"
41
+ cd "$task_output_dir"
42
+ for example in city_model build_package query_model build_site present_class; do
43
+ bundle exec ruby "$task_examples_dir/$example.rb"
44
+ done
45
+ bundle exec ruby -rlutaml -e 'abort "LML parse failed" unless Lutaml::Lml.parse_document("diagram City { class Building {} }").classes.first.name == "Building"'
46
+
24
47
  build:
48
+ needs: examples
25
49
  runs-on: ubuntu-latest
26
50
  steps:
27
51
  - name: Checkout
@@ -35,12 +59,8 @@ jobs:
35
59
  cache-version: 0
36
60
  working-directory: docs
37
61
 
38
- - name: Setup Pages
39
- id: pages
40
- uses: actions/configure-pages@v5
41
-
42
62
  - name: Build with Jekyll
43
- run: bundle exec jekyll build --verbose --trace --baseurl "${{ steps.pages.outputs.base_path }}"
63
+ run: bundle exec jekyll build --verbose --trace
44
64
  working-directory: docs
45
65
  env:
46
66
  JEKYLL_ENV: production
@@ -58,6 +78,9 @@ jobs:
58
78
  runs-on: ubuntu-latest
59
79
  needs: build
60
80
  steps:
81
+ - name: Setup Pages
82
+ uses: actions/configure-pages@v5
83
+
61
84
  - name: Deploy to GitHub Pages
62
85
  id: deployment
63
86
  uses: actions/deploy-pages@v4
@@ -6,9 +6,15 @@ on:
6
6
  - main
7
7
  paths:
8
8
  - 'docs/**'
9
+ - '.github/workflows/links.yml'
10
+ - 'scripts/check-site-urls.rb'
11
+ - 'scripts/check-vendor-link.py'
9
12
  pull_request:
10
13
  paths:
11
14
  - 'docs/**'
15
+ - '.github/workflows/links.yml'
16
+ - 'scripts/check-site-urls.rb'
17
+ - 'scripts/check-vendor-link.py'
12
18
 
13
19
  # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
14
20
  permissions:
@@ -33,6 +39,14 @@ jobs:
33
39
  run: bundle exec jekyll build --trace
34
40
  working-directory: docs
35
41
 
42
+ - name: Check local and canonical URLs against built pages
43
+ run: ruby scripts/check-site-urls.rb docs/_config.yml docs/_site
44
+
45
+ - name: Check vendor homepage with guarded anti-bot handling
46
+ run: |
47
+ python3 scripts/check-vendor-link.py --self-test
48
+ python3 scripts/check-vendor-link.py
49
+
36
50
  - name: Restore lychee cache
37
51
  uses: actions/cache@v4
38
52
  with:
data/README.adoc CHANGED
@@ -51,56 +51,19 @@ bundle exec jekyll serve
51
51
 
52
52
  === Parsing
53
53
 
54
- The `Lutaml::Parser.parse` method provides a single point of entry for parsing
55
- data model files, including:
56
-
57
- * EXPRESS files with `.exp` extension
58
- * YAML Compressed EXPRESS CACHE files
59
- * QEA files with `.qea` extension (Enterprise Architect databases)
60
- * XMI files with `.xmi` extension
61
- * XML files with `.xml` extension
62
- * LutaML files with `.lutaml` extension
63
-
64
- Depending on the input file type, `Lutaml::Parser.parse` returns:
65
-
66
- * `Expressir::Express::Model::Repository` for EXPRESS files
67
- * `Expressir::Express::Cache` for EXPRESS CACHE files
68
- * `Lutaml::Uml::Document` for QEA files (returned as single-element array)
69
- * `Lutaml::Uml::Document` for XMI files
70
- * `Lutaml::Uml::Document` for XML files
71
- * `Lutaml::Uml::Document` for LutaML files
72
-
73
- Examples to use the `Lutaml::Parser.parse`:
54
+ Parse LutaML Model Language (`.lml`/`.lutaml`) files with
55
+ link:https://github.com/lutaml/lutaml-lml[lutaml-lml]:
74
56
 
75
57
  [source,ruby]
76
58
  ----
77
59
  require "lutaml"
78
60
 
79
- # example.exp is an EXPRESS schema file
80
- model = Lutaml::Parser.parse([File.new("example.exp")])
81
- # => returns Expressir::Express::Model::Repository model
82
-
83
- # example.exp.yaml is an EXPRESS cache file created with Expressir
84
- model = Lutaml::Parser.parse([File.new("example.exp.yaml")], ::Lutaml::Parser::EXPRESS_CACHE_PARSE_TYPE)
85
- # => returns Expressir::Express::Cache model
86
-
87
- # example.xmi is an XMI file
88
- model = Lutaml::Parser.parse([File.new("example.xmi")])
89
- # => returns Lutaml::Uml::Document model
90
-
91
- # example.xml is an XML file
92
- model = Lutaml::Parser.parse([File.new("example.xml")])
93
- # => returns Lutaml::Uml::Document model
94
-
95
- # example.lutaml is an LutaML file
96
- model = Lutaml::Parser.parse([File.new("example.lutaml")])
97
- # => returns Lutaml::Uml::Document model
98
-
99
- # example.yaml is an LutaML YAML file
100
- model = Lutaml::Parser.parse([File.new("example.yaml")])
101
- # => returns Lutaml::Uml::Document model
61
+ doc = Lutaml::Lml.parse_document(File.new("model.lutaml"))
62
+ doc.classes.first.attributes.map(&:name)
102
63
  ----
103
64
 
65
+ EXPRESS schemas parse through `Lutaml::Express::Parsers::Exp.parse(io)`;
66
+ see README.md for the full family table and the repository layer.
104
67
 
105
68
  == Working with UML
106
69
 
data/docs/_config.yml CHANGED
@@ -44,7 +44,7 @@ back_to_top_text: "Back to top"
44
44
  # Footer content
45
45
  footer_content: >-
46
46
  Copyright © 2025 Ribose. Distributed by a
47
- <a href="https://github.com/lutaml/lutaml/blob/main/LICENSE">BSD-3-Clause license</a>.
47
+ <a href="https://opensource.org/licenses/MIT">MIT license</a>.
48
48
 
49
49
  # Footer last edit timestamp
50
50
  last_edit_timestamp: true
@@ -0,0 +1,43 @@
1
+ ---
2
+ permalink: /guides/cli-usage/
3
+ title: Running LutaML Workflows
4
+ parent: Guides
5
+ ---
6
+ = Running LutaML Workflows
7
+
8
+ Run the supported Ruby workflows inside the bundle that declares `gem "lutaml"`.
9
+ This keeps the umbrella, parser, and repository versions together.
10
+ Check your resolved component versions with `bundle info lutaml-lml` and
11
+ `bundle info lutaml-uml` when comparing your installation with these examples.
12
+
13
+ == Start with a script
14
+
15
+ Copy the script from link:{site-baseurl}/tutorials/getting-started/[Getting Started]
16
+ into `city_model.rb`, then run `bundle exec ruby city_model.rb`.
17
+ It prints `Building`, confirming that model creation and indexed lookup work.
18
+ Do not replace this with an old `lutaml uml` invocation: the current packaged
19
+ executable has a missing CLI dependency, as explained in
20
+ link:{site-baseurl}/references/cli/commands/[Command-Line Compatibility].
21
+
22
+ == Run a complete workflow
23
+
24
+ . Create a typed model, or obtain a UML document from a format-specific importer.
25
+ . Construct a repository with `Repository.from_document(document)`.
26
+ . Query the repository or export it with `export_to_package`.
27
+ . Load a saved package with `Repository.from_package` on subsequent runs.
28
+ . Use `StaticSite.generate` when you need a browsable HTML representation.
29
+
30
+ Each step has a runnable example in the link:{site-baseurl}/tutorials/[Tutorials].
31
+ Choose a new output path when running examples so that you keep existing models
32
+ and generated files available for comparison.
33
+
34
+ == Diagnose failures
35
+
36
+ * A `LoadError` for `lutaml/cli` indicates the executable compatibility issue;
37
+ it does not mean the model file has a syntax error.
38
+ * `Repository.from_file` rejecting `.qea` or `.xmi` means parsing belongs to
39
+ an external provider. See link:{site-baseurl}/references/api/parsers/[Parser APIs].
40
+ * A missing Graphviz `dot` executable affects diagram rendering, not UML lookup
41
+ or LUR package generation. Check `dot -V` before running that tutorial.
42
+ * A failed lookup may use the wrong qualified path. Start with `ModelRoot` and
43
+ inspect `list_packages` before choosing the class path.
@@ -311,6 +311,6 @@ Planned features for future releases:
311
311
 
312
312
  == See Also
313
313
 
314
- * link:diagram-configuration[Complete Configuration Reference]
315
- * link:../README[LutaML README]
316
- * link:../config/diagram_styles.yml[Default Styles]
314
+ * link:{site-baseurl}/references/configuration/diagram-styles/[Complete Configuration Reference]
315
+ * link:https://github.com/lutaml/lutaml/blob/main/README.md[LutaML README]
316
+ * link:{site-baseurl}/references/configuration/diagram-styles/#defaults[Default Styles]
@@ -1,4 +1,5 @@
1
1
  = Guides
2
+ :page-permalink: /guides/
2
3
  :nav_order: 3
3
4
  :has_children: true
4
5
 
@@ -8,13 +9,13 @@ This section provides task-oriented how-to documentation for common workflows an
8
9
 
9
10
  == Command-Line Usage
10
11
 
11
- === link:../cli-usage[Complete CLI Guide]
12
+ === link:{site-baseurl}/guides/cli-usage/[Complete CLI Guide]
12
13
 
13
- Comprehensive guide to using LutaML's command-line interface, including all commands, options, and workflows.
14
+ Run the supported Ruby scripts, inspect your bundle, and understand the current executable compatibility boundary.
14
15
 
15
16
  == Diagram Generation
16
17
 
17
- === link:diagram-generation[Generating EA-Style Diagrams]
18
+ === link:{site-baseurl}/guides/diagram-generation/[Generating EA-Style Diagrams]
18
19
 
19
20
  Learn how to generate pixel-perfect SVG diagrams from Enterprise Architect models with full styling support.
20
21
 
@@ -27,42 +28,42 @@ Learn how to generate pixel-perfect SVG diagrams from Enterprise Architect model
27
28
 
28
29
  == Modeling Languages
29
30
 
30
- === link:uml-modeling[UML Modeling with LutaML]
31
+ === link:{site-baseurl}/guides/uml-modeling/[UML Modeling with LutaML]
31
32
 
32
33
  Work with UML class diagrams using LutaML's native syntax and conversion tools.
33
34
 
34
- === link:sysml-modeling[SysML Modeling with LutaML]
35
+ === link:{site-baseurl}/guides/sysml-modeling/[SysML Modeling with LutaML]
35
36
 
36
37
  Extend UML with SysML concepts for systems engineering and MBSE workflows.
37
38
 
38
39
  == Configuration & Customization
39
40
 
40
- === link:../references/configuration/diagram-styles[Configuring Diagram Styles]
41
+ === link:{site-baseurl}/references/configuration/diagram-styles/[Configuring Diagram Styles]
41
42
 
42
43
  Learn how to customize diagram colors, fonts, and styling using YAML configuration files.
43
44
 
44
- === link:../references/configuration/package-metadata[Setting Up Package Metadata]
45
+ === link:{site-baseurl}/references/configuration/package-metadata/[Setting Up Package Metadata]
45
46
 
46
47
  Configure XML namespaces, schema locations, and other metadata for UML packages.
47
48
 
48
- === link:repository-management[Managing Repositories]
49
+ === link:{site-baseurl}/guides/repository-management/[Managing Repositories]
49
50
 
50
- Best practices for organizing, versioning, and maintaining LUR repositories.
51
+ Build, cache, and verify LUR repositories while preserving source models.
51
52
 
52
53
  == Parsing Guides
53
54
 
54
- === link:parsing/qea-parsing[Parsing QEA Files]
55
+ === link:{site-baseurl}/guides/parsing/qea-parsing/[Parsing QEA Files]
55
56
 
56
- How to parse Enterprise Architect QEA files directly from SQLite databases.
57
+ Connect a separate QEA importer to the typed UML repository and verify its output.
57
58
 
58
59
  **Topics covered:**
59
60
 
60
- * File validation
61
- * Performance optimization
62
- * Handling large models
63
- * Error recovery
61
+ * Importer and repository boundaries
62
+ * Checking the returned document type
63
+ * Preserving source IDs
64
+ * Verifying imported results
64
65
 
65
- === link:parsing/xmi-parsing[Parsing XMI Files]
66
+ === link:{site-baseurl}/guides/parsing/xmi-parsing/[Parsing XMI Files]
66
67
 
67
68
  Working with OMG XMI format exports from various UML tools.
68
69
 
@@ -73,7 +74,7 @@ Working with OMG XMI format exports from various UML tools.
73
74
  * Profile support
74
75
  * Validation
75
76
 
76
- === link:parsing/express-parsing[Parsing EXPRESS Schemas]
77
+ === link:{site-baseurl}/guides/parsing/express-parsing/[Parsing EXPRESS Schemas]
77
78
 
78
79
  Handle ISO 10303-11 EXPRESS schemas used in industrial standards.
79
80
 
@@ -130,6 +131,6 @@ Each guide follows this structure:
130
131
 
131
132
  == Related Sections
132
133
 
133
- * link:../tutorials[Tutorials] - Step-by-step learning paths
134
- * link:../pages[Core Topics] - Fundamental concepts
135
- * link:../references[Reference] - Detailed specifications
134
+ * link:{site-baseurl}/tutorials/[Tutorials] - Step-by-step learning paths
135
+ * link:{site-baseurl}/core/[Core Topics] - Fundamental concepts
136
+ * link:{site-baseurl}/references/[Reference] - Detailed specifications
@@ -1,4 +1,5 @@
1
1
  ---
2
+ permalink: /guides/parsing/
2
3
  title: Parsing Guides
3
4
  parent: Guides
4
5
  nav_order: 20
@@ -11,7 +12,7 @@ Comprehensive guides for parsing different model formats with LutaML.
11
12
 
12
13
  == Available Parsing Guides
13
14
 
14
- === link:express-parsing[EXPRESS Parsing]
15
+ === link:{site-baseurl}/guides/parsing/express-parsing/[EXPRESS Parsing]
15
16
 
16
17
  Guide for parsing ISO 10303-11 EXPRESS schemas used in industrial standards.
17
18
 
@@ -22,7 +23,7 @@ Guide for parsing ISO 10303-11 EXPRESS schemas used in industrial standards.
22
23
  * Model transformation
23
24
  * Integration examples
24
25
 
25
- === link:xmi-parsing[XMI Parsing]
26
+ === link:{site-baseurl}/guides/parsing/xmi-parsing/[XMI Parsing]
26
27
 
27
28
  Guide for parsing OMG XMI format exports from UML tools.
28
29
 
@@ -37,9 +38,9 @@ Guide for parsing OMG XMI format exports from UML tools.
37
38
 
38
39
  Enterprise Architect QEA format parsing is covered in multiple locations:
39
40
 
40
- * link:../../pages/concepts/qea-parsing[Concept Overview] - Understanding QEA
41
- * link:../../references/formats/qea-structure[Format Specification] - Complete details
42
- * link:../../tutorials/getting-started[Tutorial] - Step-by-step walkthrough
41
+ * link:{site-baseurl}/concepts/qea-parsing/[Concept Overview] - Understanding QEA
42
+ * link:{site-baseurl}/references/formats/qea-structure/[Format Specification] - Complete details
43
+ * link:{site-baseurl}/tutorials/getting-started/[Tutorial] - Step-by-step walkthrough
43
44
 
44
45
  == Common Parsing Patterns
45
46
 
@@ -72,6 +73,6 @@ end
72
73
 
73
74
  == Related Documentation
74
75
 
75
- * link:../../references/formats[Format Specifications] - Technical details
76
- * link:../../tutorials/getting-started[Getting Started] - Basic parsing tutorial
77
- * link:../../references/api/parsers[Parser API Reference] - Complete API docs
76
+ * link:{site-baseurl}/references/formats/[Format Specifications] - Technical details
77
+ * link:{site-baseurl}/tutorials/getting-started/[Getting Started] - Basic parsing tutorial
78
+ * link:{site-baseurl}/references/api/parsers/[Parser API Reference] - Complete API docs
@@ -0,0 +1,47 @@
1
+ ---
2
+ permalink: /guides/parsing/qea-parsing/
3
+ title: Integrating QEA Parsing
4
+ parent: Guides
5
+ ---
6
+ = Integrating QEA Parsing
7
+
8
+ QEA is Enterprise Architect's SQLite model format. In the split LutaML family,
9
+ QEA import and UML repository indexing are separate operations.
10
+ `lutaml-uml` 1.0.3 does not ship a QEA parser, and
11
+ `Repository.from_file("model.qea")` deliberately rejects that extension.
12
+
13
+ == Select and verify an importer
14
+
15
+ Use a QEA-capable provider that supports your EA schema version. Follow that
16
+ provider's installation and parsing contract; installing the `lutaml` umbrella
17
+ alone does not add a QEA parser. Work from a consistent saved copy of the EA
18
+ database so that its object and diagram tables describe the same model state.
19
+
20
+ The repository integration requires a `Lutaml::Uml::Document`.
21
+ Check the provider's result type and convert it explicitly if it uses a
22
+ different model family. A similarly named `Document` class is not sufficient.
23
+
24
+ == Build the repository
25
+
26
+ Once your importer has produced `document`:
27
+
28
+ [source,ruby]
29
+ ----
30
+ raise TypeError, "Expected a UML document" unless document.is_a?(Lutaml::Uml::Document)
31
+
32
+ repository = Lutaml::UmlRepository::Repository.from_document(document)
33
+ puts repository.statistics
34
+ ----
35
+
36
+ Verify a known package path and class, then inspect association and diagram
37
+ counts. Preserve source IDs when converting objects so that relationship and
38
+ diagram references remain meaningful. An empty repository is not proof of a
39
+ successful import merely because no exception occurred.
40
+
41
+ == Preserve and inspect results
42
+
43
+ Export the verified repository as a LUR package, keeping the QEA source and
44
+ importer configuration. See link:{site-baseurl}/tutorials/first-lur-package/[LUR
45
+ package creation] and link:{site-baseurl}/references/formats/qea-structure/[QEA
46
+ database structure]. Stored diagram objects and rendered SVG are different
47
+ outputs; a successful object import alone does not establish rendering support.
@@ -0,0 +1,44 @@
1
+ ---
2
+ permalink: /guides/repository-management/
3
+ title: Managing Repositories
4
+ parent: Guides
5
+ ---
6
+ = Managing Repositories
7
+
8
+ Keep source models, parser configuration, and generated LUR packages distinct.
9
+ A package accelerates repeated access; the original source remains necessary
10
+ for re-importing after model or dependency changes.
11
+
12
+ == Build and name artifacts
13
+
14
+ Create a repository from a UML document and export it to a versioned output path.
15
+ Record the source revision and retain your application's `Gemfile.lock`.
16
+ Package metadata describes the model, while the lockfile records the dependency
17
+ versions used to create it. See
18
+ link:{site-baseurl}/references/configuration/package-metadata/[Package Metadata].
19
+
20
+ == Refresh indexes
21
+
22
+ `Repository.from_document` builds indexes from the document's current contents.
23
+ If your application changes classes, packages, or relationships in memory,
24
+ construct a new repository from the changed document before querying or exporting.
25
+ Do not edit stored index YAML independently of the model.
26
+
27
+ == Cache imported sources
28
+
29
+ `Repository.from_file_cached(source_path, lur_path: cache_path)` takes a block
30
+ that parses the source and returns a UML document. A cache at least as new as
31
+ the source is reused; otherwise the block runs and a new package is written.
32
+ That timestamp check does not detect changed parser options or dependencies.
33
+ Choose a fresh cache path or explicitly regenerate after those changes.
34
+
35
+ == Verify a saved package
36
+
37
+ Load it with `Repository.from_package`, check a known qualified class name,
38
+ and compare expected counts from `statistics`. The
39
+ link:{site-baseurl}/tutorials/first-lur-package/[first package tutorial] performs
40
+ an export/reload check rather than only checking that a file exists.
41
+
42
+ For large packages, `from_package_lazy` defers index construction.
43
+ Choose eager or lazy loading based on your access pattern; neither changes the
44
+ source model's format or provides a QEA importer.
@@ -33,5 +33,5 @@ Since SysML extends UML, all UML modeling capabilities are available in SysML mo
33
33
 
34
34
  == See Also
35
35
 
36
- * link:uml-modeling[UML Modeling Guide]
37
- * link:../README[LutaML Documentation]
36
+ * link:{site-baseurl}/guides/uml-modeling/[UML Modeling Guide]
37
+ * link:https://github.com/lutaml/lutaml/blob/main/README.md[LutaML Documentation]
@@ -11,7 +11,7 @@ converting it into various different formats.
11
11
 
12
12
  == Language
13
13
 
14
- See link:lutaml_syntax[LutaML syntax]
14
+ See link:{site-baseurl}/uml-syntax/[LutaML syntax]
15
15
 
16
16
  == Usages
17
17
 
@@ -104,12 +104,10 @@ The following results will be produced:
104
104
  [source,lutaml]
105
105
  ----
106
106
  diagram Address {
107
- title ''
108
- caption ''
109
107
  association {
110
108
  owner_type aggregation
111
- owner
112
- member_type direct
109
+ owner Address
110
+ member_type association
113
111
  member AddressComponent
114
112
  }
115
113
  }
@@ -331,7 +331,7 @@ Diagram generation is **production-ready** with:
331
331
 
332
332
  == See Also
333
333
 
334
- * link:../../guides/diagram-generation[Diagram Generation Guide] - Complete walkthrough
335
- * link:../../references/configuration/diagram-styles[Styling Configuration] - Full config reference
336
- * link:../../tutorials/generating-diagrams[Tutorial] - Step-by-step guide
337
- * link:../architecture[System Architecture] - Technical details
334
+ * link:{site-baseurl}/guides/diagram-generation/[Diagram Generation Guide] - Complete walkthrough
335
+ * link:{site-baseurl}/references/configuration/diagram-styles/[Styling Configuration] - Full config reference
336
+ * link:{site-baseurl}/tutorials/generating-diagrams/[Tutorial] - Step-by-step guide
337
+ * link:{site-baseurl}/core/architecture/[System Architecture] - Technical details
@@ -705,7 +705,7 @@ repo = Lutaml::UmlRepository::Repository.from_package("model.lur",
705
705
 
706
706
  == See Also
707
707
 
708
- * link:qea-parsing[QEA Direct Parsing]
709
- * link:../architecture[System Architecture]
710
- * link:../../tutorials/first-lur-package[Tutorial: Building LUR Packages]
711
- * link:../../guides[Repository Management Guide]
708
+ * link:{site-baseurl}/concepts/qea-parsing/[QEA Direct Parsing]
709
+ * link:{site-baseurl}/core/architecture/[System Architecture]
710
+ * link:{site-baseurl}/tutorials/first-lur-package/[Tutorial: Building LUR Packages]
711
+ * link:{site-baseurl}/guides/[Repository Management Guide]
@@ -412,7 +412,7 @@ tables:
412
412
 
413
413
  == See Also
414
414
 
415
- * link:../../references/formats/qea-structure[Complete QEA Format Specification]
416
- * link:../architecture[System Architecture]
417
- * link:lur-format[LUR Package Format]
418
- * link:../../guides/parsing[Parsing Guides]
415
+ * link:{site-baseurl}/references/formats/qea-structure/[Complete QEA Format Specification]
416
+ * link:{site-baseurl}/core/architecture/[System Architecture]
417
+ * link:{site-baseurl}/concepts/lur-format/[LUR Package Format]
418
+ * link:{site-baseurl}/guides/parsing/[Parsing Guides]
@@ -0,0 +1,43 @@
1
+ ---
2
+ permalink: /concepts/uml-models/
3
+ title: UML Model Structure
4
+ parent: Core Topics
5
+ ---
6
+ = UML Model Structure
7
+
8
+ `lutaml-uml` represents a model as a `Lutaml::Uml::Document`. A document contains
9
+ packages, classifiers, associations, and diagrams. The repository adds indexes
10
+ and queries around that document; it is not a second parser.
11
+
12
+ == Elements and containment
13
+
14
+ * `Document` contains top-level `packages`, `classes`, `data_types`, `enums`,
15
+ `associations`, and `diagrams`.
16
+ * `Package` can contain nested packages and its own classifiers and diagrams.
17
+ * `UmlClass` contains attributes, operations, stereotypes, and relationships.
18
+ The Ruby class is `Lutaml::Uml::UmlClass`, not `Lutaml::Uml::Class`.
19
+ * `TopElementAttribute` describes a class attribute; `Association` describes
20
+ a relationship. These are separate from the Ruby language's class attributes.
21
+
22
+ Elements derived from `TopElement` expose names, IDs, visibility, stereotypes,
23
+ definitions, and tagged values. Preserve source IDs when importing a model so
24
+ that relationships and diagram references can identify the same elements.
25
+
26
+ == Repository paths
27
+
28
+ The index builder places the document under the synthetic path `ModelRoot`.
29
+ A Building class inside a City package therefore has the qualified name
30
+ `ModelRoot::City::Building`, regardless of the document's display name.
31
+ Nested packages extend that path with further `::` segments.
32
+
33
+ `Repository.from_document(document)` builds indexes from these collections.
34
+ If you mutate the document afterward, construct a fresh repository to refresh
35
+ its indexes. The link:{site-baseurl}/tutorials/getting-started/[getting-started
36
+ tutorial] creates this structure directly and checks the resulting lookup.
37
+
38
+ == Language boundaries
39
+
40
+ `Lutaml::Lml::Document` is the textual LML parser's model, while Expressir has
41
+ its own EXPRESS models. Similar method names do not make these objects
42
+ interchangeable with UML documents. Use an explicit importer or conversion step
43
+ before indexing another language's result as a UML repository.
@@ -323,7 +323,7 @@ lib/lutaml/
323
323
 
324
324
  == Related Documentation
325
325
 
326
- * link:concepts/qea-parsing[QEA Parsing] - Parse layer details
327
- * link:concepts/lur-format[LUR Format] - Repository format
328
- * link:concepts/diagram-generation[Diagram Generation] - Rendering pipeline
329
- * link:../guides[Guides] - Implementation guides
326
+ * link:{site-baseurl}/concepts/qea-parsing/[QEA Parsing] - Parse layer details
327
+ * link:{site-baseurl}/concepts/lur-format/[LUR Format] - Repository format
328
+ * link:{site-baseurl}/concepts/diagram-generation/[Diagram Generation] - Rendering pipeline
329
+ * link:{site-baseurl}/guides/[Guides] - Implementation guides
@@ -304,18 +304,18 @@ $ rm -rf ~/.lutaml
304
304
 
305
305
  Now that LutaML is installed:
306
306
 
307
- 1. link:../tutorials/getting-started[Quick Start Tutorial] - Your first steps
308
- 2. link:../guides/cli-usage[CLI Usage Guide] - Learn the commands
309
- 3. link:../references/cli/commands[Command Reference] - Complete CLI docs
307
+ 1. link:{site-baseurl}/tutorials/getting-started/[Quick Start Tutorial] - Your first steps
308
+ 2. link:{site-baseurl}/guides/cli-usage/[CLI Usage Guide] - Learn the commands
309
+ 3. link:{site-baseurl}/references/cli/commands/[Command Reference] - Complete CLI docs
310
310
 
311
311
  == Getting Help
312
312
 
313
313
  * **Documentation**: https://lutaml.github.io/lutaml/
314
314
  * **Issues**: https://github.com/lutaml/lutaml/issues
315
- * **Discussions**: https://github.com/lutaml/lutaml/discussions
315
+ * **Contributions**: https://github.com/lutaml/lutaml/pulls
316
316
 
317
317
  == See Also
318
318
 
319
- * link:overview[What is LutaML?]
320
- * link:architecture[System Architecture]
321
- * link:../tutorials/getting-started[Getting Started Tutorial]
319
+ * link:{site-baseurl}/core/overview/[What is LutaML?]
320
+ * link:{site-baseurl}/core/architecture/[System Architecture]
321
+ * link:{site-baseurl}/tutorials/getting-started/[Getting Started Tutorial]