Help us shape the future of Go! Take the 2026 Go Developer Survey

builder

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 9, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Builder to format numscript document

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AllotmentClause added in v0.0.26 

type AllotmentClause[T payload] struct {
	Portion Expression[ExprTypePortion]
	Payload T
}

One clause of an allotment block: a portion plus its payload (a Source in source position, a KeptOrDest in destination position). Portion is an expression, not a literal, so a clause can be written either inline (ExprPortion) or through a var (ExprPortionVar).

type DestInorderClause added in v0.0.26 

type DestInorderClause struct {
	Max  Expression[ExprTypeMonetary]
	Dest KeptOrDest
}

One `max <amount> <keptOrDest>` clause of a DestInorder block.

type Destination 

type Destination render

func DestAccount 

func DestAccount(expr Expression[ExprTypeAccount]) Destination

func DestAllotment added in v0.0.26 

func DestAllotment(clauses ...AllotmentClause[KeptOrDest]) Destination

func DestAllotmentWithRemaining added in v0.0.26 

func DestAllotmentWithRemaining(clauses []AllotmentClause[KeptOrDest], remaining KeptOrDest) Destination

DestAllotmentWithRemaining is DestAllotment with a trailing `remaining <keptOrDest>` clause.

The engines constrain the clause differently. The legacy machine's compiler rejects it when the known portions already sum to 100%, and rejects a portion var in an allotment that lacks it; the interpreter runs the first (the clause receives zero) and checks the second's sum at run time. Past 100%, both engines reject at run time (oracle/DIVERGENCES.md #6). internal/gen keeps generated sums strictly below 100% regardless: the machine-side compile rejections above are tolerated skips that compare nothing.

func DestInorder added in v0.0.26 

func DestInorder(clauses []DestInorderClause, remaining KeptOrDest) Destination

A destination inorder block. Per the numscript grammar, the `max` clauses are mandatory and a trailing `remaining` clause is required.

func DestOneof added in v0.1.1 

func DestOneof(clauses []DestInorderClause, remaining KeptOrDest) Destination

DestOneof renders `oneof { max ...; remaining ... }` — clause syntax is the same as DestInorder's. numscript-only (experimental-oneof feature flag); the legacy machine's grammar has no oneof.

type ExprType 

type ExprType interface {
	// contains filtered or unexported methods
}

type ExprTypeAccount 

type ExprTypeAccount interface {
	ExprType
	// contains filtered or unexported methods
}

type ExprTypeAsset 

type ExprTypeAsset interface {
	ExprType
	// contains filtered or unexported methods
}

type ExprTypeMonetary 

type ExprTypeMonetary interface {
	ExprType
	// contains filtered or unexported methods
}

type ExprTypeNumber 

type ExprTypeNumber interface {
	ExprType
	// contains filtered or unexported methods
}

type ExprTypePortion added in v0.0.26 

type ExprTypePortion interface {
	ExprType
	// contains filtered or unexported methods
}

type ExprTypeString 

type ExprTypeString interface {
	ExprType
	// contains filtered or unexported methods
}

type Expression 

type Expression[T ExprType] render

func ExprAccount 

func ExprAccount(name string) Expression[ExprTypeAccount]

func ExprAdd added in v0.0.26 

func ExprAdd(a, b Expression[ExprTypeNumber]) Expression[ExprTypeNumber]

ExprAdd renders `<a> + <b>`. Numscript only allows +/- between numbers at runtime (no other arithmetic operators, no parens, no unary minus).

func ExprAsset 

func ExprAsset(name string) Expression[ExprTypeAsset]

func ExprMonetary 

func ExprMonetary(
	asset Expression[ExprTypeAsset],
	amount Expression[ExprTypeNumber],
) Expression[ExprTypeMonetary]

func ExprMonetarySub added in v0.0.26 

func ExprMonetarySub(a, b Expression[ExprTypeMonetary]) Expression[ExprTypeMonetary]

ExprMonetarySub renders `<a> - <b>`, where a and b are monetary literals or expressions. A bracketed monetary literal's amount slot (`[ASSET N]`) only ever accepts a bare number — never a general expression — so this is the only legal way to build a negative-amount monetary: e.g. `[ASSET 0] - [ASSET 7]` evaluates to `[ASSET -7]` and is accepted by both engines' grammars (verified against the oracle directly), whereas `[ASSET -7]` or `[ASSET 0-7]` are not.

func ExprMonetaryVar added in v0.0.26 

func ExprMonetaryVar(binding string) Expression[ExprTypeMonetary]

ExprMonetaryVar routes a monetary through the vars pool, rendering `$monetary_N` bound to binding (e.g. "COIN 100"). The inline counterpart is ExprMonetary, which writes a `[<asset> <amount>]` literal.

Note the amount slot of an inline monetary literal cannot itself be a variable in either grammar (`[COIN $n]` is rejected), so a var-form monetary has to replace the whole literal rather than just its amount.

func ExprNumberBigInt 

func ExprNumberBigInt(amount *big.Int) Expression[ExprTypeNumber]

func ExprNumberVar added in v0.0.26 

func ExprNumberVar(amount *big.Int) Expression[ExprTypeNumber]

ExprNumberVar routes a number through the vars pool, rendering `$number_N`. ExprNumberBigInt is the inline form.

Note a number var is not legal everywhere a number literal is: the amount slot of a monetary literal (`[COIN $n]`) is rejected by both grammars, so this is for value positions such as a meta value.

func ExprPortion added in v0.0.26 

func ExprPortion(p Portion) Expression[ExprTypePortion]

ExprPortion renders p inline, as a `num/denom` literal.

func ExprPortionDiv added in v0.1.1 

func ExprPortionDiv(num, den Expression[ExprTypeNumber]) Expression[ExprTypePortion]

ExprPortionDiv renders `<num>/<den>`: the division-expression form of a portion, which unlike an n/d Portion literal can carry a var numerator and therefore any sign or magnitude. numscript-only: the legacy machine's grammar has no division expression, so the oracle rejects scripts using it.

func ExprPortionVar added in v0.0.26 

func ExprPortionVar(binding string) Expression[ExprTypePortion]

ExprPortionVar routes a portion through the vars pool, rendering `$portion_N` bound to binding (e.g. "1/2"). ExprPortion is the inline form.

func ExprString 

func ExprString(name string) Expression[ExprTypeString]

func ExprStringLit added in v0.0.26 

func ExprStringLit(s string) Expression[ExprTypeString]

ExprStringLit renders s inline, as a quoted string literal. ExprString is the var form.

func ExprSub added in v0.0.26 

func ExprSub(a, b Expression[ExprTypeNumber]) Expression[ExprTypeNumber]

ExprSub renders `<a> - <b>`.

func ExprVar 

func ExprVar[T ExprType](v *Var[T]) Expression[T]

func NewAccountVarFromMeta added in v0.0.26 

func NewAccountVarFromMeta(account Expression[ExprTypeAccount], key string) Expression[ExprTypeAccount]

func NewAssetVarFromMeta added in v0.0.26 

func NewAssetVarFromMeta(account Expression[ExprTypeAccount], key string) Expression[ExprTypeAsset]

func NewMonetaryVarFromBalance added in v0.0.26 

func NewMonetaryVarFromBalance(
	account Expression[ExprTypeAccount],
	asset Expression[ExprTypeAsset],
) Expression[ExprTypeMonetary]

NewMonetaryVarFromBalance declares a vars-block entry `monetary $name = balance(<account>, <asset>)` and returns an expression referencing it. balance() reads the account's balance as resolved before any statement in the script executes (both engines resolve vars-block origins up front, not lazily as the script runs).

func NewMonetaryVarFromMeta added in v0.0.26 

func NewMonetaryVarFromMeta(account Expression[ExprTypeAccount], key string) Expression[ExprTypeMonetary]

func NewNumberVarFromMeta added in v0.0.26 

func NewNumberVarFromMeta(account Expression[ExprTypeAccount], key string) Expression[ExprTypeNumber]

func NewPortionVarFromMeta added in v0.0.26 

func NewPortionVarFromMeta(account Expression[ExprTypeAccount], key string) Expression[ExprTypePortion]

func NewStringVarFromMeta added in v0.0.26 

func NewStringVarFromMeta(account Expression[ExprTypeAccount], key string) Expression[ExprTypeString]

func UnsafeAccount added in v0.0.26 

func UnsafeAccount(literal string) Expression[ExprTypeAccount]

UnsafeAccount emits literal directly as an account reference (`@<literal>`), bypassing the vars pool entirely. Unlike ExprAccount, literal is written straight into the script text rather than passed through the vars binding map, so the caller is responsible for ensuring it's a syntactically valid account address (and, if it's not fully trusted, that it can't be used to inject additional script content).

func UnsafeAsset added in v0.0.26 

func UnsafeAsset(literal string) Expression[ExprTypeAsset]

UnsafeAsset emits literal directly as an asset reference, bypassing the vars pool — the inline counterpart to ExprAsset, and the asset-typed analogue of UnsafeAccount (same caveat: the caller owns validity).

func World added in v0.0.26 

func World() Expression[ExprTypeAccount]

World is a convenience helper for `@world` — equivalent to UnsafeAccount("world").

type KeptOrDest added in v0.0.26 

type KeptOrDest render

Either `kept` or `to <destination>`, as used in inorder/allotment clauses.

func Kept added in v0.0.26 

func Kept() KeptOrDest

func To added in v0.0.26 

func To(dest Destination) KeptOrDest

type Overdraft 

type Overdraft render

func BoundedOverdraft 

func BoundedOverdraft(amt Expression[ExprTypeMonetary]) Overdraft

func UnboundedOverdraft 

func UnboundedOverdraft() Overdraft

type Portion added in v0.0.26 

type Portion struct {
	// contains filtered or unexported fields
}

A portion literal, e.g. `1/3`. Wrap it with ExprPortion to use it in an allotment clause; ExprPortionVar is the var-form alternative.

func NewPortion added in v0.0.26 

func NewPortion(num, denom *big.Int) Portion

type Source 

type Source render

func SrcAccount 

func SrcAccount(expr Expression[ExprTypeAccount]) Source

func SrcAccountOverdraft 

func SrcAccountOverdraft(
	expr Expression[ExprTypeAccount],
	overdraft Overdraft,
) Source

func SrcAllotment added in v0.0.26 

func SrcAllotment(clauses ...AllotmentClause[Source]) Source

func SrcAllotmentWithRemaining added in v0.0.26 

func SrcAllotmentWithRemaining(clauses []AllotmentClause[Source], remaining Source) Source

SrcAllotmentWithRemaining is SrcAllotment with a trailing `remaining from <source>` clause.

The engines constrain the clause differently. The legacy machine's compiler rejects it when the known portions already sum to 100%, and rejects a portion var in an allotment that lacks it; the interpreter runs the first (the clause receives zero) and checks the second's sum at run time. Past 100%, both engines reject at run time (oracle/DIVERGENCES.md #6). internal/gen keeps generated sums strictly below 100% regardless: the machine-side compile rejections above are tolerated skips that compare nothing.

func SrcCapped added in v0.0.26 

func SrcCapped(max Expression[ExprTypeMonetary], source Source) Source

A source capped by a maximum amount: `max <amount> from <source>`

func SrcColored 

func SrcColored(
	accountExpr Expression[ExprTypeAccount],
	colorExpr Expression[ExprTypeString],
) Source

func SrcColoredOverdraft 

func SrcColoredOverdraft(
	accountExpr Expression[ExprTypeAccount],
	colorExpr Expression[ExprTypeString],
	overdraft Overdraft,
) Source

func SrcInorder 

func SrcInorder(sources ...Source) Source

func SrcOneof added in v0.1.1 

func SrcOneof(sources ...Source) Source

SrcOneof renders `oneof { ... }`. The construct exists only in numscript (experimental-oneof feature flag); the legacy machine's grammar has no oneof, so scripts using it cannot be compared against the oracle.

type Statement 

type Statement render

func StmtSave added in v0.0.26 

func StmtSave(
	monetary Expression[ExprTypeMonetary],
	account Expression[ExprTypeAccount],
) Statement

StmtSave: `save <monetary> from <account>`.

func StmtSaveAll added in v0.0.26 

func StmtSaveAll(
	asset Expression[ExprTypeAsset],
	account Expression[ExprTypeAccount],
) Statement

StmtSaveAll: `save [<asset> *] from <account>`.

func StmtSend 

func StmtSend(
	monetary Expression[ExprTypeMonetary],
	source Source,
	destination Destination,
) Statement

A bounded send statement

func StmtSendAll 

func StmtSendAll(
	asset Expression[ExprTypeAsset],
	source Source,
	destination Destination,
) Statement

An unbounded send statement

func StmtSetAccountMeta added in v0.0.26 

func StmtSetAccountMeta[T ExprType](
	account Expression[ExprTypeAccount],
	key string,
	value Expression[T],
) Statement

StmtSetAccountMeta: `set_account_meta(<account>, "<key>", <value>)`.

func StmtSetTxMeta added in v0.0.26 

func StmtSetTxMeta[T ExprType](key string, value Expression[T]) Statement

StmtSetTxMeta: `set_tx_meta("<key>", <value>)`.

type Var 

type Var[T ExprType] var_[ExprType]

func NewAccountVar 

func NewAccountVar() Var[ExprTypeAccount]

func NewAssetVar 

func NewAssetVar() Var[ExprTypeAsset]

func NewNumberVar 

func NewNumberVar() Var[ExprTypeNumber]

func NewStringVar 

func NewStringVar() Var[ExprTypeString]

type VarsEnv 

type VarsEnv struct {
	// contains filtered or unexported fields
}

func BuildProgram 

func BuildProgram(statements ...Statement) (map[string]string, VarsEnv, string)

func BuildProgramWithFeatureFlags 

func BuildProgramWithFeatureFlags(
	featureFlags []string,
	statements ...Statement,
) (map[string]string, VarsEnv, string)

Same as `BuildProgram`, but accepts features flag.

IMPORTANT NOTE: this function will panic if a feature flag doesn't match `^[a-z-]+$`. Flags are meant to be passed directly, and a sintactically incorrect flag is treated as an argument error panic right away, not returned as an "error". Also note we don't keep the list of valid flags here

func (VarsEnv) FillAccount 

func (v VarsEnv) FillAccount(var_ *Var[ExprTypeAccount], account string) (string, string)

func (VarsEnv) FillAsset 

func (v VarsEnv) FillAsset(var_ *Var[ExprTypeAsset], asset string) (string, string)

func (VarsEnv) FillNumber 

func (v VarsEnv) FillNumber(var_ *Var[ExprTypeNumber], bi *big.Int) (string, string)

func (VarsEnv) FillString 

func (v VarsEnv) FillString(var_ *Var[ExprTypeString], str string) (string, string)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.