Sephirah

Sephirah is an experimental Xtext-based expression language for readable, validated formulas and rule-system computations.

The project demonstrates language-tooling work in Java: grammar design, parsing, static validation, type checking, module-style organization, Eclipse editor integration, runtime evaluation, examples, and compiler-style tests.

Sephirah is currently the concrete working layer of a larger long-term rules-language idea. Briah and Bat Kol are broader design targets, but this repository focuses on the working Sephirah layer: expressions, definitions, variable assignments, validation, editor/tooling feedback, and evaluable formula modules.

Why This Project Exists

Many applications encode formulas, rules, and conditional logic directly inside ordinary application code. That can make rules difficult to read, validate, explain, test, and modify.

Sephirah explores a different approach: make rules and formulas explicit language artifacts.

Instead of hiding rule logic inside general-purpose code, Sephirah aims to provide a readable expression layer with validation and tooling support.

What This Project Demonstrates

• Xtext grammar design
• Eclipse editor/plugin integration for .seph files
• Expression parsing
• Arithmetic, comparisons, boolean logic, conditionals, constants, variables, and function calls
• Function definitions and variable assignments
• Declarative module-style ordering
• Static validation for common language errors
• Type checking for numeric and boolean expressions
• Runtime evaluation of expressions, variables, and user-defined functions
• Compiler-style tests for language behavior
• Early CLI/demo tooling

Language Examples

Basic Expressions

SephirahDoc basicExpressions

5 + 7;
12 * 3;
(10 + 2) / 3;

Definitions and Variables

SephirahDoc definitionsAndVariables

def proficiency(level) = (level + 7) / 4;

def attack_bonus(level, strength_mod) = proficiency(level) + strength_mod;

var level = 5;
var strength_mod = 3;

attack_bonus(level, strength_mod);

Declarative Ordering

Sephirah modules are intended to be treated declaratively rather than as strictly sequential scripts. Definitions and variables can be collected across the module instead of requiring every symbol to appear before first use.

SephirahDoc declarativeOrdering

attack_bonus(level, strength_mod);

var level = 5;

var strength_mod = 3;

def attack_bonus(level, strength_mod) = proficiency(level) + strength_mod;

def proficiency(level) = (level + 7) / 4;

Validation Examples

Sephirah includes custom validation work for language errors such as:

• Unknown variables
• Unknown functions
• Duplicate variables
• Duplicate functions
• Duplicate parameters
• Function arity mismatches
• Type mismatches
• Cyclic variable references
• Cyclic function references
• Invalid boolean/numeric operands
• Division by zero when statically detectable
• Built-in function name conflicts
• Unused variables or parameters

Repository Layout

com.fearlesstyrant.sephirah/             Core grammar/runtime project
com.fearlesstyrant.sephirah.ide/         IDE integration
com.fearlesstyrant.sephirah.ui/          Eclipse UI integration
com.fearlesstyrant.sephirah.tests/       Language/runtime tests
com.fearlesstyrant.sephirah.ui.tests/    UI tests
com.fearlesstyrant.sephirah.feature/     Eclipse feature project
com.fearlesstyrant.sephirah.updatesite/  Eclipse update site project
examples/                                Small `.seph` examples
tools/                                   Repo/demo helper scripts

Core Areas of the Codebase

Area	Purpose
Grammar	Defines Sephirah syntax and expression structure
Validator	Reports language errors and editor feedback
Runtime / Evaluator	Evaluates expressions, variables, and functions
Type Support	Tracks numeric, boolean, and unknown expression types
Compiler Layer	Compiles parsed modules into evaluable runtime structures
Tests	Verifies grammar, validation, evaluation, and module behavior
Examples	Shows the language at a glance

Command-Line Demo

Sephirah includes an experimental CLI entry point:

com.fearlesstyrant.sephirah.cli.SephirahCli

Packaged CLI distribution is future work. For now, the CLI exists as an experimental demo path rather than a polished end-user command.

Demo Examples

See the generated Sephirah Showcase for a quick view of the language examples.

The examples/ folder currently includes:

examples/01-basic-expressions.seph
examples/02-definitions-and-variables.seph
examples/03-declarative-ordering.seph

Demo Tooling

This repository includes lightweight helper tools:

1. repo_health_check.ps1 — checks that the repo root is clean and not accidentally pointed at an Eclipse workspace root.
2. tools/build_showcase.py — generates a Markdown showcase from the example .seph files.
3. tools/publish_sephirah.ps1 — publishes the existing local repository to GitHub using GitHub CLI.

To run the showcase generator from the repository root:

python tools/build_showcase.py

This writes:

docs/showcase.md

Current Status

Sephirah is an early prototype, not a finished language distribution.

The current repository demonstrates:

• grammar design
• expression parsing
• validation
• type-checking direction
• editor integration
• runtime evaluation
• examples
• tests
• experimental CLI/demo work

Build automation, packaged CLI distribution, richer documentation, and clean-clone CI are future work.

Roadmap

• Stabilize the expression type system
• Finish boolean values as first-class evaluable return values
• Add CLI validation such as sephirah validate examples/*.seph
• Add non-mutating preview/diagnostic output for expression results
• Add richer examples for game/stat formulas, constraints, and rule-system expressions
• Confirm clean-clone Maven/Tycho build behavior
• Add CI once the clean-clone build is stable
• Improve documentation for validators, type inference, imports, and runtime evaluation

Portfolio Framing

Sephirah is a portfolio project for demonstrating deeper software engineering ability beyond ordinary CRUD application work.

It shows comfort with:

• Java
• Xtext
• DSL design
• parser and grammar work
• static validation
• type checking
• editor tooling
• runtime evaluation
• modular language behavior
• test-driven language development

Suggested resume bullet:

Built an Xtext-based domain-specific expression language in Java with grammar design, static validation, Eclipse editor integration, runtime evaluation, example programs, and compiler-style tests.