Externs
An extern declaration tells Gale how to call or describe code outside Gale.
The declaration is a trusted contract: Gale checks its callers against the
signature, but cannot prove that the native implementation keeps that promise.
Functions
Section titled “Functions”A function extern names a native target and declares its Gale signature:
Typed declaration for a native text function. Gale callers use clean or trim.
mod externs.text
pub extern "String.trim" trim(value: String) -> String
pub fn clean(value: String) -> String { trim(value)}
pub extern type ForeignRef
pub extern ":erlang.make_ref" reference() -> ForeignRefGale emits String.trim(value) directly at each call site. The extern
generates no wrapper module, function or @spec. The native target keeps its full
name in generated Elixir; a Gale alias cannot redirect it. Erlang
functions use spellings such as ":erlang.send". For a public Gale
API with a spec, declare the extern privately and write a public fn, like
clean above.
With runtime typechecks enabled (the default in :test), Gale checks extern
arguments and return values at the call site; ordinary builds omit those
checks. Declared types remain your responsibility when the native shape is
one Gale cannot infer.
Exceptions become Results
Section titled “Exceptions become Results”If a native function may raise an expected exception, say so. extern raises
requires a Result return type and adapts every call: a normal return
becomes Ok, each declared exception becomes Error:
Expected native exceptions become typed Result errors. An explicit native
contract is trusted; Gale proves the wrapper and its callers against it.
mod externs.numbers
pub extern exception "ArgumentError" ArgumentError { message: String}
extern raises "String.to_integer" to_integer_native(value: String) -> Result<Integer, ArgumentError>
pub fn to_integer(value: String) -> Result<Integer, ArgumentError> { to_integer_native(value)}Foreign exceptions can also be constructed with %ArgumentError{message: "invalid"},
returned inside Error, matched, and updated like ordinary structs. Construction
uses the native struct defaults and sets the declared fields; it does not invoke
a custom native exception/1 factory. Bind that factory explicitly with extern
when required. Constructing a value never raises it.
The error union must name Gale-defined or extern exception types. Other exceptions are
reraised; exits and throws are not caught. The private extern converts; the
public to_integer gives Elixir callers a named, spec’d API.
Native contracts
Section titled “Native contracts”An extern can declare a contract. Gale uses it when proving callers, but the native contract remains a trusted assumption:
extern pure ":erlang.abs" absolute(value: Integer) -> Integerensures { result == if value < 0 { -value } else { value } }
pub pure fn magnitude(value: Integer) -> Integerensures { result >= 0 }{ absolute(value)}The proof report lists the native target, its effects and its contract as
assumptions. The native body is not verified; the example tests it with
positive, negative and zero inputs.
Mark pure only when the native operation truly is pure and total on its
domain: a false promise invalidates downstream conclusions. More complex
native semantics can be described by ordinary checked Gale functions
referenced from the contract; no compiler registry is needed to add a
binding.
Native types and structs
Section titled “Native types and structs”Three declarations cover the type side of the boundary, from most to least described:
extern struct describes a native Elixir struct whose fields Gale knows. Specs
name the real %Range{} instead of term(), and Gale code can read, match,
construct and update those fields on the native value. Gale emits no
replacement defstruct and copies nothing:
A native range is a known Elixir struct, built through its native constructor.
mod externs.range
pub extern struct "Range" IntegerRange { first: Integer, last: Integer, step: Integer}
pub extern "Range.new" new(first: Integer, last: Integer) -> IntegerRangePrefer native constructors when they establish invariants (Range.new over
building the struct by hand). Construction requires every declared field;
native defstruct defaults fill the undeclared ones; @enforce_keys still
applies. At checked Gale boundaries the runtime verifies the struct module
and recursively checks declared fields, allowing undeclared native ones.
extern type describes a nominal foreign value whose structure Gale does not
describe: no fields, projects to term(). When a hidden value’s runtime
category is known, a representation clause lets checks and proofs use it
while the value stays nominal. Hidden struct fields are checked at
boundaries but never inspectable:
pub extern type Worker<Message> representation(1) pidpub extern type Token<Tag> representation(1) referencepub extern type Box<A> representation(1) struct "Native.Box" { value: A }extern exception describes the nominal native exception struct used in raises error
unions: typed fields support construction, updates and matching. Values can be
returned inside Error without raising.
Modules and behaviours
Section titled “Modules and behaviours”extern mod "Range" range_module names a native module as a value. It
imports nothing and exposes nothing. Each function still needs its own
extern signature. You need it only to pass a native module through Gale
code, and an implements clause can grant that value a declared behaviour
capability. extern "GenServer" declares Server<...> maps Gale callback
signatures onto native BEAM behaviours. The behaviours chapter
has the rules.
Checks and assumptions
Section titled “Checks and assumptions”- Checked: every Gale caller against the declared signature; with runtime checks on, argument and result representations at boundaries, including nested fields, UTF-8, proper lists and exact records.
- Assumed: the native implementation’s agreement with its declaration,
including any
pure/ensurespromises. Provenance for built-in native proof models is versioned; a matching name alone creates no axiom. - Not claimed: function arity proves nothing about a signature;
phantom/mailbox/invariant internals stay unverified; untrusted
Terminput must be decoded (decoding), not trusted.
Exact syntax and projection rules live in the language guide and the type-system reference.