Verse Language Quick Reference

single-line comment: Anything that appears between # and the end of line is part of the code comment.

inline block comment: Anything that appears between <# and #> is part of the code comment. Inline block comments can be between expressions on a single line and don’t change the expressions.

multi-line block comment: Anything that appears between <# and #> is part of the code comment. Multi-line block comments can span multiple lines.

nested block comment: Anything that appears between <# and #> is part of the code comment, and they can nest. This can be useful if you want to comment out some expressions in a line for testing and debugging without changing an existing code comment.

indented comment: Anything that appears on new lines after <#> and is indented four spaces over is part of the code comment. The first line that isn’t indented four spaces over is not part of the code comment and ends the code comment.

Creating a constant: A constant’s value cannot be changed while the program is running. You create a constant by specifying its name, type, and value.

Click image to enlarge.

Creating a variable: A variable’s value can be changed while the program is running. You create a variable by adding the keyword var before the name, and you must specify its name, type, and (optionally) its initial value.

Click image to enlarge.

Changing a variable’s value: You can change a variable’s value while the program is running by using the keyword set =.

Click image to enlarge.

logic: A logic in Verse is the type for Boolean values, which means logic can only be two possible values: true and false. To learn more about the logic type, see Logic.

int: An int in Verse can contain a positive number, a negative number, or zero, and has no fractional component. Integer values can be between the following values, inclusive:

• Min: -9,223,372,036,854,775,808

• Max: 9,223,372,036,854,775,807 To learn more about the int type, see Int.

float: A float in Verse can contain a positive or negative number that has a decimal point, zero, or the value NaN (Not a Number). Floating-point values can be between the following values, inclusive:

• Min: -2^1023 * (1 + (1 - 2^(-52)))

• Max: -2^1023 * (1 + (1 - 2^(-52))) To learn more about the float type, see Float.

string: A string in Verse can contain letters, numbers, punctuation, spaces, and emojis 🐈. A string containing no characters "" is called an empty string.

You can inject the result of an expression into a string using {} within the "". This is called string interpolation.

To learn more about the string type, see String.

message: A message in Verse can contain locale-independent text. When you initialize a message variable with a string value, that string is the default text and language for the message. The localizes specifier is required when defining a new message to produce localizable text.

You can turn the text into a displayable string at runtime by using the Localize() function, which formats the text according to your current locale.

Currently, the only text that can be returned by the Localize() function is the default text you provided when creating the message.

locale: This type represents in what context a message value should be localized. This affects the language of text and how numbers are represented, that are common to the locale.

Currently, the locale type is not fully implemented, so the Localize() function will only return the default text you provided when creating the message.

rational: The rational type is the result of integer division, and can only be used as an argument to the following functions:

• Floor(): Rounds the rational value down to the closest integer.

• Ceil(): Rounds the rational value up to the closest integer. To learn more about the rational type, see Rational.

void: The void type is useful in the following scenarios:

• As a return type of a function, indicating that the result of the function is not useful.

• As the type for constants or function parameters, indicating that the value is not useful. For example, use void for constants or function parameters when overriding a function definition.

To learn more about the void type, see Void.

any: The any type is the supertype of all types. To learn more about the any type, see Any.

comparable: The comparable type has the requirement that any value of this type can be compared for equality to any other value of this type. The comparable type is the supertype of all types that can be compared for equality. To learn more about the comparable type, see Comparable.

Creating an option: You can initialize an option with one of the following:

• No value: Assign false to the option to mark it as unset.

• Initial value: Use the keyword option followed by {}, and an expression between the {}. If the expression fails, the option will be unset and have the value false.

Specify the type by adding ? before the type of value expected to be stored in the option. For example ?int.

Accessing an element in an option: Use the query operator ? with the option, such as MaybeANumber?. Accessing the value stored in an option is a failable expression because there might not be a value in the option, and so must be used in a failure context.

Creating a range: The start of the range is the first value in the expression, and the end of the range is the value following .. in the expression. The range contains all the integers between the start and end values, inclusive.

Iterating over a range: You can use the for expression to iterate through the sequence of numbers. For more, see for.

Creating an array: Use the keyword array followed by {}. If you want to specify initial elements in the array, add the expressions between the {}, separated by ,. Specify the type by adding [] before the type of value expected to be stored in the array, for example []int.

Accessing an element in an array: Use [] with the index of the element you want to access, such as ExampleArray[0]. Accessing the value stored in an array is a failable expression because there might not be an element at that index, and so it must be used in a failure context.

Changing an element in an array: You can change the value stored in an array variable at an index by using the keyword set =.

Iterating over an array: You can access every element in an array, in order, from first to last, using the for expression. With the for expression, you can get the element with the syntax (Item : ExampleArray), or the element and its index with the syntax (Index -> Item : ExampleArray).

Getting the number of elements in an array: Use .Length on the array, and its result will be the number of elements in the array.

Concatenating arrays: You can merge arrays together by using the + operator.

Creating a tuple: Use () and specify two or more elements, separated by ,. Specify the type by using the keyword tuple followed by (), with each element’s type explicitly specified between the (). For example, tuple(int, float, string).

Accessing an element in a tuple: Use () with the index of the element you want to access, such as ExampleTuple(0). Accessing the value stored in a tuple is not a failable expression.

Tuple expansion: When you use a tuple as an argument to a function instead of specifying each individual argument, the function will be called with each element in the tuple used as an argument in the order they’re specified in the tuple.

Tuple array coercion: Tuples can be passed wherever an array is expected, provided that the types of the tuple elements are all of the same type as the array. Arrays cannot be passed where a tuple is expected.

Creating a map: Use the keyword map followed by {}. If you want to specify initial elements in the map, add the key-value pairs between the {}, separated by ,. Specify the type by adding [key-type], where key-type is the type used for the keys before the type of value expected to be stored in the map. For example, [string]int.

Accessing an element in a map: Use [] with the key of the element you want to access, such as ExampleMap[Key].

Iterating over a map: You can access every element in a map, in order, from first element inserted to last, using the for expression. With the for expression, you can get the element with the syntax (Value : ExampleMap), or the element and its key with the syntax (Key -> Value: ExampleMap).

Getting the number of key-value pairs in a map: Use .Length on the map and its result will be the number of elements in the map.

Creating an enum: Use the keyword enum followed by {}. If you want to specify initial elements in the enum, add the enumerators between the {}, separated by ,.

Accessing an enumerator: Use . on the enum, followed by the enumerator you want to use. For example direction.Up.

Creating a struct: Use the keyword struct followed by a code block. Definitions in the struct’s code block define the fields of the struct.

Instantiating a struct: You can construct an instance of a struct from an archetype. An archetype defines the values of a struct’s fields.

Accessing fields on a struct: You can access a struct’s fields to get their value by adding . between the struct instance and the field name.

Creating a class: Definitions that are nested inside a class define fields of the class. Functions defined as fields of a class are also called methods.

Instantiating a class: You can construct an instance of the class using the class name followed by {} (the archetype). An archetype defines the values of a class's fields.

Accessing fields on a class: You can access a class’s fields to get their value by adding . between the class instance and the field name.

Accessing methods on a class: You can access a class’s methods to call them by adding . between the class instance and the method name.

Self: You can use Self in a class method to refer to the instance of the class that the method was called on. You can refer to other fields of the instance the method was called on without using Self, but if you need to refer to the instance as a whole, you must use Self.

Creating a subclass: Specify a class as a subclass of another class by adding the other class between the () in class().

Overriding fields on the superclass: You can change the values of a field that’s defined in the superclass for the subclass only by adding the <override> specifier to the field name.

Overriding methods on the superclass: [INCLUDE:#overriding_methods_on_superclass_description]

Super: Similar to Self, you can use (super:) to access the superclass's implementations of fields and methods. To be able to use (super:), the field or method must be implemented in the superclass definition.

Defining a constructor for a class: You can add a constructor for a class by adding the <constructor> specifier on the function name. Instead of specifying a return type on the function, the function is assigned the class name followed by any initialization of fields. A class can have more than one constructor.

Adding variables and executing code in the constructor: You can execute expressions within a constructor with the block expression, and introduce new variables with the keyword let.

Calling other constructors in a constructor: You can call other constructors from a constructor. You can also call constructors for the superclass of the class from a constructor of the class as long as all fields are initialized. When a constructor calls another constructor and both constructors initialize fields, only the values provided to the first constructor are used for the fields. The order of evaluation for expressions between the two constructors will be in the order the expressions are written (as far as side effects are concerned), but only the values provided to the first constructor are used.

Creating an interface: You define an interface similarly to a class, except with the interface keyword. In the definition, you can specify the methods associated with the interface.

Extending an interface: An interface can extend the definition of another interface by specifying the interface to extend between the () in interface().

Implementing an interface: You can implement an interface with a class by specifying the interface between the () in class(). The class must override and implement each method defined in the interface.

Implementing multiple interfaces: A class can implement multiple interfaces. The interfaces are separated by , between the () in class().

Inheriting from an interface and another class: A class can implement an interface and be a subclass of another class. The interface and superclass are separated by , between the () in class().

Type aliasing: You can give a type a different name in your code and reference the type by that new name. The syntax is similar to constant initialization. You can also give a type alias to a function type. For more information, see Type Aliasing.

Parametric type as explicit type arguments: Verse supports parametric types (types expected as arguments). This only works with classes and functions. For more information, see Parametric Types.

Parametric type as implicit type arguments to functions: The reason to use implicit parametric types with functions is that it allows you to write code that is invariant of a particular type once, rather than for each type the function is used with. For more information, see Parametric Types.

Type macro: Verse has a special construct that can be used to get the type of an arbitrary expression. It can be used anywhere a type can be used. For more information, see Type Macro.

subtype: You can use subtype to give a constraint on a type variable. It requires that the type that may replace a type variable that is a subtype of the argument to subtype. Anything that may replace t in a call to Filter must be a subtype of comparable.

Query ?

The ? operator checks if a logic value is true. See Query for more details.

Postfix

9

TargetLocked?

Not not

The not operator negates the success or failure of an expression. See Not for more details.

Prefix

8

not TargetLocked?

Positive +

You can use the + operator as a prefix to a number to help align your code visually, but it won't change the value of the number. See Math for more details.

Prefix

8

+1

Negative -

You can use the operator - as a prefix to a number to negate the number value. See Math for more details.

Prefix

8

-1

Multiplication *

The * multiplies two number values together. See Math for more details.

Infix

7

2 * 3

Division /

The / operator divides the first number operand by the second number operand. Integer division is failable. See Math for more details.

Infix

7

6 / 3

Addition +

The + operator adds two number values together. When used with strings and arrays, the two values are concatenated. See Math for more details.

Infix

6

2 + 3

Subtraction -

The - operator subtracts the second number operand from the first operand. See Math for more details.

Infix

6

2 - 3

Addition assignment +=

With this operator, you can combine addition and assignment in the same operation to update a variable's value. See Math for more details.

Infix

5

set VariableName += 1

Subtraction assignment -=

With this operator, you can combine subtraction and assignment in the same operation to update a variable's value. See Math for more details.

Infix

5

set VariableName -= 1

Multiplication assignment *=

With this operator, you can combine multiplication and assignment in the same operation to update a variable's value. See Math for more details.

Infix

5

set VariableName *= 1

Division assignment /=

With this operator, you can combine division and assignment in the same operation to update a variable's value, unless the variable is an integer. See Math for more details.

Infix

5

set VariableName /= 2

Equal to =

The = operator succeeds when the left operand is equal to the right operand. Fails otherwise. See Comparison for more details.

Infix

4

MyScore = HighScore

Not equal to <>

The <> operator succeeds when the left operand is not equal to the right operand. Fails otherwise. See Comparison for more details.

Infix

4

MyScore <> HighScore

Less than <

The < operator succeeds when the left operand is less than the right operand. Fails otherwise. See Comparison for more details.

Infix

4

MyScore < HighScore

Less than or equal to <=

The <= operator succeeds when the left operand is less than or equal to the right operand. Fails otherwise. See Comparison for more details.

Infix

4

Score <= HighScore

Greater than >

The > operator succeeds when the left operand is greater than the right operand. Fails otherwise. See Comparison for more details.

Infix

4

MyScore > HighScore

Greater than or equal to >=

The >= operator succeeds when the left operand is greater than or equal to the right operand. Fails otherwise. See Comparison for more details.

Infix

4

MyScore >= HighScore

And and

The and operator succeeds only when all the operands succeed. See And / Or Operators for more details.

Infix

3

Value1 and Value2

Or or

The or operator succeeds if at least one of the operands succeeds. See And / Or Operators for more details.

Infix

2

Value1 or Value2

Variable and constant initialization : =

With this operator, you can store values in a constant or variable. See Constants and Variables for more details.

Infix

1

ConstantName := 5

Variable assignment set =

With this operator, you can update the values stored in a variable. See Constants and Variables for more details.

Infix

1

set VariableName = 5

Spaced: Begins with :, and each new line in the code block is uniformly indented four spaces.

Multi-line braced: Enclosed by {}, with each expression on a new line.

Single-line braced: Enclosed by {}, with each expression separated by ;.

Last expression returned with a value: By default, the last expression in the function’s code block is the result of the function and whose value must match the return type of the function.

Explicit return with a value: You can also explicitly define what the function will return using return followed by a value, such as return HighScore. The return expression exits the function immediately, even if there are more expressions after it in the code block.

Non-failable function call: A function call that can’t fail has the form FunctionName().

Failable function call: A failable function call has the form FunctionName[]. A function is marked as failable when its definition has the decides specifier.

Function calls: Only when the function call has the form FunctionName[], and the function definition has the decides specifier.

Comparison: A comparison expression compares two things using one of the comparison operators. For more information, see operators.

Integer division: For integers, the division operator / is failable, and the result is a rational type if it succeeds. For more information, see operators.

Decision: A decision expression uses the operators not, and, or or to give you control over the success and failure decision flow. For more information, see operators.

Query: A query expression uses the operator ? and checks whether a logic or option value is true. Otherwise, the expression fails. For more information, see operators.

Accessing an element in an array: Accessing the value stored in an array is a failable expression because there might not be an element at that index, and so must be used in a failure context. For more details, see array.

The condition in if expressions.

The iteration expressions and filter expressions in for expressions.

The body of a function that has the decides effect specifier.

The operand for the not operator.

The left operand for the or operator.

Initializing a variable that has the option type.

no_rollback: This is the default effect when no exclusive effect is specified. The no_rollback effect indicates that any actions performed by the function cannot be undone and so the function cannot be used in a failure context. This effect cannot be manually specified.

Exclusive Effects

transacts: This effect indicates that any actions performed by the function can be rolled back. The transacts effect is required any time a mutable variable (var) is written. You’ll be notified when you compile your code if the transacts effect was added to a function that can’t be rolled back. Note that this check is not done for functions with the native specifier.

varies: This effect indicates that the same input to the function may not always produce the same output. The varies effect also indicates that the behavior of the function is not guaranteed to stay the same with new versions of its containing package.

computes: This effect requires that the function has no side effects, and is not guaranteed to complete. There’s an unchecked requirement that the function, when provided with the same arguments, produces the same result. Any function that doesn’t have the native specifier that would otherwise have the converges effect is a good example of using the computes effect.

converges: This effect guarantees that not only is there no side effect from the execution of the related function, but that the function definitely completes (does not infinitely recurse). This effect can only appear in functions that have the native specifer, but this isn’t checked by the compiler. Code that is used to provide default values of class or values for global variables are required to have this effect. The functions sin(), cos(), and tan() are examples of functions that have the converges effect.

Additive Effects

decides: Indicates that the function can fail, and that calling this function is a failable expression. Function definitions with the decides effect must also have the transacts effect, which means the actions performed by this function can be rolled back (as if the actions were never performed), if there’s a failure anywhere in the function.

suspends: Indicates that the function is async. Creates an async context for the body of the function.

abstract: When a class or a class method has the abstract specifier, you cannot create an instance of the class. Abstract classes are intended to be used as a superclass with partial implementation or as a common interface. This is useful when it doesn't make sense to have instances of a superclass but you don't want to duplicate properties and behaviors across similar classes.

concrete: When a class has the concrete specifier, it must be possible to construct it with an empty archetype, which means that every field of the class must have a default value. Every subclass of a concrete class is implicitly concrete. A concrete class can only inherit directly from an abstract class if both classes are defined in the same module.

unique: The unique specifier can be applied to a class to make it a unique class. To construct an instance of a unique class, Verse allocates a unique identity for the resulting instance. This allows instances of unique classes to be compared for equality by comparing their identities. Classes without the unique specifier don't have any such identity, and so can only be compared for equality based on the values of their fields. This means that unique classes can be compared with the = and <> operators, and are subtypes of the comparable type.

native_callable: Indicates that an instance method is both native (implemented in C++) and may be called by other C++ code. You can see this specifier used on an instance method. This specifier doesn’t propagate to subclasses and so you don’t need to add it to a definition when overriding a method that has this specifier.

Result: Last expression in the block code block. In this example, the result of the block expression is the result of expression2.

Result: Last expression in the if code block. In this example, the result of the if expression is the result of expression1.

Result: Last expression in the if code block. In this example, the result of the if expression is the result of expression1.

Result: The result of a loop expression is void, which means it doesn’t produce a useful result.

Result: The result of a loop expression is void, which means it doesn’t produce a useful result.

Result: The result of a loop expression is void, which means it doesn’t produce a useful result.

Result: The result of a loop expression is void, which means it doesn’t produce a useful result.

Result: The result of a for expression is an array containing the result of each iteration’s code block.

Result: The result of a for expression is an array containing the result of each iteration’s code block.

Result: The result of a for expression is an array containing the result of each iteration’s code block.

Result: The result of a for expression that has a nested for expression is an array containing the array of results of each iteration from the inner loop’s code block.

Result: The defer expression has no result.

Result: The defer expression has no result.

Result: The defer expression has no result.

Result: The defer expression has no result.

Result: The defer expression has no result.

Result: The defer expression has no result.

Executes all expressions in its code block concurrently and waits for them all to finish before executing the next expression after the sync.

The body of the branch expression is started as soon as it is encountered. The body of the branch expression continues to evaluate until the code block completes or the enclosing async context completes — whichever occurs first — at which point the branch code block task is canceled.

Result: The result of a sync expression is a tuple of results from each expression in the order that the top-level expressions were specified. The result types of the expressions can be of any type, and each tuple element will have the type of its corresponding expression.

Result: A branch expression has no result, so its result type is void.

Similar to sync, but cancels all but the "winning" subexpression. If any other expressions complete at the same simulation time as the earlier expression, the first (earlier) expression "wins" and breaks any tie. Any "losing" expression tasks are canceled.

Similar to race, but expressions that complete after the first expression finishes continue to execute. If any expressions effectively complete at the same simulation update, then the earlier encountered expression that completes breaks any tie. Any incomplete expressions continue to evaluate until they complete, or until the enclosing async context completes, at which point, any remaining losing expressions are canceled — whichever occurs first.

Result: The result of a race expression is the result of the first completed expression. The result type is the most common compatible type of all expressions in the code block.

Result: The result of a rush expression is the result of the first completed expression. The result type is the most common compatible type of all expressions in the code block.

The body of a spawn creates an async context like the body of an async function. However, only a single async function call is allowed within the spawn body. The async function of the spawn is started as soon as it is encountered, and evaluates as much as possible until it encounters something suspending or blocking. The spawned async function continues to evaluate until it completes without any further connection to the location where it was spawned.

Result: A spawn has a task result (task(type)).

using: To be able to use the contents of a Verse module, you must specify the module by its path.

module: Outside of modules introduced by folders in a project, modules can be introduced within a .verse file using the module keyword.