Ballerina Language Specification, Swan Lake preview 2020-09-16

5.1.1 Type system fundamentals

Ballerina programs operate on a rich universe of values. This universe of values is partitioned into a number of basic types; every value belongs to exactly one basic type.

Values are of four kinds, each corresponding to a kind of basic type:

• simple values, like booleans and floating point numbers, which are not constructed from other values;
• structured values, like mappings and lists, which contain other values;
• sequence values, which combine aspects of simple values and structured values;
• behavioral values, like functions, which allow parts of Ballerina programs to be handled in a uniform way with other values

There is a fundamental distinction between values that have a storage identity and values that do not. A value that has storage identity has an identity that comes from the location where the value is stored. All structural and behavioural values have a storage identity, whereas all simple values do not. Storage identity for sequence values is more complicated and will be explained in the section on sequence values.

Values can be stored in variables or as members of structures. When a value has no storage identity, it can be stored directly in the variable or structure. However, when a value has storage identity, what is stored in the variable or member is a reference to the location where the value is stored rather than the value itself. Storage identity allows values in Ballerina to represent not just trees but graphs.

Ballerina provides the ability to test whether two values have the same storage identity, but does not expose the specific storage location of a value. For values with storage identity, there is the concept of creating a new value: this means creating a value that has a storage identity that is different from any existing value. For values with storage identity, there is also the concept of copying: it means to create a value that is the same, except for having a new storage identity. The concept of having storage identity is similar to the concept of a reference type in some other programming languages, but also accomodates the concept of a sequence value.

Storage identity is tied to mutability. Mutation is only well-defined for values with storage identity. When a value stored in some storage location is mutated, the change will be visible through all variables referring to the value in that location. But not all values with storage identity can be mutated: a value may not support mutation even though it has a storage identity.

Ballerina programs use types to categorize values both at compile-time and runtime. Types deal with an abstraction of values that does not consider storage identity. This abstraction is called a shape. A type denotes a set of shapes. Subtyping in Ballerina is semantic: a type S is a subtype of type T if the set of shapes denoted by S is a subset of the set of shapes denoted by T. Every value has a corresponding shape. A shape is specific to a basic type: if two values have different basic types, then they have different shapes. The shape of the values contained in a structured value are part of the shape of the structured value. Since shapes do not deal with storage identity, they represent trees rather graphs. For simple values, there is no difference between a shape and a value, with the exception of floating point values where the shape does not consider representation details that do not affect the mathematical value being represented. There are two important relations between a value and a type:

• a value looks like a type at a particular point in the execution of a program if its shape at that point is a member of the type;
• a value belongs to a type if it looks like the type, and it will necessarily continue to look like the type no matter how the value is mutated.

When a Ballerina program declares a variable to have a compile-time type, this means that the Ballerina compiler together with the runtime system will ensure that the variable will only ever contain a value that belongs to the type. Ballerina also provides mechanisms that take a value that looks like a type and use it to create a value that belongs to a type.

If a value cannot be mutated, looking like a type and belonging to a type are the same thing.

Every value has a read-only bit. If the read-only bit is on, it means that the value is not mutable. A value's read-only bit is fixed when the value is constructed, and cannot be changed thereafter. Immutability is deep: the values contained in a structured value that has its read-only bit on will all have their read-only bits on. Some basic types are inherently immutable: the read-only bit is always on for a value that belongs to an inherently immutable basic type. All simple types are inherently immutable. Some basic types are selectively immutable: a type is selectively immutable if it is possible to construct both values of the type that have the read-only bit on and values that do not have the read-only bit on. All structured types are selectively immutable. Finally, some basic types are inherently mutable: the read-only bit is never on for a value belonging to an inherently mutable basic type.

A shape is divided into two aspects: the primary aspect and the read-only aspect. A value's read-only bit is a part of the read-only aspect of the value's shape. The read-only bit of values contained in a structured value is part of the read-only aspect of those values and of the read-only aspect of the structured value. Everything about a shape except the read-only bits constitutes the primary aspect of the shape.

A value is plain data if it is a simple value, a sequence value or a structured value that does not contain a behavioral value at any depth. More precisely, a value is defined to be plain data if it is

• a simple value,
• a sequence value, or
• a structured value, all of whose members are also plain data.

Plain data values can in general contain cycles of references, but in some contexts are restricted to be acyclic. Plain data values, including values with cycles, can be compared for equality.

5.1.2 Type descriptors

Ballerina provides a rich variety of type descriptors, which programs use to describe types. For example, there is a type descriptor for each simple basic type; there is a type descriptor that describes a type as a union of two types; there is a type descriptor that uses a single value to describe a type that contains a single shape. This means that values can look like and belong to arbitrarily many types, even though they look like or belong to exactly one basic type.

The following table summarizes the type descriptors provided by Ballerina.

Type descriptors other than readonly describes types using only the primary aspect of shape: whether a value belongs to the type is not affected by the read-only aspect of the value's shape. The readonly type uses only the read-only aspect: whether a value belongs to the readonly type depends only on the read-only aspect of the value's shape.

In addition to describing a type, a type descriptor may also include information used to construct a value of the type, as well as metadata. Whereas the type described by a type descriptor is known at compile time, this additional information may need to be resolved at runtime. The typedesc basic type represents a type descriptor that has been resolved.

type-descriptor :=
   simple-type-descriptor
   | sequence-type-descriptor
   | structured-type-descriptor
   | behavioral-type-descriptor
   | other-type-descriptor

For simplicity, the type-descriptor grammar is ambiguous. The following table shows the various types of type descriptor in decreasing order of precedence, together with associativity.

5.1.3 Type-ids

Ballerina has a feature, called distinct types, which provides functionality similar to that provided by nominal types, but which works within Ballerina's structural type system. Distinct types are similar to the branded types found in some other structurally typed languages, such as Modula-3.

The semantics of distinct types are based on type-ids. These are similar to the brands used by branded types. A distinct type is created by the use of the distinct keyword in either a distinct-type-descriptor or the class-type-quals of a module-class-defn. Each such occurrence of the distinct keyword has a distinct type-id, which uniquely identifies it within a Ballerina program. A type-id has three parts:

1. a module id, which identifies the module within which the distinct-type-descriptor occurs; this consists of an organization, a module name, and a version number;
2. a local id, which identifies the occurrence of the distinct within the module; this takes one of two forms:
   • named -
     • if the distinct keyword is part of a distinct-type-descriptor that is the only distinct-type-descriptor occurring within a module-type-defn, then the local id is the name of the type defined by the module-type-defn;
     • if the distinct keyword is part of the class-type-quals of a module-class-defn, then the local id is the name of the class defined by the module-class-defn;
   • anonymous - otherwise, the local id is a compiler-generated integer;
3. a boolean flag saying whether the type-id is public; this flag is on if and only if the local id part is named and is the name of a module-type-defn that is public.

Distinct types can be used with only the object or error basic types. An object value or error value has a set of type-ids. These type-ids are fixed at the time of construction and are immutable thereafter. A value's set of type-ids may be empty. The type-ids of a value are part of the value's shape and so can affect when an object belongs to a type. The set of type-ids of an object or error value are divided into primary type-ids and secondary type-ids: the secondary type-ids could be inferred from the primary type-ids using the program's source.

An object or error value is always constructed using a specific type descriptor. A type descriptor for objects and errors thus performs a dual role: it denotes a type and it defines a mechanism to construct a value of the type. A type descriptor is definite if it induces a specific set of type-ids. The set of type-ids of an object or error value are those induced by the type-descriptor used to construct it; such a type descriptor must therefore be definite. A type descriptor that denotes a type that does not allow object or error values induces an empty set of type-ids and so is vacuously definite. For other type descriptors, the section that specifies that type descriptor will say when it is definite, the set of type-ids that it induces when it is, and which of those are primary.

5.1.4 Iterability

Values of some basic types are iterable. An iterable value supports an iteration operation, which treats the iterable value as consisting of a sequence of zero or more simpler values, which are in some sense a part of the iterable value; the iteration operation provides the values in the sequence, one after another. The sequence of values that an iteration operation on a value provides is the iteration sequence of the value. Each iterable basic type defines the iteration sequence for a value of that basic type. There is also a value associated with the completion of the iteration operation, which is nil if the iteration completed successfully and an error otherwise. The iteration operation thus determines two associated types for an iterable type: the value type, which is the type of the values in the iteration sequence, and the completion type, which is the type of the iteration completion value.

The following tables summarizes the iterable basic types.

5.2.1 Nil

nil-type-descriptor :=  ( )
nil-literal :=  ( ) | null

The nil type contains a single value, called nil, which is used to represent the absence of any other value. The nil value is written (). The nil value can also be written null, for compatibility with JSON; the use of null should be restricted to JSON-related contexts.

The nil type is special, in that it is the only basic type that consists of a single value. The type descriptor for the nil type is not written using a keyword, but is instead written () like the value.

5.2.2 Boolean

boolean-type-descriptor := boolean
boolean-literal := true | false

The boolean type consists of the values true and false.

5.2.3 Int

int-type-descriptor := int
int-literal := DecimalNumber | HexIntLiteral
DecimalNumber := 0 | NonZeroDigit Digit*
HexIntLiteral := HexIndicator HexNumber
HexNumber := HexDigit+
HexIndicator := 0x | 0X
HexDigit := Digit | a .. f | A .. F
NonZeroDigit := 1 .. 9

The int type consists of integers between -9,223,372,036,854,775,808 and 9,223,372,036,854,775,807 (i.e. signed integers than can fit into 64 bits using a two's complement representation).

The byte type is a subtype of int. The lang.int lang library module are also provides built-in subtypes for signed and unsigned integers representable in 8, 16 and 32 bits.

5.2.4 Floating point types

floating-point-type-descriptor := float | decimal
floating-point-literal :=
   DecimalFloatingPointNumber | HexFloatingPointLiteral
DecimalFloatingPointNumber :=
   DecimalNumber Exponent [FloatingPointTypeSuffix]
   | DottedDecimalNumber [Exponent] [FloatingPointTypeSuffix]
   | DecimalNumber FloatingPointTypeSuffix
DottedDecimalNumber :=
   DecimalNumber . Digit*
   | . Digit+
Exponent := ExponentIndicator [Sign] Digit+
ExponentIndicator := e | E
HexFloatingPointLiteral := HexIndicator HexFloatingPointNumber
HexFloatingPointNumber :=
   HexNumber HexExponent
   | DottedHexNumber [HexExponent]
DottedHexNumber :=
   HexDigit+ . HexDigit*
   | . HexDigit+
HexExponent := HexExponentIndicator [Sign] Digit+
HexExponentIndicator := p | P
Sign := + | -
FloatingPointTypeSuffix := DecimalTypeSuffix | FloatTypeSuffix
DecimalTypeSuffix := d | D
FloatTypeSuffix :=  f | F

5.3.1 Strings

string-type-descriptor := string
string-literal := DoubleQuotedStringLiteral
DoubleQuotedStringLiteral := " (StringChar | StringEscape)* "
StringChar := ^ ( 0xA | 0xD | \ | " )
StringEscape := StringSingleEscape | StringNumericEscape
StringSingleEscape := \t | \n | \r | \\ | \"
StringNumericEscape := \u{ CodePoint }
CodePoint := HexDigit+

A string is an sequence of zero or more Unicode characters. More precisely, it is a sequence whose singleton values represent Unicode scalar values, where a Unicode scalar value is any code point in the Unicode range of 0x0 to 0x10FFFF inclusive, other than surrogate code points, which are 0xD800 to 0xDFFF inclusive. Note that a string may include Unicode noncharacters, such as 0xFFFE and 0xFFFF.

In a StringNumericEscape, CodePoint must valid Unicode code point; more precisely, it must be a hexadecimal numeral denoting an integer n where 0 ≤ n < 0xD800 or 0xDFFF < n ≤ 0x10FFFF.

String values do not have storage identity and so the string basic type is inherently immutable.

There is a built-in subtype string:Char for single character strings.

5.3.2 XML

An xml value is a sequence representing parsed XML, such as occurs in the content of an XML element. The singleton values are of the following types:

• element
• processing instruction
• comment
• text

The element, processing instruction and comment singletons correspond directly to information items in the XML Information Set. A text singleton corresponds to one or more character information items. When an xml value is constructed, consecutive text singletons are merged, so that an xml value never contains consecutive text singletons. There are built-in subtypes xml:Element, xml:ProcessingInstruction, xml:Comment and xml:Text corresponding to the above singletons; xml:Text also allows the empty xml value.

xml-type-descriptor := xml [type-parameter]
type-parameter := < type-descriptor >

A shape belongs to type xml if its basic type is xml. A type parameter of an xml-type-descriptor must be a subtype of xml. A shape belongs to type xml<T> if all of its constituent items belong to T. So, for example, xml<xml:Element> is the type for xml values containing only elements. Note that xml<xml<T>> is the same as xml<T> and that xml<xml:Text> is the same as xml:Text.

The name of an element is represented by a string. The attributes of an element are represented by a value of type map<string>. The children of an element is represented by a value of type xml.

Singleton element, processing instruction and comment values have storage identity. Other xml values do not.

The xml:Text type is inherently immutable. This implies that both text singletons and empty xml values always have their read-only bits on. The xml:Element, xml:ProcessingInstruction and xml:Comment types are selectively immutable. The read-only bit of a xml value with length greater than one is on if and only if the read-only bit of all its constituent items is on. Immutability of xml values is deep: if the read-only bit of an xml:Element is on, then the read-only bits of the mapping representing its attributes and of the xml value representing its children are also on.

Note that although the mutable constituents of mutable xml value can be mutated, the number and the storage identity of the constituents of a xml value are fixed when the value is constructed. The storage identity of the attributes map of an element are also fixed when the element is constructed.

   {namespace-uri}local-name

5.4.1 Lists

A list value is a container that keeps its members in an ordered list. The number of members of the list is called the length of the list. The key for a member of a list is the integer index representing its position in the list, with the index of the first member being 0. For a list of length n, the indices of the members of the list, from first to last, are 0,1,...,n - 1. The shape of a list value is an ordered list of the shapes of its members.

A list is iterable: the iteration sequence consists of the members of the list in order and the iteration completion value is always nil.

The type of list values can be described by two kinds of type descriptors.

list-type-descriptor :=
   array-type-descriptor | tuple-type-descriptor

The inherent type of a list value must be a list-type-descriptor. The inherent type of a list value determines a type T_i for a member with index i. The runtime system will enforce a constraint that a value written to index i will belong to type T_i. Note that the constraint is not merely that the value looks like T_i.

Both kinds of type descriptor are covariant in the types of their members.

array-type-descriptor := member-type-descriptor [ [ array-length ] ]
member-type-descriptor := type-descriptor
array-length :=
   int-literal
   | constant-reference-expr
   | inferred-array-length
inferred-array-length := *

tuple-type-descriptor :=
   [ tuple-member-type-descriptors ]
tuple-member-type-descriptors :=
   member-type-descriptor (, member-type-descriptor)* [, tuple-rest-descriptor]
   | [ tuple-rest-descriptor ]
tuple-rest-descriptor := type-descriptor ...

5.4.2 Mappings

A mapping value is a container where each member has a key, which is a string, that uniquely identifies within the mapping. We use the term field to mean the member together its key; the name of the field is the key, and the value of the field is that value of the member; no two fields in a mapping value can have the same name.

The shape of a mapping value is an unordered collection of field shapes one for each field. The field shape for a field f has a name, which is the same as the name of f, and a shape, which is the shape of the value of f.

Each field also has a read-only bit. This is in addition to the read-only bit of the mapping value. If a mapping value's field has its read-only bit on, then that field cannot be assigned to nor removed. If the mapping value's read-only bit is on, then the read-only bit of every field is also on. A field's read-only bit is fixed when the mapping value is constructed, and cannot be changed thereafter. If a field's read-only bit is on, the read-only bit of the value of the field is also on. The read-only bit of a field is part of the read-only aspect of the mapping value's shape.

A mapping is iterable: the iteration sequence consists of the members of the mapping and the iteration completion value is always nil. The order of the iteration sequence is implementation-dependent, but implementations are encouraged to preserve and use the order in which the fields were added.

The type of mapping values can be described by two kinds of type descriptors.

mapping-type-descriptor :=
   map-type-descriptor | record-type-descriptor

The inherent type of a mapping value must be a mapping-type-descriptor. The inherent type of a mapping value determines a type T_f for the value of the field with name f. The runtime system will enforce a constraint that a value written to field f will belong to type T_f. Note that the constraint is not merely that the value looks like T_f.

Both kinds of type descriptor are covariant in the types of their members.

map-type-descriptor := map type-parameter

record-type-descriptor :=
   inclusive-record-type-descriptor | exclusive-record-type-descriptor
inclusive-record-type-descriptor :=
   record { field-descriptor* }
exclusive-record-type-descriptor :=
   record {| field-descriptor* [record-rest-descriptor] |}
field-descriptor :=
   individual-field-descriptor | record-type-inclusion
individual-field-descriptor :=
   metadata [readonly] type-descriptor field-name [? | default-value] ;
field-name := identifier
default-value := = expression
record-type-inclusion := * type-reference ;
record-rest-descriptor := type-descriptor ... ;

5.4.3 Tables

A table is a structural value, whose members are mapping values. A table provides access to its members using a key that comes from the read-only fields of the member. It keeps its members in order, but does not provide random access to a member using its position in this order.

Every table value has, in addition to its members, a key sequence, which is used to provide keyed access to its members. The key sequence is an ordered sequence of field names. The key sequence of a table is fixed when a table is constructed and cannot be changed thereafter. For each field name in the key sequence, every member of the table must have a read-only field with that name and the value of the field must be acyclic plain data. A table's key sequence determines a key value for each member of the table: if the key sequence consists of a single field name f, then the key value of a member is that value of field f of that member. If the key sequence consists of multiple field names f₁,f₂,...,f_n where n is ≥ 2, then the key value for a member r is a tuple with members v₁,v₂,...,v_n where v_i is the value of field f_i of r. A table constrains its membership so that a key value uniquely identifies a member within the table. More precisely, for every two rows r_i and r_j in a table with i not equal to j, the key value for r_i must not be equal to the key value for r_j. Key values are compared for equality using the DeepEquals abstract operation. This constraint is enforced by the table both when the table is constructed and when the table is mutated. As a special case, a table's key sequence may be empty; this represents a keyless table, whose members are not uniquely identified by a key.

The shape of a table value is a triple consisting of

• an ordered list containing for each table member, the shape of that member
• the table's key sequence, and
• a set containing for each table member, the shape of the key value of that member (derived from the table members and the key sequence)

table-type-descriptor := table row-type-parameter [key-constraint]
row-type-parameter := type-parameter
key-constraint := key-specifier | key-type-constraint
key-specifier := key ( [ field-name (, field-name)* ] )
key-type-constraint := key type-parameter

The row-type-parameter specifies the shape of the table's members. A table type table<R> KC contains a table shape if and only if every table member shape belongs to R and the table shape satisfies the key constraint KC. The type specified by a row-type-parameter must be a subtype of map<any|error>

In a table-type-descriptor table<R> key(ks), R and ks must be consistent in the following sense: for each field name f_i in ks, f_i must be a required, read-only field of R with a type that is a subtype of anydata. A table shape satisfies a key-constraint key(ks) if and only if its key sequence is ks. A table shape satisfies a key-constraint key<K> if and and only if its set of key value shapes are a subset of K. The shape of a keyless table satisfies the key-constraint key<never>.

As with other structured values, a table value has an inherent type. The inherent type of a table value must be a table-type-descriptor with a key-constraint that is a key-specifier.

A table is iterable: the iteration sequence consists of the members of the table in order and the iteration completion value is always nil.

5.5.1 Errors

error-type-descriptor := error [error-type-param]
error-type-param := < (detail-type-descriptor | inferred-type-descriptor) >
detail-type-descriptor := type-descriptor
inferred-type-descriptor := *

An error value provides information about an error that has occurred. Error values belong to a separate basic type; this makes it possible for language constructs to handle errors differently from other values.

The error type is inherently immutable. An error value contains the following information:

• a message, which is a string containing a human-readable message describing the error
• a cause, which is either nil or another error value that was the cause of this error
• a detail, which is an immutable mapping providing additional information about the error
• a stack trace, which is an immutable snapshot of the state of the execution stack

The detail mapping must be a subtype of map<Cloneable>.

The shapes of the message, cause and detail record are part of the shape of the error; the stack trace is not part of the shape. A type descriptor error<T> contains an error shape if T contains the shape of its detail. The type error contains a shape if its basic type is error.

A type of error<*> means that the type is a subtype of error, where the precise subtype is to be inferred from the context. This is allowed only within type descriptors occurring in a context that is specified to be inferable.

An error-type-descriptor is always definite and induces an empty set of type-ids. An intersection type can be used to describe an error type that induces a non-empty set of type-ids.

5.5.2 Functions

function-type-descriptor := function function-signature
function-signature := ( param-list ) return-type-descriptor

A function is a part of a program that can be explicitly executed. In Ballerina, a function is also a value, implying that it can be stored in variables, and passed to or returned from functions. When a function is executed, it is passed an argument list as input and returns a value as output.

param-list :=
   required-params [, defaultable-params] [, rest-param]
   | defaultable-params [, rest-param]
   | [rest-param]
required-params := required-param (, required-param)*
required-param := [annots] type-descriptor [param-name]
defaultable-params := defaultable-param (, defaultable-param)*
defaultable-param := [annots] type-descriptor [param-name] default-value
rest-param := [annots] type-descriptor ... [param-name]
param-name := identifier

A param-name can be omitted from a required-param, defaultable-param or rest-param only when occuring in the function-signature of a function-type-descriptor.

The argument list passed to a function consists of zero or more arguments in order; each argument is a value, but the argument list itself is not passed as a value. The argument list must conform to the param-list as described in this section. Usually, the compiler's type checking will ensure that this is the case; if not, the function will panic.

It is convenient to consider the complete param-list as having a type. This type is described by a tuple-type-descriptor that has a member-type-descriptor for each required-param and defaultable-param, and has a tuple-rest-descriptor if and only if there is a rest-param. The i-th member-type-descriptor of the tuple type descriptor is the same as the type-descriptor of the i-th member of the param-list; the type-descriptor of the tuple-rest-descriptor, if present, is the same as the type-descriptor of the rest-param.

An argument list consisting of values v₁,..., v_n conforms to a param-list that has type P, if and only if for each i with 1 ≤ i ≤ n, v_i belongs to T_i, where T_i is defined to be the type that contains a shape s if and only if P contains a list shape whose i-th member is s.

When an argument list is passed to a function, the non-rest parameters are initialized from the arguments in the argument list in order. The conformance of the argument list to the param-list declared for the function ensures that each parameter will be initialized to a value that belongs to the declared type of the parameter. If there is a rest-param, then that is a initialized to a newly created lists containing the remaining arguments in the argument-list; the inherent type of this list will be T[] where T is the type of the rest-param. The conformance of the argument list ensures that the members of this list will belong to type T.

A defaultable-param is a parameter for which a default value is specified. The expression specifying the default value may refer to previous parameters by name. For each defaultable parameter, the function's type descriptor includes a closure that computes the default value for the parameter using the values of previous parameters. The caller of the function uses the closures in the function's type descriptor to compute default values for any defaultable arguments that were not specified explicitly. These default values are included in the argument list passed to the function. Whether a parameter is defaultable, and what its default is, do not affect the shape of the function and thus do not affect typing. The closures computing the defaultable parameters are created when the type descriptor is resolved; the default value is computed by calling the closure each time the function is called and the corresponding parameter is not specified. Whether a parameter is defaultable is used at compile time, but the closure that computes the default value is only used at runtime.

The name of each parameter is included in the function's type descriptor. A caller of the function may specify the name of the parameter that an argument is supplying. In this case, the caller uses the parameter name at compile time in conjunction with the type descriptor to create the argument list. The parameter names do not affect the shape of the function and thus do not affect typing.

The process by which the function caller creates an argument list, which may make use of arguments specified both by position and by name, is described in more detail in the section on function calls.

return-type-descriptor := [ returns [annots] type-descriptor ]

When the execution of a function returns to its caller, it returns exactly one value. A function that would in other programming languages not return a value is represented in Ballerina by a function returning (). Note that the function definition does not have to explicitly return (); a return statement or falling off the end of the function body will implicitly return ().

The value returned by a function will belong to the type specified in the return-type-descriptor. An empty return-type-descriptor is equivalent to returns ().

A return-type-descriptor may be depend on the param-list in the following way. A type-reference occurring in a return-type-descriptor can refer to a parameter name if the type of the parameter is a subtype of typedesc. If p is such a parameter, then a reference to p in the return-type-descriptor denotes the type that is the value of p. The return-type-descriptor thus denotes a distinct set of shapes for each invocation of the function. A function-signature with a return-type-descriptor that uses a type-reference to refer to a parameter name in this way is said to be dependently-typed. Functions with dependently-types signatures can be declared and used within Ballerina, but Ballerina does not yet provide a mechanism to define such functions.

Function types are covariant in their return types and contravariant in the type of their parameter lists. More precisely, a function type with return type R and parameter list type P is a subtype of a function type with return type R' and parameter list type P' if and only if R is a subtype of R' and P' is a subtype of P. A function value f belongs to a function type T if the declared type of f is a subtype of T.

5.5.3 Objects

An object value contains fields and methods. A field of an object stores a value. A method of an object is a function that can be invoked on the object using a method-call-expr; when a method is invoked on an object, the function can access the object using the self variable. An object's methods are associated with the object when the object is constructed and cannot be changed thereafter. Fields and methods have names that uniquely identify them within their object; fields and methods share a single symbol space; it is not possible for an object to have a field and a method with the same name.

The type of object values can be described using an object-type-descriptor, as specified in this section. It can also be described using a class. A class both describes an object type and provides a way to construct an object belonging to the type; in particular, it provides the method definitions that are associated with the object when it is constructed. A class is defined using a module-level class definition.

The object basic type is selectively immutable. An object value has a read-only bit, which is fixed when the object is constructed. An object-type-descriptor does not describe whether the object's read-only bit is set: whether a value belongs to the type described by an object-type-descriptor is not affected by the object's read-only bit. Whether an object is read-only can be described separately using a readonly type descriptor, which can be combined with an object-type-descriptor using the type intersection operator.

object-type-descriptor :=
   [client] object {
      object-member-descriptor*
   }
object-member-descriptor :=
   object-field-descriptor
   | method-decl
   | object-type-inclusion

If the object-type-descriptor specifies client, then the object type is a client object type. A client object type may have remote methods; other objects types must not.

object-field-descriptor :=
   metadata [public] type-descriptor field-name ;

method-decl :=
   metadata
   [public][remote-qual]
   function method-name function-signature ;
method-name := identifier

remote-qual := remote

object-type-inclusion := * type-reference ;

5.5.4 Futures

future-type-descriptor := future [type-parameter]

A future value refers to a named worker, which will return a value. A future value belongs to a type future<T> if the return type of the named worker is a subtype of T.

A value belongs to a type future (without the type-parameter) if it has basic type future.

5.5.5 [Preview] Services

service-type-descriptor := service

A service is like an object, but differs in the following respects:

• a method of a service can be declared as a resource method, but cannot be declared as a remote method
• a service is stateless and does not have fields

A resource method is a special kind of method, with associated configuration data, that is invoked in response to network messages received by a Listener. A service can be thought of as the dual of a client object.

All service values belong to the type service.

It is planned that a future version of Ballerina will provide a mechanism that allows more precise typing of services. In the meantime, implementations can use annotations on type definitions to support this.

5.5.6 Type descriptors

typedesc-type-descriptor := typedesc [type-parameter]

A type descriptor value is an immutable value representing a resolved type descriptor. The type typedesc contains all values with basic type typedesc. A typedesc value t belongs to a type typedesc<T> if and only if the type described by t is a subtype of T. The typedesc type is thus covariant with its type parameter.

Referencing an identifier defined by a type definition in an expression context will result in a type descriptor value.

5.5.7 Handles

handle-type-descriptor := handle

A handle value is a reference to storage managed externally to a Ballerina program. Handle values are useful only in conjunction with functions that have external function bodies; in particular, a new handle value can be created only by a function with an external function body. Handle values are inherently immutable.

A value belongs to a type handle if it has a basic type of handle.

5.5.8 [Preview] Streams

stream-type-descriptor := stream [stream-type-parameters]
stream-type-parameters := < type-descriptor [, type-descriptor]>

A stream is an object-like value that can generate a sequence of values. There is also a value associated with the completion of the generation of the sequence, which is either nil, indicating the generation of the sequence completed successfully, or an error. A stream belongs to type stream<T,C> if the values in the generated sequence all belong to T and if the completion value belongs to C. The type stream<T> is equivalent to stream<T,()>. A value belongs to a type stream (without the type-parameter) if it has basic type stream. A type stream<T,C> where C does not include nil describes an unbounded stream.

A stream supports two primitive operations: a next operation and a close operation. The next operation has the same semantics as the next method on the Iterator object type. The close operation informs the stream that there will be no more next operations and thus allows the stream to release resources used by the stream; the close operation on a stream<T,C> has a result of type C?, where nil means that the close operation was successful.

The type descriptor stream<T,C> works like a class, in that it can be used with new to construct stream values that belong to the type. The normal implementation of a stream<T,C> is a wrapper around an object belonging to object type StreamImplementor<T,C>. The next and close operations on the stream delegate to the next and close methods on the StreamImplementor.

The stream module of the lang library provides additional operations on stream that can be implemented in terms of the primitive next and close operations.

A stream is iterable. A stream of type stream<T,C> has value type T and completion type C. Calling the next method on the iterator created for an iteration has the same effect as performing the next operation on the stream. The stream does not keep a copy of the sequence of values returned by the next operation. Any subsequent iteration operation on the same stream will not generate further values, so the iteration sequence for iterations other than the first will be the empty sequence.

Note that in this version of Ballerina the stream type is not a class because Ballerina does not yet support parameterized classes.

5.6.1 Type reference

type-reference := identifier | qualified-identifier

A type descriptor can use a type-reference to refer to a type definition in the same module or another module.

A type-reference referring to a type descriptor T is definite if and only if T. If it is, the type-ids induced by are the same as those induced by T and a type-id is primary in t if and only if it is primary in T. It is an error if the induced set of type-ids includes a non-public type-id from another module.

5.6.2 Singleton types

singleton-type-descriptor := simple-const-expr

A singleton type is a type containing a single shape. A singleton type is described using an compile-time constant expression for a single value: the type contains the shape of that value. Note that it is possible for the variable-reference within the simple-const-expr to reference a structured value; in this case, the value will have its read-only bit set; a value without its read-only bit set will thus not belong to any singleton type.

5.6.3 Any type

any-type-descriptor := any

The type descriptor any describes the type consisting of all values other than errors. A value belongs to the any type if and only if its basic type is not error. Thus all values belong to the type any|error. Note that a structure with members that are errors belongs to the any type.

The any-type-descriptor is not definite.

5.6.4 Never type

never-type-descriptor := never

The type descriptor never describes the type that does not contain any shapes. No value ever belongs to the never.

This can be useful to describe for the return type of a function, if the function never returns. It can also be useful as a type parameter. For example, xml<never> describes the an xml type that has no constituents, i.e. the empty xml value.

Note that for anytype T, the type T|never is the same as T.

5.6.5 Readonly type

readonly-type-descriptor := readonly

A shape belongs to the type readonly if its read-only bit is on.

A value belonging to an inherently immutable basic type will always have its read-only bit on. These basic types are:

• all simple types
  • nil
  • boolean
  • int
  • float
  • decimal
• string
• error
• function
• service
• typedesc
• handle

A value belonging to a selectively immutable basic type may have its read-only bit on. These basic types are:

• xml
• list
• mapping
• table
• object

5.6.6 Distinct types

distinct-type-descriptor := distinct type-descriptor

Each occurrence of a distinct-type-descriptor describes a type that is distinct from any other occurrence of a distinct-type-descriptor. Only object and error values can belong to a type described by a distinct-type-descriptor.

The type denoted by a distinct-type-descriptor D, where D is distinct T, and d is the type-id of this occurrence of D, contains a shape s of an object or error value if and only if both T contains s and the set of type-ids of s contains d. The set of type-ids induced by D consists of d as the primary type-id and the type-ids induced by T as the secondary type-ids. The type T must be definite and must be a subtype of object or a subtype of error. The type D is always definite. Note that D is always a proper subtype of T.

5.6.7 Union types

union-type-descriptor := type-descriptor | type-descriptor

The set of shapes denoted by an union type T1|T2 is the union of the set of shapes denoted by T1 and the set of shapes denoted by T2. Thus, the type T1|T2 contains a shape if and only if either the type denoted by T1 contains the shape or the type denoted by T2 contains the shape. A type descriptor T1|T2 is not a class and cannot be used with new, even if one or both of T1 and T2 are classes.

A union type T1|T2 is definite if and only if both T1 and T2 are definite and the set of type-ids induced by T1 and T2 are the same. If it is definite, then it induces the same set of type-ids as T1 and T2, and a type-id is primary if it is primary in either T1 or T2.

5.6.8 Intersection types

intersection-type-descriptor := type-descriptor & type-descriptor

The set of shapes denoted by an intersection type is the intersection of the set of shapes denoted by T1 and the set of shapes denoted by T2. Thus, the type T1&T2 contains a shape if and only if the types denoted by T1 and T2 both contain the shape. It is a error to have an intersection type that denotes an empty set of shapes. In an intersection type T1&T2, it is an error if T1 and T2 are both function types unless there is a single function-type-descriptor that denotes a type that is a subtype of both T1 and T2. A type descriptor T1&T2 is not a class and cannot be used with new, even if one or both of T1 and T2 are classes.

An intersection type T1&T2 is definite if and only if both T1 and T2 are definite. If it is definite, then it induces the union of the set of type-ids induced by T1 and T2, and a type-id is primary if it is primary in either T1 or T2.

Intersection types are particularly useful in conjunction with readonly. A set of readonly shapes can be described by readonly&T, where T describes the primary aspect of the shape.

5.6.9 Optional types

optional-type-descriptor := type-descriptor ?

A type T? means the union of T and (). It is completely equivalent to T|().

5.6.10 Anydata type

anydata-type-descriptor := anydata

The type descriptor anydata describes the type of plain data. The type anydata contains a shape if and only if it is the shape of a value that is plain data. The anydata type can thus be defined as:

  () | boolean | int | float | decimal
    | string | xml
    | anydata[] | map<anydata> | table<map<anydata>>

5.6.11 JSON types

json-type-descriptor := json

The json type is designed for processing data expression in JSON format. It is a built-in name for a union defined as follows:

type json = () | boolean | int | float | decimal | string | json[] | map<json>;

In addition, the json type is defined to have lax static typing.

5.6.12 Byte type

byte-type-descriptor := byte

The byte type is a predefined name for a union of the int values in the range 0 to 255 inclusive. It is equivalent to the built-in subtype int:Unsigned8.

5.7.1 Iterator

A value of iterable type with iteration value type T and iteration completion type C provides a way of creating an iterator object that belongs to the object type

    object {
       public next() returns record {| T value; |}|C;
    }

In this specification, we refer to this type as Iterator<T,C>.

Conceptually an iterator is at a position between members of the iteration sequence. Possible positions are at the beginning (immediately before the first member if any), between members and at the end (immediately after the last member if any). A newly created iterator is at the beginning position. For an empty sequence, there is only one possible position which is both at the beginning and at the end.

The next() method behaves as follows:

• if the iteration has encountered an error, return an error value
• otherwise, if the iterator has completed successfully by reaching the end position without an error, return nil
• otherwise
  • move the iterator to next position, and
  • return a record { value: v } where v is the member of the sequence between the previous position and the new position

Mutation of a structured value during iteration is handled as follows. A call to next() must panic if there has been any mutation to the structured value since the iterator was created other than the following:

• removing a member of the structured value that a preceding call to the iterator has already returned;
• changing the member associated with an existing key.

In the latter case, next() must return the value associated with the key at the point when next() is called.

Note that it is not possible for the next() method simply to return the values in the iteration sequence, since there would be no way to distinguish a nil or error value that is part of the iteration sequence from a nil or error value that represents the result of the iteration.

5.7.2 Iterable

An object belongs to the object type Iterable<T,C> if it has a method named iterator with no arguments and a return type that is subtype of Iterator<T,C> and it belongs to the distinct type Iterable defined in lang.object. An object that belongs to Iterable<T,C> is iterable: the object returned by the iterator method determines the iteration sequence and iteration completion value.

5.7.3 StreamImplementor

An object belongs to the object type StreamImplementor<T,C> if it belongs to Iterator<T,C> and also optionally has a method close() with return value C?. This is equivalent to belonging to the following type.

    object {
       public next() returns record {| T value; |}|C;
    }
    | object {
       public next() returns record {| T value; |}|C;
       public close() returns C?;
    }

The close method says that there will be no more calls to the next method. Any call to a next method after the close method has been called must result in a panic. A missing close method behaves like a close method that puts the object into a closed state, in which calls to next will result in a panic, and then immediately returns ().

5.7.4 Listener

The Listener type is defined in lang.object as follows.

distinct object {
   public function attach(service s, string? name = ()) returns error?;
   public function detach(service s) returns error?;
   public function start() returns error?;
   public function gracefulStop() returns error?;
   public function immediateStop() returns error?;
}

Note that if an implementation does precise service typing using annotations on type definitions, it will need to treat Listener as being parameterized in the precise service type that is used to the first argument to attach.

5.7.5 RawTemplate

The RawTemplate type describes the type of object constructed by a raw template expression. The type is defined in lang.object as follows.

distinct object {
    public (readonly & string[]) strings;
    public (any|error)[] insertions;
}

5.8.1 FillMember

The FillMember(s, k) operation is defined for a structured value s and an out-of-line key value k. It can be performed when s does not have a member with key k; if it succeeds, it will result in a member with key k being added to s. It will succeed if the inherent type of s allows the addition of a member with key k and there is a way to construct a filler value for the type descriptor that the inherent type of s requires for member k. The following table specifies when and how a filler value can be constructed for a type descriptor.

5.8.2 Cloning

There are two cloning operations. Both of these operate on values belonging to the Cloneable type defined as follows:

public type Cloneable readonly|xml|Cloneable[]|map<Cloneable>|table<map<Cloneable>>;

This type is defined in the lang.value module of the lang library. In this document, the type will be referred to as value:Cloneable.

5.8.3 DeepEquals

DeepEquals(v1, v2) is defined for any values v1, v2 that belong to type anydata. It returns true or false depending of whether the primary aspect of the shape v1 and of v2 are the same. In other words, DeepEquals returns true if and only if the values are the same ignoring whether read-only bits are on or off. DeepEquals(v1, v2) must terminate for any values v1 and v2 of type anydata, even if v1 or v2 have cycles. DeepEquals(v1, v2) returns true if v1 and v2 have the same shape, even if the graphs of references of v1 and v2 have different structures. If two values v1 and v2 have different basic types, then DeepEquals(v1, v2) will be false.

The possibility of cycles means that DeepEquals cannot be implemented simply by calling DeepEquals recursively on members. Rather DeepEquals must maintain a mapping that records for each pair of references whether it is already in process of comparing those references. When a DeepEquals operation starts, this map is empty. Whenever it starts to compare two references, it should see whether it has already recorded that pair (in either order), and, if it has, proceed on the assumption that they compare equal.

DeepEquals(Clone(x), x) is guaranteed to be true for any value of type anydata.

5.8.4 NumericConvert

NumericConvert(t, v) is defined if t is the typedesc for float, decimal or int, and v is a numeric value. It converts v to a value in t, or returns an error, according to the following table.

5.8.5 ToString

ToString(v,style) converts a value to a string in one of three styles. The conversion can be performed in one of three styles, specified by the style parameter, which are as follows.

• expression style: produces a string that looks like a Ballerina expression; there are two cases
  • when v belongs to anydata and does not have cycles, it will produce a string that is a valid Ballerina expression, such that evaluating that string will result in a value v' for which DeepEquals(v, v') is true
  • otherwise, it will produce a string that is either not a valid Ballerina expression or is a valid Ballerina expression that evaluates to a value that does not belong type type anydata
• informal style: similar to expression style, but does not preserve all the distinctions that expression style does, and avoids syntax that requires a knowledge of Ballerina
• direct style: this does a direct conversion of the value to a string rather than producing a string that describes the value
  • if v is a string, then the result of ToString(v,direct) is v
  • if v is XML, then the result of ToString(v,direct) is v in XML syntax
  • direct style falls back to informal style for basic types where there is no other natural more direct conversion

The following table summarizes the result of ToString(v,style) for each basic type.

5.8.6 Ordering

There are three abstract operations related to ordering: Compare(x, y), CompareA(x, y), CompareD(x, y). CompareA(x, y) and CompareD(x, y), which are used to define sorting, return one of the values LT, EQ, GT representing the cases where x is less than, equal to or greater than y. Compare(x, y), which is used to define the relational operators, can also return the value UN to represent the case where x is unordered with respect to y; this is used to deal with NaN.

The three operations are related as follows: Compare(x, y) is the same as CompareA(x, y) and CompareD(x, y) unless Compare(x, y) is UN.

A type is ordered if all the values that belong to the type can be compared to each other using the above three abstract operations. Thus each of the abstract operations are defined when there is an ordered type to which both arguments belong.

If C is any of the three abstract operations, and there is an ordered type to which both x and y belong, then:

• C(x, y) is LT if and only if C(y, x) is GT
• C(x, y) is EQ if and only if C(y, x) is EQ
• C(x, y) is UN if and only if C(y, x) is UN

The most straightforward ordered types are basic types where all the values of the type can be put into an order. These types are boolean, int, string. For each of these three types, for any pair of values x, y belonging to the type

• Compare(x, y) is EQ if x and y are the same value
• Compare(x, y) is LT in the following cases:
  • for int, if x is mathematically less than y
  • for boolean, if x is false and y is true
  • for string, if x is lexicographically less than y in Unicode code point order, more precisely, if
    • x is an proper initial substring of y, or
    • for the first index at which x and y differ, the code point at that index in x is less than the code point at that index in y
• CompareA(x,y), and CompareD(x,y) have the same value as Compare(x, y)

The basic type decimal is ordered. The abstract operations are defined the same as for int, except that Compare(x, y) is EQ if x and y have the same shape. In other words, the compare operations ignore precision.

The basic type float is also ordered. Compare(x,y) is as defined by IEEE 754-2008 clause 5.11. In particular:

• the Compare operation does not distinguish +0 from -0 i.e. Compare(-0.0,+0.0) is EQ
• Compare(x, y) is UN if x or y or both is NaN

When x and y belong to type float, CompareA(x, y) and CompareD(x, y) differ from Compare(x, y) as follows:

• CompareA(NaN,NaN) and CompareD(NaN, NaN) are EQ
• CompareA(x, NaN) is LT if x is not NaN
• CompareD(NaN, x) is LT if x is not NaN

If type T is ordered, then type T? Is also ordered. Comparison operations involving nil are defined as follows:

• Compare((),()), CompareA((),()) and CompareD((),()) are all EQ
• Compare(x,()) is UN if x is not ()
• CompareA(x,()) is LT if x is not ()
• CompareA((), x) is LT if x is not ()

The CompareA operation is used for sorting in ascending order; the CompareD operation is used in reverse for sorting in descending order. The net effect of the above rules is thus that both () and NaN will appear at the end of a sorted list, with NaN before (), in both ascending and descending order.

The following rules determine when a subtype of list is ordered:

• [T...] is ordered, if T is ordered;
• [] is ordered;
• [T, rest] is ordered if T is ordered and [rest] is ordered.

Each of the three abstract operations C are extended to apply to lists as follows:

• C([], []) is EQ;
• C([], [y1,...]) is LT;
• C([x1,x2,...],[y1, y2...]) is r unless r is EQ and otherwise C([x2,...],[y2,...]), where r is C(x1, y1).

5.9.1 Binding patterns

Binding patterns are used to support destructuring, which allows different parts of a single structured value each to be assigned to separate variables at the same time.

binding-pattern :=
   capture-binding-pattern
   | wildcard-binding-pattern
   | list-binding-pattern
   | mapping-binding-pattern
   | error-binding-pattern
capture-binding-pattern := variable-name
variable-name := identifier
wildcard-binding-pattern := _
list-binding-pattern := [ list-member-binding-patterns ]
list-member-binding-patterns :=
   binding-pattern (, binding-pattern)* [, rest-binding-pattern]
   | [ rest-binding-pattern ]
mapping-binding-pattern := { field-binding-patterns }
field-binding-patterns :=
   field-binding-pattern (, field-binding-pattern)* [, rest-binding-pattern]
   | [ rest-binding-pattern ] 
field-binding-pattern :=
   field-name : binding-pattern
   | variable-name
rest-binding-pattern := ... variable-name
error-binding-pattern := error [error-type-reference] ( error-arg-list-binding-pattern )
error-type-reference := type-reference
error-arg-list-binding-pattern :=
   error-message-binding-pattern [, error-cause-binding-pattern] [, error-field-binding-patterns]
   | [error-field-binding-patterns]
error-message-binding-pattern := simple-binding-pattern 
error-cause-binding-pattern := simple-binding-pattern | error-binding-pattern
simple-binding-pattern := capture-binding-pattern | wildcard-binding-pattern
error-field-binding-patterns :=
   named-arg-binding-pattern (, named-arg-binding-pattern)* [, rest-binding-pattern]
   | rest-binding-pattern
named-arg-binding-pattern := arg-name = binding-pattern

A binding pattern may succeed or fail in matching a value. A successful match causes values to be assigned to all the variables occurring the binding-pattern.

A binding pattern matches a value in any of the following cases.

• a capture-binding-pattern always matches a value and causes the matched value to be assigned to named variable;
• a wildcard-binding-pattern matches a value if the value belongs to type any, in other words if the basic type of the value is not error; it does not cause any assignments to be made;
• a list-binding-pattern with m binding patterns matches a list with n members if m is less than or equal to n, and the i-th binding pattern matches the i-th member of the list for each i in 1 to m, and either m is equal to n or the list-binding-pattern includes a rest-binding-pattern; if there is a rest-binding-pattern ...v, then a successful match causes a new list value consisting of all members of the matched list except for the the first m values to be assigned to v;
• a mapping-binding-pattern { f₁: p₁, f₂: p₂, ..., f_n: p_n, r } matches a mapping value m that includes fields f₁, f₂, ... , f_n if p_i matches the value of field f_i for each i in 1 to n; if r is ...v then a successful match causes a new mapping value consisting of all the other fields to be assigned to v; a field-binding-pattern consisting of just a variable-name x is equivalent to a field-binding-pattern x: x;
• an error-binding-pattern error ET(p_m, p_c, f₁ = p₁, f₂ = p₂, ..., f_n = p_n, r) matches an error value e if
  • e has a message that matches p_m,
  • if p_c is present, e has a cause that matches p_c,
  • e has a detail record that has fields f₁, f₂, ... , f_n such that p_i matches the value of field f_i for each i in 1 to n,
  • if ET is present, the shape of e is in ET,
  • if r is ...v, then a successful match causes a new mapping value consisting of all fields of the detail record other than f₁, f₂, ... , f_n to be assigned to v;

All the variables in a binding-pattern must be distinct e.g. [x, x] is not allowed.

Given a type descriptor for every variable in a binding-pattern, there is a type descriptor for the binding-pattern that will contain a value just in case that the binding pattern successfully matches the value causing each variable to be assigned a value belonging to the type descriptor for that variable.

• for a capture-binding-pattern, the type descriptor is the type descriptor for that variable;
• for a wildcard-binding-pattern, the type descriptor is any
• for a list-binding-pattern, the type descriptor is a tuple type descriptor;
• for a mapping-binding-pattern, the type descriptor is a record type descriptor;
• for an error-binding-pattern, the type descriptor is an error type descriptor.

5.9.2 Typed binding patterns

typed-binding-pattern := inferable-type-descriptor binding-pattern
inferable-type-descriptor := type-descriptor | var

A typed-binding-pattern combines a type-descriptor and a binding-pattern, and is used to create the variables occurring in the binding-pattern. If var is used instead of a type-descriptor, it means the type is inferred. How the type is inferred depends on the context of the typed-binding-pattern. An inferable-type-descriptor is an inferable context for a type descriptor, which means that * can be used with the type descriptor to infer certain parts of it.

The simplest and most common form of a typed-binding-pattern is for the binding pattern to consist of just a variable name. In this case, the variable is constrained to contain only values matching the type descriptor.

When the binding pattern is more complicated, the binding pattern must be consistent with the type-descriptor, so that the type-descriptor unambiguously determines a type for each variable occurring in the binding pattern. A binding pattern occurring in a typed-binding-pattern must also be irrefutable with respect to the type of value against which it is to be matched. In other words, the compiler will ensure that matching such a binding pattern against a value will never fail at runtime.

5.9.3 Variable and identifier scoping

For every variable, there is place in the program that declares it. Variables are lexically scoped: every variable declaration has a scope which determines the region of the program within which the variable can be referenced.

There are two kinds of scope: module-scope and block-scope. A variable with module-scope can be referenced anywhere within a module; if declared public, it can also be referenced from outside the module.

Identifiers with module-scope are used to identify not only variables but other module-level entities such as functions. Within module-scope, identifiers are separated into three symbol spaces:

• the main symbol space includes identifiers for variables, constants, types, functions and other identifiers that do not belong to any of the other two symbol spaces;
• the prefix symbol space contains prefixes declared by import declarations and XML namespace declaration statements;
• the annotation tag symbol space contains annotation tags declared by annotation declarations.

The prefix symbol space is special in that it is associated with a source part rather than a module.

Block-scope is divided into symbol spaces in the same way as module-scope, except that block-scope does not have a symbol space for annotation tags, since annotation tags cannot be declared with block-scope.

An identifier declared with block-scope can be referenced only within a particular block (always delimited with curly braces). Block-scope variables are created by a variety of different constructs, many of which use a typed-binding-pattern. Parameters are treated as read-only variables with block-scope.

It is not an error if an identifier is declared with block-scope and there is already a declaration of the same identifier in the same symbol space with module-scope. In this case, the block-scope declaration will hide the module-scope declaration for the region where the block-scope declaration is in scope. However, it is a compile error if an identifier is declared with block-scope and its scope overlaps with the scope of another declaration of the same identifier in the same symbol space also with block-scope.

6.2.1 Lax static typing

In some situations it is convenient for static typing to be less strict than normal. One such situation is when processing data in Ballerina using a static type that is less precise than the type that the data is in fact expected to belong to. For example, when the Ballerina json type is used for the processing of data in JSON format, the Ballerina static type will not capture the constraints of the particular JSON format that is been processed.

Ballerina supports this situation through the concept of lax static typing, which has two parts: the first part is that a type descriptor can be classified as lax; the second part is that particular kinds of expression can have less strict static typing rules when the static type of a subexpression is described by a lax type descriptor. With these less strict rules, a potential type error that would have been a compile-time error according to the normal strict static typing rules would instead be allowed at compile-time and result in an error value at runtime; the effect is thus that some static type-checking is instead done dynamically.

In this version of Ballerina, only the first step has been taken towards supporting this concept. There is a fixed set of type descriptors that are classified as lax: specifically json is lax, and map<T> is lax if T is lax. The only kinds of expression for which lax typing rules are specified are field-access-expr and optional-field-access-expr.

6.2.2 Contextually expected type

For a context in which an expression occurs, there may be a type descriptor that describes the static type that the expression is expected to have. This is called the contextually expected type. For example, if a variable is declared by a type descriptor TD, then TD will be the contextually expected type for the expression initializing the variable. A type descriptor must be resolved before it can be used to provide a contextually expected type.

Many kinds of expression that construct values use the contextually expected type to determine the type of value constructed, rather than requiring the type to be specified explicitly. For each such kind of expression, there is a set of basic types (most often consisting of a single basic type) that the value constructed by that kind of expression will always belong to. In this case, the contextually expected type is narrowed by intersecting it with this set of basic types; this narrowed type is called the applicable contextually expected type. The narrowing is performed on the type descriptor by first normalizing the type descriptor into a union, where each member of the union is not a union and describes shapes from a single basic type, and then eliminating any members of the union with the wrong basic type; if this leaves no members, then it is a compile-time error; if it leaves a single member of the union, then the the applicable contextually expected type is this single member, otherwise it is a union of the remaining members.

Note the language provides a way to say that the type of a variable is to be inferred from the static type of the expression used to initialize the variable. In this case, there is no contextually expected type for the evaluation of the expression. Not having a contextually expected type is different from having a contextually expected type that allows all values.

6.2.3 Precise and broad types

There is an additional complexity relating to inferring types. Expressions in fact have two static types, a precise type and a broad type. Usually, the precise type is used. However, in a few situations, using the precise type would be inconvenient, and so Ballerina uses the broad type. In particular, the broad type is used for inferring the type of an implicitly typed non-final variable. Similarly, the broad type is used when it is necessary to infer the member type of the inherent type of a structured value.

In most cases, the precise type and the broad type of an expression are the same. For a compound expression, the broad type of an expression is computed from the broad type of the sub-expressions in the same way as the precise type of the expression is computed from the precise type of sub-expressions. Therefore in most cases, there is no need to mention the distinction between precise and broad types.

The most important case where the precise type and the broad type are different is literals. The precise type is a singleton type containing just the shape of the value that the literal represents, whereas the broad type is the precise type widened to contain the entire basic type of which it is a subtype. For example, the precise type of the string literal "X" is the singleton type "X", but the broad type is string.

6.6.1 String template expression

string-template-expr := string BacktickString

A string-template-expr interpolates the results of evaluating expressions into a literal string. The static type of the expression in each interpolation must be a simple type and must not be nil. Within a BacktickString, every character that is not part of an interpolation is interpreted as a literal character. A string-template-expr is evaluated by evaluating the expression in each interpolation in the order in which they occur, and converting the result of the each evaluation to a string using the ToString abstract operation with the direct style. The result of evaluating the string-template-expr is a string comprising the literal characters and the results of evaluating and converting the interpolations, in the order in which they occur in the BacktickString.

A literal ` can be included in string template by using an interpolation ${"`"}.

6.6.2 XML template expression

xml-template-expr := xml BacktickString

An XML template expression constructs an xml value as follows:

1. The backtick string is parsed to produce a string of literal characters with interpolated expressions
2. The result of the previous step is parsed as XML content. More precisely, it is parsed using the production content in the W3C XML Recommendation. For the purposes of parsing as XML, each interpolated expression is interpreted as if it were an additional character allowed by the CharData and AttValue productions but no other. The result of this step is an XML Infoset consisting of an ordered list of information items such as could occur as the [children] property of an element information item, except that interpolated expressions may occur as Character Information Item or in the [normalized value] of an Attribute Information Item. Interpolated expressions are not allowed in the value of a namespace attribute.
3. This infoset is then converted to an xml value, as described in the XML type section, together with an ordered list of interpolated expressions, and for each interpolated expression a position within the XML value at which the value of the expression is to be inserted.
4. The static type of an expression occurring in an attribute value must be a simple type and must not be nil. The static type type of an expression occurring in content can either be xml or a non-nil simple type.
5. When the xml-template-expr is evaluated, the interpolated expressions are evaluated in the order in which they occur in the BacktickString, and converted to strings if necessary. A new copy is made of the xml value and the result of the expression evaluations are inserted into the corresponding position in the newly created xml value. This xml value is the result of the evaluation.

An xml-template-expr occurring within a const-expr will construct an xml value that has its read-only bit on.

6.6.3 Raw template expression

raw-template-expr := BacktickString

A raw-template-expr constructs an object belonging to the abstract RawTemplate object type.

A raw-template-expr is evaluated by

• constructing an array v whose members are the result of evaluating each interpolation's expression in the order in which they occur in the BacktickString;
• constructing an object with two fields
  • an insertions field with value v
  • a strings field consisting of a read-only array of strings containing the characters in BacktickString outside of interpolations, split at the interpolation points; the length of the this array is one more than the length of v.

The result of the raw-template-expr is the newly constructed object.

For each raw-template-expr there is a separate class, which is a subtype of the RawTemplate type. The objects constructed by a raw-template-expr belong to this class. The type of the insertions field is determined from the contextually expected type or the static type of the expressions in the BacktickString in the same way as with a list-constructor-expr. The strings and insertions fields will be read-only if required by the contextually expected type. The value of the strings field is constructed once by the class. The value of the insertions is constructed once for each evaluation of the raw-template-expr.

6.7.1 List constructor

list-constructor-expr := [ [ expr-list ] ]
expr-list := expression (, expression)*

A list-constructor-expr creates a new list value. The members of the list come from evaluating each expression in the expr-list in order.

If there is a contextually expected type, then the inherent type of the newly created list is derived from the applicable contextually expected type. If the applicable contextually expected type is a list type descriptor, then that used as the inherent type. If the applicable contextually expected type is a union type descriptor, then any members of the union that do not contain list shapes of length N will be ignored, where N is the number of expressions in the expr-list; it is a compile-time error if this does not leave a single list type descriptor, which is then used as the inherent type. The static type of the list-constructor-expr will be the same as the inherent type.

If there is no contextually expected type, then the inherent type will be a tuple-type-descriptor with a member-type-descriptor for each expression in the expr-list; the type of each member-type-descriptor will be the broad type of the corresponding expression in the expr-list.

If there is a contextually expected type, then the type that the inherent type requires for each list member provides the contextually expected type for the expression for the member; otherwise there is no contextually expected type for the expressions for members.

A member of a list can be filled in automatically if the FillMember abstract operation would succeed on it. The inherent type of a list establishes either a fixed length for the list or just a minimum length for the list, which may be zero. In either case, a list constructor may specify only the first k members, provided that for each i from k + 1 up to the fixed length of the list, the i-th member can be filled in automatically.

6.7.2 Mapping constructor

mapping-constructor-expr := { [field (, field)*] }
field := 
  specific-field
  | computed-name-field
  | spread-field
specific-field :=
   [readonly] (field-name | string-literal) : value-expr
   | [readonly] [variable-name]
value-expr := expression
computed-name-field := [ field-name-expr ] : value-expr
field-name-expr := expression
spread-field := ... expression

A mapping-constructor-expr creates a new mapping value.

A specific-field specifies a single field, where the field name is known at compile-time. A specific-field that consists of just a variable name x is equivalent to a field x: x.

The static type of the expression in a spread-field must allow only mapping values, i.e. must be a subtype of map<any|error>. All the fields of the mapping value that results from evaluating that expression are included in the mapping value being constructed. It is a compile-time error if the static type of the expression in a spread-field allows a field that duplicates a specific-field or that could also occur in another spread-field. Note that a spread-field with an inclusive record type of record { never x?; } cannot duplicate a specific field for x.

If there is a contextually expected type, then the inherent type of the newly created mapping is derived from the applicable contextually expected type. If the applicable contextually expected type is a mapping type descriptor, then that used as the inherent type. If the applicable contextually expected type is a union type descriptor, then any members of the union that are inconsistent with the field names specified in a specific-field in the mapping-constructor-expr will be ignored; it is a compile-time error if this does not leave a single mapping type descriptor, which is then used as the inherent type. The static type of the mapping-constructor-expr will be the same as the inherent type.

If there is no contextually expected type, then the inherent type will be an exclusive-record-type-descriptor with an individual-field-descriptor for each specific-field; the type of each field-descriptor will be the broad type of the value-expr in the field, unless the field is read-only in which case the type of the field-descriptor will be the precise type. The static type of the expression in every spread-field will also be added to the inherent type. If there are fields specified as a computed-name-field, then there will also be a record-rest-descriptor T..., where T is the union of the broad types of the value-expr in all such fields.

If a specific-field does not use a string-literal for the name of the field and the inherent type descriptor is a record type descriptor, then the record type descriptor must include an individual-type-descriptor for that field.

If the inherent type descriptor is a record type descriptor, a field will be added to the constructed value using the default value from the type descriptor for any field that is not specified explicitly in the mapping constructor and that has a default value.

If there is a contextually expected type, then the type that the inherent type requires for each field provides the contextually expected type for the value-expr in a field; otherwise there is no contextually expected type for the value-expr for fields. If there is a contextually expected type, the contextually expected type for the expression in a spread-field is map<T>, where the T is the smallest type such that the inherent type is a subtype of map<T>. The contextually expected type for a field-name-expr is string.

A computed-name-field specifies a single field, where the name of the field is specified by an expression enclosed in square brackets. A mapping-constructor-expr first constructs a mapping value without considering any computed-name-field. The effect of a computed-name-field is to modify the member of the mapping with the specified name after the mapping has been constructed. If the modification is incompatible with the inherent type, then the mapping-constructor-expr will panic. The modifications are performed in the order in which the computed-name-fields occur in the mapping-constructor-expr.

If the applicable contextually expected type is a subtype of readonly, then the mapping will be constructed with its read-only bit on. If the inherent type makes a specific field readonly, then that field will be constructed with its read-only bit on. A specific-field that starts with readonly will also be constructed with its read-only bit on.

6.7.3 Table constructor

table-constructor-expr := table [key-specifier] [ [row-list] ]
row-list := mapping-constructor-expr (, mapping-constructor-expr)*

A table-constructor-expr creates a new table value. The members of the table come from evaluating each mapping-constructor-expr in the row-list in order.

For example,

table key(email) [
   { email: "sanjiva@weerawarana.org", firstName: "Sanjiva", lastName: "Weerawarana" },
   { email: "jjc@jclark.com", firstName: "James", lastName: "Clark" }
]

The inherent type of the constructed table is a table type descriptor including a key-specifier table<T> key(ks), where T is the member type and ks is the key sequence. The inherent type is determined from the contextually expected type togther with the table-constructor-expr. The static type of the table-constructor-expr will be the same as this inherent type.

If there is a contextually expected type, then the member type of inherent type of the newly created table is derived from the applicable contextually expected type, which must be a table-type-descriptor. If there is no contextually expected type, then the member type of the inherent type is derived from the the static type of the expressions for the members: the member type will be the smallest record type that is a supertype of the static types of all the expressions in the row-list. It is an error if there is no contextually expected type and the row-list is empty.

The key sequence of the inherent type comes from the key-specifier of applicable contextually expected type or the key-specifier in the table-constructor-expr. If both of these are present, then they must be the same. If neither of them are present, then the key sequence is empty. The key sequence of the table value is the same as that of its inherent type. The key sequence and member type must meet the same consistency requirements as if they were specified together in a table type descriptor. For every field-name in the key sequence of the inherent type every mapping-constructor-expr in the row-list must include a specific-field that has a value-expr that is a const-expr. It is a compile-time error if two or more rows of the table have the same key value.

If there is a contextually expected type, then the type that the inherent type requires for each table member provides the contextually expected type for the expressions in the expr-list; otherwise there is no contextually expected type for these expressions.

6.8.1 Object constructor

object-constructor-expr :=
   [annots] [client] object [type-reference] {
      object-member*
   }
object-member := object-field | method-defn

The resulting of evaluating an object-constructor-expr is an object. The object-constructor-expr must specify client if any method-defn includes a remote-qual.

The annotations applying to the object-constructor-expr and its members are evaluated when the object-constructor-expr is evaluated. This means that every object resulting from the evaluation of an object-constructor-expr has its own type descriptor.

If the applicable contextually expected type is a subtype of readonly, then the object will be constructed with its read-only bit on.

If there is a type-reference, then the referenced type is included in the object's type in the same was as an object-type-inclusion, and the type-ids of the constructed object are type-ids of the referenced type. If there is no type-reference, then the applicable contextually expected type T must be definite, and the type-ids of the constructed object are the type-ids, if any, induced by T.

object-field :=
   metadata [object-visibility-qual] [final]
   type-descriptor field-name [= field-initializer] ;
field-initializer := expression

An object-field declares and initializes a field of the object.

If a field does not specify a field-initializer, then there must be an init method and the init method must initialize the field.

If final is present, then the field must be assigned to exactly once, either by its initializer or in the init method.

An object-constructor-expr will construct an object with its read-only bit set if

• every object-field is declared as final and has a type-descriptor that is a subtype of readonly; or
• it occurs within a const-expr or the applicable contextually expected type is a subtype of readonly; in this case, the contextually expected type for a field-initializer will be the intersection of readonly and the type specified in the type-descriptor of the object-field.

method-defn :=
   metadata [object-visibility-qual] [remote-qual]
   function method-name function-signature method-defn-body
method-defn-body := function-defn-body

A method-defn defines a method of an object.

Within a method-defn-body, the fields and methods of the object are not implicitly in-scope; instead the keyword self is bound to the object and can be used to access fields and methods of the object.

A method-defn with a method-name of init is used to initialize the object and is treated specially. The return type of the init method must be a subtype of the union of error and nil, and must contain nil; if init returns an error, it means that initialization of the object failed.

The parameter list of an init method within an object-constructor-expr must be empty.

At any point in the body of a init method, the compiler determines which fields are potentially uninitialized. A field is potentially uninitialized at some point if that field does not have an initializer and it is not definitely assigned at that point. It is a compile error if a init method:

• accesses a field at a point where it is potentially initialized, or
• at a point where there is any potentially uninitialized field
  • returns nil, or
  • uses the self variable other than to access or modify the value of a field.

The visibility of the init method cannot be private.

Any init method is not part of the shape of an object, and so does not affect when an object value belongs to a type. The init method can be called in a method-call-expr only when the expression preceding the . is self.

object-visibility-qual := public|private

A visibility qualifier of private can be used within an object-constructor-expr expression; this means that the visibility region consists of all method definitions in the object-constructor-expr.

6.8.2 New expression

new-expr := explicit-new-expr | implicit-new-expr
explicit-new-expr := new class-descriptor ( arg-list )
class-descriptor := identifier | qualified-identifier | stream-type-descriptor

A new-expr constructs a new object or stream. The class-descriptor in an explicit-new-expr must refer to a class or a stream type.

When the class-descriptor refers to a class, the explicit-new-expr allocates storage for an object of the type defined by the class and initializes it by passing the supplied arg-list to the init method defined by the class. It is a compile error if the type-descriptor if the arg-list does not match the signature of the class's init method. If the result of calling the init method is an error value e, then the result of evaluating the explicit-new-expr is e; otherwise the result is the newly initialized object. A class without an init method behaves as it had an init method with no parameters and an empty body (which will always return nil).

When the class-reference refers to a stream type stream<T,E>, the arg-list must either be empty or be a single argument belonging to object type StreamImplementor<T,E?>. When the arg-list is empty, the result will be an empty stream (i.e. a stream whose next method returns nil). When the arg-list evaluates to a StreamImplementor object, the result will be a stream that wraps that object.

An explicit-type-expr specifying a class-descriptor T has static type T, except that if T is an class type and the type of the init method is E?, where E is a subtype of error, then it has static type T|E.

implicit-new-expr := new [( arg-list )]

An implicit-new-expr is equivalent to an explicit-new-expr that specifies the applicable contextually expected type as the class-descriptor. An implicit-new-expr consisting of just new is equivalent to new(). It is an error if the applicable contextually expected type is not a class or stream type.

6.36.1 From clause

from-clause := from typed-binding-pattern in expression

A from clause is executed as follows:

• for each input frame f
  • evaluate the in expression with f in scope resulting in an iterable value c;
  • create an Iterator object i from c
  • do the following in a loop L
    • call i.next() resulting in a value r;
    • if r is an error, then complete execution of the from-clause early with error r;
    • if r is (), stop loop L;
    • let v be r.value;
    • emit a frame consisting of f augmented with the variables resulting from binding typed-binding-pattern to v.

6.36.2 Where clause

where-clause := where expression

A where clause is executed as follows:

• for each input frame f
  • execute the expression with f in scope resulting in value b;
  • if b is true, emit f.

6.36.3 Let clause

let-clause := let let-var-decl [, let-var-decl]* 

A let clause consisting of a single let-var-decl is executed as follows:

• for each input frame f
  • evaluate the expression with f in scope resulting in a value v;
  • emit a frame consisting of f augmented with the result of binding type-binding-pattern to v.

A let clause with more than one let-var-decl is transformed into multiple let clauses: let x1 = E1, x2 = E2 is transformed into let x1 = E1 let x2 = E2.

6.36.4 Join clause

join-clause := [outer] join typed-binding-pattern in expression join-on-condition
join-on-condition := on expression equals expression

A join clause performs an inner or left outer equijoin.

A join clause is executed as follows:

• compute a mapping for the right side of the join; during this computation variable bindings from input frames are not in scope:
  • create an empty mapping m that maps from keys to lists of frames (using DeepEquals to compare keys);
  • evaluate the expression following in resulting in an iterable value c;
  • create an Iterator object i from c;
  • do the following in a loop L
    • call i.next() resulting in a value r;
    • if r is an error, then complete execution of the join-clause early with error r;
    • if r is (), stop loop L;
    • let v be r.value;
    • let f be a frame with the result of binding the typed-binding-pattern to v;
    • evaluate the expression to right of equals with f in scope resulting in a value k;
    • add an entry to m with key k and and frame f;
• for each input frame f
  • evaluate the expression to the left of equals with frame f in scope resulting in a value k;
  • let fs be the list of frames for key k in m;
  • for each frame f' in fs
    • emit a frame consisting of f augmented with f';
  • if outer was specified and fs is empty, then emit a single frame consisting of f augmented with a frame that binds every variable occurring in typed-binding-pattern to ().

In the above, if c evaluates to a table, and the result of evaluating the expression to the right of equals for a member of the table will always be the key value for that member of the table, then the above can be optimized by using the table instead of creating a new mapping.

Variables bound by previous clauses are not in scope for the expression following in, nor for the expression on the right of equals. Variables bound by the typed-binding-pattern are not in scope for the expression following in, nor for the expression on the left of equals.

When outer is specified, the typed-binding-pattern is treated specially: the inferable-type-descriptor in the typed-binding-pattern must be var, and for each variable occurring in the typed-binding-pattern, if the type that would be inferred usually for the variable would be T, then the type inferred in this case will be T?.

6.36.5 Order by clause

order-by-clause := order by order-key [, order-key]*
order-key := expression [order-direction]
order-direction := ascending | descending

The static type of the expression in an order-key must be an ordered type. The order-direction is ascending if not explicitly specified.

An order-by clause is executed by constructing a list of entries, where each entry consists of:

• a frame
• a list of keys, one for each order-key in the order-by-clause, and
• an integer index

In order to define the correct ordering of the list, we first define a CompareK operation that compares two keys with a specified direction: CompareK(x,y,d) is CompareA(x,y) if d is ascending and otherwise (d is descending) is Reverse(CompareD(x,y)), where Reverse applied to LT, EQ, GT is GT, EQ, LT respectively. Now define an operation CompareKL(x,y,d) applying to two lists of keys and a list of directions as follows. Let x be [x₁,x₂,...,x_n], y be [y₁,y₂,...,y_n], and d be [d₁, d₂,...,d_n]. Then let r be CompareK(x₁,y₁,d₁). Then the result of CompareKL(x,y,d) is:

• r, if r is not EQ
• otherwise, EQ, if n is 1
• otherwise, CompareKL([x₂,...,x_n],[y₂,...,y_n],[d₂,...,d_n]).

Then in a correct ordering of the list of entries when the list of directions is d, an entry with keys with keys x and index i is before an entry with keys y and index j if CompareKL(x,y,d) is LT or if CompareKL(x,y,d) is EQ and i is less than j.

An order-by clause is executed as follows:

• create an empty list E of entries
• for each input frame f add an entry to E in which
  • the frame is f
  • the list of keys is a list of the results of evaluating each order-key's expression with f in scope
  • the index is the length of E
• sort E so that it is ordered correctly as described above
• for each entry in E, emit the entry's frame

6.36.6 Limit clause

limit-clause := limit expression

A limit clause limits the number of frames emitted by a query pipeline.

A limit clause is executed as follows:

• evaluate expression resulting in a value n; variable bindings from input frames are not in scope for this evaluation;
• if n is less than zero, then panic;
• for each input frame f, while n is greater than 0
  • decrement n;
  • emit f.

The static type of expression must be a subtype of int.

6.36.7 Select clause

select-clause := select expression

A select clause is executed as follows:

• for each input frame f
  • evaluate the expression with f in scope resulting in value v
  • emit v

6.36.8 On conflict clause

on-conflict-clause := on conflict expression

An on conflict clause is allowed only for a query expression that constructs a table with a key sequence. The expression is evaluated when the select clause emits a value that conflicts with a previous value, in the sense that both values have the same key value in the table. The expression is evaluated with the same frame in scope as the select clause that emitted the value that conflicts with the previous value. The static type of the expression must be a subtype of error?. If the result of evaluating the expression is an error e, then the result of evaluating the query-expr is e. Otherwise, the result must be nil, and the earlier new value replaces the earlier conflicting value, in the same way as if there not been an on conflict clause.

Note that the expression may have side-effects; for example, it may call a function that logs an error.

6.37.1 XML name pattern

xml-name-pattern := xml-atomic-name-pattern [| xml-atomic-name-pattern]*

xml-atomic-name-pattern :=
  *
  | identifier
  | xml-namespace-prefix : identifier
  | xml-namespace-prefix : *

An XML name pattern matches a string specifying the name of an XML element.

An xml-atomic-name-pattern that is * matches any name.

An xml-namespace-prefix in an xml-atomic-name-pattern must be declared by an xmlns-decl. If there is an in-scope default namespace (declared by an xmlns-decl), an xml-atomic-pattern that is just an identifier specifies a name in that default namespace.

6.37.2 XML filter expression

xml-filter-expr := expression .< xml-name-pattern >

An xml-filter-expr selects constituents of a sequence that are elements with a name matching a specified name pattern. The static type of the expression must be a subtype of xml. The static type of the xml-filter-expr is xml<xml:Element>.

6.37.3 XML step expression

An xml-step-expr provides access to the children or descendants of an element, similar to a location path in XPath.

xml-step-expr := expression xml-step-start xml-step-extend*

xml-step-start :=
   xml-all-children-step
   | xml-element-children-step
   | xml-element-descendants-step
xml-all-children-step := /*
xml-element-children-step := /< xml-name-pattern >
xml-element-descendants-step := /**/< xml-name-pattern >

xml-step-extend :=
   .< xml-name-pattern >
   | [ expression ]
   | . method-name ( arg-list )

The static type of the expression must be a subtype of xml.

An xml-step-expr that starts with an xml-all-children-step

   E /* X

is equivalent to

   xml:map(xml:elements(E), v => xml:getChildren(v) X)

where v is a variable name not used in X.

An xml-step-expr that starts with an xml-element-children-step

   E /< NP > X

is equivalent to

   xml:map(xml:elements(E), v => xml:getChildren(v) .<NP> X)

where v is a variable name not used in X.

An xml-step-expr that starts with an xml-element-descendants-step

   E /**/< NP > X

is equivalent to

   xml:map(xml:elements(E), v => xml:getDescendants(v) .<NP> X)

where v is a variable name not used in X.

7.7.1 Single wait action

single-wait-action := wait wait-future-expr

A single-wait-action waits for a single future.

A single-wait-action is evaluated by first evaluating wait-future-expr resulting in a value f of basic type future; the single-wait-action then performs a wait operation on f.

The static type of the single-wait-action is the eventual type of the wait-future-expr.

7.7.2 Multiple wait action

multiple-wait-action := wait { wait-field (, wait-field)* }
wait-field :=
  variable-name
  | field-name : wait-future-expr

A multiple-wait-action waits for multiple futures, returning the result as a record.

A wait-field that is a variable-name v is equivalent to a wait-field v: v, where v must be the name of an in-scope named worker.

A multiple-wait-action is evaluated by evaluating each wait-future-expr resulting in a value of type future for each wait-field. The multiple-wait-action then performs a wait operation on all of these futures. If all the wait operations complete normally, then it constructs a record with a field for each wait-field, whose name is the field-name and whose value is the result of the wait operation. If any of the wait operations complete abruptly, then the multiple-wait-action completes abruptly.

The static type of the multiple-wait-action is a record where the static type of each field is the eventual type of the corresponding wait-future-expr.

7.7.3 Alternate wait action

alternate-wait-action := wait wait-future-expr (| wait-future-expr)+

An alternate-wait-action waits for one of multiple futures to terminate.

An alternate-wait-action is evaluated by first evaluating each wait-future-expr, resulting in a set of future values. The alternate-wait-action then performs a wait operation on all of these members of this set. As soon as one of the wait operations completes normally with a non-error value v, the alternate-wait-action completes normally with result v. If all of the wait operations complete normally with an error, then it completes normally with result e, where e is the result of the last wait operation to complete. If any of the wait operations completely abruptly before the alternate-wait-action completes, then the alternate-wait-action completes abruptly.

The static type of the alternate-wait-action is the union of the eventual type of all of its wait-future-exprs.

7.8.1 Send action

send-action := sync-send-action | async-send-action
sync-send-action := expression ->> peer-worker
async-send-action := expression -> peer-worker ;

A send-action sends a message to the worker that is identified by peer-worker. A send-action starts by evaluating the expression, resulting in a value v; the Clone abstract operation is then applied to v resulting in value c. This value c is added to the message queue maintained by the sending worker for messages to be sent to the sending worker;this queue continues to exist even if the receiving worker has already terminated.

For each send-action S, the compiler determines a unique corresponding receive-action R, such that a message sent by S will be received by R, unless R's worker has terminated abnormally or with failure. It is a compile-time error if this cannot be done. The compiler determines a failure type for the corresponding receive-action. If the receive-action was not executed and its worker terminated normally, then the termination value of the worker will belong to the failure type. The failure type will be a (possibly empty) subtype of error.

The difference between async-send-action and sync-send-action is in what happens after the message is added to the queue. The evaluation of async-send-action completes immediately after this, and the result is always (). A subsequent flush action can be used to check whether the message was received. With sync-send-action, evaluation waits until the receiving worker either executes a receive action that receives the queued message or terminates. The evaluation of sync-send-action completes as follows:

• if the queued message was received, then normally with result nil;
• otherwise
  • if the receiving worker terminated with failure, then normally with the result being the the termination value of the receiving worker, which will be an error;
  • if the receiving worker terminated abnormally, then abruptly with a panic, with the associated value being the termination value of the receiving worker.

The static type of the sync-send-action is F|() where F is the failure type of the corresponding receive action. If F is empty, then this static type will be equivalent to ().

The static type of the expression must be a subtype of value:Cloneable. The contextually expected type used to interpret expression is the contextually expected type from the corresponding receive-action.

If the receive-action corresponding to an async-send-action has a non-empty failure type, then it is a compile-time error unless it can be determined that a sync-send-action or a flush-action will be executed before the sending worker terminates with success.

If a worker W is about to terminate normally and there are messages still to be sent in a queue (which must be the result of executing an async-send-action), then the worker waits until the messages have been received or some receiving worker terminates. If a receiving worker R terminates without the message being received, R must have terminated abnormally, because the rule in the preceding paragraph. In this case, W terminates abnormally and W will use R's termination value as its termination value.

7.8.2 Receive action

receive-action := single-receive-action | multiple-receive-action

single-receive-action := <- peer-worker

multiple-receive-action :=
   <-  { receive-field (, receive-field)* }
receive-field :=
   peer-worker
   | field-name : peer-worker

7.8.3 Flush action

flush-action := flush [peer-worker]

If peer-worker is specified, then flush waits until the queue of messages to be received by peer-worker is empty or until the peer-worker terminates.

Send-receive correspondence for async-send-action implies that the queue will eventually become empty, unless the peer-worker terminates abnormally or with failure. The evaluation of flush-action completes as follows:

• if the queue of messages is empty, then normally with result nil;
• otherwise
  • if the peer-worker terminated with failure, then normally with the result being the the termination value of the peer-worker, which will be an error;
  • if the peer-worker terminated abnormally, then abruptly with a panic, with the associated value being the termination value of the peer-worker.

If the flush-action has a preceding async-send-action without any intervening sync-send-action or other flush-action, then the static type of the flush-action is F|(), where F is the failure type of the receive-action corresponding to that async-send-action. Otherwise, the static type of the flush-action is nil.

If peer-worker is omitted, then the flush-action flushes the queues to all other workers. In this case, the static type will be the union of the static type of flush on each worker separately.

7.8.4 Send-receive correspondence

This section provides further details about how compile-time correspondence is established between sends and receive. This is based on the concept of the index of a message in its queue: a message has index n in its queue if it is the nth message added to the queue during the current execution of the worker.

• A send action/statement has index i in its queue if the message that it adds to the queue is always the i-th message added to the queue during the execution of its worker. It is a compile time error if a send statement or action does not have an index in its queue.
• A receive action has index i in a queue if any message that it removes from the queue is always the i-th message removed from the queue during the execution of its worker. It is a compile time error if a receive action does not have an index in each of its queues.
• A send action/statement and a receive action correspond if they have the same index in a queue.
• It is a compile time error if two or more receive actions have the same index in a queue.
• A send action/statement is in the same send set as another send action/statement if they have the same index in a queue. It is allowed for a send set to have more than one member.
• The maximum index that a receive action has in a queue must be the same as the maximum index that a send action or statement has in that queue.
• It is a compile time error if it is possible for a worker to terminate with success before it has executed all its receive actions.
• It is a compile time error if it is possible for a worker to terminate with success before it has executed one member from every send set.

7.14.1 Lvalues

An lvalue is what the left hand side of an assignment evaluates to. An lvalue refers to a storage location which is one of the following:

• a variable;
• a specific named field of an object;
• the member of a structured value having a specific out-of-line key, which will be either an integer or a string according as the structured value is a list or a mapping.

Note that an lvalue cannot refer to a member of a table.

An lvalue that is both defined and initialized refers to a storage location that holds a value:

• an lvalue referring to a variable is always defined but may be uninitialized;
• an lvalue referring to a specific named field of an object is always defined but may not be initialized until the init method returns
• an lvalue referring to member of a structured value having a specific key is undefined if the structured value does not have a member with that key; if such an lvalue is defined, it is also initialized; note that an lvalue always refers to a structured value that is already constructed.

lvexpr :=
   variable-reference-lvexpr
   | field-access-lvexpr
   | member-access-lvexpr

The left hand side of an assignment is syntactically a restricted type of expression, called an lvexpr. When the evaluation of an lvexpr completes normally, its result is an lvalue. The evaluation of an lvexpr can also complete abruptly, with a panic or check-fail, just as with the evaluation of an expression.

The compiler determines a static type for each lvexpr just as it does for expressions, but the meaning is slightly different. For an lvexpr L to have static type T means that if the runtime evaluation of L completes normally resulting in an lvalue x, then if x is defined and initialized, it refers to a storage location that holds a value belonging to type T. In addition to a type, the compiler determines for each lvexpr whether it is potentially undefined and whether it is potentially uninitialized.

An lvalue supports three operations: store, read and filling-read.

The fundamental operation on an lvalue is to store a value in the storage location it refers to. This operation does not required the lvalue to be defined or initialized; a successful store operation on an undefined lvalue will result in the addition of a member to the structured value; a store on an uninitialized lvalue will initialize it. When an lvalue refers to a variable, it is possible to determine at compile-time whether the store of a value is permissible based on the declaration of the variable and the static type of the value to be stored. However, when the lvalue refers to a member of a structured value, this is not in general possible for three reasons.

1. The guarantee provided by an lvalue having a static type T is not that the referenced storage location can hold every value that belongs to type T; rather the guarantee is that every value that the referenced storage location can hold belongs to type T. This is because structured types are covariant in their member types. The values that the storage location can actually hold are determined by the inherent type of the structured value.
2. The member may not be defined and the inherent type of the structured value may not allow a member with that specific key. The permissible keys of a structured value can be constrained by closed record types, fixed-length array types, and tuple types (with any rest descriptor).
3. The structured value may be immutable. The static type of an lvalue referring to a member of a structured value makes no guaranteees that the structured value is not immutable.

The first of these reasons also applies to lvalues that refer to fields of objects. Accordingly, stores to lvalues other than lvalues that refer to variables must be verified at runtime to ensure that they are not impermissible for any of the above three reasons. An attempt to perform an impermissible store results in a panic at runtime.

List values maintain the invariant that there is a unique integer n, the length of the list, such that a member k of the list is defined if and only if k is a non-negative integer less than n. When a store is performed on an lvalue referring to a member k of a list value and the length of the list is n and k is > n, then each member with index i for each ≤ i < k is filled in, by using the FillMember abstract operation. The FillMember abstract operation may fail; in particular it will fail if the list is a fixed-length array. If the FillMember operation fails, then the attempt to store will panic.

An lvalue also allows a read operation, which is used by the compound assignment statement. Unlike a store operation, a read operation cannot result in a runtime panic. A read operation cannot be performed on an lvalue that is undefined or uninitialized.

Finally, a lvalue supports a filling-read operation, which is used to support chained assignment. A filling-read is performed only an lvalue with a static type that is a structured type. It differs from a read operation only when it is performed on a potentially undefined lvalue. If the lvalue is undefined at runtime, then the filling-read will use the FillMember abstract operation on the member that the lvalue refers to. If the FillMember operation fails, then the filling-read panics. Unlike the read operation, the filling-read operation can be performed on an undefined lvalue; it cannot, however, be performed on an uninitialized lvalue.

The evaluation of an lvexpr is specified in terms of the evaluation of its subexpressions, the evaluation of its sub-lvexprs, and store and filling-read operations on lvalues. If any of these result in a panic, then the evaluation of the lvexpr completes abruptly with a panic.

variable-reference-lvexpr := variable-reference

The result of evaluating variable-reference-lvexpr is an lvalue referring to a variable. Its static type is the declared or inferred type of the variable. The lvexpr is potentially uninitialized if it is possible for execution to have reached this point without initializing the referenced variable.

field-access-lvexpr := lvexpr . field-name

The static type of lvexpr must be either a subtype of the mapping basic type or a subtype of the object basic type.

In the case where the static type of lvexpr is a subtype of the object basic type, the object type must have a field with the specified name, and the resulting lvalue refers to that object field.

In the case where the static type of lvexpr is a subtype of the mapping basic type, the semantics are as follows.

• The following requirements apply at compile time: the type of lvexpr must include mapping shapes that have the specified field-name; type descriptor for lvexpr must include field-name as an individual-type-descriptor (if lvexpr is a union, then this requirement applies to every member of the union); lvexpr must not be potentially uninitialized, but may be potentially undefined.
• It is evaluated as follows:
  1. evaluate lvexpr to get lvalue lv;
  2. perform a filling-read operation on lv to get mapping value m;
  3. the result is an lvalue referring to the member of m with the specified field-name.
• The static type of the field-access-expr is the member type for the key type K in T, where T is the static type of the lvexpr and K is the singleton string type containing the field-name; the field-access-expr is potentially undefined if K is an optional key type for T.

member-access-lvexpr := lvexpr [ expression ]

The static type of lvexpr must be either a subtype of the mapping basic type or a subtype of the list basic type. In the former case, the contextually expected type of expression must be string and it is an error if the static type of expression is not string; in the latter case, the contextually expected type of expression must be int and it is an error if the static type of expression is not int.

It is evaluated as follows:

1. evaluate expression to get a string or int k;
2. evaluate lvexpr to get lvalue lv;
3. perform a filling-read operation on lv to get a list or mapping value v;
4. the result is an lvalue referring to the member of c with key k.

The static type of the member-access-expr is the member type for the key type K in T, where T is the static type of the lvexpr and K is the static type type of expression; the member-access-expr is potentially undefined if K is an optional key type for T.

7.14.2 Assignment statement

assignment-stmt := lvexpr = action-or-expr ;

The static type of action-or-expr must be a subtype of the static type of lvexpr. The static type of lvexpr provides the contextually expected type for action-or-expr. It is not an error for lvexpr to be potentially undefined or potentially uninitialized.

It is executed at as follows:

1. execute action-or-expr to get a value v;
2. evaluate lvexpr to get an lvalue lv;
3. perform the store operation of lv with value v.

7.14.3 Compound assignment statement

compound-assignment-stmt := lvexpr CompoundAssignmentOperator action-or-expr ;
CompoundAssignmentOperator := BinaryOperator =
BinaryOperator := + | - | * | / | & | | | ^ | << | >> | >>>

It is a compile error if lvexpr is potentially undefined unless the static type of lvexpr is a subtype of the list basic type. It is a compile error if lvexpr is potentially uninitialized.

Let T1 be the static type of lvexpr, and let T2 be the static type of action-expr. Then let T3 be the static type of an expression E1 BinaryOp E2 where E1 has type T1 and E2 has type T2. It is a compile error if T3 is not a subtype of T1.

It is executed as follows:

1. execute action-or-expr to get a value v2;
2. evaluate lvexpr to get an lvalue lv;
3. if lv is undefined, panic (lv must refer to an undefined member of a list)
4. perform the read operation on lv to get a value v1
5. perform the operation specified by BinaryOperator on operands v1 and v2, resulting in a value v3
6. perform the store operation on lv with value v3.

7.14.4 Destructuring assignment statement

destructuring-assignment-stmt :=
   binding-pattern-not-variable-reference = action-or-expr ;
binding-pattern-not-variable-reference :=
   wildcard-binding-pattern
   | list-binding-pattern
   | mapping-binding-pattern
   | error-binding-pattern

A destructuring assignment is executed by evaluating the action-or-expr resulting in a value v, and then matching the binding pattern to v, causing assignments to the variables occurring in the binding pattern.

The binding-pattern has a static type implied by the static type of the variables occurring in it. The static type of action-or-expr must be a subtype of this type.

8.3.1 Listener declaration

listener-decl :=
   metadata
   [public] listener [type-descriptor] variable-name = expression ;

A listener-decl declares a module listener. A module listener declares a variable in a similar way to a final variable declaration, but the type of the variable is always a subtype of the Listener object type, and it has the additional semantic of registering the variable's value with the module as a listener. As with a variable declared in a final variable declaration, the variable can be referenced by a variable-reference, but cannot be assigned to. A module may have multiple multiple listeners.

If the type-descriptor is present it specifies the static type of the variable; if it is not present, the the static type is the static type of expression. In both cases, the static type is constrained to be a subtype of the Listener object type.

When a listener-decl is initialized as part of module initialization, its expression is evaluated. If expression evaluation completes abruptly, then module initialization fails. Otherwise the variable is initialized with the result of the evaluation.

8.3.2 Service declaration

service-decl :=
  metadata
  service [variable-name] on expression-list service-body-block
expression-list := expression (, expression)*

A service-decl creates a service and attaches it to one or more listeners. If a variable-name is specified, it also declares a variable; as with a variable declared in a final variable declaration, the variable can be referenced by a variable-reference, but cannot be assigned to.

The service-body-block has the same semantics as in a service-constructor-expr. The static type of each expression in the expression list must be a subtype of the union of error with the Listener object type. If an implementation is using annotations to provide more precise typing of services, then any annotations on the service type that is the first parameter of the __attach method in the object type of each expression in expression list will constrain the type of the service value constructed by the service-body-block.

A service-decl is initialized as part of module initialization as follows. The service-body-block is evaluated as in a service-constructor resulting in a service value s. If variable-name is specified, then the variable is initialized to s. Then for each expression in expression-list:

1. the expression is evaluated resulting in a value which is either an error or an object obj that is a subtype of Listener;
2. if it is an error, module initialization fails;
3. otherwise, obj is registered as a module listener (registering the same object multiple times is the same as registering it once);
4. s is then attached to obj using obj's __attach method;
5. if the call to __attach fails, then module initialization fails.