Collie

A linter and formatter for Lrama Style BNF grammar files (.y files). Collie helps you write clean, maintainable, and error-free grammar files for parser generators like Lrama, Yacc, and Bison.

• 18 Built-in Lint Rules - Catch common errors and suggest improvements
• Lrama Extension Support - Full support for parameterized rules, named references, and inline rules
• Smart Formatting - Consistent indentation, alignment, and spacing
• Configurable - Customize rules and formatting options via .collie.yml
• Multiple Output Formats - Text, JSON, and GitHub Actions annotations
• Auto-correction - Automatically fix certain issues

gem install collie

Or add to your Gemfile:

gem 'collie', require: false

Try Collie in your browser without installing anything:

Open Playground (Coming soon)

# Check for issues
collie lint parse.y

# Auto-fix issues where possible
collie lint -a parse.y

# Check formatting
collie fmt --check parse.y

# Format in-place
collie fmt parse.y

# Show diff
collie fmt --diff parse.y

collie rules

Create a .collie.yml file in your project root:

# Inherit from another config (optional)
inherit_from: .collie_base.yml

# Rule configuration
rules:
  DuplicateToken:
    enabled: true
    severity: error

  TokenNaming:
    enabled: true
    severity: convention
    pattern: '^[A-Z][A-Z0-9_]*$'

  LongRule:
    enabled: true
    max_alternatives: 10

  # Disable specific rules
  LeftRecursion:
    enabled: false

# Formatter options
formatter:
  indent_size: 4
  align_tokens: true
  align_alternatives: true
  blank_lines_around_sections: 2
  max_line_length: 120

# File patterns
include:
  - '**/*.y'
exclude:
  - 'vendor/**/*'
  - 'tmp/**/*'

%token <node> CLASS MODULE DEF
%token <id> IDENTIFIER CONSTANT
%token <num> INTEGER FLOAT

%left '+' '-'
%left '*' '/'
%right '^'

%%

program
    : class_definition
    | module_definition
    ;

class_definition
    : CLASS CONSTANT '{' class_body '}'
        { $$ = make_class($2, $4); }
    ;

expr
    : expr '+' expr    { $$ = add($1, $3); }
    | expr '-' expr    { $$ = sub($1, $3); }
    | expr '*' expr    { $$ = mul($1, $3); }
    | '(' expr ')'     { $$ = $2; }
    | IDENTIFIER       { $$ = var($1); }
    | INTEGER          { $$ = num($1); }
    ;

%%

Collie fully supports Lrama-specific syntax:

# Parameterized Rules
%rule pair(X, Y): X COMMA Y ;

number_pair
    : pair(NUMBER, NUMBER)
        { $$ = make_pair($1, $3); }
    ;

# Named References
assignment
    : IDENTIFIER[var] EQUALS NUMBER[value]
        { assign($var, $value); }
    ;

# Inline Rules
%inline opt(X): /* empty */ | X ;

Use the reusable workflow in your project:

# .github/workflows/lint.yml
name: Lint Grammar Files

on: [push, pull_request]

jobs:
  lint:
    uses: ydah/collie/.github/workflows/lint.yml@main
    with:
      files: 'src/**/*.y'
      config: '.collie.yml'
      fail-on-warnings: true

require 'collie'

# Parse a grammar file
parser = Collie::Parser::Parser.new(source_code)
ast = parser.parse

# Analyze the grammar
symbol_table = Collie::Analyzer::SymbolTable.new(ast)
symbol_table.build

# Run linter
config = Collie::Config.new
linter = Collie::Linter.new(config)
offenses = linter.lint(ast)

# Format the grammar
formatter = Collie::Formatter::Formatter.new(config.formatter_options)
formatted_code = formatter.format(ast)

collie lint [OPTIONS] FILES

Options:
  --config PATH         Path to config file (default: .collie.yml)
  --format FORMAT       Output format: text, json, github (default: text)
  -a, --autocorrect     Auto-fix offenses where possible
  --only RULES          Run only specified rules (comma-separated)
  --except RULES        Exclude specified rules (comma-separated)

collie fmt [OPTIONS] FILES

Options:
  --config PATH         Path to config file
  --check               Check only, don't modify files
  --diff                Show diff of changes

collie rules [OPTIONS]

Options:
  --format FORMAT       Output format: text, json (default: text)

# Install dependencies
bundle install

# Run tests
bundle exec rspec

# Run linter
bundle exec rubocop

# Run all checks
bundle exec rake

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

The gem is available as open source under the terms of the MIT License.

Developed for improving the development experience with Lrama, the next-generation parser generator for Ruby.

• collie-lsp - LSP (Language Server Protocol) implementation for Collie
• vscode-collie - VS Code extension for Collie

• Lrama - LALR (1) parser generator
• Bison - GNU parser generator

• RuboCop - Ruby static code analyzer (inspiration for architecture)