Expressir: EXPRESS in Ruby

Create a 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 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: