# LCHR

**Repository Path**: ACleverDisguise/lchr

## Basic Information

- **Project Name**: LCHR
- **Description**: An implementation of [Constraint Handling Rules (CHR)](https://constraint-handling-rules.org/) in the Lua programming language.
- **Primary Language**: Lua
- **License**: WTFPL
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-19
- **Last Updated**: 2026-02-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LCHR

An implementation of [Constraint Handling Rules (CHR)](https://constraint-handling-rules.org/) in the Lua programming language.

## Software Architecture

CHR is a capstone language that typically sits atop a host.  The stereotypical host is a Prolog host, but there are CHR implementations in Java, Haskell, C, and Logtalk in varying degrees of completion and efficiency of implementation.  This project proposes to add Lua to the list.

A LCHR file is standard Lua code that will be typically structured thusly:

```lua
local chr = require 'chr`
local chrm = chr.new() -- alternatively chr()

--[[ Normal Lua code for modules, configuration, pre-execution, etc. goes here. ]]

chrm.directives [[
    % Optional CHR directives go here.
    % Directives are optional because all of them have sane defaults.
]]

chrm.predicates {
    -- predicates are Lua functions which *must* return `true` or `false` specifically
    -- they may not be merely `truthy`
    -- these predicates are used in CHR code proper as guards and other Lua
}

chrm.constraints [[
    % Actual CHR syntax is used here.
    % Any predicate calls that are not predefined by CHR must be in the chr.predicates record, supplied in Lua.
]]

chr.run(chrm)

```

Behind the scenes LCHR will compile and validate the directives and constraints.  It will build up the runtime components it needs to execute CHR code and can then be invoked in a variety of ways.

### But why!?

Lua is a simple, yet very powerful, scripting language that has a very friendly syntax and access to a lot of libraries that a Prolog implementation would struggle to match.  It has a lot of presence in game and industrial applications as a result, places where Prolog cannot fit (industrial/embedded) or where it is too alien for the people making the products (games).

CHR is a powerful toolkit for building bespoke constraint solvers.  Constraint programming is a paradigm that can dramatically clarify code in declarative ways while also dramatically speeding execution of complex algorithms in elegant ways that more brute force approaches cannot match.  For example, a sudoku solver in plain Prolog with logic variables and backtracking can take multiple seconds to solve a complicated puzzle while taking a few milliseconds when solved with a bespoke solver in CHR.

Pairing the simplicity, ubiquity, small size, and (for a scripting language) raw speed of Lua with the powerful techniques of constraint programming is a no-brainer.

## Installation

## Documentation

## Contribution

1.  Fork the repository
2.  Create `Feat_xxx` branch
3.  Commit your code
4.  Create Pull Request