Uxntal Labels

A label is a non-numeric, non-opcode, and non-runic symbol that correspond to a number between 0 and 65536. A label name is made of two parts, a scope and a sublabel. Sublabels can be added to a scope with the &name rune, or by writing the full name, like @scope/name. Note that a labels like bed, add and cafe are considered numeric.

Enums are labels with unique values that can be used as constants in a program, they begin by rolling back the program address with |00:

|00 @Suit &clubs $1 &diamonds $1 &hearts $1 &spades

@is-diamond ( suit -- f )
	.Suit/clubs EQU
	JMP2r

Structs define padded labels, for example the ;person/age label holds a value of 2, using that offset allows to access specific members of a data structure by applying the sublabels to a pointer:

|00 @Person &name $2 &age $1 &height $2
@members
	=dict/melanye 2a 008c
	=dict/alexane 2c 009a

@get-height ( member* -- height* )
	;Person/height ADD2 LDA2
	JMP2r

Constants are labels that hold a specific value through the entire execution of the program. They allow to create label that can be used in place of a number, making the code more readable.

|1400 @limit

@within-limit ( value* -- f )
	;limit LTH2
	JMP2r

Pro Tip: Labels can also be used with the padding runes to define a global length. For example, if one needs to specify a length of 0x30 for multiple members of a struct, a value can be specified as follow:

|30 @length
|00 @struct &field $length

Labels Scope

Uxntal objects are defined statically using a @label token, it allows for the enclosed methods to access local &labels. The example below creates an object with the method get-x, accessible from outside the scope as Object/get-x. By capitalizing the object name, we communicate to the assembler that the label will not be called and should not raise a warning.

@Object &x $1 &y $1

&get-x ( -- x )
	,&x LDR
	JMP2r

New methods and members can be appended to an existing scope by creating a label with the scope name followed by a slash and the name of the extension. The &labels declared within the extension have the same permissions for accessing local labels as during the object definition. To learn more, see symbols.

@Object/get-y ( -- y )
	,&y LDR
	JMP2r

When calling local routines the scope's name can be omitted. To see a complete example in that pseudo object-oriented style, see timer.tal.

&get-both ( -- x y )
	Object/get-x 
	!/get-y

Anonymous Labels

In the context of Uxntal, lambdas is a label designated by a curly bracket that points to its associated closing bracket, and can be nested. Under the hood, the opening bracket assembles to the address of the closing bracket which allows the destination address to be used like any other label such as a JCI ?{, a JMI, !{ or a plain literal ;{.

Counted Strings

Similarly to counted strings, lambdas can encode strings in memory by preceeding their content by the address of the end of the string, so the reading of that string data is not looking for a null byte, but running until reaching the bounds. The advantage is that the address of the next character to append is readily available.

@on-reset ( -> )
    ;cstr print-counted
    BRK

@cstr ={ "foo 20 "bar }

@print-counted ( cstr* -- )
    LDA2k SWP2 INC2 INC2
    &l ( -- )
        LDAk #18 DEO
        INC2 GTH2k ?&l
    POP2 POP2 JMP2r

Data Structures

We can inline a list of items, here's an implementation a function that returns the member in a list, or nil. Notice how the lambda jump requires the list address to be moved from the return stack.

{ =cat =dog =bat } STH2r ;rat member?

@member? ( {items}* target* -- res* )
	,&t STR2
	DUP2k #0002 SUB2 LDA2 ADD2 SWP2
	&l ( -- )
		LDA2k [ LIT2 &t $2 ] EQU2 ?&found
		INC2 INC2 GTH2k ?&l
	POP2 ;nil &found NIP2
	JMP2r

Unless Blocks

It is important to notice that a in the case of a conditional jump, the lambda's content is jumped over when the flag byte is true.

.button LDZ ?{ skipped-on-button }

Lambdas can also be nested into one another, only the outermost layer of a nested lambda is evaluated at a time:

#01 { { "foo $1 } STH2r !print-lambda } STH2r JCN2

incoming uxntal syntax uxntal syntax uxntal syntax uxntal syntax uxntal syntax uxntal syntax uxntal macros uxntal macros uxntal opcodes drifblim