Language Directives

Directives in Kura remain compile-time only meta-programming annotations and hints for the compiler.

Compile-Time Only:
Directives get evaluated entirely at compile-time.

Hints, Not Explicit Action:
Directives do not affect program correctness or output semantics, the compiler may ignore them.

Directives do not:

• Affect program semantics
• Change evaluation results
• Introduce runtime-visible behavior guarantees

Directives do:

• Influence the compiler's decisions
• Provide the compiler with extra metadata

Directive behavior is implementation-defined, and may vary across compiler versions, but program semantics remain unaffected.

The compiler may use any available directive during optimization, analysis or IR generation.
The absence of a directive will never change the program.

Directive Rules

@meta(tags: [ Player ])
fn view() =>
  #button{
    #text("Hello World")
  }

Directives get attached to:

• Bindings
• Functions
• UI Elements

One item can have many Directives:

@vec
@meta(tags: [ Player ])
let pos = [ 10, 10, 10 ]

// order does not matter, you can also have:

@meta(tags: [ Player ])
@vec
let pos = [ 10, 10, 10 ]
// this means the same to the compiler

Some directives are mutually exclusive and will produce compile-time errors.

Available Directives

Kura's directives fall under the following categories:

• Metadata -- Add metadata to bindings, functions and/or UI elements.
• Optimizations -- Hint to the compiler about how to apply optimizations.

Kura has the following directives available:

Directive	Category	Purpose
@meta	Metadata Propagation	For meta-programming a specific bindings, functions or UI elements
@vec	Optimizations	Hint to the compiler that a specific Seq should get treated as a vector A contiguous fixed-width, SIMD/GPU friendly representation
@list	Optimizations	Hint to the compiler that a specific Seq should get treated as a list A flexible non-contiguous sequence

@meta

fn view() =>
  // attach the Button and User tags to the button
  @meta(tags: [ Button, User ])
  #button{
    // the meta from above will cascade to its children
    // the text element will receive the tags from its parent
    #text("Hello World")
    // no need for the @meta(tags: Button|User)

    // you can add more tags to subsequent nodes by using another @meta directive
    @meta(tags: [ Player ])
    #input
    // this merges the tags for the above input into:
    //   - Player
    //   - Button
    //   - User
  }

The @meta Directive allows you to attach metadata to a specific bindings, functions and/or UI elements.
The metadata will cascade to its children. Metadata gets inherited through lexical scope and may get extended in nested scopes.

Attaching this metadata allows the compiler to inject it into the generated IR.
This can enhance UI performance traces like those from Tracy.

@list

@list
let items = [ 10, 10, 10 ]
// create a Seq where each item is the Number 10

The @list Directive hints to the compiler that the Seq should get treated like a list - a logically sequential structure, but not physically contiguous in-memory.

This directive cannot get applied with the following directives also present

• @vec

Doing so will cause a compilation error.

@vec

@vec
let pos = [ 10, 10, 10 ]
// create a Seq where each item is the Number 10

The @vec Directive hints to the compiler that the Seq should get treated like a vector - a contiguous fixed-width sequence optimized for SIMD and GPU friendly layouts.

This directive cannot get applied with the following directives also present

• @list

Doing so will cause a compilation error.

User-Defined Directives

Kura contains no way for a user to define custom Directives due to the specialized and intrinsic nature of Directives themselves.