= LutaML: Ruby library for accessing data models

== Purpose

LutaML aims to be a universal data model accessor that allows parsing
data models in multiple languages, including:

* EXPRESS (https://www.expresslang.org[EXPRESS Language Foundation], ISO 10303-11)
* XMI (from OMG)
* UML in LutaML format


== Install

With bundler, in `Gemfile`:

[source,ruby]
----
gem "lutaml"
----

Directly:

[source,console]
----
$ gem install lutaml
----

== Usage

=== Parsing

The `Lutaml::Parser.parse` method provides a single point of entry for parsing
data model files.

The return object is always a `Lutaml::LutamlPath::DocumentWrapper` object,
where `#original_document` returns the native parsed models.

[source,ruby]
----
# example.exp is an EXPRESS schema file
wrapper = Lutaml::Parser.parse([File.new("example.exp")])
# => returns a Lutaml::LutamlPath::DocumentWrapper object
wrapper.original_document
# => returns the original Expressir::Repository object
----

[source,ruby]
----
# example.exp.yaml is an EXPRESS cache file created with Expressir
wrapper = Lutaml::Parser.parse([File.new("example.exp.yaml")], ::Lutaml::Parser::EXPRESS_CACHE_PARSE_TYPE)
# => returns the DocumentWrapper but with the repository loaded from the Expressir cache file
----


=== Selecting EXPRESS schemas

LutaML supports the `ModelElement#to_hash(..., select_proc:)` functionality
of Expressir, allowing Expressir to only call `to_hash` on schemas that
fit a dynamic criteria.

The criteria is set via a Ruby `Proc` object, as follows.

[source,ruby]
----
# Sets the filter
filtered_schemas = ["action_schema", "date_time_schema"]

# Sets the Proc
wrapper.select_proc = Proc.new do |value|
  if value.is_a?(Expressir::Model::Declarations::Schema)
    filtered_schemas.include?(value.id)
  else
    true
  end
end

serialized = wrapper.to_liquid
# => returns the filtered to_hash method
----


=== CLI

There is a command-line interface available for parsing supported data model files.

* EXPRESS `*.exp`
* LutaML UML `*.lutaml`
* LutaML YAML datastruct files

[source,bash]
----
# Will generate `test.dot` file in the current directory
$ lutaml -o . test.lutaml

# Will generate `test.png` file in the `assets` directory
$ lutaml -o assets -t png test.lutaml
----

For additional info refer to `lutaml --help output`.


== Copyright and license

Copyright Ribose. BSD-3 License.