8000 GitHub - kexhq/kex at time-floordiv-div · GitHub
[go: up one dir, main page]

Skip to content
kexhqPublic

About

Pragmatically functional BEAM language

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

 
 

Latest commit

 

History

1,520 Commits

Folders and files

Repository files navigation

Kex

CI

Kex is a functional programming language with Ruby-like syntax, immutable data by default, UFCS for chaining function calls, type-directed make blocks, pattern matching, and explicit side-effect boundaries.

It is designed for code that reads like a scripting language without giving up typed records, sum types, pure functions, and predictable dispatch.

Warning

No backward compatibility is attempted before version 1.0.0. The language, the standard library, the package format and the on-disk layouts change between releases without deprecation cycles.

Kex ships with Tey, its package, compiler, runtime, and standard-library manager. Installing Tey installs a working kex:

brew tap kexhq/tey
brew install kexhq/tey/tey
kex --version

Without Homebrew, the same install is one line — it fetches the published release, verifies its checksum, and runs tey kex install for the compiler:

curl -fsSL https://kex.run/install.sh | sh

Teaching an AI agent Kex

kex --skill prints a guide to writing Kex, made for an AI agent to read before it writes any; kex --help points every agent at it. In Claude Code the same guide installs as a plugin:

/plugin install kex --marketplace kexhq/kex

The kex on your PATH is Tey's dispatcher: it runs whichever toolchain Tey has selected, so there is only ever one compiler command and Tey decides what it means.

tey kex list [--pre]        # released and installed versions
tey kex install [<version>] # newest stable, or the one you name
tey kex use <version>       # switch what `kex` runs
tey upgrade [--pre] [<version>] # upgrade Tey itself (non-brew installs)

Kex and Tey are released as a pair, so tey kex install also fetches the Tey that Kex release shipped with and keeps it beside the toolchain; while that Kex is selected, tey runs it. A pre-release is tested with its own Tey that way, even under Homebrew. --no-tey skips it.

The tap follows the stable line; --HEAD still works and builds from main. Pre-releases never arrive through brew — tey kex install --pre and tey kex list --pre are the channel-aware way to them. Docker images are published as ghcr.io/kexhq/kex (:slim for a small one that keeps the BEAM backend), and carry tey as well as kex — which is what makes them usable as a CI image on any platform that takes one. Maintainers cutting a release: see docs/releasing.md.

Tey itself is written in Kex; its implementation lives entirely under the Tey supermodule in tey/src/tey/.

record Vector2D do
  x : Float
  y : Float
end

make Vector2D do
  let +(other: This) -> This do
    return Vector2D { x: @x + other.x, y: @y + other.y }
  end

  let *(factor: Float) -> This do
    return Vector2D { x: @x * factor, y: @y * factor }
  end

  let near?(other: This) -> Bool do
    (@x - other.x).abs < 0.01 && (@y - other.y).abs < 0.01
  end

  let to(String) -> String? do
    Just("(${@x}, ${@y})")
  end
end

main do
  let position = Vector2D { x: 3.0, y: 4.0 }
  let velocity = Vector2D { x: 1.0, y: -0.5 }

  let arrived = position + velocity * 2.0
  IO.printLine("next position: ${arrived.to(String).or("")}")
  IO.printLine("arrived? ${arrived.near?(Vector2D { x: 5.0, y: 3.0 })}")
end

Why Kex

Kex tries to make the common path feel light:

  • UFCS chains function calls, passing each result as the next call’s first argument: items.filter(...).map(...).take(10).
  • Domain behavior lives near the type through make, without classes or inheritance-heavy hierarchies. @field is shorthand for this.field inside those blocks, and operators (+, ==, ...) can be overloaded the same way.
  • Pattern matching works in function clauses, match expressions, and receiver patterns.
  • Effects are visible: functions are pure unless marked foul, and main is the effect boundary.
  • Immutable record updates stay concise: New { field: value } copies a receiver, while repeated new.field = value assignments functionally rebind a local copy.
  • serving turns a record into a typed OTP-style server protocol with checked calls, asynchronous casts, timeouts, and deferred replies.
  • Records, sum types, optional values, result values, ranges, streams, maps, and lists are built into the language model.

Language Tour

Natural Function Chaining

Uniform Function Call Syntax means value.f(arg) is equivalent to f(value, arg). You get fluent pipelines while keeping functions as plain functions.

let suspicious = requests
  .filter { |req| req.path.startsWith?("/admin") }
  .reject(&.authenticated?)
  .map { |req| SecurityEvent.from(req) }
  .take(20)

# Equivalent forms; pick whichever reads better locally.
requests.map(~normalize)
map(requests, ~normalize)

Type-Directed Behavior Without Classes

make blocks group functions by the type of their first argument. The same function name — even an operator — can exist for different receiver types; dispatch is based on the receiver. Inside a make block, @field is shorthand for this.field.

record Vector2D do
  x : Float
  y : Float
end

module Vector2D do
  let Zero = Vector2D { x: 0.0, y: 0.0 }
  let UnitX = Vector2D { x: 1.0, y: 0.0 }
end

record Vector3D do
  x : Float
  y : Float
  z : Float
end

make Vector2D do
  let +(other: This) -> This do
    return Vector2D { x: @x + other.x, y: @y + other.y }
  end

  let *(factor: Float) -> This do
    return Vector2D { x: @x * factor, y: @y * factor }
  end

  let dot(other: This) -> Float do
    return @x * other.x + @y * other.y
  end

  let to(String) -> String? do
    return Just("(${@x}, ${@y})")
  end
end

make Vector3D do
  let +(other: This) -> This do
    return Vector3D { x: @x + other.x, y: @y + other.y, z: @z + other.z }
  end

  let to(String) -> String? do
    return Just("(${@x}, ${@y}, ${@z})")
  end
end

let unitX = Vector2D { x: 1.0, y: 0.0 }
let shot = (unitX * 2.0 + Vector2D { x: 0.0, y: 5.0 }).to(String).or("")
# "(2.0, 5.0)" — `*` resolves through Vector2D::*, `+` through Vector2D::+

Pattern Matching As Control Flow

Kex supports multi-clause functions, match expressions, destructuring, and @pattern to match on the receiver itself (separate from the @field shorthand shown above).

let fizzBuzz(n: Int) -> String do
  match (n.modulo(3), n.modulo(5)) do
    (0, 0) => "FizzBuzz"
    (0, _) => "Fizz"
    (_, 0) => "Buzz"
    (_, _) => n.to(String).or("")
  end
end

main do
  (1..100)
    .map(~fizzBuzz)
    .each { |s| IO.printLine(s) }
end

Functional Record Updates

Inside a record's make block, New { ... } copies the current receiver and replaces selected fields. For several updates, implicit new starts as the receiver and field assignment functionally rebinds that local copy:

make User do
  let birthday -> User = New { age: @age + 1 }

  let activateAs(name: String) -> User do
    new.name = name
    new.active? = true
    return new
  end
end

The original record is never mutated. See docs/records-and-updates.md.

Typed Servers

serving attaches checked call and cast slots to record state:

record ShoppingList do
  items : [String] = []
end

serving ShoppingList do
  slot items -> Reply<[String]> = { reply: @items }

  slot add(item: String) -> Reply<Integer> do
    new.items = [item | @items]
    return { new, reply: new.items.count }
  end

  slot clear -> Void = New { items: [] }
end

let groceries = Process.spawn(ShoppingList {})
groceries.add("coffee", within: 10_000)

On BEAM these are OTP gen_server processes using ordinary tuple requests, including direct Erlang/Elixir interoperability. See docs/serving.md.

Networking

Networking is opt-in and backend-aware: strict URI/IP/DNS values, process-owned TCP/UDP/Unix/TLS handles, buffered HTTP/1.1, and WebSocket clients live outside the prelude. See the current API, examples, limits, and backend behavior in docs/networking.md; docs/net-plan.md tracks the remaining redesign work.

Records, Sum Types, Optional, Result

Data modeling is direct: records for product types, type for unions, ? for optional values, and Result for fallible flows.

type ParseError = InvalidFormat(String) | Overflow | EmptyInput

let parseInt(s: String) -> Result<Int, ParseError> do
  return Error(EmptyInput) if s.empty?
  match Integer.parse(s) do
    Ok(n)    => Ok(n)
    Error(_) => Error(InvalidFormat(s))
  end
end

let parsePort(s: String) -> Result<Int, ParseError> do
  let n = parseInt(s).try
  return Error(Overflow) if n > 65535
  return Ok(n)
end

foul loadConfig(path: String) -> Result<Config, AppError> do
  let content = IO.readFile(path).try
  let parsed = Config.parse(content).try
  let port = parsePort(parsed.get("port")).try
  return Ok(Config { port: port, host: parsed.get("host") })
end

Purity Is the Default

Functions are pure unless marked foul. Pure code cannot call foul code, so side effects stay visible in the type of the program.

let compute(x: Int) = x * 2 + 1

foul readConfig(path: String) do
  return FS.File.read(path)
end

# Compile error: pure code cannot call foul code.
let bad(path: String) = readConfig(path)

main is implicitly foul, so programs still have a natural place for IO.

Local Mutation With var and !

Bindings are immutable by default. var opts into local mutation, and ! is reassignment sugar for functions that return an updated value — it rebinds the variable rather than mutating the underlying value in place, so aliases never see the change.

main do
  let frozen = [1, 2, 3]
  # frozen.push!(4)
  # runtime error: cannot use '!' on immutable binding: frozen

  var list = [1, 2, 3, 4, 5]
  list.push!(6)
  list.filter!(&.even?)
  list.map! { |x| x * 10 }
  # list is now [20, 40, 60]
end

Lazy Streams and Ranges

Ranges and streams share collection-style operations. Infinite streams stay lazy until consumed.

let naturals = Stream.from(0) { |n| n + 1 }

let primes = Stream.from(2) { |n| n + 1 }
  .filter do |n|
    (2..n - 1).all? { |d| n.modulo(d) != 0 }
  end

let firstTenPrimes = primes.take(10)

let squaresOfMultiplesOfThree = (1..100)
  .filter { |x| x.modulo(3) == 0 }
  .map { |x| x * x }
  .take(5)

Currying and Partial Application

~ creates a partially applied function. Bound arguments fill left-to-right; _ marks an explicit open slot for a specific position. Chained (args) groups that fully saturate the function call it immediately — no extra wrapping.

let add(a, b) = a + b
let multiply(a, b) = a * b

let inc = ~add(1)
let double = ~multiply(2)

main do
  let multipled = [1, 2, 3].map(~multiply(10))
  IO.printLine(multipled)

  let summed = (1..100).reduce(0, ~(+))
  IO.printLine(summed)
end

Traits

Traits declare required functions and can provide default implementations. Implementing types get the defaults for free.

trait Shape do
  area      : () -> Float
  perimeter : () -> Float

  let describe = "area=${this.area}, perimeter=${this.perimeter}"
end

record Circle do
  radius : Float
end

record Rectangle do
  width  : Float
  height : Float
end

make Circle, implement: Shape do
  let area      = Math.PI * @radius * @radius
  let perimeter = 2.0 * Math.PI * @radius
end

make Rectangle, implement: Shape do
  let area      = @width * @height
  let perimeter = 2.0 * (@width + @height)
  let describe  = "Rectangle ${@width}x${@height} (area=${this.area})"  # override default
end

let shapes = [
  Circle { radius: 5.0 },
  Rectangle { width: 4.0, height: 6.0 },
]

shapes.each { |s| IO.printLine(s.describe) }
# area=78.53981633974483, perimeter=31.41592653589793
# Rectangle 4.0x6.0 (area=24.0)

DSL-Friendly Builders

Kex is intended to make embedded DSLs feel native. Block arguments and do |x| ... end syntax let library code read like built-in language constructs.

let app = Http.routes do
  get "/" do |req|
    Response.ok("Welcome")
  end

  get "/users/:id" do |req|
    match UserService.find(req.params.id) do
      Just(user) => Response.json(user)
      None => Response.notFound("user not found")
    end
  end

  post "/users" do |req|
    let user = UserService.create(req.body)
    return Response.created(user) if user.ok?

    return Response.error("error while creating user")
  end
end

A real one, from Metro — Kex's Rails-like web framework. A page is a tree of nodes whose children are collected from the block, and render walks it once, escaping text and attribute values on the way out (Metro.Html generates a constructor for every HTML element at compile time with compiled do; here is one of them, in full):

module Html do
  record Tag do
    name       : String
    attributes : {String: String} = {}
    children   : [Node] = []
  end

  type Node = Tag(Tag) | Text(String)

  text : String -> Node
  let text(contents) = Text(contents)

  let div(attributes: {String: String}, children: Block<[Node]> = {[]}) -> Node do
    return Tag(Tag { name: "div", attributes: attributes, children: children() })
  end

  render : Node -> String
  let render(Text(contents)) = Template.escapeHtml(contents)
  let render(Tag(tag)) do
    let attributes = tag.attributes.entries.map { |name, value|
      " ${name}=\"${Template.escapeHtml(value)}\""
    }.join("")
    let inner = tag.children.map { |child| render(child) }.join("")
    return "<${tag.name}${attributes}>${inner}</${tag.name}>"
  end
end

using Html

main do
  let page = div({"class": "menu"}) do
    text("Not <b>markup</b>")
  end
  IO.printLine(Html.render(page))
  # <div class="menu">Not &lt;b&gt;markup&lt;/b&gt;</div>
end

Type-Level Constructors and Constants

Constructors and constants for a type live in a module of the same name, declared alongside the type. Constructors are capitalized lets that build an instance; constants are capitalized lets that just hold a value. One name thus carries up to three declarations — record for the data, module for the type-level functions, make for functions taking a value of the type.

record Temperature do
  celsius : Float
end

module Temperature do
  let Celsius(value: Float) -> Temperature do
    return Temperature { celsius: value }
  end

  let Fahrenheit(value: Float) -> Temperature do
    return Temperature { celsius: (value - 32.0) * 5.0 / 9.0 }
  end

  let Freezing = Temperature { celsius: 0.0 }
end

make Temperature do
  let to(String) -> String? do
    return Just("${@celsius}C")
  end
end

let boiling = Temperature.Fahrenheit(212.0).to(String).or("")  # "100.0C"
let zero = Temperature.Freezing.to(String).or("")              # "0.0C"

Try It

Build the compiler:

make build

Run a file:

make run F=examples/fizzbuzz.kex
build/kex examples/vectors_advanced.kex

Start the REPL:

make repl

Editor support

The compiler includes a Language Server Protocol mode with completion, inferred type/declaration hover, and live compiler diagnostics for unsaved buffers:

kex --lsp

The VS Code extension in editors/vscode adds Kex syntax highlighting and launches this server. It's published on the VS Code Marketplace:

code --install-extension Kex.kex-language

Or search for "Kex" in the Extensions view. See its README for development instructions and to build it from source instead.

The Vim/Neovim runtime files in editors/vim add syntax highlighting, indentation, and % matching on do/end; on Neovim they also ship a vim.lsp.config entry for the same server. There's no separate plugin repo yet — install straight from this checkout, e.g. with lazy.nvim:

{ dir = "/path/to/kex/editors/vim", name = "kex", lazy = false }

See its README for plugin-manager examples and how to put it on your runtimepath directly.

Install the binary somewhere on your PATH:

make build
sudo make install

By default, make install copies the existing build/kex to /usr/local/bin/kex. It intentionally does not build as root. To install elsewhere:

make install PREFIX=$HOME/.local

Commands

make build          # Build the compiler
make test           # Run C++ unit tests
make spec           # Run executable language specs
make parse          # Parse all examples
make repl           # Start the interactive REPL
make run F=file     # Run a .kex file (type-checks first; use --no-check to skip)
make check F=file         # Run semantic analysis only
make check-examples       # Type-check all examples
make install              # Install build/kex to /usr/local/bin/kex
make uninstall      # Remove the installed binary
make clean          # Remove build artifacts

# Compile a nested file with an explicit project module root (repeatable)
build/kex --compile --source-root src -o build/beam src/tools/task.kex

Requires CMake 3.20+ and a C++20 compiler. Readline is optional.

Building from source in CI

make build (or cmake --build build --parallel $(nproc), what it wraps) already bounds parallelism to the host's CPU count — see the comment on JOBS in the Makefile. A downstream project building Kex+Tey directly with cmake --build build --parallel (no job count, meaning unbounded) has hit OOM kills on standard 2 vCPU/7GB CI runners: enough independent heavy C++20 translation units (the compiler itself, the vendored LSP framework's code generator, and — only relevant if the default all target is built — the test executables) become ready to compile at once that GNU Make launches far more cc1plus processes than the runner has memory for (#363).

If you only need build/kex (for example to then run make -C tey build KEX=/path/to/kex), build just that target rather than the default all, and always pass an explicit, conservative job count on a small runner:

cmake -B build -G "Unix Makefiles" -DKEX_BOOST_STATIC=ON
cmake --build build --target kex --parallel 2   # not bare --parallel

--target kex skips every test executable but still builds the vendored LSP framework (kex's built-in --lsp mode links it), so it is lighter than a full build, not free — an explicit job count is what actually caps memory use on a small runner.

Examples

Good starting points:

  • examples/basics.kex - core syntax
  • examples/traits.kex - Shape trait, required/default/overridden functions, multiple traits
  • examples/vectors_advanced.kex - records, type-level constructors, functions called through UFCS
  • examples/streams.kex - lazy ranges and streams
  • examples/template_stdlib.kex - DSL-style template blocks (see also examples/templates/)
  • examples/error_handling.kex - Result, optional values, and Result handling
  • spec/type_dispatch.kex - dispatch through make and receiver patterns
  • spec/operator_overloading.kex - overloading +, *, == per receiver type
  • spec/at_field_shorthand.kex - @field/@function(...) inside make blocks
  • spec/mutating_calls.kex - var/let and ! mutation semantics
  • spec/record_module_constructors.kex - constructors/constants in a module of the record's name stay namespaced under it
  • spec/math.kex - the Math module (Math.PI, Math.sqrt, trig, logs, ...)
  • spec/testing_dsl.spec.kex - the describe/it/assert testing DSL itself
  • spec/json_parser.spec.kex - a spec for examples/json_parser.kex using describe/it/assert (see "Specs for example files" in docs/testing.md)

Project Structure

src/
  lexer/        Tokenizer
  parser/       Recursive descent parser
  ast/          AST node types
  semantic/     Scope resolution, purity checking, type checking
  interpreter/  Tree-walk interpreter
  stdlib/       Kex standard library; prelude.kex selects the automatically visible subset
  main.cxx      CLI entry point

examples/       Language showcase files
spec/           Runnable programs with expected output
tests/          C++ unit tests
docs/           Language reference documentation
grammar.ebnf    Formal grammar specification

Compiler Development

The compiler is written in C++20 and needs CMake 3.20+. On macOS or Linux with Homebrew, the repo's Brewfile installs every native dependency a source checkout needs:

brew bundle --no-upgrade

--no-upgrade keeps it to the missing formulae; without it, brew also upgrades every one of these it already has installed. The Brewfile exists for working on Kex itself — it is not part of how anyone installs Kex, and nothing but a local dev setup reads it. What the dependencies cover: CMake (the build system itself), GMP (arbitrary-precision Integer), PCRE2 (regex in the interpreter — the BEAM backend uses Erlang's re instead), Boost.Context (native fibers), Erlang/OTP 27 or newer (erlc for the runtime beams and BEAM backend), OpenSSL (SHA-256 on Linux only — macOS uses CommonCrypto), and readline (optional, nicer REPL).

The wasm target's extra dependencies — emsdk pinned to 5.0.7 and the prebuilt GMP/PCRE2 under third_party/*-wasm — are not installable through brew; see those READMEs.

Source flows through:

Lexer -> Parser -> AST -> Analyzer -> ┬─ Evaluator (tree-walk interpreter, default)
                                      └─ IR -> Core Erlang -> BEAM

The default runner is the BEAM: kex file.kex compiles through the lowering IR (src/ir/) that emits Core Erlang for the BEAM backend (kex -c / -R / -e); it matches the interpreter at full spec parity.

Key implementation choices:

  • AST nodes and runtime values use std::variant.
  • make Vec2 do let add(...) end registers behavior as Vec2::add.
  • UFCS resolves by checking the receiver type and looking up the mangled function name.
  • Purity is enforced in a semantic pass before evaluation.

Status

Working today:

  • Lexer, parser, AST, semantic analysis, and tree-walk evaluation
  • BEAM backend: lowering IR → Core Erlang codegen (kex -c/-R/-e), at full spec parity with the interpreter
  • Process primitives (spawn, receive, send, loop, Task) on both the interpreter and BEAM
  • Typed Process<Message> handles and serving state machines with calls, casts, state/stop transitions, timeouts, and deferred replies
  • Records, sum types, functions, lambdas, pattern matching, destructuring
  • Lists, maps, ranges, streams, strings, chars, numbers, optional values, result values
  • UFCS, make dispatch, to conversion convention, operator overloading
  • @field/@function(...) shorthand for this inside make blocks
  • foul purity boundaries, and local var mutation enforced at runtime
  • Traits: trait ... do end, make X implement: Trait do end, Comparable, Equatable
  • Currying and partial application with ~func(args), ~(op), and _ placeholders
  • Type checker active by default (kex run gates on type checking; --no-check to skip)
  • Stdlib type signatures, trait-constrained overload resolution, lambda type inference
  • Arbitrary-precision Integer (GMP-backed), numeric tower, match exhaustiveness checking
  • Rich stdlib: uniq, partition, indexOf, flatMap, contains?, min/max returning Optional, char predicates (digit?, alpha?, space?), and more
  • Regexes (using Regex): PCRE2 in the interpreter, Erlang re on BEAM — same PCRE language; regex`\d+` tag literals validated at compile time (via the validate<Tag> companion convention), regex$…`` with auto-escaped interpolation, matches/`matches?`/`scan`/`replace`/`split`, and a map-like `Match` with numbered and named (`:atom`) captures
  • REPL with optional readline support

Planned or incomplete:

  • Compiling Kex itself to WASM (today only the interpreter is compiled to wasm, for the in-browser REPL)
  • Richer supervision DSL and generated child specifications for typed servers
  • A full module system across BEAM modules
  • is? / as type introspection and explicit conversion
  • Namespace/import resolution beyond using blocks
  • Compiled metaprogramming beyond the parser/design sketch

License

MIT

About

Pragmatically functional BEAM language

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0