# OxigenLang

> OxigenLang (also called Oxigen) is a modern, general-purpose programming language created by Javan Hutchinson. It is implemented in Rust and runs on a bytecode virtual machine with a baseline Cranelift JIT that is on by default. Source files use the `.oxi` extension and run with the `oxigen` command.

Key facts:

- Creator: Javan Hutchinson (https://github.com/javanhut). OxigenLang was designed and is developed by Javan Hutchinson.
- Website: https://www.oxigenlang.org (oxigenlang.org and oxigenlang.com redirect here). Source: https://github.com/javanhut/OxigenLang. License: MIT or Apache-2.0.
- Paradigm: dynamically typed with optional, enforced type annotations; first-class functions and closures; structs with methods and single inheritance; Rust-style enums; named patterns matched with `choose`; a two-tier error model (propagating errors and `Error`/`Value` result values).
- Runtime: bytecode VM in Rust plus a Cranelift JIT that tiers hot functions to native code; share-nothing parallelism on OS threads with `diverge`/`converge`; embeddable in Rust hosts with capability sandboxing.
- Tooling: REPL, `oxigen fmt` formatter, `oxigen test` test runner, `oxigen check` JSON diagnostics, `oxigen explain` error codes, a language server and Neovim support.
- Standard library: 24 modules: ansi, api, array, channel, datetime, encoding, env, ffi, hash, io, json, math, net, os, parse_args, path, random, regex, result, sets, strings, test, time, toml.
- Try it: https://www.oxigenlang.org/playground/ runs OxigenLang in the browser via WebAssembly.

Syntax at a glance:

```oxi
introduce strings

struct Person {
    name <str>
    age <int>
}

Person includes {
    fun greet() { "Hello, {self.name}" }
}

pattern is_even(n) when n % 2 == 0

main {
    p := Person("Ada", 36)
    println(p.greet())
    each i in range(4) {
        choose i {
            is_even -> println("{i} is even"),
            else -> println("{i} is odd")
        }
    }
}
```

## Start here

- [Getting started](https://www.oxigenlang.org/docs/getting-started/index.md): Install OxigenLang, run your first program, and learn the oxigen command: the REPL, fmt, check, test and explain.
- [Syntax quick reference](https://www.oxigenlang.org/docs/syntax/index.md): All of OxigenLang's syntax on one page: variables, types, functions, control flow, structs, enums, patterns, errors and imports.
- [Conventions](https://www.oxigenlang.org/docs/conventions/index.md): How idiomatic Oxigen reads: explicit types, implicit returns, one construct per job, and naming and layout rules.

## Language guide

- [Variables](https://www.oxigenlang.org/docs/variables/index.md): The four ways to declare a variable in OxigenLang, and what each says about mutability and type.
- [Data types](https://www.oxigenlang.org/docs/data-types/index.md): Integers, floats, strings, chars, booleans, arrays, tuples, maps, sets, bytes and None in OxigenLang.
- [Operators](https://www.oxigenlang.org/docs/operators/index.md): Arithmetic, comparison, logical and postfix operators in OxigenLang, and the order they bind in.
- [Control flow](https://www.oxigenlang.org/docs/control-flow/index.md): Decisions with option and unless, guards with when, and loops with each and repeat in OxigenLang.
- [Functions](https://www.oxigenlang.org/docs/functions/index.md): Named and anonymous functions in OxigenLang: typed, default, optional and named parameters, closures and recursion.
- [Structs](https://www.oxigenlang.org/docs/structs/index.md): Structs in OxigenLang: typed fields, methods with includes, inheritance, hidden fields and self.
- [Enums](https://www.oxigenlang.org/docs/enums/index.md): Enums in OxigenLang: unit, tuple and struct variants, discriminants, and matching on them.
- [Pattern matching](https://www.oxigenlang.org/docs/pattern-matching/index.md): Name a condition once with pattern, then dispatch on it with choose. Pattern matching in OxigenLang.
- [Type system](https://www.oxigenlang.org/docs/type-system/index.md): OxigenLang is dynamic by default. Add an annotation and a variable's type is locked and checked by the VM.
- [Angle forms and errors](https://www.oxigenlang.org/docs/angle-forms/index.md): OxigenLang's <...> forms: type annotations, casts, Error and Value results, <guard>, <log>, <fail> and <test>.
- [Imports and modules](https://www.oxigenlang.org/docs/imports/index.md): Import the standard library or your own files with introduce: namespaces, selective imports and module caching.
- [Concurrency](https://www.oxigenlang.org/docs/concurrency/index.md): Run work on every core with diverge and converge. Share-nothing tasks on real OS threads, with no locks.
- [Testing](https://www.oxigenlang.org/docs/testing/index.md): Write <test> blocks with expect() matchers next to your code and run them with oxigen test.
- [Built-in functions](https://www.oxigenlang.org/docs/builtins/index.md): Every built-in OxigenLang function, from print and len to range, type and the collection helpers.

## Standard library

- [Overview](https://www.oxigenlang.org/docs/stdlib/index.md): The 23 modules of the OxigenLang standard library, what each is for, and how to import them.
- [math](https://www.oxigenlang.org/docs/stdlib/math/index.md): The OxigenLang math module: arithmetic, rounding, trigonometry, logarithms and integer number theory.
- [strings](https://www.oxigenlang.org/docs/stdlib/strings/index.md): The OxigenLang strings module: splitting, joining, trimming, case conversion, searching and padding.
- [array](https://www.oxigenlang.org/docs/stdlib/array/index.md): The OxigenLang array module: map, filter, reduce, folds, searching, grouping and sorting.
- [sets](https://www.oxigenlang.org/docs/stdlib/sets/index.md): The OxigenLang sets module: union, intersection, difference, subset tests and filtering.
- [json](https://www.oxigenlang.org/docs/stdlib/json/index.md): The OxigenLang json module: parse and serialize JSON, read and write JSON files, and query nested maps by dotted path.
- [toml](https://www.oxigenlang.org/docs/stdlib/toml/index.md): The OxigenLang toml module: parse and serialize TOML, read and write TOML files, and query nested tables by dotted path.
- [regex](https://www.oxigenlang.org/docs/stdlib/regex/index.md): The OxigenLang regex module: matching, searching, capturing and replacing with regular expressions.
- [result](https://www.oxigenlang.org/docs/stdlib/result/index.md): The OxigenLang result module: check, default, chain and recover Error || Value results without an option block.
- [io](https://www.oxigenlang.org/docs/stdlib/io/index.md): The OxigenLang io module: whole-file reads and writes, and line input from the console.
- [os](https://www.oxigenlang.org/docs/stdlib/os/index.md): The OxigenLang os module: running programs, background processes, signals, environment variables, directories and facts about the machine.
- [path](https://www.oxigenlang.org/docs/stdlib/path/index.md): The OxigenLang path module: build, split and inspect path strings, and check that one path is inside another.
- [net](https://www.oxigenlang.org/docs/stdlib/net/index.md): The OxigenLang net module: an HTTP and HTTPS client with streaming, plus TCP and UDP sockets.
- [api](https://www.oxigenlang.org/docs/stdlib/api/index.md): The OxigenLang api module: an HTTP server with routing, JSON, HTML and static-file responses and a threaded accept loop.
- [time](https://www.oxigenlang.org/docs/stdlib/time/index.md): The OxigenLang time module: clocks, sleeping and measuring elapsed time.
- [datetime](https://www.oxigenlang.org/docs/stdlib/datetime/index.md): The OxigenLang datetime module: UTC calendar dates and times, formatting and parsing.
- [random](https://www.oxigenlang.org/docs/stdlib/random/index.md): The OxigenLang random module: random integers, floats, booleans and picks from an array.
- [encoding](https://www.oxigenlang.org/docs/stdlib/encoding/index.md): The OxigenLang encoding module: Base64, hex and URL percent-encoding.
- [hash](https://www.oxigenlang.org/docs/stdlib/hash/index.md): The OxigenLang hash module: SHA-256, SHA-1 and MD5 digests as lowercase hex.
- [ansi](https://www.oxigenlang.org/docs/stdlib/ansi/index.md): The OxigenLang ansi module: terminal colours, text styles and cursor control.
- [parse_args](https://www.oxigenlang.org/docs/stdlib/parse-args/index.md): The OxigenLang parse_args module: a command-line flag parser built on os.args().
- [env](https://www.oxigenlang.org/docs/stdlib/env/index.md): The OxigenLang env module: load key/value pairs from a .env file.
- [test](https://www.oxigenlang.org/docs/stdlib/test/index.md): The OxigenLang test module: the expect() assertion matchers behind oxigen test.
- [channel](https://www.oxigenlang.org/docs/stdlib/channel/index.md): The OxigenLang channel module: pass messages between diverge tasks in order, with timeouts and closing.
- [ffi](https://www.oxigenlang.org/docs/stdlib/ffi/index.md): The OxigenLang ffi module: call C libraries by their C signatures, with structs, pointers, variadic functions and callbacks.

## Embedding and internals

- [Embedding in Rust](https://www.oxigenlang.org/docs/embedding/index.md): Embed OxigenLang in a Rust program such as a game engine: native functions, host values, capability sandboxing, loop budgets and hot reload.
- [FFI architecture](https://www.oxigenlang.org/docs/ffi-architecture/index.md): How OxigenLang calls C: signature parsing, value marshalling through libffi, struct layout, callbacks re-entering the VM, and the ffi capability.
- [JIT architecture](https://www.oxigenlang.org/docs/jit-architecture/index.md): How OxigenLang's Cranelift baseline JIT works: tiering, supported opcodes, inline caches, specialized entries, safety invariants and benchmarks.

## Optional

- [Full documentation in one file](https://www.oxigenlang.org/llms-full.txt): every page above, concatenated
- [Benchmarks](https://www.oxigenlang.org/benchmarks/): OxigenLang against CPython, Node and Bun
- [About OxigenLang and its creator](https://www.oxigenlang.org/about/)