Expressions and macros

An expression is a document. The example builds an expression program once and evaluates it with an input document. The macro example expands an expression before compilation and evaluation.

Example

Build an expression and evaluate it

expression_text holds this document:

TRON

47 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	1C 2B	txt "+"
06	2C 3F78	txt "?x"
09	02 01000000000000 00	i64 1
12	0E 15 00 0700 030000 00 04000000 060000 00 09000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @4 → @6 → @9
27	12000000 00000000	root → @12; previous: none

input_text holds this document:

TRON

33 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	1C 78	txt "x"
06	02 29000000000000 00	i64 41
0F	0F 0A 04000000 0600 0000	map leaf, size 10: @4 → @6
19	0F000000 00000000	root → @F; previous: none

python

228 B

async with (await stardust.parse(expression_text, "tron")) as expression, (await stardust.build(expression)) as program, \
        (await stardust.parse(input_text, "tron")) as input:
    result = (await program.evaluate(input))

TRON

21 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	02 2A000000000000 00	i64 42
0D	04000000 00000000	root → @4; previous: none

Reusing programs

A program keeps the expression that you built, independently of any one evaluation.

You can evaluate one program concurrently with separate input documents.
Keep the program until its evaluations finish.
Then release it under the ownership rule of its operation.

Operations

Operation	Returns	Summary
build	program	build(expression) borrows the expression document and returns an owned program.
build_macro	program	build_macro(title, authored, arguments) binds AST arguments into an unstored macro and returns an owned program.
expand_macro	document	expand_macro(title, authored, arguments) returns the expanded expression document without building it.
Program.evaluate	document	program.evaluate(input) returns an independent owned result document.
Program.close	none	Release the program handle.
Database.expression	program	Build an owned program from a path or inline expression, expanding stored macros.

build

python

79 B

def build(expression: Document, explain: BuildExplain | None = None) -> Program

Parameters

Parameter	Type	Ownership	Default	Meaning
`expression`	`Document`	Borrowed for the call	Required	The native expression AST to compile. The call borrows this document.
`explain`	`BuildExplain \| None`	Caller-owned output	None	Optional explain output. This record contains explain output for `build`.

Errors

Status	When
`"compile_failed"`	the expression does not compile
`"out_of_memory"`	native memory is exhausted

Notes

Expression documents.

Examples

Build an expression and evaluate its input

expression_text holds this document:

TRON

47 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	1C 2B	txt "+"
06	2C 3F78	txt "?x"
09	02 01000000000000 00	i64 1
12	0E 15 00 0700 030000 00 04000000 060000 00 09000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @4 → @6 → @9
27	12000000 00000000	root → @12; previous: none

input_text holds this document:

TRON

33 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	1C 78	txt "x"
06	02 29000000000000 00	i64 41
0F	0F 0A 04000000 0600 0000	map leaf, size 10: @4 → @6
19	0F000000 00000000	root → @F; previous: none

python

228 B

async with (await stardust.parse(expression_text, "tron")) as expression, (await stardust.build(expression)) as program, \
        (await stardust.parse(input_text, "tron")) as input:
    result = (await program.evaluate(input))

TRON

21 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	02 2A000000000000 00	i64 42
0D	04000000 00000000	root → @4; previous: none

Inspect one measured cost stage

expression_text holds this document:

TRON

47 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	1C 2B	txt "+"
06	2C 3F78	txt "?x"
09	02 01000000000000 00	i64 1
12	0E 15 00 0700 030000 00 04000000 060000 00 09000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @4 → @6 → @9
27	12000000 00000000	root → @12; previous: none

python

179 B

explain = stardust.BuildExplain()
async with (await stardust.parse(expression_text, "tron")) as expression, (await stardust.build(expression, explain)):
    result = explain.total

TRON

108 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	BC 6172656E615F62 79746573	txt "arena_bytes"
10	02 00000000000000 00	i64 0
19	0F 0A 04000000 1000 0000	map leaf, size 10: @4 → @10
23	3C 637075	txt "cpu"
27	02 46000000000000 00	i64 70
30	0F 0A 23000000 2700 0000	map leaf, size 10: @23 → @27
3A	4C 77616C6C	txt "wall"
3F	02 50000000000000 00	i64 80
48	0F 0A 3A000000 3F00 0000	map leaf, size 10: @3A → @3F
52	07 12 21800000 1900 0000 30000000 4800 0000	map branch, size 18, depth 0 (root), slots 0, 5, 15: @19 → @30 → @48
64	52000000 00000000	root → @52; previous: none

Explain expression compilation

expression_text holds this document:

TRON

47 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	1C 2B	txt "+"
06	2C 3F78	txt "?x"
09	02 01000000000000 00	i64 1
12	0E 15 00 0700 030000 00 04000000 060000 00 09000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @4 → @6 → @9
27	12000000 00000000	root → @12; previous: none

python

173 B

explain = stardust.BuildExplain()
async with (await stardust.parse(expression_text, "tron")) as expression, (await stardust.build(expression, explain)):
    result = explain

TRON

486 B

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	BC 6172656E615F62 79746573	txt "arena_bytes"
010	02 00000000000000 00	i64 0
019	0F 0A 04000000 1000 0000	map leaf, size 10: @4 → @10
023	3C 637075	txt "cpu"
027	02 00000000000000 00	i64 0
030	0F 0A 23000000 2700 0000	map leaf, size 10: @23 → @27
03A	4C 77616C6C	txt "wall"
03F	02 0A000000000000 00	i64 10
048	0F 0A 3A000000 3F00 0000	map leaf, size 10: @3A → @3F
052	07 12 21800000 1900 0000 30000000 4800 0000	map branch, size 18, depth 0 (root), slots 0, 5, 15: @19 → @30 → @48
064	BC 6172656E615F62 79746573	txt "arena_bytes"
070	02 00000000000000 00	i64 0
079	0F 0A 64000000 7000 0000	map leaf, size 10: @64 → @70
083	3C 637075	txt "cpu"
087	02 28000000000000 00	i64 40
090	0F 0A 83000000 8700 0000	map leaf, size 10: @83 → @87
09A	4C 77616C6C	txt "wall"
09F	02 28000000000000 00	i64 40
0A8	0F 0A 9A000000 9F00 0000	map leaf, size 10: @9A → @9F
0B2	07 12 21800000 7900 0000 90000000 A800 0000	map branch, size 18, depth 0 (root), slots 0, 5, 15: @79 → @90 → @A8
0C4	BC 6172656E615F62 79746573	txt "arena_bytes"
0D0	02 00000000000000 00	i64 0
0D9	0F 0A C4000000 D000 0000	map leaf, size 10: @C4 → @D0
0E3	3C 637075	txt "cpu"
0E7	02 32000000000000 00	i64 50
0F0	0F 0A E3000000 E700 0000	map leaf, size 10: @E3 → @E7
0FA	4C 77616C6C	txt "wall"
0FF	02 3C000000000000 00	i64 60
108	0F 0A FA000000 FF00 0000	map leaf, size 10: @FA → @FF
112	07 12 21800000 D900 0000 F0000000 0801 0000	map branch, size 18, depth 0 (root), slots 0, 5, 15: @D9 → @F0 → @108
124	14 12 707265706172 655F657870726573 73696F6E	txt "prepare_expression"
138	0F 0A 24010000 5200 0000	map leaf, size 10: @124 → @52
142	7C 636F6D70696C65	txt "compile"
14A	0F 0A 42010000 B200 0000	map leaf, size 10: @142 → @B2
154	14 10 737461676573 5F636F6D706C6574 6564	txt "stages_completed"
166	02 02000000000000 00	i64 2
16F	0F 0A 54010000 6601 0000	map leaf, size 10: @154 → @166
179	EC 6172656E615F63 61706163697479	txt "arena_capacity"
188	02 00000100000000 00	i64 65536
191	0F 0A 79010000 8801 0000	map leaf, size 10: @179 → @188
19B	5C 746F74616C	txt "total"
1A1	0F 0A 9B010000 1201 0000	map leaf, size 10: @19B → @112
1AB	9C 63616368655F68 6974	txt "cache_hit"
1B5	09	bit true
1B6	0F 0A AB010000 B501 0000	map leaf, size 10: @1AB → @1B5
1C0	07 1E D2480000 3801 0000 4A010000 6F01 0000 91010000 A101 0000 B6010000	map branch, size 30, depth 0 (root), slots 1, 4, 6, 7, 11, 14: @138 → @14A → @16F → @191 → @1A1 → @1B6
1DE	C0010000 00000000	root → @1C0; previous: none

C exports: stardust_expr_build, stardust_expr_program_error

build_macro

python

79 B

def build_macro(title: str, authored: Document, arguments: Document) -> Program

Parameters

Parameter	Type	Ownership	Default	Meaning
`title`	`str`	Value	Required	The diagnostic title of this unstored macro.
`authored`	`Document`	Borrowed for the call	Required	The native authored macro definition with its declared parameters and expression body.
`arguments`	`Document`	Borrowed for the call	Required	Native AST arguments bound to the macro's declared parameters before expansion.

Errors

Status	When
`"invalid_argument"`	the arguments include an undeclared macro parameter
`"invalid_definition"`	the macro is invalid or expands recursively
`"not_found"`	the macro refers to an unknown macro
`"compile_failed"`	the expansion does not compile
`"out_of_memory"`	native memory is exhausted

Notes

Macro documents.

Examples

Bind an unstored macro and evaluate it

macro_text holds this document:

TRON

135 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	5C 696E707574	txt "input"
0A	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
17	6C 696E73657274	txt "insert"
1E	5C 696E707574	txt "input"
24	0F 0A 17000000 1E00 0000	map leaf, size 10: @17 → @1E
2E	1C 2B	txt "+"
30	02 01000000000000 00	i64 1
39	0E 15 00 0700 030000 00 2E000000 240000 00 30000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @2E → @24 → @30
4E	6C 706172616D73	txt "params"
55	0F 0A 4E000000 0A00 0000	map leaf, size 10: @4E → @A
5F	7C 657870616E6473	txt "expands"
67	0F 0A 5F000000 3900 0000	map leaf, size 10: @5F → @39
71	07 0E 00050000 5500 0000 67000000	map branch, size 14, depth 0 (root), slots 8, 10: @55 → @67
7F	71000000 00000000	root → @71; previous: none

arguments_text holds this document:

TRON

68 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	1C 2A	txt "*"
06	7C 3F616D6F756E74	txt "?amount"
0E	02 02000000000000 00	i64 2
17	0E 15 00 0700 030000 00 04000000 060000 00 0E000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @4 → @6 → @E
2C	5C 696E707574	txt "input"
32	0F 0A 2C000000 1700 0000	map leaf, size 10: @2C → @17
3C	32000000 00000000	root → @32; previous: none

input_text holds this document:

TRON

38 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	6C 616D6F756E74	txt "amount"
0B	02 0A000000000000 00	i64 10
14	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
1E	14000000 00000000	root → @14; previous: none

python

325 B

async with (await stardust.parse(macro_text, "tron")) as authored, (await stardust.parse(arguments_text, "tron")) as arguments, \
        (await stardust.build_macro("twice-plus-one", authored, arguments)) as program, \
        (await stardust.parse(input_text, "tron")) as input:
    result = (await program.evaluate(input))

TRON

21 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	02 15000000000000 00	i64 21
0D	04000000 00000000	root → @4; previous: none

C exports: stardust_macro_build, stardust_expr_program_error

expand_macro

python

81 B

def expand_macro(title: str, authored: Document, arguments: Document) -> Document

Parameters

Parameter	Type	Ownership	Default	Meaning
`title`	`str`	Value	Required	The diagnostic title of this unstored macro.
`authored`	`Document`	Borrowed for the call	Required	The native authored macro definition with its declared parameters and expression body.
`arguments`	`Document`	Borrowed for the call	Required	Native AST arguments bound to the macro's declared parameters before expansion.

Errors

Status	When
`"invalid_argument"`	the arguments include an undeclared macro parameter
`"invalid_definition"`	the macro is invalid or expands recursively
`"not_found"`	the macro refers to an unknown macro
`"out_of_memory"`	native memory is exhausted

Notes

Macro documents.

Examples

Expand an unstored macro as a native document

macro_text holds this document:

TRON

135 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	5C 696E707574	txt "input"
0A	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
17	6C 696E73657274	txt "insert"
1E	5C 696E707574	txt "input"
24	0F 0A 17000000 1E00 0000	map leaf, size 10: @17 → @1E
2E	1C 2B	txt "+"
30	02 01000000000000 00	i64 1
39	0E 15 00 0700 030000 00 2E000000 240000 00 30000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @2E → @24 → @30
4E	6C 706172616D73	txt "params"
55	0F 0A 4E000000 0A00 0000	map leaf, size 10: @4E → @A
5F	7C 657870616E6473	txt "expands"
67	0F 0A 5F000000 3900 0000	map leaf, size 10: @5F → @39
71	07 0E 00050000 5500 0000 67000000	map branch, size 14, depth 0 (root), slots 8, 10: @55 → @67
7F	71000000 00000000	root → @71; previous: none

arguments_text holds this document:

TRON

68 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	1C 2A	txt "*"
06	7C 3F616D6F756E74	txt "?amount"
0E	02 02000000000000 00	i64 2
17	0E 15 00 0700 030000 00 04000000 060000 00 0E000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @4 → @6 → @E
2C	5C 696E707574	txt "input"
32	0F 0A 2C000000 1700 0000	map leaf, size 10: @2C → @17
3C	32000000 00000000	root → @32; previous: none

python

209 B

async with (await stardust.parse(macro_text, "tron")) as authored, (await stardust.parse(arguments_text, "tron")) as arguments:
    result = (await stardust.expand_macro("twice-plus-one", authored, arguments))

TRON

84 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	1C 2A	txt "*"
06	7C 3F616D6F756E74	txt "?amount"
0E	02 02000000000000 00	i64 2
17	0E 15 00 0700 030000 00 04000000 060000 00 0E000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @4 → @6 → @E
2C	1C 2B	txt "+"
2E	02 01000000000000 00	i64 1
37	0E 15 00 0700 030000 00 2C000000 170000 00 2E000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @2C → @17 → @2E
4C	37000000 00000000	root → @37; previous: none

C exports: stardust_macro_expand, stardust_document_error

Program.evaluate

python

97 B

def evaluate(self, input: Document | None = None, explain: EvalExplain | None = None) -> Document

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`Program`	Borrowed for the call	Required	The program owner for this operation. Keep it alive during the call.
`input`	`Document \| None`	Borrowed for the call	None	Variables for evaluation. Absent input uses an empty object.
`explain`	`EvalExplain \| None`	Caller-owned output	None	Optional explain output. This record contains explain output for `evaluate`.

Errors

Status	When
`"evaluation_failed"`	the expression fails on the input
`"closed"`	the program is closed
`"out_of_memory"`	native memory is exhausted

Notes

Expression evaluation.

Examples

Build an expression and evaluate its input

expression_text holds this document:

TRON

47 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	1C 2B	txt "+"
06	2C 3F78	txt "?x"
09	02 01000000000000 00	i64 1
12	0E 15 00 0700 030000 00 04000000 060000 00 09000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @4 → @6 → @9
27	12000000 00000000	root → @12; previous: none

input_text holds this document:

TRON

33 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	1C 78	txt "x"
06	02 29000000000000 00	i64 41
0F	0F 0A 04000000 0600 0000	map leaf, size 10: @4 → @6
19	0F000000 00000000	root → @F; previous: none

python

228 B

async with (await stardust.parse(expression_text, "tron")) as expression, (await stardust.build(expression)) as program, \
        (await stardust.parse(input_text, "tron")) as input:
    result = (await program.evaluate(input))

TRON

21 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	02 2A000000000000 00	i64 42
0D	04000000 00000000	root → @4; previous: none

Explain expression evaluation

expression_text holds this document:

TRON

47 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	1C 2B	txt "+"
06	2C 3F78	txt "?x"
09	02 01000000000000 00	i64 1
12	0E 15 00 0700 030000 00 04000000 060000 00 09000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @4 → @6 → @9
27	12000000 00000000	root → @12; previous: none

input_text holds this document:

TRON

33 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	1C 78	txt "x"
06	02 29000000000000 00	i64 41
0F	0F 0A 04000000 0600 0000	map leaf, size 10: @4 → @6
19	0F000000 00000000	root → @F; previous: none

python

279 B

explain = stardust.EvalExplain()
async with (await stardust.parse(expression_text, "tron")) as expression, (await stardust.build(expression)) as program, \
        (await stardust.parse(input_text, "tron")) as input, (await program.evaluate(input, explain)):
    result = explain

TRON

634 B

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	BC 6172656E615F62 79746573	txt "arena_bytes"
010	02 00000000000000 00	i64 0
019	0F 0A 04000000 1000 0000	map leaf, size 10: @4 → @10
023	3C 637075	txt "cpu"
027	02 00000000000000 00	i64 0
030	0F 0A 23000000 2700 0000	map leaf, size 10: @23 → @27
03A	4C 77616C6C	txt "wall"
03F	02 0A000000000000 00	i64 10
048	0F 0A 3A000000 3F00 0000	map leaf, size 10: @3A → @3F
052	07 12 21800000 1900 0000 30000000 4800 0000	map branch, size 18, depth 0 (root), slots 0, 5, 15: @19 → @30 → @48
064	BC 6172656E615F62 79746573	txt "arena_bytes"
070	02 00000000000000 00	i64 0
079	0F 0A 64000000 7000 0000	map leaf, size 10: @64 → @70
083	3C 637075	txt "cpu"
087	02 96000000000000 00	i64 150
090	0F 0A 83000000 8700 0000	map leaf, size 10: @83 → @87
09A	4C 77616C6C	txt "wall"
09F	02 96000000000000 00	i64 150
0A8	0F 0A 9A000000 9F00 0000	map leaf, size 10: @9A → @9F
0B2	07 12 21800000 7900 0000 90000000 A800 0000	map branch, size 18, depth 0 (root), slots 0, 5, 15: @79 → @90 → @A8
0C4	BC 6172656E615F62 79746573	txt "arena_bytes"
0D0	02 00000000000000 00	i64 0
0D9	0F 0A C4000000 D000 0000	map leaf, size 10: @C4 → @D0
0E3	3C 637075	txt "cpu"
0E7	02 00000000000000 00	i64 0
0F0	0F 0A E3000000 E700 0000	map leaf, size 10: @E3 → @E7
0FA	4C 77616C6C	txt "wall"
0FF	02 00000000000000 00	i64 0
108	0F 0A FA000000 FF00 0000	map leaf, size 10: @FA → @FF
112	07 12 21800000 D900 0000 F0000000 0801 0000	map branch, size 18, depth 0 (root), slots 0, 5, 15: @D9 → @F0 → @108
124	BC 6172656E615F62 79746573	txt "arena_bytes"

Show all 59 nodes

Offset (hex)	Bytes (hex)	Meaning
130	02 00000000000000 00	i64 0
139	0F 0A 24010000 3001 0000	map leaf, size 10: @124 → @130
143	3C 637075	txt "cpu"
147	02 A0000000000000 00	i64 160
150	0F 0A 43010000 4701 0000	map leaf, size 10: @143 → @147
15A	4C 77616C6C	txt "wall"
15F	02 AA000000000000 00	i64 170
168	0F 0A 5A010000 5F01 0000	map leaf, size 10: @15A → @15F
172	07 12 21800000 3901 0000 50010000 6801 0000	map branch, size 18, depth 0 (root), slots 0, 5, 15: @139 → @150 → @168
184	EC 646F63756D656E 745F6279746573	txt "document_bytes"
193	02 2A000000000000 00	i64 42
19C	0F 0A 84010000 9301 0000	map leaf, size 10: @184 → @193
1A6	14 11 707265706172 655F766172696162 6C6573	txt "prepare_variables"
1B9	0F 0A A6010000 5200 0000	map leaf, size 10: @1A6 → @52
1C3	14 10 737461676573 5F636F6D706C6574 6564	txt "stages_completed"
1D5	02 03000000000000 00	i64 3
1DE	0F 0A C3010000 D501 0000	map leaf, size 10: @1C3 → @1D5
1E8	EC 6172656E615F63 61706163697479	txt "arena_capacity"
1F7	02 00000100000000 00	i64 65536
200	0F 0A E8010000 F701 0000	map leaf, size 10: @1E8 → @1F7
20A	EC 61646F70745F64 6F63756D656E74	txt "adopt_document"
219	0F 0A 0A020000 1201 0000	map leaf, size 10: @20A → @112
223	07 0E 14000000 0002 0000 19020000	map branch, size 14, depth 1, slots 2, 4: @200 → @219
231	8C 6576616C756174 65	txt "evaluate"
23A	0F 0A 31020000 B200 0000	map leaf, size 10: @231 → @B2
244	5C 746F74616C	txt "total"
24A	0F 0A 44020000 7201 0000	map leaf, size 10: @244 → @172
254	07 1E E20A0000 9C01 0000 B9010000 DE01 0000 23020000 3A02 0000 4A020000	map branch, size 30, depth 0 (root), slots 1, 5, 6, 7, 9, 11: @19C → @1B9 → @1DE → @223 → @23A → @24A

Offset (hex)	Bytes (hex)	Meaning
272	54020000 00000000	root → @254; previous: none

C exports: stardust_expr_evaluate, stardust_result_take_document, stardust_result_error, stardust_result_release

Program.close

python

23 B

def close(self) -> None

Consumes the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`Program`	Consumed owner	Required	The program owner to release. Do not use it after this call.

Examples

Build an expression and evaluate its input

expression_text holds this document:

TRON

47 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	1C 2B	txt "+"
06	2C 3F78	txt "?x"
09	02 01000000000000 00	i64 1
12	0E 15 00 0700 030000 00 04000000 060000 00 09000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @4 → @6 → @9
27	12000000 00000000	root → @12; previous: none

input_text holds this document:

TRON

33 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	1C 78	txt "x"
06	02 29000000000000 00	i64 41
0F	0F 0A 04000000 0600 0000	map leaf, size 10: @4 → @6
19	0F000000 00000000	root → @F; previous: none

python

228 B

async with (await stardust.parse(expression_text, "tron")) as expression, (await stardust.build(expression)) as program, \
        (await stardust.parse(input_text, "tron")) as input:
    result = (await program.evaluate(input))

TRON

21 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	02 2A000000000000 00	i64 42
0D	04000000 00000000	root → @4; previous: none

C exports: stardust_expr_program_release

Database.expression

python

92 B

def expression(self, source: str | Document, explain: BuildExplain | None = None) -> Program

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`Database`	Borrowed for the call	Required	The database owner for this operation. Keep it alive during the call.
`source`	`str \| Document`	Value	Required	An inline native definition or a stored definition path.
`explain`	`BuildExplain \| None`	Caller-owned output	None	Optional explain output. This record contains explain output for `build`.

Errors

Status	When
`"not_found"`	no expression is stored at the path
`"invalid_definition"`	a macro it calls is invalid or expands recursively
`"compile_failed"`	the expanded expression does not compile
`"closed"`	the database is closed
`"out_of_memory"`	native memory is exhausted

Notes

The program keeps the expression and macros selected at build time and survives database closure. Build again to use later definition changes.

Expression documents.

Examples

Build an expression with the database's macros and evaluate it

expression_text holds this document:

TRON

47 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	1C 2B	txt "+"
06	2C 3F78	txt "?x"
09	02 01000000000000 00	i64 1
12	0E 15 00 0700 030000 00 04000000 060000 00 09000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @4 → @6 → @9
27	12000000 00000000	root → @12; previous: none

input_text holds this document:

TRON

33 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	1C 78	txt "x"
06	02 29000000000000 00	i64 41
0F	0F 0A 04000000 0600 0000	map leaf, size 10: @4 → @6
19	0F000000 00000000	root → @F; previous: none

python

227 B

async with (await stardust.parse(expression_text, "tron")) as expression, (await db.expression(expression)) as program, \
        (await stardust.parse(input_text, "tron")) as input:
    result = (await program.evaluate(input))

TRON

21 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	02 2A000000000000 00	i64 42
0D	04000000 00000000	root → @4; previous: none

C exports: stardust_db_expression_build, stardust_expr_program_error