# FlexLang

> A language for declaring the data that system components exchange and the protocols that govern those exchanges.

Flex is open and non-proprietary, and is maintained independently of any vendor implementation.

- /flex/appendices/grammar — the concrete syntax in EBNF, normative and complete.
- /flex/appendices/positions — every construct and the positions that accept it.

The whole language reference is also published as a single file at /llms-full.txt, roughly 50k tokens.

## Table of Contents

- [What Flex is](https://flexlang.org/flex/start.md): A language for declaring the data that system components exchange and the protocols that govern those exchanges.
- [Grammar](https://flexlang.org/flex/appendices/grammar.md): The concrete syntax of Flex, in EBNF.
- [Reserved Words](https://flexlang.org/flex/appendices/keywords.md): Every word Flex reserves.
- [Diagnostic Index](https://flexlang.org/flex/appendices/diagnostic-index.md): Every diagnostic the checker can report, and the section that shows what causes it.
- [What goes where](https://flexlang.org/flex/appendices/positions.md): A Flex file is its `module` header, then its imports, then a run of global declarations.
- [array](https://flexlang.org/flex/data-types/array.md): A homogeneous, ordered, variable-length collection, written by suffixing `[]` to the element type.
- [const](https://flexlang.org/flex/data-types/const.md): A named, immutable value declared at module scope.
- [enum](https://flexlang.org/flex/data-types/enum.md): A named type whose values are listed in the declaration, each fixed to a literal of a primitive backing type.
- [newtype](https://flexlang.org/flex/data-types/newtype.md): A nominal single-field wrapper, distinct from the type it wraps: no conversion runs in either direction, and two newtypes over one underlying type are not interchangeable.
- [optional](https://flexlang.org/flex/data-types/optional.md): A value that is either present or absent: `Optional<T>` holds `some(v)` or `none`.
- [primitives](https://flexlang.org/flex/data-types/primitives.md): The built-in types every other type is composed from: `bit`, `string`, `float32`, `float64`, and the arbitrary-width integers `intN` and `uintN`.
- [struct](https://flexlang.org/flex/data-types/struct.md): A named record of zero or more typed fields.
- [tuple](https://flexlang.org/flex/data-types/tuple.md): An ordered, fixed-length group of two or more values, each with its own type.
- [type alias](https://flexlang.org/flex/data-types/type-alias.md): A structurally transparent name for an existing type, declared with `type`.
- [variant](https://flexlang.org/flex/data-types/variant.md): A discriminated union: a named set of constructors, each carrying zero or more payload types.
- [block, let, assert](https://flexlang.org/flex/expressions/block-let-assert.md): A braced sequence of statements ending in one tail expression.
- [if](https://flexlang.org/flex/expressions/if.md): A choice between two branches on a `bit` condition.
- [literals](https://flexlang.org/flex/expressions/literals.md): The forms that write a value out directly: the primitive literals, and the composite forms for a struct, a tuple, and an array.
- [match](https://flexlang.org/flex/expressions/match.md): A test of one value against ordered arms, where the first pattern that matches decides the result.
- [operators](https://flexlang.org/flex/expressions/operators.md): The arithmetic, concatenation, comparison, equality, logical, bitwise, and shift operators.
- [try](https://flexlang.org/flex/expressions/try.md): An expression whose failure becomes an absent value.
- [value_cast](https://flexlang.org/flex/expressions/value-cast.md): An explicit conversion between numeric types.
- [builtin functions](https://flexlang.org/flex/functions/builtin-functions.md): The fixed library of functions every module already has.
- [function](https://flexlang.org/flex/functions/function.md): A top-level declaration taking at least one parameter and returning a declared type.
- [transform](https://flexlang.org/flex/functions/transform.md): A named translation between message types.
- [comprehension](https://flexlang.org/flex/iteration/comprehension.md): An array whose elements are computed.
- [fold, map, filter, flatmap](https://flexlang.org/flex/iteration/fold-map-filter-flatmap.md): Looping expressions over a collection.
- [comments and whitespace](https://flexlang.org/flex/lexical/comments-and-whitespace.md): Text the language ignores.
- [identifiers](https://flexlang.org/flex/lexical/identifiers.md): A name a declaration or a binding carries.
- [annotation](https://flexlang.org/flex/metadata/annotation.md): A named piece of metadata with optional parameters and optional scope restrictions.
- [contract](https://flexlang.org/flex/metadata/contract.md): A named block whose last statement is an `assert`.
- [import](https://flexlang.org/flex/modules/import.md): A declaration bringing another module's top-level declarations into this file's scope, either behind an alias or one element at a time.
- [module](https://flexlang.org/flex/modules/module.md): A file header naming the file.
- [branch](https://flexlang.org/flex/protocols/branch.md): A decision a component makes inside a local protocol by evaluating guards.
- [choice](https://flexlang.org/flex/protocols/choice.md): A decision about which arm of a global protocol runs, made by the components named after `in`.
- [component](https://flexlang.org/flex/protocols/component.md): A named participant in a protocol: something that sends and receives messages.
- [connection](https://flexlang.org/flex/protocols/connection.md): A unidirectional channel between two components: one always sends, the other always receives.
- [do](https://flexlang.org/flex/protocols/do.md): A call to another protocol.
- [exch](https://flexlang.org/flex/protocols/exch.md): One interaction between two components: the send and the matching receive as a single step of a global protocol.
- [global protocol](https://flexlang.org/flex/protocols/global-protocol.md): A whole conversation between components, written as one ordered sequence of exchanges.
- [group](https://flexlang.org/flex/protocols/group.md): A named set of components and other groups: an architectural boundary drawn around runnable software, not a participant in it.
- [in block](https://flexlang.org/flex/protocols/in-block.md): Local statements inside a global protocol, executed by one component.
- [listen](https://flexlang.org/flex/protocols/listen.md): A decision made inside a local protocol by the message that arrives.
- [local protocol](https://flexlang.org/flex/protocols/local-protocol.md): The behavior of one component, written as one ordered sequence of statements.
- [loop, break](https://flexlang.org/flex/protocols/loop.md): A block that repeats until something inside it breaks out.
- [parallel](https://flexlang.org/flex/protocols/parallel.md): Branches inside a global protocol that run at the same time.
- [recv](https://flexlang.org/flex/protocols/recv.md): In a local protocol, a message arriving at the component the statement is written in.
- [send](https://flexlang.org/flex/protocols/send.md): In a local protocol, a message leaving the component the statement is written in.
- [system](https://flexlang.org/flex/protocols/system.md): A named set of local protocols that runs together: one protocol per component, giving the whole assembly's behavior.