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

clojure

175 B

(with-open [expression (sd/parse expression-text :tron)
            program (sd/build expression)
            input (sd/parse input-text :tron)]
  (sd/evaluate program 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.
evaluate	document	program.evaluate(input) returns an independent owned result document.
close	none	Release the program handle.
expression	program	Build an owned program from a path or inline expression, expanding stored macros.

build

clojure

12 B

[expression]

clojure

20 B

[expression options]

Parameters

Parameter	Type	Ownership	Default	Meaning
`expression`	`Document`	Borrowed for the call	Required	The native expression AST to compile. The call borrows this document.
`options`	`map`	Value	{}	Binding options map. The :library key selects the loaded native library. Omission uses the binding's default library. 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

clojure

175 B

(with-open [expression (sd/parse expression-text :tron)
            program (sd/build expression)
            input (sd/parse input-text :tron)]
  (sd/evaluate program 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

clojure

148 B

(with-open [expression (sd/parse expression-text :tron)
            program (sd/build expression {:explain? true})]
  (:total (sd/explain program)))

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 38000000000000 00	i64 56
30	0F 0A 23000000 2700 0000	map leaf, size 10: @23 → @27
3A	4C 77616C6C	txt "wall"
3F	02 3E000000000000 00	i64 62
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

clojure

139 B

(with-open [expression (sd/parse expression-text :tron)
            program (sd/build expression {:explain? true})]
  (sd/explain program))

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 08000000000000 00	i64 8
030	0F 0A 23000000 2700 0000	map leaf, size 10: @23 → @27
03A	4C 77616C6C	txt "wall"
03F	02 0E000000000000 00	i64 14
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 2C000000000000 00	i64 44
090	0F 0A 83000000 8700 0000	map leaf, size 10: @83 → @87
09A	4C 77616C6C	txt "wall"
09F	02 2D000000000000 00	i64 45
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 3A000000000000 00	i64 58
0F0	0F 0A E3000000 E700 0000	map leaf, size 10: @E3 → @E7
0FA	4C 77616C6C	txt "wall"
0FF	02 41000000000000 00	i64 65
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

clojure

26 B

[title authored arguments]

Parameters

Parameter	Type	Ownership	Default	Meaning
`title`	`Name`	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

clojure

253 B

(with-open [authored (sd/parse macro-text :tron)
            arguments (sd/parse arguments-text :tron)
            program (sd/build-macro "twice-plus-one" authored arguments)
            input (sd/parse input-text :tron)]
  (sd/evaluate program 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

clojure

26 B

[title authored arguments]

Parameters

Parameter	Type	Ownership	Default	Meaning
`title`	`Name`	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

clojure

160 B

(with-open [authored (sd/parse macro-text :tron)
            arguments (sd/parse arguments-text :tron)]
  (sd/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

evaluate

clojure

9 B

[program]

clojure

15 B

[program input]

clojure

23 B

[program input options]

Parameters

Parameter	Type	Ownership	Default	Meaning
`program`	`Program`	Borrowed for the call	Required	The program owner for this operation. Keep it alive during the call.
`input`	`Document`	Borrowed for the call	Absent	Variables for evaluation. Absent input uses an empty object.
`options`	`map`	Value	{}	Binding options map. The :library key selects the loaded native library. Omission uses the binding's default library. 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

clojure

175 B

(with-open [expression (sd/parse expression-text :tron)
            program (sd/build expression)
            input (sd/parse input-text :tron)]
  (sd/evaluate program 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

clojure

231 B

(with-open [expression (sd/parse expression-text :tron)
            program (sd/build expression)
            input (sd/parse input-text :tron)
            output (sd/evaluate program input {:explain? true})]
  (sd/explain output))

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 09000000000000 00	i64 9
030	0F 0A 23000000 2700 0000	map leaf, size 10: @23 → @27
03A	4C 77616C6C	txt "wall"
03F	02 12000000000000 00	i64 18
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 86000000000000 00	i64 134
090	0F 0A 83000000 8700 0000	map leaf, size 10: @83 → @87
09A	4C 77616C6C	txt "wall"
09F	02 86000000000000 00	i64 134
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 05000000000000 00	i64 5
0F0	0F 0A E3000000 E700 0000	map leaf, size 10: @E3 → @E7
0FA	4C 77616C6C	txt "wall"
0FF	02 05000000000000 00	i64 5
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 9A000000000000 00	i64 154
150	0F 0A 43010000 4701 0000	map leaf, size 10: @143 → @147
15A	4C 77616C6C	txt "wall"
15F	02 A3000000000000 00	i64 163
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

close

clojure

8 B

[handle]

Consumes the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`handle`	`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

clojure

175 B

(with-open [expression (sd/parse expression-text :tron)
            program (sd/build expression)
            input (sd/parse input-text :tron)]
  (sd/evaluate program 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

expression

clojure

11 B

[db source]

clojure

19 B

[db source options]

Parameters

Parameter	Type	Ownership	Default	Meaning
`db`	`Database`	Borrowed for the call	Required	The database owner for this operation. Keep it alive during the call.
`source`	`Source`	Value	Required	An inline native definition or a stored definition path.
`options`	`map`	Value	{}	Binding options map. The :library key selects the loaded native library. Omission uses the binding's default library. 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

clojure

183 B

(with-open [expression (sd/parse expression-text :tron)
            program (sd/expression db expression)
            input (sd/parse input-text :tron)]
  (sd/evaluate program 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