#SEL documentation

SEL is a small expression language for business rules with five implementations — Python, JavaScript, PHP, C++23 and Common Lisp — that give the same answer, in memory or translated for a database. Start wherever your question is.

#Reading paths

#Contents

Start here

• Overview — the problem, what a program is, the design principles, where SEL fits, what it leaves out
• How parity is achieved and guaranteed — never the host's idea of a number or a string; generated artifacts; every layer of the gate

The language

• Syntax — programs, names, values and kinds, numbers, text, lists and records, booleans, NULL, variables, binders, errors
• Operators — precedence, exact arithmetic, the three comparison families, coalescing, assignment, the pipeline operator .>
• Functions — control, aggregates, sorting, grouping, slicing, joins, null safety, text, numbers, binary, regular expressions

Using SEL — every snippet in five languages, quoted from programs the test suite runs

• Using SEL — installing; the host API in one page
• A REPL in thirty lines
• Validation — a form's rules, in the browser and on the server
• Scripting with host functions — the application's functions, the business's policy

SEL and SQL

• SQL conditions — a rule as a WHERE clause, on SQLite, MariaDB and PostgreSQL, naive and described
• SQL pipelines — whole statements, hybrid plans, and the example data
  • Star schema — PostgreSQL
  • Entity–attribute–value — SQLite
  • Third normal form — PostgreSQL
  • Unnormalised data — MariaDB
  • Your own functions, in SQL — host functions spelled as PostgreSQL stored functions
  • Complex data, in memory — PostgreSQL, and no database at all
• SEL and SQL — reference — dialects, entry points, fragments, bindings, kinds, refusals, caveats

Extending

• Extending SEL — host functions, dialects of your own, SQL spellings, and how a builtin joins the language
• Contributing — the order of work, the argument and value APIs, operators, conformance cases, the traps each host has fallen into, the checks, a sixth host

Reference

• Builtin index and Limits and error codes — generated from the specification's manifests
• The specification, the grammar and the error codes — normative
• The dialect map format and the SQL error codes
• The conformance suite and the SQL case format

Internals

• SQL translation: the design and the kind warrant
• Math-plan operations — generated
• The test harness, Packaging, Changelog

#Two ways to read this

These pages are Markdown, and read well on GitHub. The same pages are also a styled site — language tabs instead of five stacked code blocks, a navigation sidebar, dark mode:

node tools/build-docs.mjs --serve 8080      # needs `npm install` once
docker build -f docs/Dockerfile -t sel-docs . && docker run --rm -p 8080:80 sel-docs

Every expr => result example on these pages is executed by all five implementations, every code block quoted from examples/ is compared with the file it came from, and every link is checked — the documentation is part of the test suite.