expressir 2.1.29 → 2.1.31

data/docs/index.adoc

@@ -0,0 +1,242 @@
+---
+layout: home
+title: Home
+nav_order: 1
+---
+
+= Expressir
+:toc: macro
+:toclevels: 2
+
+[.lead]
+*EXPRESS parser and toolkit for Ruby.* Parse, analyze, and transform EXPRESS data models with a comprehensive Ruby API.
+
+image:https://img.shields.io/gem/v/expressir.svg[RubyGems Version,link="https://rubygems.org/gems/expressir"]
+image:https://github.com/lutaml/expressir/workflows/rake/badge.svg[Build Status,link="https://github.com/lutaml/expressir/actions?workflow=rake"]
+
+'''
+
+toc::[]
+
+== What is Expressir?
+
+Expressir ("EXPRESS in Ruby") is a comprehensive Ruby parser and toolkit for working with EXPRESS data models, the data modeling language defined in ISO 10303-11. It enables you to:
+
+* *Parse* EXPRESS schemas from multiple formats
+* *Analyze* complex data models and their relationships
+* *Transform* schemas using a rich Ruby API
+* *Generate* documentation using Liquid templates
+* *Package* schemas into efficient LER (LutaML EXPRESS Repository) bundles
+* *Track* schema changes across versions
+
+=== Key Features
+
+[cols="1,3",options="header"]
+|===
+|Feature
+|Description
+
+|*Multiple Format Support*
+|Parse EXPRESS (ISO 10303-11), STEPmod XML, and EXPRESS XML formats
+
+|*Rich Data Model*
+|Complete Ruby representation of EXPRESS schemas with full type information
+
+|*LER Packages*
+|Pre-indexed, fast-loading schema bundles with 20x+ performance improvement
+
+|*Schema Analysis*
+|Built-in tools for documentation coverage, validation, and dependency analysis
+
+|*Liquid Integration*
+|Generate documentation and reports using flexible Liquid templates
+
+|*CLI Tools*
+|Command-line interface for formatting, validation, benchmarking, and more
+
+|*Changes Tracking*
+|Track and manage schema modifications across versions
+
+|*Ruby-First Design*
+|Idiomatic Ruby API with comprehensive test coverage
+|===
+
+== Quick Start
+
+=== Installation
+
+Add Expressir to your Gemfile:
+
+[source,ruby]
+----
+gem 'expressir'
+----
+
+Or install directly:
+
+[source,bash]
+----
+gem install expressir
+----
+
+=== Parse Your First Schema
+
+[source,ruby]
+----
+require 'expressir'
+
+# Parse an EXPRESS file
+repository = Expressir::Express::Parser.from_file('schema.exp')
+
+# Access schemas
+repository.schemas.each do |schema|
+  puts "Schema: #{schema.id}"
+  puts "Entities: #{schema.entities.size}"
+  puts "Types: #{schema.types.size}"
+end
+----
+
+=== Use the CLI
+
+[source,bash]
+----
+# Format a schema
+expressir format schema.exp
+
+# Validate schemas
+expressir validate schema.exp
+
+# Check documentation coverage
+expressir coverage schema.exp
+
+# Create an LER package
+expressir package build schema.exp output.ler
+----
+
+== Documentation Structure
+
+This documentation is organized into four main sections:
+
+=== Core Topics
+
+Fundamental concepts and essential information:
+
+* link:introduction.html[Introduction] - What is Expressir and when to use it
+* link:getting-started.html[Getting Started] - Installation and first steps
+* link:express-language.html[EXPRESS Language] - Understanding EXPRESS data modeling
+* link:data-model.html[Data Model] - Expressir's Ruby data model
+* link:parsers.html[Parsers] - Parsing EXPRESS files
+* link:schema-manifests.html[Schema Manifests] - Managing collections of EXPRESS schemas
+* link:ler-packages.html[LER Packages] - High-performance schema packages
+
+=== link:tutorials/[Tutorials]
+
+Step-by-step guides for common workflows:
+
+* link:tutorials/parsing-your-first-schema.html[Parsing Your First Schema]
+* link:tutorials/working-with-multiple-schemas.html[Working with Multiple Schemas]
+* link:tutorials/creating-ler-package.html[Creating LER Packages]
+* link:tutorials/querying-schemas.html[Querying Schemas]
+* link:tutorials/liquid-templates.html[Liquid Templates]
+* link:tutorials/documentation-coverage.html[Documentation Coverage]
+
+=== link:guides/[Guides]
+
+Task-oriented how-to documentation:
+
+* link:guides/cli/[CLI Commands] - Command-line interface usage
+* link:guides/ruby-api/[Ruby API] - Programmatic usage
+* link:guides/ler/[LER] - Working with LER packages
+* link:guides/manifests/[Manifests] - Managing schema collections
+* link:guides/changes/[Changes] - Tracking schema changes
+* link:guides/liquid/[Liquid] - Template integration
+
+=== link:references/[References]
+
+Detailed technical specifications:
+
+* link:references/cli-commands.html[CLI Commands Reference]
+* link:references/ruby-api.html[Ruby API Reference]
+* link:references/data-model/[Data Model Reference]
+* link:references/liquid-drops/[Liquid Drops Reference]
+* link:references/ler-format.html[LER Format Specification]
+* link:references/changes-format.html[Changes Format Specification]
+
+== Common Use Cases
+
+=== For Data Modelers
+
+* Parse and validate EXPRESS schemas
+* Check documentation coverage
+* Format and clean schemas
+* Track changes between versions
+
+=== For Developers
+
+* Integrate EXPRESS parsing into Ruby applications
+* Build schema analysis tools
+* Generate documentation from schemas
+* Create custom schema transformations
+
+=== For Organizations
+
+* Package large schema collections for distribution
+* Maintain schema version history
+* Automate schema validation in CI/CD
+* Generate standardized documentation
+
+== Performance
+
+Expressir is designed for performance:
+
+[cols="2,1,1",options="header"]
+|===
+|Operation
+|Traditional
+|With LER
+
+|Parse 40+ schemas
+|10-15 seconds
+|<500ms (20x+ faster)
+
+|Entity lookup
+|O(n) scan
+|O(1) indexed (<1ms)
+
+|Type resolution
+|Multiple passes
+|Pre-resolved
+|===
+
+== Architecture
+
+Expressir consists of three main components:
+
+[source]
+----
+┌─────────────────────────────────────┐
+│          Ruby API / CLI             │  ← Your Application
+├─────────────────────────────────────┤
+│         Expressir Model             │  ← Rich Data Model
+│  (Entities, Types, Schemas, etc.)   │
+├─────────────────────────────────────┤
+│          EXPRESS Parser             │  ← Multiple Formats
+│  (EXPRESS, STEPmod, EXPRESS XML)    │
+└─────────────────────────────────────┘
+----
+
+== Support
+
+* *Issues*: https://github.com/lutaml/expressir/issues[GitHub Issues]
+* *Discussions*: https://github.com/lutaml/expressir/discussions[GitHub Discussions]
+* *Contributing*: link:https://github.com/lutaml/expressir/blob/main/CONTRIBUTING.md[Contributing Guide]
+
+== License
+
+Expressir is distributed under the BSD-2-Clause license. See the link:https://github.com/lutaml/expressir/blob/main/LICENSE[LICENSE] file for details.
+
+== Credits
+
+Copyright © 2025 Ribose Inc.
+
+Expressir is developed and maintained by https://www.ribose.com[Ribose Inc.] as part of the https://www.lutaml.org[LutaML] project family.

data/docs/lychee.toml

@@ -0,0 +1,84 @@
+# Lychee link checker configuration for Expressir documentation
+# https://github.com/lycheeverse/lychee
+
+# Maximum number of concurrent network requests
+max_concurrency = 8
+
+# Maximum number of redirects to follow
+max_redirects = 5
+
+# Request timeout in seconds
+timeout = 30
+
+# Maximum number of retries per request
+max_retries = 2
+
+# Wait time between retries in seconds
+retry_wait_time = 2
+
+# User agent string
+user_agent = "Mozilla/5.0 (compatible; Lychee/1.0; +https://github.com/lutaml/expressir)"
+
+# Only check links with these schemes
+scheme = ["https", "http"]
+
+# Accepted HTTP status codes
+accept = [
+  "100..=103",
+  "200..=299",
+  "429",
+]
+
+# Exclude these URLs from checking
+exclude = [
+  # Local development URLs
+  "http://localhost*",
+  "http://127\\.0\\.0\\.1*",
+  "http://0\\.0\\.0\\.0*",
+
+  # Placeholder URLs
+  "http://example\\.com*",
+  "https://example\\.com*",
+  "http://example\\.org*",
+  "https://example\\.org*",
+
+  # Private/internal networks
+  "http://192\\.168\\..*",
+  "http://10\\..*",
+  "http://172\\.(1[6-9]|2[0-9]|3[01])\\..*",
+
+  # Avoid checking certain external sites that may rate-limit
+  "https://www\\.linkedin\\.com/.*",
+  "https://twitter\\.com/.*",
+  "https://x\\.com/.*",
+
+  # External sites with broken or moved URLs
+  "https://www\\.nist\\.gov/.*",
+  "https://www\\.steptools\\.com/.*",
+
+  # GitHub URLs that require authentication
+  "https://github\\.com/.*/(issues|pull)/[0-9]+/files.*",
+
+  # GitHub Discussions (may not be enabled for all repos)
+  "https://github\\.com/.*/discussions.*",
+
+  # GitHub blob URLs (may vary by repository structure)
+  "https://github\\.com/.*/blob/main/.*",
+
+  # Fragments only (internal page anchors without base URL)
+  "^#.*",
+]
+
+# Exclude specific paths from being checked
+exclude_path = [
+  "vendor",
+  "node_modules",
+  ".bundle",
+  ".cache",
+  "_site",
+  "fixtures",
+  "test",
+  "spec",
+  ".jekyll-cache",
+  "old-docs",
+]

data/examples/demo_ler_usage.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+# Complete LER Demonstration Script
+# Shows package creation, searching, and querying using CLI commands
+
+set -e
+
+echo "======================================================================"
+echo "           LER Package Creation and Query Demonstration              "
+echo "======================================================================"
+echo
+
+# Step 1: Create LER package
+echo "Step 1: Creating LER Package"
+echo "----------------------------------------------------------------------"
+echo "Building from: examples/ler/simple_schema.exp"
+echo
+
+bundle exec expressir package build \
+  examples/ler/simple_schema.exp \
+  examples/ler/simple_example.ler \
+  --name "Simple Product Management Schema" \
+  --version "1.0.0" \
+  --description "Demonstrates LER features with product entities" \
+  --express-mode include_all \
+  --resolution-mode resolved \
+  --serialization-format yaml
+
+echo "✓ Package created: examples/ler/simple_example.ler"
+echo
+
+# Step 2: Show package info
+echo "Step 2: Package Information"
+echo "----------------------------------------------------------------------"
+bundle exec expressir package info examples/ler/simple_example.ler
+echo
+
+# Step 3: List entities
+echo "Step 3: List All Entities"
+echo "----------------------------------------------------------------------"
+bundle exec expressir package list examples/ler/simple_example.ler --type entity
+echo
+
+# Step 4: List types
+echo "Step 4: List All Types"
+echo "----------------------------------------------------------------------"
+bundle exec expressir package list examples/ler/simple_example.ler --type type
+echo
+
+# Step 5: Search with patterns
+echo "Step 5: Search with Wildcard Pattern 'product*'"
+echo "----------------------------------------------------------------------"
+bundle exec expressir package search examples/ler/simple_example.ler "product*"
+echo
+
+# Step 6: Search specific type
+echo "Step 6: Search for Entities Only"
+echo "----------------------------------------------------------------------"
+bundle exec expressir package search examples/ler/simple_example.ler "product" --type entity
+echo
+
+# Step 7: Validation
+echo "Step 7: Package Validation"
+echo "----------------------------------------------------------------------"
+bundle exec expressir package validate examples/ler/simple_example.ler \
+  --strict \
+  --check-interfaces \
+  --check-completeness
+echo
+
+# Step 8: Tree view
+echo "Step 8: Package Tree View"
+echo "----------------------------------------------------------------------"
+bundle exec expressir package tree examples/ler/simple_example.ler --depth 3
+echo
+
+echo "======================================================================"
+echo "  Demo Complete!"
+echo "======================================================================"
+echo
+echo "Package saved at: examples/ler/simple_example.ler"
+echo
+echo "Try these additional commands:"
+echo "  expressir package info examples/ler/simple_example.ler --format json"
+echo "  expressir package search examples/ler/simple_example.ler 'product_*' --regex"
+echo "  expressir package tree examples/ler/simple_example.ler --counts"
+echo

data/examples/ler/README.md

@@ -0,0 +1,111 @@
+# LER (LutaML EXPRESS Repository) Examples
+
+This directory contains example EXPRESS schemas and demonstration scripts for the LER package system.
+
+## Files
+
+### Schema Files
+- **simple_schema.exp** - A simple example schema with products, types, and enumerations
+
+### Example Scripts
+- **../ler_build.rb** - Build LER package from schema
+- **../ler_query.rb** - Query entities and types from package
+- **../ler_stats.rb** - Get comprehensive statistics
+- **../ler_cli.rb** - Demonstrate CLI commands
+
+## Quick Start
+
+### 1. Build the Package
+
+```bash
+ruby examples/ler_build.rb
+```
+
+This creates `examples/ler/simple_example.ler` containing:
+- The parsed schema
+- Pre-built indexes for fast queries
+- Metadata and configuration
+
+### 2. Query the Package
+
+```bash
+ruby examples/ler_query.rb
+```
+
+Demonstrates:
+- Loading packages (<100ms)
+- Finding specific entities
+- Listing entities
+- Finding types
+- Filtering types by category
+
+### 3. View Statistics
+
+```bash
+ruby examples/ler_stats.rb
+```
+
+Shows:
+- Entity and type counts
+- Distribution by schema
+- Type categorization
+- Interface relationships
+- Validation results
+
+### 4. Use CLI Commands
+
+```bash
+ruby examples/ler_cli.rb
+```
+
+Demonstrates all CLI commands:
+- `expressir package info`
+- `expressir entity find/list`
+- `expressir type find/list`
+- `expressir stats show`
+
+## Direct CLI Usage
+
+Once you've built the package, you can use these commands directly:
+
+```bash
+# Package information
+bundle exec expressir package info examples/ler/simple_example.ler
+
+# Find entity
+bundle exec expressir entity find "simple_example.product" \
+  --from examples/ler/simple_example.ler
+
+# List all entities
+bundle exec expressir entity list --from examples/ler/simple_example.ler
+
+# List types by category
+bundle exec expressir type list --from examples/ler/simple_example.ler \
+  --category enumeration
+
+# Show statistics
+bundle exec expressir stats show examples/ler/simple_example.ler
+```
+
+## Creating Your Own Packages
+
+To create a package from your schemas:
+
+```ruby
+require 'expressir'
+
+# Option 1: From a single schema file (automatic dependency resolution)
+repo = Expressir::Model::Repository.from_files(['your_schema.exp'])
+repo.export_to_package('output.ler', name: 'My Package', version: '1.0')
+
+# Option 2: Using CLI
+# bundle exec expressir package build your_schema.exp output.ler \
+#   --name "My Package" --version "1.0"
+```
+
+## Performance
+
+LER packages provide significant performance benefits:
+- **Loading**: <100ms (vs seconds of parsing)
+- **Queries**: <1ms (pre-built indexes)
+- **Distribution**: Single .ler file (vs multiple .exp files)

data/examples/ler/simple_schema.exp

@@ -0,0 +1,33 @@
+(*
+Simple example schema for LER demonstration
+*)
+
+SCHEMA simple_example;
+
+  TYPE product_status = ENUMERATION OF
+    (draft,
+     approved,
+     released,
+     obsolete);
+  END_TYPE;
+
+  TYPE identifier = STRING;
+  END_TYPE;
+
+  ENTITY product;
+    id : identifier;
+    name : STRING;
+    status : product_status;
+    created_date : STRING; -- Simplified for example
+  END_ENTITY;
+
+  ENTITY product_version;
+    id : identifier;
+    version_number : STRING;
+    of_product : product;
+  END_ENTITY;
+
+  TYPE product_select = SELECT (product, product_version);
+  END_TYPE;
+
+END_SCHEMA; -- simple_example

data/examples/ler_build.rb

@@ -0,0 +1,75 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Build LER package from EXPRESS schema
+# This script demonstrates creating a self-contained LER package
+
+require_relative "../lib/expressir"
+
+puts "LER Package Builder Example"
+puts "=" * 60
+puts
+
+# Input schema
+SCHEMA_FILE = File.expand_path("ler/simple_schema.exp", __dir__)
+OUTPUT_PACKAGE = File.expand_path("ler/simple_example.ler", __dir__)
+
+unless File.exist?(SCHEMA_FILE)
+  puts "Error: Schema file not found: #{SCHEMA_FILE}"
+  exit 1
+end
+
+puts "Building LER package from: #{File.basename(SCHEMA_FILE)}"
+puts "Output: #{File.basename(OUTPUT_PACKAGE)}"
+puts
+
+# Step 1: Parse schema
+puts "Step 1: Parsing schema..."
+parsed = Expressir::Express::Parser.from_file(SCHEMA_FILE)
+puts "  ✓ Found #{parsed.schemas.size} schema(s)"
+
+# Step 2: Build repository
+puts "\nStep 2: Building repository..."
+repo = Expressir::Model::Repository.new
+
+# Initialize schemas if needed (for compatibility)
+repo.instance_variable_set(:@schemas, []) if repo.schemas.nil?
+
+parsed.schemas.each { |schema| repo.schemas << schema }
+repo.resolve_all_references
+puts "  ✓ Repository built with #{repo.schemas.size} schema(s)"
+
+# Step 3: Show statistics
+puts "\nStep 3: Repository statistics..."
+stats = repo.statistics
+puts "  Entities: #{stats[:total_entities]}"
+puts "  Types: #{stats[:total_types]}"
+puts "  Types by category:"
+stats[:types_by_category].each do |category, count|
+  puts "    #{category}: #{count}"
+end
+
+# Step 4: Export to package
+puts "\nStep 4: Creating LER package..."
+repo.export_to_package(
+  OUTPUT_PACKAGE,
+  name: "Simple Example Package",
+  version: "1.0.0",
+  description: "Example schema demonstrating LER packaging",
+  express_mode: "include_all",
+  resolution_mode: "resolved",
+  serialization_format: "yaml",
+)
+
+file_size = File.size(OUTPUT_PACKAGE)
+puts "  ✓ Package created: #{File.basename(OUTPUT_PACKAGE)}"
+puts "  Size: #{file_size} bytes (#{(file_size / 1024.0).round(2)} KB)"
+
+puts "\n#{'=' * 60}"
+puts "Success! Package ready at: #{OUTPUT_PACKAGE}"
+puts "\nTry these commands:"
+puts "  ruby examples/ler_query.rb"
+puts "  ruby examples/ler_stats.rb"
+puts "  bundle exec expressir package info #{OUTPUT_PACKAGE}"
+puts "  bundle exec expressir entity list --from #{OUTPUT_PACKAGE}"
+puts