expressir 2.1.15 → 2.1.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebacd504321a9a5298e41193d5739458ece4cb77971721a1abab68aa2d42a28f
-  data.tar.gz: 8e9881151845c7716af9fe10088867f1fa3fb6ca37231db4c4c20ffef74f54c7
+  metadata.gz: 5018391261c5ce2fbad69c753c2e1b14e11b2cf39e49b57a984ec00be70e2055
+  data.tar.gz: 35b88b0188c829f57ec86455bfcd8f8ee073c0df8c0fa16456990eb28af33a00
 SHA512:
-  metadata.gz: f44c8c856af5ce6b6c2bb72fc3a600ed58b0adcfad91371944d83c070d434a9472cbd06b2596e9f7ba20ca7ca3a258f9a7410a75625536bb7c36b2a73c4f094e
-  data.tar.gz: 93c84f64ba62d33f358e5144d508db7db349ed67097f92dc0fc8ef5ab2139118d072609fdaabf7023529429fd33fc2867528f89cf5a73bd58db1ccf10a3eb44a
+  metadata.gz: 6e3b27dd2b3fd8709ae737ec43cc694630e90d2f49530520a7f7d27e86cbe635cf46b143b15c6cff339fed452929422c23b70f8fe066543407aa748fe40cf224
+  data.tar.gz: a0f67b51074b9db60f54f500ad3b15ad4f22cd58ddd5cd895bd39a792afd4d2be0eb1d94da28766622702634b216a4ce234e9c930462a528ffe1ee644f7aee02

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-03-19 17:57:28 UTC using RuboCop version 1.74.0.
+# on 2025-03-21 10:31:17 UTC using RuboCop version 1.74.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -26,7 +26,7 @@ Lint/ShadowingOuterLocalVariable:
   Exclude:
     - 'lib/expressir/express/visitor.rb'
 
-# Offense count: 3
+# Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AutoCorrect, AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods, NotImplementedExceptions.
 # NotImplementedExceptions: NotImplementedError
@@ -35,43 +35,50 @@ Lint/UnusedMethodArgument:
     - 'lib/expressir/express/cache.rb'
     - 'lib/expressir/express/parser.rb'
 
-# Offense count: 48
+# Offense count: 61
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Exclude:
+    - 'lib/expressir/benchmark.rb'
+    - 'lib/expressir/cli.rb'
+    - 'lib/expressir/config.rb'
     - 'lib/expressir/express/formatter.rb'
     - 'lib/expressir/express/hyperlink_formatter.rb'
+    - 'lib/expressir/express/parser.rb'
     - 'lib/expressir/express/resolve_references_model_visitor.rb'
     - 'lib/expressir/express/visitor.rb'
     - 'lib/expressir/model/declarations/schema.rb'
     - 'lib/expressir/model/model_element.rb'
 
-# Offense count: 1
+# Offense count: 2
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 # AllowedMethods: refine
 Metrics/BlockLength:
   Max: 141
 
-# Offense count: 40
+# Offense count: 45
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Exclude:
+    - 'lib/expressir/benchmark.rb'
     - 'lib/expressir/express/formatter.rb'
     - 'lib/expressir/express/model_visitor.rb'
+    - 'lib/expressir/express/parser.rb'
     - 'lib/expressir/express/visitor.rb'
     - 'lib/expressir/model/declarations/schema.rb'
     - 'lib/expressir/model/model_element.rb'
     - 'spec/support/model_element_helper.rb'
 
-# Offense count: 67
+# Offense count: 80
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 34
+  Max: 44
 
-# Offense count: 32
+# Offense count: 35
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Exclude:
+    - 'lib/expressir/benchmark.rb'
     - 'lib/expressir/express/formatter.rb'
     - 'lib/expressir/express/visitor.rb'
     - 'lib/expressir/model/declarations/schema.rb'

data/README.adoc

@@ -30,7 +30,41 @@ Expressir consists of 3 parts:
 // ** OMG UML 2 for Eclipse (XMI 2.1)
 
 
-== Usage
+== Installation
+
+Add this line to your application's `Gemfile`:
+
+[source, sh]
+----
+gem "expressir"
+----
+
+And then execute:
+
+[source, sh]
+----
+$ bundle install
+----
+
+Or install it yourself as:
+
+[source, sh]
+----
+$ gem install expressir
+----
+
+
+== Testing
+
+Run the test suite:
+
+[source, sh]
+----
+bundle exec rake
+----
+
+
+== Usage: CLI
 
 This gem ships with a CLI tool. To check what's available you can simply run
 `expressir`, by default it will display some usage instructions.
@@ -40,9 +74,13 @@ This gem ships with a CLI tool. To check what's available you can simply run
 $ expressir
 
 Commands:
-  expressir format PATH     # pretty print EXPRESS schema located at PATH
-  expressir help [COMMAND]  # Describe available commands or one specific command
-  expressir version         # The Expressir Version
+  expressir benchmark FILE_OR_YAML             # Benchmark schema loading performance for a file or list of files from YAML
+  expressir benchmark-cache FILE_OR_YAML       # Benchmark schema loading with caching
+  expressir clean PATH                         # Strip remarks and prettify EXPRESS schema at PATH
+  expressir format PATH                        # pretty print EXPRESS schema located at PATH
+  expressir help [COMMAND]                     # Describe available commands or one specific command
+  expressir validate *PATH                     # validate EXPRESS schema located at PATH
+  expressir version                            # Expressir Version
 ----
 
 === Pretty print
@@ -52,97 +90,189 @@ Commands:
 expressir format schemas/resources/action_schema/action_schema.exp
 ----
 
+=== Clean schema
+
+The `clean` command strips remarks and prettifies EXPRESS schemas. You can
+optionally save the result to a file.
+
+[source, sh]
+----
+# Output to stdout
+expressir clean schemas/resources/action_schema/action_schema.exp
 
-== Development
+# Save to file
+expressir clean schemas/resources/action_schema/action_schema.exp --output clean_schema.exp
+----
 
-We are following Sandi Metz's Rules for this gem, you can read
-the http://robots.thoughtbot.com/post/50655960596/sandi-metz-rules-for-developers[description of the rules here] All new code should follow these rules.
-If you make changes in a pre-existing file that violates these rules you should
-fix the violations as part of your contribution.
+=== Benchmarking
 
-=== Setup
+Expressir includes powerful benchmarking capabilities for measuring schema
+loading performance. You can benchmark individual files or multiple files listed
+in a YAML configuration.
 
-Clone the repository.
+==== Benchmark a single file
 
 [source, sh]
 ----
-git clone https://github.com/metanorma/expressir
+# Basic benchmarking
+expressir benchmark schemas/resources/action_schema/action_schema.exp
+
+# With detailed output
+expressir benchmark schemas/resources/action_schema/action_schema.exp --verbose
+
+# Using benchmark-ips for more detailed statistics
+expressir benchmark schemas/resources/action_schema/action_schema.exp --ips
+
+# With specific output format
+expressir benchmark schemas/resources/action_schema/action_schema.exp --format json
+----
+
+==== Benchmark multiple files from YAML
+
+Create a YAML file with a list of schema paths:
+
+.schemas.yml
+[source, yaml]
+----
+schemas:
+  - schemas/resources/action_schema/action_schema.exp
+  - schemas/resources/approval_schema/approval_schema.exp
+  - schemas/resources/date_time_schema/date_time_schema.exp
 ----
 
-Setup your environment.
+Then benchmark all schemas at once:
 
 [source, sh]
 ----
-bin/setup
-git submodule update --init
-bundle exec rake generate
-bundle exec rake compile
+expressir benchmark schemas.yml --verbose
 ----
 
-Run the test suite
+==== Benchmark with caching
+
+You can also benchmark schema loading with caching to measure parsing time,
+cache writing time, and cache reading time:
 
 [source, sh]
 ----
-bundle exec rake
+# Benchmark a single file with caching
+expressir benchmark-cache schemas/resources/action_schema/action_schema.exp
+
+# With custom cache location
+expressir benchmark-cache schemas/resources/action_schema/action_schema.exp --cache_path /tmp/schema_cache.bin
+
+# Benchmark multiple files from YAML with caching
+expressir benchmark-cache schemas.yml --verbose
 ----
 
+==== Benchmark options
 
+The benchmark commands support several options:
 
-== Installation
+[options="header"]
+|===
+| Option | Description
+| `--ips` | Use benchmark-ips for detailed statistics
+| `--verbose` | Show detailed output
+| `--save` | Save benchmark results to file
+| `--format FORMAT` | Output format: json, csv, or default
+| `--cache_path PATH` | (benchmark-cache only) Path to store the cache file
+|===
 
-Add this line to your application's `Gemfile`:
+When using the `--format json` option, results will be output in JSON format,
+making it easy to parse for further analysis or visualization.
 
-[source, sh]
+
+
+== Usage: Ruby
+
+=== Parsing EXPRESS schema files
+
+==== General
+
+The library provides two main methods for parsing EXPRESS files.
+
+==== Parsing a single file
+
+Use the `from_file` method to parse a single EXPRESS schema file:
+
+[source,ruby]
 ----
-gem "expressir"
+# Parse a single file
+repository = Expressir::Express::Parser.from_file("path/to/schema.exp")
+
+# With options
+repository = Expressir::Express::Parser.from_file(
+  "path/to/schema.exp",
+  skip_references: false,  # Set to true to skip resolving references
+  include_source: true,    # Set to true to include original source in the model
+  root_path: "/base/path"  # Optional base path for relative paths
+)
 ----
 
-And then execute:
+The `from_file` method will raise a `SchemaParseFailure` exception if the schema
+fails to parse, providing information about the specific file and the parsing
+error:
 
-[source, sh]
+[source,ruby]
 ----
-$ bundle install
+begin
+  repository = Expressir::Express::Parser.from_file("path/to/schema.exp")
+rescue Expressir::Express::Error::SchemaParseFailure => e
+  puts "Failed to parse schema: #{e.message}"
+  puts "Filename: #{e.filename}"
+  puts "Error details: #{e.parse_failure_cause.ascii_tree}"
+end
 ----
 
-Or install it yourself as:
+==== Parsing multiple files
 
-[source, sh]
+Use the `from_files` method to parse multiple EXPRESS schema files:
+
+[source,ruby]
 ----
-$ gem install expressir
+# Parse multiple files
+files = ["schema1.exp", "schema2.exp", "schema3.exp"]
+repository = Expressir::Express::Parser.from_files(files)
 ----
 
+You can provide a block to track loading progress and handle errors:
 
-== Usage
+[source,ruby]
+----
+files = ["schema1.exp", "schema2.exp", "schema3.exp"]
+repository = Expressir::Express::Parser.from_files(files) do |filename, schemas, error|
+  if error
+    puts "Error loading #{filename}: #{error.message}"
+    # Skip the file with an error or take other action
+  else
+    puts "Successfully loaded #{schemas.length} schemas from #{filename}"
+  end
+end
+----
 
 === Filtering out schemas
 
-Use the `select_proc` argument of `to_hash`.
-
-Example:
+You can filter out specific schemas from the repository easily since
+`Expressir::Model::Repository` implements `Enumerable`.
 
 [source,ruby]
 ----
-
 schema_yaml = YAML.load_file('documents/iso-10303-41/schemas.yaml')
 schema_paths = schema_yaml['schemas'].map {|x,y| y['path'].gsub("../../", "")}
 
 repo = Expressir::Express::Parser.from_files(schema_paths)
 
 filtered_schemas = ["action_schema", "date_time_schema"]
-select_proc = Proc.new do |value|
-  if value.is_a?(Expressir::Model::Declarations::Schema)
-    filtered_schemas.include?(value.id)
-  else
-    true
-  end
+repo.select do |schema|
+  filtered_schemas.include?(schema.name)
+end.each do |schema|
+  puts "Schema name: #{schema.name}"
+  puts "Schema file: #{schema.file}"
+  puts "Schema version: #{schema.version}"
 end
-
-repo_hash = repo.to_hash(select_proc: select_proc)
-schemas = repo_hash['schemas']
-schemas.map {|s| s["id"] }
 ----
 
-=== Convert models to liquid
+=== Convert models to Liquid
 
 Use `to_liquid` method to convert the models of `Expressir::Model::*` to liquid
 drop models (`Expressir::Liquid::*`).
@@ -158,24 +288,24 @@ repo_drop = repo.to_liquid
 where `repo` is an instance of `Expressir::Model::Repository` and
 `repo_drop` is an instance of `Expressir::Liquid::RepositoryDrop`.
 
-The liquid drop models of `Expressir::Liquid::*` have the same attributes
+The Liquid drop models of `Expressir::Liquid::*` have the same attributes
 (`model_attr`) as the models of `Expressir::Model::*`.
 
 For example, `Expressir::Model::Repository` has the following attributes:
 
-- schemas
+* `schemas`
 
 and each `Expressir::Model::Declarations::Schema` has the following attributes:
 
-- file
-- version
-- interfaces
-- constants
-- entities
-- subtype_constraints
-- functions
-- rules
-- procedures
+* `file`
+* `version`
+* `interfaces`
+* `constants`
+* `entities`
+* `subtype_constraints`
+* `functions`
+* `rules`
+* `procedures`
 
 Thus, `Expressir::Liquid::Repository` has the same attribute `schemas`
 and `Expressir::Liquid::Declarations::SchemaDrop` has same attribute `file`.
@@ -188,6 +318,7 @@ schema = repo_drop.schemas.first
 schema.file = "path/to/file.exp"
 ----
 
+
 == Contributing
 
 First, thank you for contributing! We love pull requests from everyone. By
@@ -207,12 +338,23 @@ Here are a few technical guidelines to follow:
 * Party!
 
 
+== Documentation
+
+Expressir provides detailed documentation on various aspects of its functionality:
+
+* link:docs/benchmarking.adoc[Benchmarking]: Learn about Expressir's built-in
+capabilities for measuring schema loading performance, particularly useful for
+large schemas or when optimizing performance.
+
+* link:docs/liquid_drops.adoc[Liquid Integration]: Documentation on how to use
+Expressir models with Liquid templates for flexible document generation.
+
 == License
 
 Expressir is distributed under the BSD 2-clause license.
 
-Expressir originally contained some code from the NIST Reeper project but
-has been completely rewritten.
+NOTE: Expressir originally contained some code from the NIST Reeper project but no
+longer contains them.
 
 The https://www.nist.gov/services-resources/software/reeper[NIST Reeper license]
 is reproduced below:

data/docs/benchmarking.adoc

@@ -0,0 +1,107 @@
+= Benchmarking schema loading in Expressir
+
+Expressir provides built-in benchmarking capabilities for measuring schema
+loading performance. This is particularly useful for large schemas or when
+optimizing performance.
+
+== Activating benchmark mode
+
+Benchmark mode can be activated using environment variables:
+
+[source,bash]
+----
+# Basic benchmarking
+EXPRESSIR_BENCHMARK=true ruby your_script.rb
+
+# Verbose output with timing for each file
+EXPRESSIR_BENCHMARK=true EXPRESSIR_BENCHMARK_VERBOSE=true ruby your_script.rb
+
+# Use benchmark-ips for more detailed statistics
+EXPRESSIR_BENCHMARK=true EXPRESSIR_BENCHMARK_IPS=true ruby your_script.rb
+
+# Save benchmark results to file
+EXPRESSIR_BENCHMARK=true EXPRESSIR_BENCHMARK_SAVE=true ruby your_script.rb
+----
+
+== Environment variables
+
+The following environment variables control benchmarking:
+
+|===
+| Variable | Description | Default
+
+| `EXPRESSIR_BENCHMARK`
+| Enable benchmarking mode
+| `false`
+
+| `EXPRESSIR_BENCHMARK_IPS`
+| Use benchmark-ips for detailed statistics
+| `false`
+
+| `EXPRESSIR_BENCHMARK_VERBOSE`
+| Show verbose output for benchmarking
+| `false`
+
+| `EXPRESSIR_BENCHMARK_SAVE`
+| Save benchmark results to file
+| `false`
+
+| `EXPRESSIR_BENCHMARK_ITERATIONS`
+| Number of iterations for benchmark-ips
+| `3`
+
+| `EXPRESSIR_BENCHMARK_WARMUP`
+| Warmup time for benchmark-ips in seconds
+| `1`
+
+| `EXPRESSIR_BENCHMARK_PARALLEL`
+| Enable parallel processing (future feature)
+| `false`
+|===
+
+== Sample usage
+
+A sample benchmark script is provided at
+`spec/benchmarks/schema_loading_benchmark.rb`. You can run it with various
+configurations to see the benchmarking in action:
+
+[source,bash]
+----
+# Basic benchmarking
+EXPRESSIR_BENCHMARK=true ruby spec/benchmarks/schema_loading_benchmark.rb
+
+# Detailed IPS benchmarking
+EXPRESSIR_BENCHMARK=true EXPRESSIR_BENCHMARK_IPS=true ruby spec/benchmarks/schema_loading_benchmark.rb
+----
+
+== Programmatic access
+
+You can also access benchmarking functionality programmatically:
+
+[source,ruby]
+----
+require 'expressir'
+
+# Check if benchmarking is enabled
+if Expressir.configuration.benchmark_enabled?
+  puts "Benchmarking is active"
+end
+
+# Measure a specific operation
+result = Expressir::Benchmark.measure_file("path/to/file.exp") do
+  # Code to benchmark
+  do_something()
+end
+
+# Measure a collection of files
+results = Expressir::Benchmark.measure_collection(files) do |file|
+  # Process each file
+  process_file(file)
+end
+----
+
+== Future features
+
+Future versions of Expressir will include parallel schema loading capabilities
+that can be benchmarked using the `EXPRESSIR_BENCHMARK_PARALLEL=true`
+environment variable.

data/expressir.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |spec|
   spec.email = ["open.source@ribose.com"]
 
   spec.summary = "EXPRESS parser and toolkit for Ruby"
-  spec.description = "Expressir (“EXPRESS in Ruby”) is a Ruby parser for EXPRESS and a set of tools for accessing EXPRESS data models."
+  spec.description = 'Expressir ("EXPRESS in Ruby") is a Ruby parser for EXPRESS and a set of tools for accessing EXPRESS data models.'
 
   spec.homepage = "https://github.com/lutaml/expressir"
   spec.license = "BSD-2-Clause"
@@ -33,6 +33,8 @@ Gem::Specification.new do |spec|
 
   spec.test_files = `git ls-files -- {spec}/*`.split("\n")
 
+  spec.add_dependency "benchmark-ips"
+  spec.add_dependency "csv"
   spec.add_dependency "liquid"
   spec.add_dependency "lutaml-model", "~>0.7"
   spec.add_dependency "parslet", "~> 2.0"