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

838 B

stardust_document *expression = NULL;
stardust_document *input = NULL;
stardust_expr_program *program = NULL;
stardust_result *evaluated = NULL;
stardust_document *result = NULL;
uint32_t status = stardust_parse(expression_text, STARDUST_TRON, &expression);
if (status == STARDUST_OK) status = stardust_parse(input_text, STARDUST_TRON, &input);
if (status == STARDUST_OK) status = stardust_expr_build(expression, NULL, &program);
if (status == STARDUST_OK) status = stardust_expr_evaluate(program, input, NULL, &evaluated);
if (status == STARDUST_OK) status = stardust_result_take_document(evaluated, &result);
stardust_result_release(evaluated);
stardust_expr_program_release(program);
stardust_document_release(input);
stardust_document_release(expression);
if (status != STARDUST_OK) {stardust_document_release(result); return status;}

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
stardust_expr_build	Status. program through output	build(expression) borrows the expression document and returns an owned program.
stardust_macro_build	Status. program through output	build_macro(title, authored, arguments) binds AST arguments into an unstored macro and returns an owned program.
stardust_macro_expand	Status. document through output	expand_macro(title, authored, arguments) returns the expanded expression document without building it.
stardust_expr_evaluate	Status. document through output	program.evaluate(input) returns an independent owned result document.
stardust_expr_program_release	`void`	Release the program handle.
stardust_db_expression_build	Status. program through output	Build an owned program from a path or inline expression, expanding stored macros.

stardust_expr_build

132 B

uint32_t stardust_expr_build(const stardust_document *source, stardust_expr_build_explain *explain, stardust_expr_program **output);

109 B

uint32_t stardust_expr_program_error(const stardust_expr_program *program, stardust_diagnostic_view *output);

Parameters

stardust_expr_build

Parameter	Type	Ownership	Default	Meaning
`source`	`const stardust_document *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`explain`	`stardust_expr_build_explain *`	Caller-owned output	NULL	Receives a record. Its pointer fields follow the record's ownership contract.
`output`	`stardust_expr_program **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_expr_program_error

Parameter	Type	Ownership	Default	Meaning
`program`	`const stardust_expr_program *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_diagnostic_view *`	Caller-owned output	Required	Receives a record. Its pointer fields follow the record's ownership contract.

Errors

Status	When
`STARDUST_COMPILE_FAILED`	the expression does not compile
`STARDUST_OUT_OF_MEMORY`	native memory is exhausted
`STARDUST_INVALID_ARGUMENT`	a required input or output pointer is NULL, or an input owner is not ready

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

838 B

stardust_document *expression = NULL;
stardust_document *input = NULL;
stardust_expr_program *program = NULL;
stardust_result *evaluated = NULL;
stardust_document *result = NULL;
uint32_t status = stardust_parse(expression_text, STARDUST_TRON, &expression);
if (status == STARDUST_OK) status = stardust_parse(input_text, STARDUST_TRON, &input);
if (status == STARDUST_OK) status = stardust_expr_build(expression, NULL, &program);
if (status == STARDUST_OK) status = stardust_expr_evaluate(program, input, NULL, &evaluated);
if (status == STARDUST_OK) status = stardust_result_take_document(evaluated, &result);
stardust_result_release(evaluated);
stardust_expr_program_release(program);
stardust_document_release(input);
stardust_document_release(expression);
if (status != STARDUST_OK) {stardust_document_release(result); return status;}

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

446 B

stardust_document *expression = NULL;
stardust_expr_build_explain explain = {0};
stardust_expr_program *program = NULL;
uint32_t status = stardust_parse(expression_text, STARDUST_TRON, &expression);
if (status == STARDUST_OK) status = stardust_expr_build(expression, &explain, &program);
stardust_expr_program_release(program);
stardust_document_release(expression);
if (status != STARDUST_OK) return status;
stardust_cost 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 0C000000000000 00	i64 12
30	0F 0A 23000000 2700 0000	map leaf, size 10: @23 → @27
3A	4C 77616C6C	txt "wall"
3F	02 0D000000000000 00	i64 13
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

454 B

stardust_document *expression = NULL;
stardust_expr_build_explain explain = {0};
stardust_expr_program *program = NULL;
uint32_t status = stardust_parse(expression_text, STARDUST_TRON, &expression);
if (status == STARDUST_OK) status = stardust_expr_build(expression, &explain, &program);
stardust_expr_program_release(program);
stardust_document_release(expression);
if (status != STARDUST_OK) return status;
stardust_expr_build_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 02000000000000 00	i64 2
030	0F 0A 23000000 2700 0000	map leaf, size 10: @23 → @27
03A	4C 77616C6C	txt "wall"
03F	02 02000000000000 00	i64 2
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 08000000000000 00	i64 8
090	0F 0A 83000000 8700 0000	map leaf, size 10: @83 → @87
09A	4C 77616C6C	txt "wall"
09F	02 07000000000000 00	i64 7
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 0C000000000000 00	i64 12
0F0	0F 0A E3000000 E700 0000	map leaf, size 10: @E3 → @E7
0FA	4C 77616C6C	txt "wall"
0FF	02 0D000000000000 00	i64 13
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

Also calls: stardust_expr_program_error

stardust_macro_build

155 B

uint32_t stardust_macro_build(stardust_bytes title, const stardust_document *authored, const stardust_document *arguments, stardust_expr_program **output);

109 B

uint32_t stardust_expr_program_error(const stardust_expr_program *program, stardust_diagnostic_view *output);

Parameters

stardust_macro_build

Parameter	Type	Ownership	Default	Meaning
`title`	`stardust_bytes`	Value	Required	The diagnostic title of this unstored macro.
`authored`	`const stardust_document *`	Borrowed handle	Required	The native authored macro definition with its declared parameters and expression body.
`arguments`	`const stardust_document *`	Borrowed handle	Required	Native AST arguments bound to the macro's declared parameters before expansion.
`output`	`stardust_expr_program **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_expr_program_error

Parameter	Type	Ownership	Default	Meaning
`program`	`const stardust_expr_program *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_diagnostic_view *`	Caller-owned output	Required	Receives a record. Its pointer fields follow the record's ownership contract.

Errors

Status	When
`STARDUST_INVALID_ARGUMENT`	the arguments include an undeclared macro parameter
`STARDUST_INVALID_DEFINITION`	the macro is invalid or expands recursively
`STARDUST_NOT_FOUND`	the macro refers to an unknown macro
`STARDUST_COMPILE_FAILED`	the expansion does not compile
`STARDUST_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

1.1 kB

stardust_document *authored = NULL;
stardust_document *arguments = NULL;
stardust_document *input = NULL;
stardust_expr_program *program = NULL;
stardust_result *evaluated = NULL;
stardust_document *result = NULL;
stardust_bytes title = {(const uint8_t *)"twice-plus-one", 14};
uint32_t status = stardust_parse(macro_text, STARDUST_TRON, &authored);
if (status == STARDUST_OK) status = stardust_parse(arguments_text, STARDUST_TRON, &arguments);
if (status == STARDUST_OK) status = stardust_parse(input_text, STARDUST_TRON, &input);
if (status == STARDUST_OK) status = stardust_macro_build(title, authored, arguments, &program);
if (status == STARDUST_OK) status = stardust_expr_evaluate(program, input, NULL, &evaluated);
if (status == STARDUST_OK) status = stardust_result_take_document(evaluated, &result);
stardust_result_release(evaluated);
stardust_expr_program_release(program);
stardust_document_release(input);
stardust_document_release(arguments);
stardust_document_release(authored);
if (status != STARDUST_OK) {stardust_document_release(result); return status;}

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

Also calls: stardust_expr_program_error

stardust_macro_expand

152 B

uint32_t stardust_macro_expand(stardust_bytes title, const stardust_document *authored, const stardust_document *arguments, stardust_document **output);

97 B

uint32_t stardust_document_error(const stardust_document *doc, stardust_diagnostic_view *output);

Parameters

stardust_macro_expand

Parameter	Type	Ownership	Default	Meaning
`title`	`stardust_bytes`	Value	Required	The diagnostic title of this unstored macro.
`authored`	`const stardust_document *`	Borrowed handle	Required	The native authored macro definition with its declared parameters and expression body.
`arguments`	`const stardust_document *`	Borrowed handle	Required	Native AST arguments bound to the macro's declared parameters before expansion.
`output`	`stardust_document **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_document_error

Parameter	Type	Ownership	Default	Meaning
`doc`	`const stardust_document *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_diagnostic_view *`	Caller-owned output	Required	Receives a record. Its pointer fields follow the record's ownership contract.

Errors

Status	When
`STARDUST_INVALID_ARGUMENT`	the arguments include an undeclared macro parameter
`STARDUST_INVALID_DEFINITION`	the macro is invalid or expands recursively
`STARDUST_NOT_FOUND`	the macro refers to an unknown macro
`STARDUST_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

587 B

stardust_document *authored = NULL;
stardust_document *arguments = NULL;
stardust_document *result = NULL;
stardust_bytes title = {(const uint8_t *)"twice-plus-one", 14};
uint32_t status = stardust_parse(macro_text, STARDUST_TRON, &authored);
if (status == STARDUST_OK) status = stardust_parse(arguments_text, STARDUST_TRON, &arguments);
if (status == STARDUST_OK) status = stardust_macro_expand(title, authored, arguments, &result);
stardust_document_release(arguments);
stardust_document_release(authored);
if (status != STARDUST_OK) {stardust_document_release(result); return status;}

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

Also calls: stardust_document_error

stardust_expr_evaluate

163 B

uint32_t stardust_expr_evaluate(stardust_expr_program *program, const stardust_document *variables, stardust_expr_eval_explain *explain, stardust_result **output);

92 B

uint32_t stardust_result_take_document(stardust_result *result, stardust_document **output);

96 B

uint32_t stardust_result_error(const stardust_result *result, stardust_diagnostic_view *output);

54 B

void stardust_result_release(stardust_result *result);

Parameters

stardust_expr_evaluate

Parameter	Type	Ownership	Default	Meaning
`program`	`stardust_expr_program *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`variables`	`const stardust_document *`	Borrowed handle	NULL	Keep the handle alive until the call returns.
`explain`	`stardust_expr_eval_explain *`	Caller-owned output	NULL	Receives a record. Its pointer fields follow the record's ownership contract.
`output`	`stardust_result **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_result_take_document

Parameter	Type	Ownership	Default	Meaning
`result`	`stardust_result *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_document **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_result_error

Parameter	Type	Ownership	Default	Meaning
`result`	`const stardust_result *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_diagnostic_view *`	Caller-owned output	Required	Receives a record. Its pointer fields follow the record's ownership contract.

stardust_result_release

Parameter	Type	Ownership	Default	Meaning
`result`	`stardust_result *`	Consumed handle	NULL	Ends ownership. Do not use the handle after this call.

Errors

Status	When
`STARDUST_EVALUATION_FAILED`	the expression fails on the input
`STARDUST_OUT_OF_MEMORY`	native memory is exhausted
`STARDUST_INVALID_ARGUMENT`	a required input or output pointer is NULL, or an input owner is not ready

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

838 B

stardust_document *expression = NULL;
stardust_document *input = NULL;
stardust_expr_program *program = NULL;
stardust_result *evaluated = NULL;
stardust_document *result = NULL;
uint32_t status = stardust_parse(expression_text, STARDUST_TRON, &expression);
if (status == STARDUST_OK) status = stardust_parse(input_text, STARDUST_TRON, &input);
if (status == STARDUST_OK) status = stardust_expr_build(expression, NULL, &program);
if (status == STARDUST_OK) status = stardust_expr_evaluate(program, input, NULL, &evaluated);
if (status == STARDUST_OK) status = stardust_result_take_document(evaluated, &result);
stardust_result_release(evaluated);
stardust_expr_program_release(program);
stardust_document_release(input);
stardust_document_release(expression);
if (status != STARDUST_OK) {stardust_document_release(result); return status;}

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

762 B

stardust_document *expression = NULL;
stardust_document *input = NULL;
stardust_expr_program *program = NULL;
stardust_result *output = NULL;
stardust_expr_eval_explain explain = {0};
uint32_t status = stardust_parse(expression_text, STARDUST_TRON, &expression);
if (status == STARDUST_OK) status = stardust_parse(input_text, STARDUST_TRON, &input);
if (status == STARDUST_OK) status = stardust_expr_build(expression, NULL, &program);
if (status == STARDUST_OK) status = stardust_expr_evaluate(program, input, &explain, &output);
stardust_result_release(output);
stardust_expr_program_release(program);
stardust_document_release(input);
stardust_document_release(expression);
if (status != STARDUST_OK) return status;
stardust_expr_eval_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 02000000000000 00	i64 2
030	0F 0A 23000000 2700 0000	map leaf, size 10: @23 → @27
03A	4C 77616C6C	txt "wall"
03F	02 02000000000000 00	i64 2
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 16000000000000 00	i64 22
090	0F 0A 83000000 8700 0000	map leaf, size 10: @83 → @87
09A	4C 77616C6C	txt "wall"
09F	02 16000000000000 00	i64 22
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 02000000000000 00	i64 2
0F0	0F 0A E3000000 E700 0000	map leaf, size 10: @E3 → @E7
0FA	4C 77616C6C	txt "wall"
0FF	02 02000000000000 00	i64 2
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 1C000000000000 00	i64 28
150	0F 0A 43010000 4701 0000	map leaf, size 10: @143 → @147
15A	4C 77616C6C	txt "wall"
15F	02 1D000000000000 00	i64 29
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

Also calls: stardust_result_take_document, stardust_result_error, stardust_result_release

stardust_expr_program_release

67 B

void stardust_expr_program_release(stardust_expr_program *program);

Consumes the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`program`	`stardust_expr_program *`	Consumed handle	NULL	Ends ownership. Do not use the handle 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

838 B

stardust_document *expression = NULL;
stardust_document *input = NULL;
stardust_expr_program *program = NULL;
stardust_result *evaluated = NULL;
stardust_document *result = NULL;
uint32_t status = stardust_parse(expression_text, STARDUST_TRON, &expression);
if (status == STARDUST_OK) status = stardust_parse(input_text, STARDUST_TRON, &input);
if (status == STARDUST_OK) status = stardust_expr_build(expression, NULL, &program);
if (status == STARDUST_OK) status = stardust_expr_evaluate(program, input, NULL, &evaluated);
if (status == STARDUST_OK) status = stardust_result_take_document(evaluated, &result);
stardust_result_release(evaluated);
stardust_expr_program_release(program);
stardust_document_release(input);
stardust_document_release(expression);
if (status != STARDUST_OK) {stardust_document_release(result); return status;}

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

stardust_db_expression_build

159 B

uint32_t stardust_db_expression_build(stardust_db *db, const stardust_db_source *source, stardust_expr_build_explain *explain, stardust_expr_program **output);

109 B

uint32_t stardust_expr_program_error(const stardust_expr_program *program, stardust_diagnostic_view *output);

Parameters

stardust_db_expression_build

Parameter	Type	Ownership	Default	Meaning
`db`	`stardust_db *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`source`	`const stardust_db_source *`	Borrowed input	Required	An inline native definition or a stored definition path.
`explain`	`stardust_expr_build_explain *`	Caller-owned output	NULL	Receives a record. Its pointer fields follow the record's ownership contract.
`output`	`stardust_expr_program **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_expr_program_error

Parameter	Type	Ownership	Default	Meaning
`program`	`const stardust_expr_program *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_diagnostic_view *`	Caller-owned output	Required	Receives a record. Its pointer fields follow the record's ownership contract.

Errors

Status	When
`STARDUST_NOT_FOUND`	no expression is stored at the path
`STARDUST_INVALID_DEFINITION`	a macro it calls is invalid or expands recursively
`STARDUST_COMPILE_FAILED`	the expanded expression does not compile
`STARDUST_CLOSED`	the database is closed
`STARDUST_OUT_OF_MEMORY`	native memory is exhausted
`STARDUST_INVALID_ARGUMENT`	a required input or output pointer is NULL, or an input owner is not ready

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

936 B

stardust_document *expression = NULL;
stardust_document *input = NULL;
stardust_expr_program *program = NULL;
stardust_result *evaluated = NULL;
stardust_document *result = NULL;
uint32_t status = stardust_parse(expression_text, STARDUST_TRON, &expression);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = expression};
if (status == STARDUST_OK) status = stardust_parse(input_text, STARDUST_TRON, &input);
if (status == STARDUST_OK) status = stardust_db_expression_build(db, &source, NULL, &program);
if (status == STARDUST_OK) status = stardust_expr_evaluate(program, input, NULL, &evaluated);
if (status == STARDUST_OK) status = stardust_result_take_document(evaluated, &result);
stardust_result_release(evaluated);
stardust_expr_program_release(program);
stardust_document_release(input);
stardust_document_release(expression);
if (status != STARDUST_OK) {stardust_document_release(result); return status;}

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

Also calls: stardust_expr_program_error