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

numscript

package module
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: Oct 6, 2026 License: MIT Imports: 5 Imported by: 1

README

Numscript CLI

GitHub Release Go Reference Go codecov

Numscript is the DSL used to express financial transaction within the Formance ledger. You can try it in its online playground

The CLI in this repo allows you to play with numscript locally, check if there are parsing or logic errors in your numscript files, and run the numscript language server

The language server features include:

  • Diagnostics
  • Hover on values
  • Detect document symbols
  • Go to definition
Installation

You can install the numscript cli with one of the following ways:

Using curl

curl -sSf https://raw.githubusercontent.com/formancehq/numscript/main/install.sh | bash

Using golang toolchain

go install github.com/formancehq/numscript/cmd/numscript@latest
Telemetry

Release builds of the numscript CLI send anonymous crash reports to Sentry when the program panics. A crash report contains the panic message, a stack trace, and the CLI version — nothing else. No reports are sent during normal operation, and development builds (built from source with go install or go build, where the version is develop) never send anything.

To disable crash reporting entirely, set the NUMSCRIPT_NO_TELEMETRY environment variable to any non-empty value:

export NUMSCRIPT_NO_TELEMETRY=1

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	CurrentBytecodeVersion     = vm.CurrentBytecodeVersion
	PeekCompiledProgramVersion = vm.PeekProgramVersion
	PeekVarsVersion            = vm.PeekVarsVersion
)
View Source 
var (
	VerifyCompiledProgram         = vm.Verify
	VerifyCompiledProgramWithVars = vm.VerifyWithVars
)
View Source 
var DecodeCompiledProgram = vm.DecodeProgram
View Source 
var DecodeVars = vm.DecodeVars
View Source 
var ErrScalingNotSupported = interpreter.ErrScalingNotSupported
View Source 
var NewVm = vm.NewVm
View Source 
var ParseErrorsToString = parser.ParseErrorsToString

Functions

func Compile added in v0.1.1 

func Compile(source string) (VarsEncoder, CompiledProgram, error)

func CompileWithFeatureFlags added in v0.1.1 

func CompileWithFeatureFlags(source string, featureFlags map[string]struct{}) (VarsEncoder, CompiledProgram, error)

Types

type AccountBalance 

type AccountBalance = interpreter.AccountBalance

type AccountDependency added in v0.0.25 

type AccountDependency = interpreter.AccountDependency

type AccountMetadataRow added in v0.0.25 

type AccountMetadataRow = interpreter.AccountMetadataRow

Input account metadata (opaque, string-valued) read via meta()

type AccountsMetadata 

type AccountsMetadata = interpreter.AccountsMetadata

type BalanceQuery 

type BalanceQuery = interpreter.BalanceQuery

For each account, list of the needed assets

type BalanceQueryItem added in v0.0.25 

type BalanceQueryItem = interpreter.BalanceQueryItem

type BalanceRow added in v0.0.25 

type BalanceRow = interpreter.BalanceRow

type Balances 

type Balances = interpreter.Balances

type BytecodeVersion added in v0.1.1 

type BytecodeVersion = vm.BytecodeVersion

BytecodeVersion is the version of the bytecode wire format a compiled program or an encoded Vars was written with — major.minor, versioned independently of the library itself: a new library release does not imply a new bytecode version. A reader accepts a blob of its own major with a minor no newer than its own (BytecodeVersion.CanRead); anything else the decoders reject with UnsupportedBytecodeVersionError. Major 0 is unstable: a 0.x build reads only its exact version, so a host holding a 0.x blob this build rejects should recompile the script from source.

CurrentBytecodeVersion is what this build's Compile and Encode write and the newest it can execute. A host that stores bytecode compiled by one build and executes it with another can compare it against the stored blob's version before trusting the bytecode to run; PeekCompiledProgramVersion and PeekVarsVersion read that version from the raw bytes without decoding the rest, and without checking that this build can read it.

type CompiledProgram added in v0.1.1 

type CompiledProgram = vm.Program

type ExecutionResult 

type ExecutionResult = interpreter.ExecutionResult

func ExecVm added in v0.1.1 

func ExecVm[S VMStore](ctx context.Context, machine *Vm, vars *Vars, store S) (ExecutionResult, error)

type InterpreterError 

type InterpreterError = interpreter.InterpreterError

type MetaDependency added in v0.0.25 

type MetaDependency = interpreter.MetaDependency

type Metadata 

type Metadata = interpreter.Metadata

The transaction metadata, set by set_tx_meta()

type MetadataQuery 

type MetadataQuery = interpreter.MetadataQuery

type MissingFundsErr added in v0.0.21 

type MissingFundsErr = interpreter.MissingFundsErr

type NegativeAmountErr added in v0.0.26 

type NegativeAmountErr = interpreter.NegativeAmountErr

type ParseResult 

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

This struct represents a parsed numscript source code

func Parse 

func Parse(code string) ParseResult

func (ParseResult) Compile added in v0.1.1 

func (p ParseResult) Compile() (VarsEncoder, CompiledProgram, error)

func (ParseResult) CompileWithFeatureFlags added in v0.1.1 

func (p ParseResult) CompileWithFeatureFlags(featureFlags map[string]struct{}) (VarsEncoder, CompiledProgram, error)

CompileWithFeatureFlags compiles the program, rejecting any construct gated behind an experimental feature flag that isn't in featureFlags.

func (ParseResult) GetNeededVariables added in v0.0.12 

func (p ParseResult) GetNeededVariables() map[string]string

Returns a map from a variable's name to its type.

doesn't include variables whose value is already defined within the script

func (ParseResult) GetParsingErrors 

func (p ParseResult) GetParsingErrors() []ParserError

func (ParseResult) GetSource 

func (p ParseResult) GetSource() string

func (ParseResult) ResolveDependencies added in v0.0.25 

func (p ParseResult) ResolveDependencies(ctx context.Context, vars VariablesMap, store Store) (ResolvedDependencies, error)

ResolveDependencies statically determines which accounts and metadata the script reads and writes, resolving account/asset/key expressions against the given vars and store.

func (ParseResult) Run 

func (p ParseResult) Run(ctx context.Context, vars VariablesMap, store Store) (ExecutionResult, InterpreterError)

func (ParseResult) RunWithFeatureFlags added in v0.0.10 

func (p ParseResult) RunWithFeatureFlags(
	ctx context.Context,
	vars VariablesMap,
	store Store,
	featureFlags map[string]struct{},
) (ExecutionResult, InterpreterError)

type ParserError 

type ParserError = parser.ParserError

type Posting 

type Posting = interpreter.Posting

type ResolvedDependencies added in v0.0.25 

type ResolvedDependencies = interpreter.ResolvedDependencies

type SetAccountMetadataRow added in v0.0.25 

type SetAccountMetadataRow = interpreter.SetAccountMetadataRow

The account metadata set during the execution (tagged, typed values)

type SetAccountsMetadata added in v0.0.25 

type SetAccountsMetadata = interpreter.SetAccountsMetadata

type StaticStore 

type StaticStore = interpreter.StaticStore

type Store 

type Store = interpreter.Store

type UnsupportedBytecodeVersionError added in v0.1.1 

type UnsupportedBytecodeVersionError = vm.UnsupportedBytecodeVersionError

BytecodeVersion is the version of the bytecode wire format a compiled program or an encoded Vars was written with — major.minor, versioned independently of the library itself: a new library release does not imply a new bytecode version. A reader accepts a blob of its own major with a minor no newer than its own (BytecodeVersion.CanRead); anything else the decoders reject with UnsupportedBytecodeVersionError. Major 0 is unstable: a 0.x build reads only its exact version, so a host holding a 0.x blob this build rejects should recompile the script from source.

CurrentBytecodeVersion is what this build's Compile and Encode write and the newest it can execute. A host that stores bytecode compiled by one build and executes it with another can compare it against the stored blob's version before trusting the bytecode to run; PeekCompiledProgramVersion and PeekVarsVersion read that version from the raw bytes without decoding the rest, and without checking that this build can read it.

type VMStore added in v0.1.1 

type VMStore = vm.Store

type Value 

type Value = interpreter.Value

type VariablesMap 

type VariablesMap = interpreter.VariablesMap

type Vars added in v0.1.1 

type Vars = vm.Vars

type VarsEncoder added in v0.1.1 

type VarsEncoder = compiler.VarsEncoder

type VerifiedVarsInfo added in v0.1.1 

type VerifiedVarsInfo = vm.VerifiedVarsInfo

VerifyCompiledProgram statically checks that a program is safe to execute: ExecVm assumes well-formed bytecode and will panic rather than error on a program that is not. Compile's output always is, so this is for programs that came from somewhere else — DecodeCompiledProgram, most obviously.

VerifyCompiledProgramWithVars additionally checks the program against the vars it will be given; prefer it whenever vars are in play, since a program that loads a variable is only safe against a pool that actually has it. On success it also returns a VerifiedVarsInfo: a caller that reuses the same compiled Program across many calls (e.g. an LRU cache keyed on the compiled bytes) can keep this and use its CheckVars method to skip re-running verification — a whole-program static pass — when it sees a Vars shape it already knows is compatible.

type Vm added in v0.1.1 

type Vm = vm.Vm

type VmAssetMismatchError added in v0.1.1 

type VmAssetMismatchError = vm.AssetMismatchError

VM execution error types, aliased so ExecVm callers can classify failures with errors.As without reaching into internal packages — the same pattern as the interpreter's error types above. The Vm prefix keeps them apart from the interpreter's MissingFundsErr/NegativeAmountErr, which are different types with different fields.

type VmBadMetaValueError added in v0.1.1 

type VmBadMetaValueError = vm.BadMetaValueError

VM execution error types, aliased so ExecVm callers can classify failures with errors.As without reaching into internal packages — the same pattern as the interpreter's error types above. The Vm prefix keeps them apart from the interpreter's MissingFundsErr/NegativeAmountErr, which are different types with different fields.

type VmCannotCastScopedAccountToString added in v0.1.1 

type VmCannotCastScopedAccountToString = vm.CannotCastScopedAccountToString

VM execution error types, aliased so ExecVm callers can classify failures with errors.As without reaching into internal packages — the same pattern as the interpreter's error types above. The Vm prefix keeps them apart from the interpreter's MissingFundsErr/NegativeAmountErr, which are different types with different fields.

type VmDivideByZeroError added in v0.1.1 

type VmDivideByZeroError = vm.DivideByZeroError

VM execution error types, aliased so ExecVm callers can classify failures with errors.As without reaching into internal packages — the same pattern as the interpreter's error types above. The Vm prefix keeps them apart from the interpreter's MissingFundsErr/NegativeAmountErr, which are different types with different fields.

type VmInternalError added in v0.1.1 

type VmInternalError = vm.InternalError

VM execution error types, aliased so ExecVm callers can classify failures with errors.As without reaching into internal packages — the same pattern as the interpreter's error types above. The Vm prefix keeps them apart from the interpreter's MissingFundsErr/NegativeAmountErr, which are different types with different fields.

type VmInvalidAccountName added in v0.1.1 

type VmInvalidAccountName = vm.InvalidAccountName

VM execution error types, aliased so ExecVm callers can classify failures with errors.As without reaching into internal packages — the same pattern as the interpreter's error types above. The Vm prefix keeps them apart from the interpreter's MissingFundsErr/NegativeAmountErr, which are different types with different fields.

type VmInvalidAllotmentSum added in v0.1.1 

type VmInvalidAllotmentSum = vm.InvalidAllotmentSum

VM execution error types, aliased so ExecVm callers can classify failures with errors.As without reaching into internal packages — the same pattern as the interpreter's error types above. The Vm prefix keeps them apart from the interpreter's MissingFundsErr/NegativeAmountErr, which are different types with different fields.

type VmInvalidColor added in v0.1.1 

type VmInvalidColor = vm.InvalidColor

VM execution error types, aliased so ExecVm callers can classify failures with errors.As without reaching into internal packages — the same pattern as the interpreter's error types above. The Vm prefix keeps them apart from the interpreter's MissingFundsErr/NegativeAmountErr, which are different types with different fields.

type VmInvalidPostingError added in v0.1.1 

type VmInvalidPostingError = vm.InvalidPostingError

VM execution error types, aliased so ExecVm callers can classify failures with errors.As without reaching into internal packages — the same pattern as the interpreter's error types above. The Vm prefix keeps them apart from the interpreter's MissingFundsErr/NegativeAmountErr, which are different types with different fields.

type VmInvalidScope added in v0.1.1 

type VmInvalidScope = vm.InvalidScope

VM execution error types, aliased so ExecVm callers can classify failures with errors.As without reaching into internal packages — the same pattern as the interpreter's error types above. The Vm prefix keeps them apart from the interpreter's MissingFundsErr/NegativeAmountErr, which are different types with different fields.

type VmInvalidUncappedSource added in v0.1.1 

type VmInvalidUncappedSource = vm.InvalidUncappedSource

VM execution error types, aliased so ExecVm callers can classify failures with errors.As without reaching into internal packages — the same pattern as the interpreter's error types above. The Vm prefix keeps them apart from the interpreter's MissingFundsErr/NegativeAmountErr, which are different types with different fields.

type VmMetadataNotFoundError added in v0.1.1 

type VmMetadataNotFoundError = vm.MetadataNotFoundError

VM execution error types, aliased so ExecVm callers can classify failures with errors.As without reaching into internal packages — the same pattern as the interpreter's error types above. The Vm prefix keeps them apart from the interpreter's MissingFundsErr/NegativeAmountErr, which are different types with different fields.

type VmMissingFundsError added in v0.1.1 

type VmMissingFundsError = vm.MissingFundsError

VM execution error types, aliased so ExecVm callers can classify failures with errors.As without reaching into internal packages — the same pattern as the interpreter's error types above. The Vm prefix keeps them apart from the interpreter's MissingFundsErr/NegativeAmountErr, which are different types with different fields.

type VmNegativeAmountError added in v0.1.1 

type VmNegativeAmountError = vm.NegativeAmountError

VM execution error types, aliased so ExecVm callers can classify failures with errors.As without reaching into internal packages — the same pattern as the interpreter's error types above. The Vm prefix keeps them apart from the interpreter's MissingFundsErr/NegativeAmountErr, which are different types with different fields.

type VmNegativeBalanceError added in v0.1.1 

type VmNegativeBalanceError = vm.NegativeBalanceError

VM execution error types, aliased so ExecVm callers can classify failures with errors.As without reaching into internal packages — the same pattern as the interpreter's error types above. The Vm prefix keeps them apart from the interpreter's MissingFundsErr/NegativeAmountErr, which are different types with different fields.

type VmNegativePortionError added in v0.1.1 

type VmNegativePortionError = vm.NegativePortionError

VM execution error types, aliased so ExecVm callers can classify failures with errors.As without reaching into internal packages — the same pattern as the interpreter's error types above. The Vm prefix keeps them apart from the interpreter's MissingFundsErr/NegativeAmountErr, which are different types with different fields.

type VmStoreError added in v0.1.1 

type VmStoreError = vm.StoreError

VM execution error types, aliased so ExecVm callers can classify failures with errors.As without reaching into internal packages — the same pattern as the interpreter's error types above. The Vm prefix keeps them apart from the interpreter's MissingFundsErr/NegativeAmountErr, which are different types with different fields.

Source Files

View all Source files

Directories

Path Synopsis
Builder to format numscript document
 Builder to format numscript document
cmd
numscript command
internal
analysis
ansi
builtins
cmd
compiler
flags
funds
Package funds is the funds engine shared by the VM and the tree-walking interpreter: per-(account, scope, asset, color) balances, a FIFO queue of funding sources fed by Pull/PullUncapped, and the postings produced by Send/SendUncapped.
 Package funds is the funds engine shared by the VM and the tree-walking interpreter: per-(account, scope, asset, color) balances, a FIFO queue of funding sources fed by Pull/PullUncapped, and the postings produced by Send/SendUncapped.
gen
Package gen produces random numscript programs for differential testing.
 Package gen produces random numscript programs for differential testing.
interpreter
ir
Package ir is the compiler's intermediate representation, and everything that operates on it: Parse and Dump convert to and from the textual format (see ir-textual-format.md), Typecheck checks register types, Assemble lowers to a vm.Program.
 Package ir is the compiler's intermediate representation, and everything that operates on it: Parse and Dump convert to and from the textual format (see ir-textual-format.md), Typecheck checks register types, Assemble lowers to a vm.Program.
ir/internal/syntax
ir/internal/syntax/antlrParser
jsonrpc2
lsp
mcp_impl
parser
parser/antlrParser
specs_format
typecheck
Package typecheck is the shared, side-effect-free type checker for numscript.
 Package typecheck is the shared, side-effect-free type checker for numscript.
utils
vm
oracle module

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.