_{Official ZPE/YASS documentation}Directives

Directives and annotations are written using the @ syntax. They provide compiler instructions, function metadata, or runtime requirements for the declaration that follows them.

@compile

The @compile annotation controls whether the following function is included in a compiled application. Use @compile false for development helpers or source-only entry points that should not be emitted.

@compile false
function source_only_helper()
  print("Not included in a compiled application")
end function
  

This does not remove the function during ordinary runtime or HYPR execution. Its implementation was made available in ZPE 1.14.9 (Spurriergate, September 2026).

@directive

The @directive annotation tells the YASS compiler to apply a named compiler directive. Directives may change compiler behaviour or enable a source-level option.

prevent_auto_include

The prevent_auto_include directive prevents a compiled program from automatically including a file at the start of the program.

Note, before ZPE 1.14.11 directives always required a colon after the name of the property before the value of the directive: @directive requires_explicit_declaration : true

@directive prevent_auto_include true

requires_explicit_declaration

The requires_explicit_declaration directive was added in ZPE 1.12.9 (Piper Pine Marten, September 2024). It tells the compiler to report variables that are used before they have been declared. Declare a variable before assigning or reading it:

@directive requires_explicit_declaration true

string $x = ""
$x = "Hello world" // This will work
print($x)

$y = "Hello world" // This will not work
print($y)

@requires

The @requires annotation declares a requirement that ZPE checks for a user-defined function.

@requires return

@requires return requires the function to leave with a return value. The requirement is checked when execution leaves the function, including normal fall-through. The compiler also reports functions that can be shown to finish without returning a value.

@requires return
function get_name()
  return "Jamie"
end function

@requires permission

@requires permission N requires the active ZPE permission level to be at least N before the function body runs. User-defined functions have permission level 0 when no requirement is given.

@requires permission 4
function administer()
  return true
end function

ZPE 1.14.11 is the first version to support @requires return and @requires permission.

External documentation

Directives can attach documentation metadata to functions. External documentation is appended to functions at compile time when exporting to a library file. After compilation, the -h doc command can return documentation by name.

@doc "MyFunction : This function returns true"
@author "Jamie Balfour"
@date "July 2020"
function MyFunction ()
  return true
end function

The description must be quoted after the @doc annotation. This form is available from version 1.4.1 onwards and is useful when distributing compiled code or adding it as a library.

Documentation can be retrieved from a compiled script with:

zpe -h doc -f file.zex -s $function_name

Prior to version 1.4.1

Older versions of ZPE exported internal documentation using @ commands inside multiline comments.

/*@doc My function:This function returns true*/

The colon splits the documentation into a name on the left and a description on the right. The comment must use the multiline comment delimiters /* and */.

The standard library contains examples of these directives.