hecate

A batteries-included language development toolkit for Crystal.

Table of Contents

• Install
• Usage
  • Quick Example
  • Available Shards
• Development
• Contributing
• License

Install

Add the shards you need to your shard.yml:

dependencies:
  hecate-core:
    github: hecatecr/hecate-core
    version: ~> 0.1.0
  hecate-lex:
    github: hecatecr/hecate-lex
    version: ~> 0.1.0
  hecate-ast:
    github: hecatecr/hecate-ast
    version: ~> 0.1.0

Run shards install.

Usage

Quick Example

Build a simple expression lexer:

require "hecate-core"
require "hecate-lex"

# Define your lexer
lexer = Hecate::Lex.define do |ctx|
  ctx.token :WS, /\s+/, skip: true
  ctx.token :INT, /\d+/
  ctx.token :PLUS, /\+/
  ctx.token :MINUS, /-/
  ctx.token :MULTIPLY, /\*/
  ctx.token :DIVIDE, /\//
end

# Create a source file
source_map = Hecate::Core::SourceMap.new
source_id = source_map.add_file("example.expr", "42 + 13 * 2")
source_file = source_map.get(source_id).not_nil!

# Lex the input
tokens, diagnostics = lexer.scan(source_file)

# Handle any errors
if diagnostics.any?
  renderer = Hecate::Core::TTYRenderer.new
  diagnostics.each { |diag| renderer.emit(diag, source_map) }
else
  # Process tokens
  tokens.each do |token|
    puts "#{token.kind}: '#{token.lexeme(source_file)}'"
  end
end

Available Shards

Hecate is organized as a monorepo with independently versioned shards:

• hecate-core - Diagnostics, source mapping, and utilities
• hecate-ast - AST node definitions and visitor pattern
• hecate-lex - Lexer generation with declarative DSL
• hecate-parse - Parser combinators and Tree-sitter bridge (coming soon)
• hecate-sem - Semantic analysis and type checking (coming soon)
• hecate-ir - Intermediate representation (coming soon)
• hecate-codegen - Code generation backends (coming soon)
• hecate-cli - Command-line interface (coming soon)

Development

Prerequisites

• Crystal 1.17.0 or higher
• Git
• Just (optional, for convenience commands)

Setup

1. Clone the repository:

   git clone https://github.com/hecatecr/hecate.git
   cd hecate
   

2. Install dependencies:

   just install
   # or manually: SHARDS_OVERRIDE=shard.dev.yml shards install
   

3. Run all tests:

   just test
   

4. Run tests for a specific shard:

   just test-shard core
   just test-shard lex
   just test-shard ast
   

Development Workflow

The monorepo uses a dual shard configuration:

• Production shards (shards/*/shard.yml) - Point to GitHub repositories
• Development shards (shard.dev.yml) - Use local path dependencies

All development commands should be run from the repository root using the justfile or with SHARDS_OVERRIDE=shard.dev.yml.

Contributing

Contributions are welcome! Please follow these guidelines:

1. Issues and PRs should be filed against this monorepo, not individual shard repositories
2. All development happens in the monorepo - individual shard repos are read-only mirrors
3. Tests are required - Write tests before implementation (TDD approach)
4. Run the full test suite before committing to catch cross-shard compilation errors
5. Follow Crystal conventions and the patterns established in the codebase

See our Contributing Guide for detailed information.

License

MIT © Chris Watson. See LICENSE for details.