Suma: utility for the STEP Unified Model-driven Architecture

Purpose

SUMA, the "STEP Unified Model-Based Standards Architecture", is a authoring and publication system developed for the management of EXPRESS schemas and its documentation.

This utility is used by the ISO 10303 collection to build the following artifacts:

the STEP Resource Library (SRL)

Features

EXPRESS schema management for STEP standards
Document collection building and compilation
EXPRESS links validation and extraction
Schema listing file generation
Integration with the Metanorma ecosystem
Progress tracking for schema loading operations

Installation

$ gem install suma

Usage: CLI

General

# Defaults to `suma help`
$ suma
Commands:
  suma build METANORMA_SITE_MANIFEST        # Build collection specified in site manifest (`metanorma*.yml`)
  suma reformat EXPRESS_FILE_PATH           # Reformat EXPRESS files
  suma validate SUBCOMMAND ...ARGS          # Validate express documents
  suma generate_schemas METANORMA_MANIFEST_FILE SCHEMA_MANIFEST_FILE # Generate schemas manifest file from Metanorma manifest YAML file
  suma extract_terms SCHEMA_MANIFEST_FILE GLOSSARIST_OUTPUT_PATH # Extract terms from schema manifest file
  suma help [COMMAND]                       # Describe available commands or one specific command

Build command

The build command processes a Metanorma site manifest and generates the specified output.

$ suma build METANORMA_SITE_MANIFEST [options]

Parameters:

METANORMA_SITE_MANIFEST: This is the path to the Metanorma site manifest, typically metanorma.yml.

Options:

--[no-]compile: Compile or skip compilation of collection (default: true)
--schemas-all-path=PATH, -s PATH: Generate file that contains all schemas in the collection

The generated schemas-*.yaml file name is derived from the input file name with the word metanorma replaced with schemas.

To compile SRL subset test collection

$ bundle exec suma build metanorma-test.yml

To build SRL collection

$ bundle exec suma build metanorma-srl.yml

To generate schema listing without compilation

$ bundle exec suma build --no-compile metanorma-srl.yml
# => generates schemas-srl.yml

All documents need to have a schemas.yaml in their document root that lists out which schemas the document includes.

Reformat command

The reformat command provides utilities for reformatting EXPRESS files.

$ suma reformat EXPRESS_FILE_PATH [options]

Parameters:

EXPRESS_FILE_PATH: Path to an EXPRESS file or a folder containing EXPRESS files

Options:

--[no-]recursive, -r: Select EXPRESS files recursively based on the specified folder path (default: false)

To reformat all EXPRESS files under the current directory recursively

$ bundle exec suma reformat `pwd` -r

This command:

Loads the EXPRESS files specified in the EXPRESS_FILE_PATH
Reformats and saves the loaded EXPRESS files

Validate command

General

The validate command groups various validation utilities for EXPRESS documents.

$ suma validate SUBCOMMAND [options]

Subcommands: - links - Validate EXPRESS links - ascii - Check for non-ASCII characters in EXPRESS files

Links subcommand

The links subcommand extracts and validates EXPRESS links without creating intermediate files.

$ suma validate links SCHEMAS_FILE DOCUMENTS_PATH [OUTPUT_FILE]

Parameters:

SCHEMAS_FILE: Path to the schemas file (default: "schemas-srl.yml")
DOCUMENTS_PATH: Path to the documents directory (default: "documents")
OUTPUT_FILE: Path to write validation results (default: "validation_results.txt")

To validate EXPRESS links in documents

$ bundle exec suma validate links schemas-srl.yml documents validation_results.txt

This command:

Loads the schemas specified in the SCHEMAS_FILE
Searches for EXPRESS links in all AsciiDoc files in the DOCUMENTS_PATH
Validates these links against the loaded schemas
Writes validation results to the OUTPUT_FILE
Provides progress bars to track schema loading and link validation

ASCII subcommand

The ascii subcommand detects non-ASCII characters in EXPRESS files and reports on those exact lines, providing replacement suggestions.

$ suma validate ascii EXPRESS_FILE_PATH [options]

Parameters:

EXPRESS_FILE_PATH: Path to an EXPRESS file or a folder containing EXPRESS files

Options:

--[no-]recursive, -r: Select EXPRESS files recursively based on the specified folder path (default: false)
--[no-]yaml, -y: Output results in YAML format for machine processing (default: false)

To validate all EXPRESS files in a specific directory recursively

$ bundle exec suma validate ascii ../iso-10303/schemas -r

To validate and output results in YAML format

$ bundle exec suma validate ascii ../iso-10303/schemas -r -y > validation.yml

This command:

Loads the EXPRESS files specified in the EXPRESS_FILE_PATH
Scans each line for non-ASCII characters
Reports detailed information about each violation, including:
- Filename and line number
- The exact line content
- Visual indication of the non-ASCII sequence location
- Character details with hexadecimal representation
Provides specific replacement suggestions:
- For math symbols: provides equivalent AsciiMath notation
- For other non-ASCII characters: provides ISO 10303-11 encoded string literal format
Displays a summary table showing:
- File path (directory/filename)
- Each non-ASCII symbol found
- Suggested replacement for each symbol
- Number of occurrences of each character
- Totals row showing unique character count and overall occurrences
Summarizes findings across all scanned files
Optionally outputs structured data in YAML format with detailed occurrence information

Human-readable output format example:

/path/to/file.exp:
  Line 42, Column 15:
    ENTITY some_entity (name: STRING, description: "résumé");
                                       ^^^^^
      "é" - Hex: 0xe9, UTF-8 bytes: 0xc3 0xa9
      Replacement: ISO 10303-11: "000000E9"

      "s" - Hex: 0x73, UTF-8 bytes: 0x73

      "u" - Hex: 0x75, UTF-8 bytes: 0x75

      "m" - Hex: 0x6d, UTF-8 bytes: 0x6d

      "é" - Hex: 0xe9, UTF-8 bytes: 0xc3 0xa9
      Replacement: ISO 10303-11: "000000E9"

  Found 1 non-ASCII sequence(s) in file.exp

Summary:
  Scanned 3 EXPRESS file(s)
  Found 1 non-ASCII sequence(s) in 1 file(s)

+------------------+--------------------+-----------------------------+-------------+
|       File       |       Symbol       |        Replacement          | Occurrences |
+------------------+--------------------+-----------------------------+-------------+
| path/to/file.exp | "é" (0xe9)         | ISO 10303-11: "000000E9"    | 2           |
+------------------+--------------------+-----------------------------+-------------+
| TOTAL            | 1 unique           |                             | 2           |
+------------------+--------------------+-----------------------------+-------------+

Japanese Character Example

For Japanese characters like 神戸 (Kobe), the command will provide ISO 10303-11 encoded string literal replacements:

"神" - Hex: 0x795e, UTF-8 bytes: 0xe7 0xa5 0x9e
Replacement: ISO 10303-11: "0000795E"

"戸" - Hex: 0x6238, UTF-8 bytes: 0xe6 0x88 0xb8
Replacement: ISO 10303-11: "00006238"

Math Symbol Example

For mathematical symbols, the command will provide equivalent AsciiMath notation:

"×" - Hex: 0xd7, UTF-8 bytes: 0xc3 0x97
Replacement: AsciiMath: xx

Generate schemas command

The suma generate_schemas command generates a schema manifest file containing all schemas defined in the Metanorma manifest file.

$ suma generate_schemas METANORMA_MANIFEST_FILE SCHEMA_MANIFEST_FILE [options]

Parameters:

METANORMA_MANIFEST_FILE: Path to the Metanorma manifest file (e.g.: "metanorma-smrl-all.yml")

Options:

--exclude_path, -e: Exclude schemas by pattern (e.g. *_lf.exp)

To generate schemas manifest file from Metanorma manifest file

$ bundle exec suma generate_schemas metanorma-smrl-all.yml schemas-smrl-all.yml
# => generates schemas-smrl-all.yml

To generate schemas manifest file from Metanorma manifest file and exclude schemas with names like *_lf.exp

$ bundle exec suma generate_schemas metanorma-smrl-all.yml schemas-smrl-all.yml -e *_lf.exp
# => generates schemas-smrl-all.yml without schemas with names like *_lf.exp

All documents need to have a schemas.yaml in their document root that lists out which schemas the document includes.

Extract terms command

The suma extract_terms command extracts terms from SCHEMA_MANIFEST_FILE and generates Glossarist v2 dataset in the output directory.

$ suma extract_terms SCHEMA_MANIFEST_FILE GLOSSARIST_OUTPUT_PATH [options]

Parameters:

SCHEMA_MANIFEST_FILE: Path to SCHEMA_MANIFEST_FILE
GLOSSARIST_OUTPUT_PATH: Path to the output directory for the Glossarist v2 dataset

Options:

language_code: Language code for the Glossarist (default: "eng")

To extract terms from SCHEMA_MANIFEST_FILE

$ bundle exec suma extract_terms path/to/schemas-smrl-all.yml glossarist_output
# => generates glossarist_output/concept/foo.yaml and glossarist_output/localized_concept/bar.yaml

To extract terms from SCHEMA_MANIFEST_FILE with language code "fra"

$ bundle exec suma extract_terms path/to/schemas-smrl-all.yml glossarist_output -l fra
# => generates glossarist_output/concept/foo.yaml and glossarist_output/localized_concept/bar.yaml

Usage: Ruby

General

Suma can be used programmatically in your Ruby applications. The following examples demonstrate common usage patterns.

Building collections

require 'suma'

# Build a collection with default settings
Suma::Processor.run(
  metanorma_yaml_path: "metanorma-srl.yml",
  schemas_all_path: "schemas-srl.yml",
  compile: true,
  output_directory: "_site"
)

# Generate schema listing without compilation
Suma::Processor.run(
  metanorma_yaml_path: "metanorma-srl.yml",
  schemas_all_path: "schemas-srl.yml",
  compile: false,
  output_directory: "_site"
)

Working with schema configurations

require 'suma'

# Load schemas using SchemaConfig
schemas_file_path = "schemas-srl.yml"
schemas_config = Suma::SchemaConfig::Config.from_yaml(IO.read(schemas_file_path))

# Set the initial path to resolve relative paths
schemas_config.set_initial_path(schemas_file_path)

# Access schema information
schemas_config.schemas.each do |schema|
  puts "Schema ID: #{schema.id}"
  puts "Schema path: #{schema.path}"
end

suma

Runtime

Suma: utility for the STEP Unified Model-driven Architecture

Purpose

Features

Installation

Usage: CLI

General

Build command

Reformat command

Validate command

General

Links subcommand

ASCII subcommand

Japanese Character Example

Math Symbol Example

Generate schemas command

Extract terms command

Usage: Ruby

General

Building collections

Working with schema configurations

Copyright and license