API reference

fp.callables¶

Use fp.callables to define callable structs or adapt a native function or closure with as_unary. For example, a formatter that owns its prefix can implement a consuming protocol so a Result transformation calls it once. Most calls to other packages accept native functions or closures directly. Ownership and errors explains how each receiver mode treats a callable's state.

How the library calls user code: callable protocols, receiver dispatch and native functions as values.

Every higher-order operation calls user code through these protocols. A callable fixes its argument, result and error types in a contract trait, and implements each receiver mode it supports as its own trait:

Arity	Shared	Exclusive	Consuming
one owned argument	`Unary.call`	`MutableUnary.call_mut`	`OnceUnary.call_once`
two owned arguments	`Binary.call`	`MutableBinary.call_mut`	`OnceBinary.call_once`
no argument	`Thunk.call`	`MutableThunk.call_mut`	`OnceThunk.call_once`

call_once calls a callable of any mode once, preferring the consuming mode; call_repeated calls one that stays usable, and requires RepeatableUnary, RepeatableBinary or RepeatableThunk. as_unary moves a native function or closure into a NativeUnary. BorrowCallable and BorrowOnceCallable borrow their argument instead of taking it, and invoke_borrowed and invoke_borrowed_once call them. Errors keep their exact types. Partial, Composition, Flipped and Identity from fp.functions implement these protocols.

Where each consumer enters:

Consumer	Accepts
`pipe`, `flow`, `compose`	Two to eight plain functions directly; otherwise `Thunk`/`Unary`/`Binary` values and native functions promoted with `as_unary`
`piped(...).then`	Plain functions, closures and `Unary` values, one per call, with no limit
`flip`	`Binary` values and plain functions with two or more parameters
Owned iteration callbacks, `fori_loop`, `while_loop`, `scan`	Native callbacks and shared-receiver `Unary`/`Binary` values
Iteration predicates, `while_loop` predicates	Native predicates and `BorrowCallable`
`Result` methods and folds	Native callbacks, `Unary`, `OnceUnary`, `BorrowCallable` and `BorrowOnceCallable`
`attempt_once`	`OnceThunk`
`fp.match` and `fp.rewrite` clauses	Plain functions and lambdas without captures, taking one to three parameters
`fp.algebra`, `fp.effects`	Native functions and closures for `map`, `flat_map`, `traverse`, `modify`, `censor` and `local`; `Unary`, `Binary`, `Thunk` in any receiver mode; `BorrowCallable` for Reader's `local` and `action`, which also takes `BorrowOnceCallable`

Lazy iteration callbacks are non-raising, because the native iterator protocol raises only StopIteration; terminal callbacks keep their own error channel.

Summary¶

Name	Kind	Summary
`as_unary`	function	Store a native function or closure as a `Unary` value.
`call_once`	function	Call a unary callback once, in whichever receiver mode it has.
`call_repeated`	function	Call a unary callback that stays usable afterwards.
`invoke_borrowed`	function	Call a `BorrowCallable` with a borrowed payload, raising its error as `E`.
`invoke_borrowed_once`	function	Call a `BorrowOnceCallable` once with a borrowed payload, consuming it.
`NativeUnary`	struct	A native function or closure stored as a `Unary` value, made by `as_unary`.
`Binary`	trait	A two-argument callable that can be called repeatedly through a shared receiver.
`BinaryContract`	trait	The types of a callable that takes two owned arguments.
`BorrowCallContract`	trait	The types of a callable that borrows its argument.
`BorrowCallable`	trait	A callable that borrows its argument and can be called repeatedly.
`BorrowOnceCallable`	trait	A callable that borrows its argument and is called at most once, consuming its state.
`MutableBinary`	trait	A two-argument callable that can be called repeatedly with exclusive access to its state.
`MutableThunk`	trait	A producer that can be called repeatedly with exclusive access to its state.
`MutableUnary`	trait	A one-argument callable that can be called repeatedly with exclusive access to its state.
`OnceBinary`	trait	A two-argument callable that is called at most once, consuming its state.
`OnceThunk`	trait	A producer that is called at most once, consuming its state; `attempt_once` takes one.
`OnceUnary`	trait	A one-argument callable that is called at most once, consuming its state.
`Thunk`	trait	A producer that can be called repeatedly through a shared receiver.
`ThunkContract`	trait	The types of a callable that takes no argument: a deferred producer.
`Unary`	trait	A one-argument callable that can be called repeatedly through a shared receiver.
`UnaryContract`	trait	The types of a callable that takes one owned argument.
`BorrowCallCompatible`	alias	Whether `invoke_borrowed[E]` accepts handler `H` with a payload of type `T`.
`RepeatableBinary`	alias	Whether a binary callback stays usable after a call; `call_repeated` requires it.
`RepeatableThunk`	alias	Whether a thunk stays usable after a call; `call_repeated` requires it.
`RepeatableUnary`	alias	Whether a unary callback stays usable after a call: it has a shared or exclusive receiver.

Functions¶

as_unary¶

Source: fp/callables/native.mojo

def as_unary[A, R, //, F: _Unary[A, R]](
    var function: F,
) -> NativeUnary[A, R, Never, F, False]

Store a native function or closure as a Unary value.

This moves the callable in and never calls or copies it. Most entry points take native functions without it; it is needed for closures in pipelines and compositions, and wherever generic code needs a Unary value. fp.functions re-exports it.

Parameters

A (Movable & Deinitable, inferred): The argument type.
R (Movable & Deinitable, inferred): The result type.
F: The function's type: a plain function or a closure taking one owned argument.

Arguments

function (var F): The function or closure, moved in.

Returns

NativeUnary[A, R, Never, F, False]: A NativeUnary holding function, callable with call or directly.

1 more overload

Store a raising native function or closure, keeping its exact error type.

def as_unary[A, R, E, //, F: _RaisingUnary[A, R, E]](
    var function: F,
) -> NativeUnary[A, R, E, F, True]

call_once¶

Source: fp/callables/invoke.mojo

def call_once[F: UnaryContract & Movable & Deinitable](
    var f: F,
    var arg: F.Arg,
) raises F.Error -> F.Out

Call a unary callback once, in whichever receiver mode it has.

A consuming callback is consumed; otherwise the exclusive, then the shared receiver is used. Algorithms call a callback they run once through this.

Parameters

F (UnaryContract & Movable & Deinitable): The callback's type: any UnaryContract with at least one receiver mode.

Arguments

f (var F): The callback, consumed.
arg (var F.Arg): The argument, consumed.

Returns

F.Out: The callback's result.

Raises

F.Error: The callback's error, unchanged.

2 more overloads

Call a binary callback once, in whichever receiver mode it has.

def call_once[F: BinaryContract & Movable & Deinitable](
    var f: F,
    var first: F.First,
    var second: F.Second,
) raises F.Error -> F.Out

Call a thunk once, in whichever receiver mode it has.

def call_once[F: ThunkContract & Movable & Deinitable](
    var f: F,
) raises F.Error -> F.Out

call_repeated¶

Source: fp/callables/invoke.mojo

def call_repeated[F: UnaryContract & Movable & Deinitable](
    mut f: F,
    var arg: F.Arg,
) raises F.Error -> F.Out where RepeatableUnary[F]

Call a unary callback that stays usable afterwards.

The exclusive receiver is used when the callback has one, otherwise the shared one. Algorithms that call a callback for every element call it through this.

Parameters

F (UnaryContract & Movable & Deinitable): The callback's type; RepeatableUnary[F] must hold.

Arguments

f (mut F): The callback, borrowed mutably.
arg (var F.Arg): The argument, consumed.

Returns

F.Out: The callback's result.

Raises

F.Error: The callback's error, unchanged.

2 more overloads

Call a binary callback that stays usable afterwards.

def call_repeated[F: BinaryContract & Movable & Deinitable](
    mut f: F,
    var first: F.First,
    var second: F.Second,
) raises F.Error -> F.Out where RepeatableBinary[F]

Call a thunk that stays usable afterwards.

def call_repeated[F: ThunkContract & Movable & Deinitable](
    mut f: F,
) raises F.Error -> F.Out where RepeatableThunk[F]

invoke_borrowed¶

Source: fp/callables/invoke.mojo

def invoke_borrowed[E, H: BorrowCallable, T: AnyType](
    ref payload: T,
    handler: H,
) raises E -> H.Result where BorrowCallCompatible[E, H, T]

Call a BorrowCallable with a borrowed payload, raising its error as E.

The error is moved unchanged; it is never converted, erased or recovered.

Parameters

E (Movable & Deinitable): The error type the call raises: the handler's own error, or any type when the handler raises nothing.
H (BorrowCallable): The handler's type.
T (AnyType): The payload's type, which must be exactly H.Payload.

Arguments

payload (ref T): The argument, borrowed for the call.
handler (H): The handler, borrowed.

Returns

H.Result: The handler's result.

Raises

E: The handler's error, as E.

invoke_borrowed_once¶

Source: fp/callables/invoke.mojo

def invoke_borrowed_once[E, H: BorrowOnceCallable, T: AnyType](
    ref payload: T,
    var handler: H,
) raises E -> H.Result where BorrowCallCompatible[E, H, T]

Call a BorrowOnceCallable once with a borrowed payload, consuming it.

Parameters

E (Movable & Deinitable): The error type the call raises: the handler's own error, or any type when the handler raises nothing.
H (BorrowOnceCallable): The handler's type.
T (AnyType): The payload's type, which must be exactly H.Payload.

Arguments

payload (ref T): The argument, borrowed for the call.
handler (var H): The handler, consumed by the call.

Returns

H.Result: The handler's result.

Raises

E: The handler's error, as E.

Structs¶

NativeUnary¶

Source: fp/callables/native.mojo

struct NativeUnary[A, R, E, F, raising: Bool](
    Unary,
    Copyable where conforms_to(F, Copyable),
    ImplicitlyCopyable where conforms_to(F, ImplicitlyCopyable),
)

A native function or closure stored as a Unary value, made by as_unary.

It is Copyable when the stored function is. At O3 a call through it compiles to the same instructions as a direct call.

Parameters

A (Movable & Deinitable): The argument type.
R (Movable & Deinitable): The result type.
E (Movable & Deinitable): The error type; Never for a function that does not raise.
F (Movable & Deinitable): The stored function's type.
raising (Bool): Whether the stored function raises.

Implements

Copyable, ImplicitlyCopyable, Unary, UnaryContract

Fields

function (F): The stored function or closure.

Aliases

Arg
Out
Error

NativeUnary.call { #NativeUnary.call .api-name }¶

def __call__(self, var arg: Arg) raises Error -> Out

Call the stored function directly, as call does.

Arguments

arg (var Arg): The argument, consumed.

Returns

Out: The function's result.

Raises

Error: The function's error, unchanged; nothing when it does not raise.

NativeUnary.call¶

def call(self, var arg: Arg) raises Error -> Out

Call the stored function.

Arguments

arg (var Arg): The argument, consumed.

Returns

Out: The function's result.

Raises

Error: The function's error, unchanged; nothing when it does not raise.

Traits¶

Binary¶

Source: fp/callables/protocols.mojo

trait Binary(BinaryContract, Movable, Deinitable)

A two-argument callable that can be called repeatedly through a shared receiver.

Implements

BinaryContract

Binary.call¶

def call(self, var first: First, var second: Second) raises Error -> Out

Call with two owned arguments.

The receiver is borrowed, so the value can be called again.

Arguments

first (var First): The first argument, consumed.
second (var Second): The second argument, consumed.

Returns

Out: The result.

Raises

Error: Error, the callable's own error type; nothing when it is Never.

BinaryContract¶

Source: fp/callables/protocols.mojo

trait BinaryContract

The types of a callable that takes two owned arguments.

A library callable implements the receiver modes it supports: Binary, MutableBinary or OnceBinary.

Associated aliases

First: The first argument's type.
Second: The second argument's type.
Out: The result type.
Error: The error type; Never for a callable that does not raise.

BorrowCallContract¶

Source: fp/callables/protocols.mojo

trait BorrowCallContract

The types of a callable that borrows its argument.

The payload is borrowed for the duration of the call, so it need not be movable, and the callable cannot keep a reference to it.

Associated aliases

Payload: The borrowed argument's type.
Result: The result type.
Failure: The error type; Never for a callable that does not raise.

BorrowCallable¶

Source: fp/callables/protocols.mojo

trait BorrowCallable(BorrowCallContract, Movable, Deinitable)

A callable that borrows its argument and can be called repeatedly.

Iteration predicates, while_loop predicates, Result.fold and Reader's local and action take one. invoke_borrowed calls it.

Implements

BorrowCallContract

BorrowCallable.invoke¶

def invoke(self, ref payload: Payload) raises Failure capturing -> Result

Call with a borrowed argument.

Arguments

payload (ref Payload): The argument, borrowed for the call.

Returns

Result: The result.

Raises

Failure capturing: Failure, the callable's own error type; nothing when it is Never.

BorrowOnceCallable¶

Source: fp/callables/protocols.mojo

trait BorrowOnceCallable(BorrowCallContract, Movable, Deinitable)

A callable that borrows its argument and is called at most once, consuming its state.

Result.fold_once and Reader's action take one. invoke_borrowed_once calls it.

Implements

BorrowCallContract

BorrowOnceCallable.invoke_once¶

def invoke_once(
    deinit self,
    ref payload: Payload,
) raises Failure capturing -> Result

Call once with a borrowed argument, consuming the receiver.

Arguments

payload (ref Payload): The argument, borrowed for the call.

Returns

Result: The result.

Raises

Failure capturing: Failure, the callable's own error type; nothing when it is Never.

MutableBinary¶

Source: fp/callables/protocols.mojo

trait MutableBinary(BinaryContract, Movable, Deinitable)

A two-argument callable that can be called repeatedly with exclusive access to its state.

Implements

BinaryContract

MutableBinary.call_mut¶

def call_mut(mut self, var first: First, var second: Second) raises Error -> Out

Call with two owned arguments.

The receiver is borrowed mutably, so the call may update its state, and the value can be called again.

Arguments

first (var First): The first argument, consumed.
second (var Second): The second argument, consumed.

Returns

Out: The result.

Raises

Error: Error, the callable's own error type; nothing when it is Never.

MutableThunk¶

Source: fp/callables/protocols.mojo

trait MutableThunk(ThunkContract, Movable, Deinitable)

A producer that can be called repeatedly with exclusive access to its state.

Implements

ThunkContract

MutableThunk.call_mut¶

def call_mut(mut self) raises Error -> Out

Produce a value.

The receiver is borrowed mutably, so the call may update its state, and the value can be called again.

Returns

Out: The result.

Raises

Error: Error, the callable's own error type; nothing when it is Never.

MutableUnary¶

Source: fp/callables/protocols.mojo

trait MutableUnary(UnaryContract, Movable, Deinitable)

A one-argument callable that can be called repeatedly with exclusive access to its state.

Implements

UnaryContract

MutableUnary.call_mut¶

def call_mut(mut self, var arg: Arg) raises Error -> Out

Call with one owned argument.

The receiver is borrowed mutably, so the call may update its state, and the value can be called again.

Arguments

arg (var Arg): The argument, consumed.

Returns

Out: The result.

Raises

Error: Error, the callable's own error type; nothing when it is Never.

OnceBinary¶

Source: fp/callables/protocols.mojo

trait OnceBinary(BinaryContract, Movable, Deinitable)

A two-argument callable that is called at most once, consuming its state.

Implements

BinaryContract

OnceBinary.call_once¶

def call_once(
    deinit self,
    var first: First,
    var second: Second,
) raises Error -> Out

Call with two owned arguments.

The call consumes the receiver.

Arguments

first (var First): The first argument, consumed.
second (var Second): The second argument, consumed.

Returns

Out: The result.

Raises

Error: Error, the callable's own error type; nothing when it is Never.

OnceThunk¶

Source: fp/callables/protocols.mojo

trait OnceThunk(ThunkContract, Movable, Deinitable)

A producer that is called at most once, consuming its state; attempt_once takes one.

Implements

ThunkContract

OnceThunk.call_once¶

def call_once(deinit self) raises Error -> Out

Produce a value.

The call consumes the receiver.

Returns

Out: The result.

Raises

Error: Error, the callable's own error type; nothing when it is Never.

OnceUnary¶

Source: fp/callables/protocols.mojo

trait OnceUnary(UnaryContract, Movable, Deinitable)

A one-argument callable that is called at most once, consuming its state.

Implements

UnaryContract

OnceUnary.call_once¶

def call_once(deinit self, var arg: Arg) raises Error -> Out

Call with one owned argument.

The call consumes the receiver.

Arguments

arg (var Arg): The argument, consumed.

Returns

Out: The result.

Raises

Error: Error, the callable's own error type; nothing when it is Never.

Thunk¶

Source: fp/callables/protocols.mojo

trait Thunk(ThunkContract, Movable, Deinitable)

A producer that can be called repeatedly through a shared receiver.

Implements

ThunkContract

Thunk.call¶

def call(self) raises Error -> Out

Produce a value.

The receiver is borrowed, so the value can be called again.

Returns

Out: The result.

Raises

Error: Error, the callable's own error type; nothing when it is Never.

ThunkContract¶

Source: fp/callables/protocols.mojo

trait ThunkContract

The types of a callable that takes no argument: a deferred producer.

A library callable implements the receiver modes it supports: Thunk, MutableThunk or OnceThunk.

Associated aliases

Out: The result type.
Error: The error type; Never for a callable that does not raise.

Unary¶

Source: fp/callables/protocols.mojo

trait Unary(UnaryContract, Movable, Deinitable)

A one-argument callable that can be called repeatedly through a shared receiver.

Partial, Composition, Flipped, Identity and NativeUnary implement it. Algorithms call it through call_once or call_repeated.

Implements

UnaryContract

Unary.call¶

def call(self, var arg: Arg) raises Error -> Out

Call with one owned argument.

The receiver is borrowed, so the value can be called again.

Arguments

arg (var Arg): The argument, consumed.

Returns

Out: The result.

Raises

Error: Error, the callable's own error type; nothing when it is Never.

UnaryContract¶

Source: fp/callables/protocols.mojo

trait UnaryContract

The types of a callable that takes one owned argument.

A library callable fixes its argument, result and error types here, and implements the receiver modes it supports: Unary, MutableUnary or OnceUnary.

Associated aliases

Arg: The argument type.
Out: The result type.
Error: The error type; Never for a callable that does not raise.

Aliases¶

BorrowCallCompatible¶

Source: fp/callables/invoke.mojo

comptime BorrowCallCompatible[E, H: BorrowCallContract, T: AnyType = H.Payload]: Bool = ( T == H.Payload and (_ErrorCompatible[E, H.Failure]) )

Whether invoke_borrowed[E] accepts handler H with a payload of type T.

True when T is exactly H.Payload, including embedded origins, and H raises E or nothing. A generic function that forwards a borrowed callback carries it in its where clause.

Parameters

E (Movable & Deinitable): The error type of the caller.
H (BorrowCallContract): The borrowed callable.
T (AnyType): The payload type; H.Payload by default.

RepeatableBinary¶

Source: fp/callables/invoke.mojo

comptime RepeatableBinary[F: BinaryContract] = conforms_to(F, Binary) or conforms_to(F, MutableBinary)

Whether a binary callback stays usable after a call; call_repeated requires it.

Parameters

F (BinaryContract): The callback's type.

RepeatableThunk¶

Source: fp/callables/invoke.mojo

comptime RepeatableThunk[F: ThunkContract] = conforms_to(F, Thunk) or conforms_to(F, MutableThunk)

Whether a thunk stays usable after a call; call_repeated requires it.

Parameters

F (ThunkContract): The thunk's type.

RepeatableUnary¶

Source: fp/callables/invoke.mojo

comptime RepeatableUnary[F: UnaryContract] = conforms_to(F, Unary) or conforms_to(F, MutableUnary)

Whether a unary callback stays usable after a call: it has a shared or exclusive receiver.

call_repeated requires it. Generic code that calls a callback more than once asserts it first, so a consuming-only callback is rejected when the program compiles.

Parameters

F (UnaryContract): The callback's type.

fp.callables¶

Summary¶

Functions¶

as_unary¶

call_once¶

call_repeated¶

invoke_borrowed¶

invoke_borrowed_once¶

Structs¶

NativeUnary¶

NativeUnary.__call__ { #NativeUnary.call .api-name }¶

NativeUnary.call¶

Traits¶

Binary¶

Binary.call¶

BinaryContract¶

BorrowCallContract¶

BorrowCallable¶

BorrowCallable.invoke¶

BorrowOnceCallable¶

BorrowOnceCallable.invoke_once¶

MutableBinary¶

MutableBinary.call_mut¶

MutableThunk¶

MutableThunk.call_mut¶

MutableUnary¶

MutableUnary.call_mut¶

OnceBinary¶

OnceBinary.call_once¶

OnceThunk¶

OnceThunk.call_once¶

OnceUnary¶

OnceUnary.call_once¶

Thunk¶

Thunk.call¶

ThunkContract¶

Unary¶

Unary.call¶

UnaryContract¶

Aliases¶

BorrowCallCompatible¶

RepeatableBinary¶

RepeatableThunk¶

RepeatableUnary¶

NativeUnary.call { #NativeUnary.call .api-name }¶