Expressir: EXPRESS in Ruby

Create a schema manifest YAML file with a list of schema paths:

Then benchmark all schemas at once:

You can also benchmark schema loading with caching to measure parsing time, cache writing time, and cache reading time:

The benchmark commands support several options:

When using the --format json option, results will be output in JSON format, making it easy to parse for further analysis or visualization.

Use the coverage command to check documentation coverage of EXPRESS schemas:

The output shows which entities are missing documentation, calculates coverage percentages, and provides an overall documentation coverage summary.

The coverage command supports different output formats and exclusion options:

You can exclude specific EXPRESS entity types from coverage analysis using the --exclude option.

This is useful when certain entity types don’t require documentation coverage, such as TYPE entities whose descriptions are generated by template strings.

Expressir checks documentation coverage for all EXPRESS elements (ModelElement subclasses), including:

Schema-level entities:

TYPE

Type definitions (supports subtype exclusion, see below)

ENTITY

Entity definitions

CONSTANT

Constant definitions

FUNCTION

Function definitions

RULE

Rule definitions

PROCEDURE

Procedure definitions

SUBTYPE_CONSTRAINT

Subtype constraint definitions

INTERFACE

Interface definitions

Nested entities within other constructs:

PARAMETER

Function and procedure parameters

VARIABLE

Variables within functions, rules, and procedures

ATTRIBUTE

Entity attributes

DERIVED_ATTRIBUTE

Derived attributes in entities

INVERSE_ATTRIBUTE

Inverse attributes in entities

UNIQUE_RULE

Unique rules within entities

WHERE_RULE

Where rules within entities and types

ENUMERATION_ITEM

Items within enumeration types

INTERFACE_ITEM

Items within interfaces

INTERFACED_ITEM

Interfaced items

SCHEMA_VERSION

Schema version information

SCHEMA_VERSION_ITEM

Schema version items

For TYPE elements, you can exclude specific subtypes using the TYPE:SUBTYPE syntax:

For FUNCTION elements, you can exclude inner functions (functions nested within other functions, rules, or procedures) using the FUNCTION:INNER syntax:

This is useful when you want to focus documentation coverage on top-level functions while excluding nested helper functions that may not require individual documentation. The exclusion works recursively, excluding functions at any nesting level within other constructs.

Valid FUNCTION subtypes that can be excluded:

INNER

Inner functions nested within other functions, rules, or procedures (at any depth)

FUNCTION outer_function : BOOLEAN;
  -- This inner function would be excluded with FUNCTION:INNER
  FUNCTION inner_helper_function : BOOLEAN;
    -- Even deeply nested functions are excluded
    FUNCTION deeply_nested_function : BOOLEAN;
      RETURN (TRUE);
    END_FUNCTION;
    RETURN (TRUE);
  END_FUNCTION;

  RETURN (TRUE);
END_FUNCTION;

RULE example_rule FOR (some_entity);
  -- Inner functions in rules are also excluded
  FUNCTION inner_function_in_rule : BOOLEAN;
    RETURN (TRUE);
  END_FUNCTION;
WHERE
  WR1: inner_function_in_rule();
END_RULE;

PROCEDURE example_procedure;
  -- Inner functions in procedures are also excluded
  FUNCTION inner_function_in_procedure : BOOLEAN;
    RETURN (TRUE);
  END_FUNCTION;
END_PROCEDURE;

The FUNCTION:INNER exclusion helps maintain focus on documenting the primary API functions while ignoring implementation details of nested helper functions.

You can exclude entire files from the overall coverage calculation using the --ignore-files option. This is useful when you have files that should not contribute to the overall documentation coverage statistics, such as test schemas, example files, or legacy schemas.

The default text output displays:

1. Directory coverage (when analyzing multiple directories)

2. File coverage, showing:

   • File path

   • List of undocumented entities

   • Coverage percentage

3. Overall documentation coverage statistics

This helps identify areas of your EXPRESS schemas that need documentation improvement.

The changes validate command validates EXPRESS Changes YAML files and optionally normalizes them through round-trip serialization.

The validate command performs the following checks:

1. Verifies the YAML file can be parsed

2. Validates against the SchemaChange model structure

3. Ensures all required fields are present

4. Checks that change items have valid types

When using --normalize, the command:

1. Loads the file and validates it

2. Serializes it back to YAML with consistent formatting

3. Either outputs to stdout, saves in-place, or writes to a new file

This is useful for:

• Standardizing formatting: Ensures consistent YAML structure

• Catching errors early: Validates before committing changes

• Cleaning up files: Removes inconsistencies in formatting

The changes import-eengine command converts Express Engine (eengine) comparison XML files to EXPRESS Changes YAML format.

The eengine compare XML format is created through exp-engine-engine/kernel/compare.lisp in the Express Engine code. Expressir is compatible with v5.2.7 of eengine output.

The import command:

1. Parses the eengine XML comparison file

2. Automatically detects the XML mode (Schema/ARM/MIM)

3. Extracts additions, modifications, and deletions

4. Converts modified objects to EXPRESS Changes item format

5. Preserves interface change information (interfaced.items)

6. Creates or updates an EXPRESS Changes YAML file

7. Supports appending new versions to existing files

When the output file already exists:

• Same version: Replaces the existing version with that version

• New version: Adds a new version to the file

This allows you to build up a complete change history incrementally across multiple schema versions.

Syntax:

Where:

INPUT_XML

Path to the eengine comparison XML file

SCHEMA_NAME

Name of the schema being tracked (e.g., aic_csg, action_schema)

VERSION

Version number for this set of changes (e.g., "2", "3")

Options:

-o, --output PATH

Output YAML file path (stdout if not specified)

--verbose

Show verbose output including parsed items

The command automatically detects and handles all three eengine XML comparison formats:

Schema mode

<schema.changes> root element with <schema.additions>, <schema.modifications>, and <schema.deletions> sections. See API docs for details.

Example workflow for importing changes from multiple versions:

This creates a single YAML file tracking changes across all three versions:

The library provides two main methods for parsing EXPRESS files.

Use the from_file method to parse a single EXPRESS schema file:

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:

Use the from_files method to parse multiple EXPRESS schema files:

You can provide a block to track loading progress and handle errors:

The EXPRESS schema manifest is a file format defined by ELF at EXPRESS schema manifest specification.

Expressir provides a SchemaManifest class for managing collections of EXPRESS schema files. This is particularly useful when working with multiple related schemas or when you need to organize schema files in a structured way.

The SchemaManifest class allows you to:

• Load schema file lists from YAML manifest files

• Manage schema metadata and paths

• Programmatically create and manipulate schema collections

• Save manifest configurations to files

The schema manifest uses a structured YAML format:

Schema manifests are supported by several CLI commands:

Expressir provides programmatic API access for parsing Express Engine comparison XML and converting it to EXPRESS Changes format.

Parse Eengine XML into a structured object model:

Convert Eengine XML directly to EXPRESS Changes format:

The eengine XML format tracks interface changes (USE_FROM, REFERENCE_FROM) with the interfaced.items attribute. This attribute lists the specific items being imported or referenced from another schema.

Eengine XML files track interface changes (USE_FROM, REFERENCE_FROM) with the interfaced.items attribute:

The import command recognizes all standard EXPRESS construct types:

• ENTITY - Entity definitions

• TYPE - Type definitions

• FUNCTION - Function definitions

• PROCEDURE - Procedure definitions

• RULE - Rule definitions

• CONSTANT - Constant definitions

• USE_FROM - Interface imports (preserves interfaced.items)

• REFERENCE_FROM - Interface references (preserves interfaced.items)