ΛLogos

logos.std.compiler.metaprog

Module std · package logos-std

Types

structEmitter

struct Emitter

Buffers one Logos compilation unit (a package <name>; ... chunk) for the host compiler. Fill via emit_*/push_*/tpl* (or buf directly), then flush with commit; the host parser wants exactly one package statement per committed chunk.

Fields

buf: String

Buffered source text of the current chunk; cleared by commit.

Methods

fn commit(self: &mut Emitter) -> void

Flushes buffered source to the host compiler and clears the buffer; no-op when empty.

fn emit_into(self: &mut Emitter, pkg: &[u8]) -> void

Begins a new chunk by writing package <pkg>; to the buffer.

fn emit_raw(self: &mut Emitter, src: &[u8]) -> void

Appends src to the buffer followed by a newline.

fn emit_target_pkg(self: &mut Emitter, view: &OView) -> void

Begins a new chunk in the user’s own package, read from view’s root MODULE node.

fn new() -> Emitter

Creates an Emitter with an empty buffer.

fn push_num(self: &mut Emitter, n: u64) -> void

Appends n in decimal.

fn push_text(self: &mut Emitter, s: &[u8]) -> void

Appends s to the buffer without a trailing newline (unlike emit_raw).

fn push_view(self: &mut Emitter, v: SView) -> void

Appends the bytes of v verbatim.

fn tpl1(self: &mut Emitter, tmpl: &[u8], k1: &[u8], v1: SView) -> void

Renders tmpl into the buffer, replacing $k1 with the bytes of v1. $$ emits a literal $; an unmatched $ident passes through unchanged.

fn tpl2(self: &mut Emitter, tmpl: &[u8], k1: &[u8], v1: SView, k2: &[u8], v2: SView) -> void

Renders tmpl into the buffer, substituting two $key bindings; same rules as tpl1.

fn tpl3(self: &mut Emitter, tmpl: &[u8], k1: &[u8], v1: SView, k2: &[u8], v2: SView, k3: &[u8], v3: SView) -> void

Renders tmpl into the buffer, substituting three $key bindings; same rules as tpl1.

structExprBlob

struct ExprBlob

Marker return type for quoted expressions (ABI = WritStatic; a single *const u8).

Fields

ptr: *const u8

WritStatic-shaped blob pointer.

structIdent

struct Ident

Borrowed identifier bytes; ptr borrows the source arena.

Implements: Copy

Fields

len: u64

Byte length.

ptr: *const u8

Pointer to the identifier bytes (borrowed, not owned).

Methods

fn eq(self: &Ident, other: &Ident) -> bool

Returns true if the two identifiers have identical byte content.

structIdentSpan

struct IdentSpan

Describes one substitution binding passed to the quote_expr! host shim.

Fields

count: u64

Slot count at ptr for kind 0 (1 = scalar, M = cursor); unused for kind 1.

kind: u64

Substitution mode: 0 = Ident (scalar or cursor), 1 = ExprBlob splice.

ptr: *const Ident

Pointer to an Ident slot array (kind 0) or to ExprBlob data past its 8-byte size prefix (kind 1).

structItem

struct Item

Handle to an untyped AST item node (struct/enum/fn/... declaration).

Fields

raw: WAny

Value-form WAny Ref to the item’s TinyObjectMap node.

Methods

fn field(self: &Item, view: &OView, idx: u64) -> Item

Returns the idx-th field-def node wrapped as an Item.

fn field_count(self: &Item, view: &OView) -> u64

Returns the number of struct fields (0 if the node has no FIELDS array).

fn name(self: &Item, view: &OView) -> Ident

Returns the item’s name (NAME key) as borrowed identifier bytes.

structItemList

struct ItemList

Multi-item return value for a metacall that emits more than one item.

Fields

blobs: Vec<QuoteItemBlob>

The emitted items, in emission order; each forwarded to logos_emit_item_blob_subst by the metacall thunk.

structOView

struct OView

Owning view over the trigger module’s writ AST document.

Holds one retained ref on the host MemHolder, released on Drop.

Implements: Drop

Fields

base: *const u8

Absolute base address of the document’s single segment.

holder: *mut u8

Opaque retained host MemHolder; null when no document is loaded.

size: u64

Segment size in bytes.

Methods

fn array_get(self: &OView, v: WAny, idx: u64) -> WAny

Returns element idx of an array node; null/non-ref v → null WAny.

No bounds check — idx must be less than array_len(v).

fn array_len(self: &OView, v: WAny) -> u64

Returns the length of an array node (v = Ref to a WArray<WAny>); null/non-ref → 0.

fn as_type(self: &OView, val: WAny) -> Type

Decodes a <type:T> Writ value (schema-107 TOM) into a Type via type_from_anyval.

fn ast_enum_variant(self: &OView, node: WAny, idx: u64) -> WAny

Returns the idx-th variant node of an enum node.

fn ast_enum_variant_count(self: &OView, node: WAny) -> u64

Returns an enum node’s variant count; 0 if the variant list is absent.

fn ast_field_name(self: &OView, field_def: WAny) -> SView

Returns a field-def node’s NAME as a string view.

fn ast_field_type_name(self: &OView, field_def: WAny) -> SView

Returns the NAME of a field-def’s TYPE child; empty SView if the field has no TYPE.

fn ast_lit_str_view(self: &OView, lit: WAny) -> SView

Returns a STRING-token literal’s byte view minus the surrounding quotes; empty if absent.

fn ast_node_code(self: &OView, node: WAny) -> u64

Returns the node’s AST code (la::Code — e.g. ARR_TYPE=64, SLICE_TYPE=111).

Read from the TOM’s schema_type_code; 0 for a null/non-ref node.

fn ast_node_name(self: &OView, node: WAny) -> SView

Returns the node’s NAME (key 1) as a string view.

fn ast_struct_field(self: &OView, node: WAny, idx: u64) -> WAny

Returns the idx-th field-def node from the node’s FIELDS (key 22) array.

fn ast_struct_field_count(self: &OView, node: WAny) -> u64

Returns the length of the node’s FIELDS (key 22) array; 0 if absent.

fn ast_type_child(self: &OView, node: WAny) -> WAny

Returns the TYPE (key 3) child of a field-def / type node.

The element type of an array/slice, or the pointee of a ref; null WAny if absent.

fn ast_type_param_count(self: &OView, node: WAny) -> u64

Returns the node’s generic type-parameter count (TYPE_PARAMS key 27); 0 if absent.

fn ast_type_param_name(self: &OView, node: WAny, idx: u64) -> SView

Returns the idx-th generic type-parameter name; empty SView if the list is absent.

fn ast_variant_arity(self: &OView, variant: WAny) -> u64

Returns a variant node’s payload arity.

0 for a unit variant; 1 for a single unwrapped payload; else the payload-list length.

fn base_ptr(self: &OView) -> *const u8

Returns the document segment’s absolute base pointer.

fn drop(self: OView) -> void
fn find_template_decl(self: &OView, name: &[u8]) -> WAny

Returns the first MODULE item whose NAME matches name byte-for-byte; null WAny if none.

fn get_bool(self: &OView, v: WAny) -> bool

Returns true iff v is a Pod with a nonzero inline value.

fn get_i64(self: &OView, v: WAny) -> i64

Returns a Pod’s inline integer as i64; alias of get_int.

fn get_int(self: &OView, v: WAny) -> i64

Returns a Pod’s inline integer (i56, sign-extended); non-pod → 0.

fn get_str_view(self: &OView, v: WAny) -> SView

Returns the borrowed UTF-8 bytes of a string node (v = Ref to a WString).

Empty view if v is null/non-ref.

fn get_u64(self: &OView, v: WAny) -> u64

Returns a Pod’s inline integer cast to u64; non-pod → 0.

fn module_package_append(self: &OView, buf: &mut String) -> void

Appends the user-root MODULE’s dotted package name (e.g. a.b.c) to buf.

fn node_at(self: &OView, offset: u32) -> WAny

Wraps a flat arena offset into a node handle (WAny::Ref(base + offset)).

The only base + offset step; all further navigation is WAny::resolve().

fn root(self: &OView) -> WAny

Returns the document root WAny.

DocumentHeader = { WAny root } at base+0; the at-rest root word is self-relative to base, so it is materialized: Ref → base + delta, Pod → verbatim, 0 → null Ref.

fn tiny_map_get(self: &OView, node: WAny, key: u8) -> WAny

Reads field key of a TinyObjectMap node (node = Ref to a WMap<Wu6, WAny>).

Null/non-ref node, or an absent key, yields a null WAny.

structQuoteItemBlob

struct QuoteItemBlob

Bundle returned by quote_item! { ... } and consumed by the compiler’s item-splice path.

Carries the serialized item template plus packed ident/blob/cursor payloads.

Fields

blobs_blob: *const u8

Null or [u64 N][N x {offset,size}][bytes] payload of spliced sub-blobs.

cursors_blob: *const u8

Null or packed repeat-cursor payload driving $x... repeat expansion.

idents_blob: *const u8

Null or [u64 N][N x {ptr,len}][bytes] payload of $ident substitutions.

template_ptr: *const u8

Pointer to the serialized item-template blob (rodata).

template_size: u64

Template blob size in bytes.

structSView

struct SView

Borrowed, non-owning (ptr, len) view of UTF-8 string bytes.

Implements: Copy

Fields

len: u64

Length in bytes.

ptr: *const u8

Pointer to the first byte; null for an empty view.

structTemplate

struct Template

Declaration-as-data handle: a struct/enum/fn/trait/impl declaration carrying type params.

Inspection goes through OView.

Fields

raw: WAny

Value-form WAny Ref to the declaration’s AST node.

Methods

fn body(self: &Template) -> Item

Returns the same underlying node viewed as an Item (for field/variant inspection).

fn name(self: &Template, view: &OView) -> Ident

Returns the declaration’s name (NAME key) as borrowed identifier bytes.

fn type_param_count(self: &Template, view: &OView) -> u64

Returns the number of generic type parameters (0 if none).

fn type_param_name(self: &Template, view: &OView, idx: u64) -> Ident

Returns the name of the idx-th generic type parameter.

structType

struct Type

Type-level value handle produced by type_of::<T>().

kind mirrors LogosType::Kind (Void=0, I32=1, ...); name/size/align/uid are filled by the compiler when materialising a Type literal.

Fields

align: i64

Alignment of the type in bytes.

kind: u32

Numeric LogosType::Kind discriminant (Void=0, I32=1, ...).

name: &[u8]

Type name bytes (rodata-backed; empty on values decoded by type_from_anyval).

size: i64

Size of the type in bytes.

uid: u64

Compiler-assigned unique type id.

Methods

fn ident(self: &Type) -> Ident

Returns the type’s name as a borrowed Ident.

fn is_array(self: &Type) -> bool

Returns true if the kind is Array ([T; N]).

fn is_bool(self: &Type) -> bool

Returns true if the kind is Bool.

fn is_enum(self: &Type) -> bool

Returns true if the kind is Enum.

fn is_float(self: &Type) -> bool

Returns true if the kind is F32 or F64.

fn is_integer(self: &Type) -> bool

Returns true for fixed-width integer kinds (i8..i128, u8..u128, incl. 24/56-bit).

usize/isize/char are separate kinds and NOT included.

fn is_pointer(self: &Type) -> bool

Returns true if the kind is Ptr, Ref, or MutRef.

fn is_primitive(self: &Type) -> bool

Returns true for bool, float, and fixed-width integer kinds (kinds 1..=17).

Excludes Void, usize/isize, char, and all compound kinds.

fn is_struct(self: &Type) -> bool

Returns true if the kind is Struct or ZonedStruct.

fn is_void(self: &Type) -> bool

Returns true if the kind is Void.

structTypeList

struct TypeList

Zero-sized A-layer carrier for a variadic type pack.

Functions

fnall

fn all(pred: fn(Type) -> bool) -> bool

Returns true iff every pack member satisfies pred (vacuously true on an empty pack).

fnany

fn any(pred: fn(Type) -> bool) -> bool

Returns true iff any pack member satisfies pred (false on an empty pack).

fnargmax_by

fn argmax_by(proj: fn(Type) -> i64) -> i64

Returns the index of the pack member maximising proj, or -1 on an empty pack. Ties resolve to the lowest index.

fnargmin_by

fn argmin_by(proj: fn(Type) -> i64) -> i64

Returns the index of the pack member minimising proj, or -1 on an empty pack. Ties resolve to the lowest index.

fncount_if

fn count_if(pred: fn(Type) -> bool) -> i64

Counts pack members for which pred returns true.

fnerror

fn error(msg: &[u8]) -> void

Reports msg as a metaprog-hook error; the host fails compilation after the hook returns. A hook may report several errors per invocation; all surface together.

fnerror_at

fn error_at(target_offset: u32, msg: &[u8]) -> void

Reports msg like error, attributed to the user-AST node at target_offset. The host prefixes the message with <file>:<line>: from the node’s SRC_LINE field.

fnfilter

fn filter(pred: fn(Type) -> bool, out: *mut Type) -> i64

Writes pack members satisfying pred front-packed into out; returns the accepted count. out must have room for sizeof...(T) elements; slots past the returned count are untouched.

fnfind_index

fn find_index(pred: fn(Type) -> bool) -> i64

Returns the index of the first pack member satisfying pred, or -1 if none.

fnfold_i64

fn fold_i64(init: i64, step: fn(i64, Type) -> i64) -> i64

Folds the pack into an i64 accumulator via step, starting from init. Polymorphic-accumulator fold awaits closure-arg generics; i64 covers the common cases (counts, sums, max, layout offsets) directly.

fnfold_to_type

fn fold_to_type(init: Type, f: fn(Type, Type) -> Type) -> Type

Left-folds f over the pack’s Types starting from init.

fngensym

fn gensym(prefix: &[u8]) -> Ident

Returns a fresh hygienic identifier <prefix>__hyg_<N>, unique across the whole compile.

The bytes are host-owned and stay valid for the rest of the compilation.

fnis_array

fn is_array(t: Type) -> bool

Returns true iff t is the Array kind.

fnis_bool_kind

fn is_bool_kind(t: Type) -> bool

Returns true iff t is the bool kind.

fnis_enum

fn is_enum(t: Type) -> bool

Returns true iff t is the Enum kind.

fnis_float_kind

fn is_float_kind(t: Type) -> bool

Returns true iff t is f32 or f64.

fnis_integer

fn is_integer(t: Type) -> bool

Returns true iff t is any integer kind (signed/unsigned, 8–128 bits incl. 24/56).

fnis_pointer

fn is_pointer(t: Type) -> bool

Returns true iff t is Ptr, Ref, or MutRef.

fnis_primitive_kind

fn is_primitive_kind(t: Type) -> bool

Returns true iff t is a primitive scalar kind (integer, float, or bool; not Void).

fnis_struct

fn is_struct(t: Type) -> bool

Returns true iff t is a struct or zoned-struct kind.

fnis_void

fn is_void(t: Type) -> bool

Returns true iff t is the Void kind.

fnitem_list_new

fn item_list_new() -> ItemList

Creates an empty ItemList with no blobs.

fnkind_name

fn kind_name(k: u32) -> &[u8]

Returns a short printable name for a Type kind tag; unknown tags yield "?".

fnlength

fn length() -> i64

Returns the pack length (compile-time constant; folds to a lit_int).

fnmax_by

fn max_by(proj: fn(Type) -> i64) -> i64

Returns the largest proj(t) over the pack (i64::MIN on an empty pack).

fnmin_by

fn min_by(proj: fn(Type) -> i64) -> i64

Returns the smallest proj(t) over the pack (i64::MAX on an empty pack).

fnname_eq

fn name_eq(a: &[u8], b: &[u8]) -> bool

Returns true iff byte slices a and b have equal length and contents.

fnoview_module_ast

fn oview_module_ast() -> OView

Acquires a retained view of the trigger’s AST document.

holder is null when no document is loaded — branch on that before using base.

fnschema_code

fn schema_code() -> u64

Returns a layout-faithful structural hash of _T’s in-memory schema. Mixes kind/size/align, recursing into struct field types; structurally identical layouts hash equal regardless of names. Pointers are opaque leaves — recursion stops there, breaking cycles on self-referential types.

fnschema_pack

fn schema_pack() -> u64

Mixes schema_code::<_H>() into the fold over the tail pack (head/tail recursion).

fnsum_by

fn sum_by(proj: fn(Type) -> i64) -> i64

Returns the sum of proj(t) over the pack — handy for total size, alignment, etc.

fntemplate_of_at

fn template_of_at(off: u32) -> Template

Creates a Template from a module-AST arena byte offset.

Compiler-intrinsic target: template_of::<X>() lowers to a call of this with the resolved item’s arena offset (the hook-side OView supplies the base).

fntransform

fn transform(f: fn(Type) -> Type) -> [Type; 0]

Applies f to each pack member and returns the mapped [Type; sizeof...(T)] array.

fntype_from_anyval

fn type_from_anyval(val: WAny) -> Type

Decodes a <type:T> node handle (WAny Ref to a schema-107 TOM) into a Type.

Returns a zero-filled Type if val is not a Ref to a schema-107 TinyObjectMap. Only kind and uid are decoded; name/size/align stay empty/zero.

fnview_of_str

fn view_of_str(s: &[u8]) -> SView

Wraps a str as an SView, e.g. to bind a literal as a tpl* value.

fnview_of_string

fn view_of_string(s: &String) -> SView

Wraps a String’s buffer as an SView. Borrows: the view is valid only while the source String is alive and unmodified.