Getting Started with Expressir

Purpose

This guide will help you install Expressir and take your first steps with both the command-line interface (CLI) and Ruby API. Within minutes, you’ll be parsing EXPRESS schemas and exploring the results.

References

Concepts

Gem

A Ruby library package that can be installed and managed with RubyGems

Bundle

Ruby’s dependency manager (Bundler) for managing gem versions

CLI

Command-Line Interface - programs run from the terminal

Repository

Expressir’s container for parsed schemas

Schema

An EXPRESS data model containing entities, types, and functions

Prerequisites

Before installing Expressir, ensure you have:

Ruby 2.7 or later

Check your Ruby version:

ruby --version

If you need to install Ruby, visit ruby-lang.org/en/documentation/installation

RubyGems

Comes with Ruby by default. Verify with:

gem --version
Bundler (recommended)

For managing dependencies in your projects:

gem install bundler

Installation

There are two ways to install Expressir:

Option 1: System-wide Installation

Install Expressir globally on your system:

gem install expressir

This makes the expressir command available system-wide.

For use in a specific project, add Expressir to your Gemfile:

# Gemfile
source 'https://rubygems.org'

gem 'expressir'

Then install:

bundle install

This approach is recommended because it:

  • Locks specific versions for reproducibility

  • Isolates dependencies per project

  • Works well with CI/CD systems

Verify Installation

Confirm Expressir is installed correctly:

# Check version
expressir version

# View available commands
expressir help

You should see output listing Expressir’s version and available commands.

First Steps with CLI

Let’s parse your first EXPRESS schema using the command line.

Create a Sample Schema

Create a simple EXPRESS file named example.exp:

SCHEMA example_schema;

  ENTITY person;
    name : STRING;
    age : INTEGER;
  END_ENTITY;

  ENTITY organization;
    org_name : STRING;
    employees : SET [0:?] OF person;
  END_ENTITY;

END_SCHEMA;

Parse and Format the Schema

Use the format command to parse and pretty-print the schema:

expressir format example.exp

This will output the formatted schema to your terminal, confirming that:

  1. The schema parses correctly

  2. Expressir understands the structure

  3. The formatting engine works

Validate the Schema

Check if the schema is valid:

expressir validate example.exp

A valid schema should display: "Validation passed for all EXPRESS schemas."

Explore Other Commands

Try these commands to explore Expressir’s capabilities:

# View all available commands
expressir help

# Get help for a specific command
expressir help format

# Check version
expressir version

First Steps with Ruby API

Now let’s use Expressir programmatically from Ruby.

Basic Parsing Example

Create a Ruby script named parse_example.rb:

require 'expressir'

# Parse an EXPRESS file
repository = Expressir::Express::Parser.from_file('example.exp')

# Access the parsed schema
schema = repository.schemas.first
puts "Schema name: #{schema.id}"
puts "Number of entities: #{schema.entities.length}"

# List all entities
schema.entities.each do |entity|
  puts "  Entity: #{entity.id}"
  entity.attributes.each do |attr|
    puts "    - #{attr.id}: #{attr.type}"
  end
end

Run it:

ruby parse_example.rb

Expected output:

Schema name: example_schema
Number of entities: 2
  Entity: person
    - name: STRING
    - age: INTEGER
  Entity: organization
    - org_name: STRING
    - employees: SET [0:?] OF person

Interactive Exploration with IRB

You can also explore Expressir interactively:

irb

Then in the IRB session:

require 'expressir'

# Parse a file
repo = Expressir::Express::Parser.from_file('example.exp')

# Explore the structure
repo.schemas.first.entities.first
# => Returns the first entity

# Access attributes
repo.schemas.first.entities.first.attributes
# => Returns array of attributes

Error Handling Example

Expressir provides clear error messages when parsing fails:

require 'expressir'

begin
  repository = Expressir::Express::Parser.from_file('invalid.exp')
rescue Expressir::Express::Error::SchemaParseFailure => e
  puts "Parse error in #{e.filename}:"
  puts e.message
  puts e.parse_failure_cause.ascii_tree
end

Testing Your Installation

Run Expressir’s test suite to ensure everything works:

# Clone the repository (if you want to contribute)
git clone https://github.com/lutaml/expressir.git
cd expressir

# Install dependencies
bundle install

# Run tests
bundle exec rake

All tests should pass, confirming your installation is working correctly.

Common Issues and Solutions

"Command not found: expressir"

Problem: The expressir command isn’t in your PATH.

Solutions:

  1. If installed with bundler, use: bundle exec expressir

  2. Ensure RubyGems bin directory is in PATH:

    echo 'export PATH="$HOME/.gem/ruby/X.X.0/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

    Replace X.X with your Ruby version

"cannot load such file — expressir"

Problem: Expressir gem not found by Ruby.

Solutions:

  1. Install the gem: gem install expressir

  2. If using Bundler: bundle install

  3. Check your Ruby environment: gem env

Parser Errors

Problem: Schema fails to parse.

Solutions:

  1. Verify EXPRESS syntax is valid

  2. Check for special characters or encoding issues

  3. Use --verbose flag for detailed error messages

  4. Consult the EXPRESS language specification

Next Steps

Now that you have Expressir installed and working, you can:

Learn by doing

Try the Parsing Your First Schema tutorial for a comprehensive introduction

Explore CLI commands

Read the CLI guides to master command-line usage

Dive into Ruby API

Study the Ruby API guides for programmatic control

Understand the model

Learn about Expressir’s data model to work with schemas effectively

Work with LER packages

Explore LER packages for high-performance schema distribution

Quick Reference

Most Used CLI Commands 

# Format (pretty-print) a schema
expressir format schema.exp

# Validate schema
expressir validate schema.exp

# Check documentation coverage
expressir coverage schema.exp

# Show version
expressir version

# Get help
expressir help [COMMAND]

Most Used Ruby Methods 

# Parse a single file
repo = Expressir::Express::Parser.from_file('schema.exp')

# Parse multiple files
repo = Expressir::Express::Parser.from_files(['schema1.exp', 'schema2.exp'])

# Access schemas
repo.schemas.each { |schema| puts schema.id }

# Find entities
schema.entities.find { |e| e.id == 'person' }

# Convert to Liquid drops
repo_drop = repo.to_liquid

Getting Help

If you encounter issues:

Documentation

Browse the complete documentation site

GitHub Issues

Report bugs or request features

Community

Join discussions and ask questions in GitHub Discussions

Source Code

Explore the code on GitHub

Bibliography