lang/spec.html

<!DOCTYPE html>
<html lang="en">
<head>
  <title>Ballerina Language Specification</title>
  <meta charset="utf-8" />
  <style type="text/css">
    body { font-family: sans-serif; line-height: 1.38;  }
    pre.grammar code, code.grammar { background-color: #D0D0D0; }
    pre, code { font-family: Consolas, monospace; }
    table { border: solid thin; border-collapse: collapse; }
    td, th { border: solid thin; padding: 0.5em; }
    p.status { font-size: large; font-weight: bold; }
  </style>
</head>
<body>
<h1>Ballerina Language Specification, 2024R1</h1>
<p>
Primary contributors:
</p>
<ul>
<li>James Clark, <a href="mailto:jjc@jclark.com">jjc@jclark.com</a></li>
<li>Sanjiva Weerawarana, <a href="mailto:sanjiva@weerawarana.org">sanjiva@weerawarana.org</a></li>
<li>Sameera Jayasoma, <a href="mailto:sameera@wso2.com">sameera@wso2.com</a></li>
<li>Hasitha Aravinda, <a href="mailto:hasitha@wso2.com">hasitha@wso2.com</a></li>
</ul>
<p>
(Other contributors are listed in <a href="#contributors">Appendix D</a>.)
</p>
<p>
Copyright © 2018-2024 <a href="https://wso2.com/">WSO2</a>
</p>
<p>
Licensed under the <a
href="https://creativecommons.org/licenses/by-nd/4.0/">Creative Commons
Attribution-NoDerivatives 4.0 International</a> license
</p>
<p class="status">
Language and document status
</p>
<p>
The language described in this specification is now stable. We do not plan to
make changes that introduce significant incompatibilities.
</p>
<p>
This release contains a preview of the regular expression feature. Minor
changes may be made before it becomes stable.
</p>
<p>
Comments on this document are welcome and should be made by creating an issue in
<code><a href="https://github.com/ballerina-platform/ballerina-spec"
>https://github.com/ballerina-platform/ballerina-spec</a></code>, which is the
GitHub repository where this specification is maintained.
</p>
<section class="toc">
<h2>Table of contents</h2>
<p><a href="#introduction">1. Introduction</a></p>
<p><a href="#notation">2. Notation</a></p>
<p><a href="#program_structure">3. Program structure</a></p>
<p><a href="#lexical_structure">4. Lexical structure</a></p>
<p><a href="#values_types">5. Values, types and variables</a></p>
<p><a href="#expressions">6. Expressions</a></p>
<p><a href="#actions_statements">7. Actions and statements</a></p>
<p><a href="#module_level">8. Module-level declarations</a></p>
<p><a href="#metadata">9. Metadata</a></p>
<p><a href="#data_tags">10. Data tags</a></p>
<p><a href="#lang_library">11. Lang library</a></p>
<p><a href="#references">A. References</a></p>
<p><a href="#changes">B. Changes since previous versions</a></p>
<p><a href="#planned_future_functionality">C. Planned future functionality</a></p>
<p><a href="#contributors">D. Other contributors</a></p>
</section>
<section>
<h2 id="introduction">1. Introduction</h2>
<p>
Ballerina is a statically typed, concurrent programming language, focusing on
network interaction and structured data. It is intended to be the core of a
language-centric middleware platform. It has all the general-purpose
functionality expected of a modern programming language, but it also has several
unusual aspects that make it particularly suitable for its intended purpose.
</p>
<p>
First, it provides language constructs specifically for consuming and providing
network services. Future versions of Ballerina will add language constructs for
other middleware functionality such as event stream processing and reliable
messaging; this is described in more detail in <a
href="#planned_future_functionality">Appendix C</a>.
</p>
<p>
Second, its abstractions and syntax for concurrency and network interaction have
been designed so that there is a close correspondence with sequence diagrams.
This enables a bidirectional mapping for any Ballerina function between its
textual representation in the syntax described in this specification and its
graphical representation as a sequence diagram, such that the sequence diagram
fully shows the aspects of the behavior of that function that relate to
concurrency and network interaction.
</p>
<p>
Third, it has a type system that is more flexible and allows for looser coupling
than traditional statically typed languages. The type system is structural:
instead of requiring the program to explicitly say which types are compatible
with each other, compatibility of types and values is determined automatically
based on their structure; this is particularly useful when combining data from
multiple, independently-designed systems. In addition, the type system provides
union types and open records. This flexibility allows the type system to be used
as a schema for the data that is exchanged in distributed applications.
Ballerina's data types are designed to work particularly well with JSON; any
JSON value has a direct, natural representation as a Ballerina value. Ballerina
also provides support for XML and tabular data.
</p>
<p>
Ballerina is not a research language. It is intended to be a pragmatic language
suitable for mass-market commercial adoption. It tries to feel familiar to
programmers who are used to popular, modern C-family languages, notably Java, C#
and JavaScript. It also gets ideas and inspiration from many other existing
programming languages including TypeScript, Go, Rust, D, Kotlin, Swift, Python
and Perl.
</p>
<p>
The Ballerina language has been designed in conjunction with the Ballerina
platform, which provides comprehensive support for a module-based software
development model, including versioning, dependency management, testing,
documentation, building and sharing. Modules are organized into repositories;
there is a globally-shared, central repository, but repositories can also be
local.
</p>
<p>
The Ballerina language includes a small library, the lang library, which
provides fundamental operations on the data types defined by the language; the
lang library is defined by this specification. The Ballerina platform includes
an extensive standard library, which includes not only the usual low-level,
general-purpose functionality, but also support for a wide variety of network
protocols, interface standards, data formats and authentication/authorization
standards, which make writing secure, resilient distributed applications
significantly easier than with other languages. The standard library is not
specified in this document.
</p>
</section>
<section>
<h2 id="notation">2. Notation</h2>
<p>
Productions are written in the form:
</p>

<pre>symbol := rhs
</pre>
<p>
where symbol is the name of a nonterminal, and <code>rhs</code> is as follows:
</p>
<ul>
<li><code>0xX</code> means the single character whose Unicode code point is
denoted by the hexadecimal numeral X</li>
<li><code>^x</code> means any single Unicode code point that does not match x
and is not a disallowed character;</li>
<li><code>x..y</code> means any single Unicode character whose code point is
greater than or equal to that of x and less than or equal to that of y</li>
<li><code class="grammar">xyz</code> means the characters <code>xyz</code> literally</li>
<li><code class="grammar">xyz</code><sub>NR</sub> means the characters <code>xyz</code> literally,
and <code>xyz</code> is not a reserved keyword</li>
<li><code>symbol </code>means a reference to production for the nonterminal
<code>symbol</code></li>
<li><code>x|y</code> means x or y</li>
<li><code>x&amp;y</code> means x and y, interleaved in any order</li>
<li><code>[x]</code> means zero or one times</li>
<li><code>x?</code> means x zero or one times</li>
<li><code>x*</code> means x zero or more times</li>
<li><code>x+</code> means x one or more times</li>
<li><code>(x)</code> means x (grouping)</li>
</ul>
<p>
The <code>rhs</code> of a symbol that starts with a lower-case letter implicitly allows white
space and comments, as defined by the production <code>TokenWhiteSpace</code>,
between the terminals and nonterminals that it references.
</p>
</section>
<section>
<h2 id="program_structure">3. Program structure</h2>
<p>
A Ballerina program is divided into modules. A module has a source form and a
binary form. The source form of a module consists of an ordered collection of
one or more source parts; each source part is a sequence of bytes that is the
UTF-8 encoding of part of the source code for the module. The format of a source
part is defined by this specification. The format of a binary module is
specified by the Ballerina platform.
</p>
<p>
A source module can reference other modules. Each source module can be
separately compiled into a binary module: compilation of a source module needs
access only to the binary form of other modules referenced from the source
module. A source module identifies each module that it references using an
organization name and a module name, which is divided into one or more parts.
Both the organization name and each part of the module name are Unicode strings.
Any organization name starting with the string <code>ballerina</code> is
reserved for use by the Ballerina platform.
</p>
<p>
The Ballerina platform defines a packaging system for Ballerina modules, which
allows one or more modules to be combined into a package. The packaging system
treats the first part of each module's name as being a package name. All the
modules combined into a package share the same package name. Packages have both
a source and a binary format. The source format stores the source form of a
package's modules in a hierarchical filesystem. The binary format stores the
binary form of a package's module as a sequence of bytes.
</p>
<p>
Binary packages can be stored in a package repository. Packages are versioned;
versions are semantic, as described in the SemVer specification. A package
repository can store multiple versions of the same package. Thus, within a
repository, binary packages are organized into a three-level hierarchy:
</p>
<ol>
<li>organization;</li>
<li>package name;</li>
<li>version.</li>
</ol>
<p>
The source format of a package includes a <code>Ballerina.toml</code> file that
allows control over the package versions used for referenced modules.
</p>
<p>
The packaging system also allows control over which modules are exported from a
package; modules that are not exported from a package are visible only to
modules within the package.
</p>
</section>
<section>
<h2 id="lexical_structure">4. Lexical structure</h2>
<p>
The grammar in this document specifies how a sequence of Unicode code points is
interpreted as part of the source of a Ballerina module. A Ballerina module part
is a sequence of octets (8-bit bytes); this sequence of octets is interpreted as
the UTF-8 encoding of a sequence of code points and must comply with the
requirements of RFC 3629.
</p>
<p>
After the sequence of octets is decoded from UTF-8, the following two
transformations must be performed before it is parsed using the grammar in this
document:
</p>
<ul>
<li>if the sequence starts with a byte order mark (code point 0xFEFF), it must
be removed</li>
<li>newlines are normalized as follows:
<ul>
<li>the two character sequence 0xD 0xA is replaced by 0xA</li>
<li>a single 0xD character that is not followed by 0xD is replaced by 0xA</li>
</ul>
</li>
</ul>
<p>
The sequence of code points must not contain any of the following disallowed
code points:
</p>
<ul>
<li>surrogates (0xD800 to 0xDFFF)</li>
<li>non-characters (the 66 code points that Unicode designates as
non-characters)</li>
<li>C0 control characters (0x0 to 0x1F and 0x1F) other than white space (0x9,
0xA, 0xC, 0xD)</li>
<li>C1 control characters (0x80 to 0x9F)</li>
</ul>
<p>
Note that the grammar notation ^X does not allow the above disallowed code
points.
</p>

<pre
class="grammar">identifier := UnquotedIdentifier | QuotedIdentifier
UnquotedIdentifier := (IdentifierInitialChar | IdentifierEscape) (IdentifierFollowingChar | IdentifierEscape)*
QuotedIdentifier := <code>'</code> (IdentifierFollowingChar | IdentifierEscape)+
IdentifierInitialChar :=  AsciiLetter | <code>_</code> | UnicodeIdentifierChar
IdentifierFollowingChar := IdentifierInitialChar | Digit
IdentifierEscape := IdentifierSingleEscape | NumericEscape
IdentifierSingleEscape := <code>\</code> ^ ( AsciiLetter | 0x9 | 0xA | 0xD | UnicodePatternWhiteSpaceChar )
NumericEscape := <code>\u{</code> CodePoint <code>}</code>
CodePoint := HexDigit+
AsciiLetter := <code>A</code> .. <code>Z</code> | <code>a</code> .. <code>z</code>
UnicodeIdentifierChar := ^ ( AsciiChar | UnicodeNonIdentifierChar )
AsciiChar := 0x0 .. 0x7F
UnicodeNonIdentifierChar :=
   UnicodePrivateUseChar
   | UnicodePatternWhiteSpaceChar
   | UnicodePatternSyntaxChar
UnicodePrivateUseChar :=
   0xE000 .. 0xF8FF
   | 0xF0000 .. 0xFFFFD
   | 0x100000 .. 0x10FFFD
UnicodePatternWhiteSpaceChar := 0x200E | 0x200F | 0x2028 | 0x2029
UnicodePatternSyntaxChar := <em>character with Unicode property Pattern_Syntax=True</em>
Digit := <code>0</code> .. <code>9</code>
</pre>
<p>
Note that the set of characters allowed in identifiers follows the requirements
of Unicode TR31 for immutable identifiers; the set of characters is immutable in
the sense that it does not change between Unicode versions.
</p>
<p>
The <code>QuotedIdentifier</code> syntax allows a reserved keyword
<code><var>K</var></code> can be used as an identifier by preceding it with a
single quote i.e. <code>'<var>K</var></code>. The <code>IdentifierEscape</code>
syntax allows an arbitrary non-empty string to be treated as an identifier. In a
<code>NumericEscape</code>, <code>CodePoint</code> must valid Unicode code
point; more precisely, it must be a hexadecimal numeral denoting an integer
<em>n</em> where 0 &#x2264; <em>n</em> &lt; 0xD800 or 0xDFFF &lt; n &#x2264;
0x10FFFF.
</p>

<pre
class="grammar">RestrictedIdentifier := AsciiLetter RestrictedFollowingChar* RestrictedIdentifierWord*
RestrictedIdentifierWord := <code>_</code> RestrictedFollowingChar+
RestrictedFollowingChar := AsciiLetter | Digit
</pre>

<p>
Identifiers used for the names of organizations and modules are restricted to
<code>RestrictedIdentifier</code>.
</p>

<pre
class="grammar">TokenWhiteSpace := (Comment | WhiteSpaceChar)*
Comment := <code>//</code> AnyCharButNewline*
AnyCharButNewline := ^ 0xA
WhiteSpaceChar := 0x9 | 0xA | 0xD | 0x20
</pre>
<p>
<code>TokenWhiteSpace</code> is implicitly allowed on the right hand side of
productions for non-terminals whose names start with a lower-case letter.
</p>

<pre
class="grammar">NoSpaceColon := <code>:</code>
</pre>
<p>
When <code>NoSpaceColon</code> is used in a production,
<code>TokenWhiteSpace</code> is not allowed immediately before or after the
colon. When a literal <code>:</code> is used in a production, white space is
handled in the same was as for any other character.
</p>

</section>
<section>
<h2 id="values_types">5. Values, types and variables</h2>

<section>
<h3>Overview</h3>

<section>
<h4>Type system fundamentals</h4>
<p>
Ballerina programs operate on a rich universe of values. This universe of values
is partitioned into a number of <em>basic types</em>; every value belongs to
exactly one basic type.
</p>
<p>
Values are of four kinds, each corresponding to a kind of basic type:
</p>
<ul>
<li>simple values, like booleans and floating point numbers, which are not
composed from other values;</li>
<li>structured values, like mappings and lists, which contain values of arbitrary basic types;</li>
<li>sequence values, which consists of sequences of values of the same basic type;</li>
<li>behavioral values, like functions and objects, which are not just data.</li>
</ul>
<p>
There is a fundamental distinction between values that have a <em>storage
identity</em> 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.
</p>
<p>
Values can be stored in variables or as members of structures or in constituents
of sequences. When a value has no storage identity, it can be stored directly in
the variable, structure or sequence. However, when a value has storage identity,
what is stored in the variable, structure or sequence 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.
</p>
<p>
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 <em>new</em>
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 <em>copying</em>: 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.
</p>
<p>
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 <em>shape</em>. A type denotes a set of
shapes. Subtyping in Ballerina is <em>semantic</em>: 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.
</p>
<p>
A value is <em>plain data</em> 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 <em>plain data</em> if it is
</p>
<ul>
<li>a simple value,</li>
<li>a sequence value,</li>
<li>a structured value, all of whose members are also plain data.</li>
</ul>
<p>
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.
</p>
<p>
The two most important kinds of behavioural values are functions and objects. A
function value can be executed by calling it; when a function is called, it is
passed values and arguments and returns a value. An object encapsulates data
with functions that operate on the data: an object's members are divided into
fields, which hold the data, and methods, which are the functions that operate
on the data.
</p>
</section>

<section>
<h4>Mutation</h4>
<p>
There are two kinds of things that can be mutated in Ballerina: variables and
values. Mutation of values is tied to storage identity: mutation is only
possible 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.
</p>
<p>
The possibility of mutation gives rise to two relations between a value and a
type:
</p>
<ul>
<li>a value <em>looks like</em> a type at a particular point in the execution of
a program if its shape at that point is a member of the type;</li>
<li>a value <em>belongs to</em> 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.</li>
</ul>
<p>
If a value cannot be mutated, looking like a type and belonging to a type are
the same thing.
</p>
<p>
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 hold 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.
</p>
<p>
Every value has a read-only bit. If the read-only bit is on, it means that the
value is immutable. A value's read-only bit is fixed when the value is
constructed, and cannot be changed thereafter. Ballerina maintains the invariant
that immutability is deep: any value reachable from a value with its read-only
bit set is guaranteed to have its read-only bit set. Here <em>reachable</em>
means reachable through read operations: every member of a structure value is
reachable from the structure value; every constituent of a sequence value is
reachable from the sequence value; every member of an object value is reachable
from the object value. Reachability is transitive: if <var>t</var> is reachable
from <var>s</var>, and <var>s</var> is reachable from <var>r</var>, then
<var>t</var> is reachable from <var>r</var>. Reachability is also considered
reflexive: a value is reachable from itself.
</p>
<p>
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 as are functions. 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 as are
objects. Finally, some basic types are inherently mutable: the read-only bit is
never on for a value belonging to an inherently mutable basic type.
</p>
<p>
Each selectively immutable basic type can be partitioned into two
<em>uniform</em> types, one containing values with the read-only bit on, and one
containing values where the read-only bit is off. For every other basic type,
there is a single uniform type. Every uniform type is thus either completely
readonly or completely mutable; every value thus belongs to exactly one uniform
type, and mutation cannot change the uniform type to which a value belongs.
</p>
<p>
It is also possible to limit the mutability of variables, by making them final.
This means that the value that a variable holds cannot be changed after the
variable has been initialized. Unlike immutability of variables, this is not
deep. A final variable can hold a mutable value.
</p>
</section>

<section>
<h4>Isolation</h4>
<p>
There are three possible operations on storage: read, write and execute. The
concept of immutability relates to reading and writing storage, and provides
limited information about execution: execution cannot lead to mutation of an
immutable value. For functions and objects, it is useful to have more
information about how execution may lead to mutation. Ballerina has a concept of
<em>isolation</em> that provides this.
</p>
<p>
In addition to defining when a value is reachable from a value, we can define
when a value is reachable from a variable: a value is reachable from a variable
if the value is reachable from the value that the variable holds. We
can also define when mutable state is reachable from a value or variable: the
mutable state of a value v is reachable from a value or variable, if v is
reachable from the value or variable; the mutable state of a variable v is
reachable only from the variable v.
</p>
<p>
Objects have an isolated bit in addition to a read-only bit; an object value is
isolated if its isolated bit is set. Mutable state is defined to be <em>freely
reachable</em> from a value or variable if it is reachable without following a
reference to an isolated object. A variable or value is an <em>isolated
root</em> if its mutable state is isolated from the rest of the program's
mutable state: any mutable state that is freely reachable from the isolated root
is reachable from outside only through the isolated root. More precisely, if
some mutable state <var>s</var> is freely reachable from an isolated root value
<var>r</var>, then <var>s</var> is not freely reachable from a variable or value
that is not reachable from <var>r</var> except by following a reference through
<var>r</var>; similarly, if some mutable state <var>s</var> is freely reachable
from an isolated root variable <var>r</var>, then <var>s</var> is not freely
reachable from a value that is not reachable from <var>r</var> and is not freely
reachable from any variable other than <var>r</var>. A variable can also be
declared to be isolated. Ballerina maintains the invariant that isolated objects
and isolated variables are isolated roots. Ballerina also guarantees that any
mutable state freely reachable from an isolated object or isolated variable is
accessed only within the scope of a <a href="#lock_statement">lock
statement</a>, which ensures that there is no data race in accessing that
mutable state. This implies that there will be no data race accessing any
mutable state that is reachable (not just freely reachable) from an isolated
object or isolated variable.
</p>
<p>
Functions and methods have an isolated bit in addition to a read-only bit; a
function or method is isolated if its isolated bit is set. Ballerina guarantees
that a call an isolated method or function will only result in access to mutable
state if at least one of the following conditions applies:
</p>
<ul>
<li>the mutable state is freely reachable from an argument passed to the
function or method and the access happens on the strand on which the function is
called; the object on which a method is invoked is considered as an argument for
this purpose;</li>
<li>the mutable state is freely reachable from an isolated variable or an
isolated object;</li>
<li>the mutable state is part of a new value created by the call.</li>
</ul>
<p>
The caller of a function can thus ensure that a function call will not lead to a
data race by ensuring that no data race is possible for the mutable state freely
reachable from the arguments that it passes to the function, for example by
passing only immutable values or isolated objects.
</p>

</section>
<section>
<h4>Type descriptors</h4>
<p>
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
<em>basic</em> type.
</p>
<p>
The following table summarizes the type descriptors provided by Ballerina.
</p>
<table>
  <tr>
   <td><strong>Kind</strong></td>
   <td><strong>Name</strong></td>
   <td><strong>Set of values denoted by type descriptor</strong></td>
  </tr>
  <tr>
   <td rowspan="5">basic, simple</td>
   <td>nil</td>
   <td>()</td>
  </tr>
  <tr>
   <td>boolean</td>
   <td>true, false</td>
  </tr>
  <tr>
   <td>int</td>
   <td>64-bit signed integers</td>
  </tr>
  <tr>
   <td>float</td>
   <td>64-bit IEEE 754-2008 binary floating point numbers</td>
  </tr>
  <tr>
   <td>decimal</td>
   <td>decimal floating point numbers</td>
  </tr>
  <tr>
   <td rowspan="2">basic, sequence</td>
   <td>string</td>
   <td>a sequence of Unicode scalar values</td>
  </tr>
  <tr>
   <td>XML</td>
   <td>a sequence of zero or more elements, processing instructions, comments or
text items</td>
  </tr>
  <tr>
   <td rowspan="5">basic, structured</td>
   <td>array</td>
   <td>an ordered list of values, optionally with a specific length, where a
single type is specified for all members of the list</td>
  </tr>
  <tr>
   <td>tuple</td>
   <td>an ordered list of values, where a type is specified separately for each
member of the list</td>
  </tr>
  <tr>
   <td>map</td>
   <td>a mapping from keys, which are strings, to values; specifies mappings in
terms of a single type to which all keys are mapped</td>
  </tr>
  <tr>
   <td>record</td>
   <td>a mapping from keys, which are strings, to values; specifies maps in
terms of names of fields (required keys) and value for each field</td>
  </tr>
  <tr>
   <td>table</td>
   <td>a ordered collection of mappings, where a mapping is uniquely identified
within the table by a key derived from the mapping</td>
  </tr>
  <tr>
   <td rowspan="7">basic, behavioral</td>
   <td>error</td>
   <td>an indication that there has been an error, with a string identifying the
reason for the error, and a mapping giving additional details about the error</td>
  </tr>
  <tr>
   <td>function</td>
   <td>a function with 0 or more specified parameter types and a single return
type</td>
  </tr>
  <tr>
   <td>future</td>
   <td>a value to be returned by a function execution</td>
  </tr>
  <tr>
   <td>object</td>
   <td>a combination of named fields and named methods</td>
  </tr>
  <tr>
   <td>typedesc</td>
   <td>a type descriptor</td>
  </tr>
  <tr>
   <td>handle</td>
   <td>reference to externally managed storage</td>
  </tr>
  <tr>
   <td>stream</td>
   <td>a sequence of values that can be generated lazily</td>
  </tr>
  <tr>
   <td rowspan="11">other</td>
   <td>singleton</td>
   <td>a single value described by a literal</td>
  </tr>
  <tr>
   <td>readonly</td>
   <td>any value whose read-only bit is on</td>
  </tr>
  <tr>
   <td>any</td>
   <td>any value other than an error</td>
  </tr>
  <tr>
   <td>never</td>
   <td>no value</td>
  </tr>
  <tr>
   <td>optional</td>
   <td>a value that is either () or belongs to a type</td>
  </tr>
  <tr>
   <td>union</td>
   <td>a value that belongs to at least one of a number of types</td>
  </tr>
  <tr>
   <td>intersection</td>
   <td>a value that belongs to all of a number of types</td>
  </tr>
  <tr>
   <td>distinct</td>
   <td></td>
  </tr>
  <tr>
   <td>anydata</td>
   <td>plain data (a simple value, sequence value or structured value that
   does not contain behavioral members at any depth)</td>
  </tr>
  <tr>
   <td>json</td>
   <td>the union of (), int, float, decimal, string, and maps and arrays whose
values are, recursively, json</td>
  </tr>
  <tr>
   <td>byte</td>
   <td>int in the range 0 to 255 inclusive</td>
  </tr>
</table>
<p>
A shape is divided into two <em>aspects</em>: the <em>primary aspect</em> and
the <em>read-only aspect</em>. A value's read-only bit is a part of the
<em>read-only aspect</em> 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. If two
plain data values compare equal, then the primary aspect of their shapes is the
same, but there may be differences in the read-only aspect.
</p>
<p>
Type descriptors other than <code>readonly</code> 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 <code>readonly</code> type uses
only the read-only aspect: whether a value belongs to the <code>readonly</code>
type depends only on the read-only aspect of the value's shape.
</p>
<p>
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.
</p>

<pre
class="grammar">type-descriptor :=
   simple-type-descriptor
   | sequence-type-descriptor
   | structured-type-descriptor
   | behavioral-type-descriptor
   | other-type-descriptor
</pre>
<p>
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.
</p>
<table>
  <tr>
   <td><strong>Operator</strong></td>
   <td><strong>Associativity</strong></td>
  </tr>
  <tr>
   <td><code>distinct T</code></td>
   <td></td>
  </tr>
  <tr>
   <td><code>T[]</code><br /><code>T?</code></td>
   <td></td>
  </tr>
  <tr>
   <td><code>T1 &amp; T2</code></td>
   <td>left</td>
  </tr>
  <tr>
   <td><code>T1 | T2</code></td>
   <td>left</td>
  </tr>
  <tr>
   <td><code>function(args) returns T</code></td>
   <td>right</td>
  </tr>
</table>


</section>
<section>
<h4>Type-ids</h4>
<p>
Ballerina has a feature, called <em>distinct types</em>, 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.
</p>
<p>
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
<code>distinct</code> keyword in either a <a
href="#distinct_types">distinct-type-descriptor</a> or the
<code>class-type-quals</code> of a <code>module-class-defn</code>. Each such
occurrence of the <code>distinct</code> keyword has a distinct type-id, which
uniquely identifies it within a Ballerina program. A type-id has three parts:
</p>
<ol>
<li>a module id, which identifies the module within which the
distinct-type-descriptor occurs; this consists of an organization, a module
name, and an array of platform-specified strings, which could include
information about, for example, the repository or version of the package the
module comes from;</li>
<li>a local id, which identifies the occurrence of the
<code>distinct</code> within the module; this takes one of two forms:
<ul>
<li>named - 
<ul>
<li>if the <code>distinct</code> 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;</li>
<li>if the <code>distinct</code> 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;</li>
</ul>
</li>
<li>anonymous - otherwise, the local id is a compiler-generated integer;</li>
</ul>
</li>
<li>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.</li>
</ol>
<p>
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.
</p>
<p>
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 <em>definite</em> 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.
</p>

</section>
<section>
<h4>Iterability</h4>
<p>
Values of some basic types are <em>iterable</em>. 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 <em>iteration sequence</em> 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.
</p>
<p>
The following tables summarizes the iterable basic types.
</p>
<table>
<tr>
<th>Basic type</th>
<th>Iteration sequence</th>
<th>Type descriptor</th>
<th>Value type</th>
<th>Completion type</th>
</tr>
<tr>
<td>string</td>
<td>length 1 substrings</td>
<td><code>string</code></td>
<td><code>string:Char</code></td>
<td><code>()</code></td>
</tr>
<tr>
<td>xml</td>
<td>singleton xml values</td>
<td><code>xml&lt;T&gt;</code></td>
<td><code>T</code></td>
<td><code>()</code></td>
</tr>
<tr>
<td>list</td>
<td>members in order</td>
<td><code>T[]</code></td>
<td><code>T</code></td>
<td><code>()</code></td>
</tr>
<tr>
<td>mapping</td>
<td>members</td>
<td><code>map&lt;T&gt;</code></td>
<td><code>T</code></td>
<td><code>()</code></td>
</tr>
<tr>
<td>table</td>
<td>members in order</td>
<td><code>table&lt;T&gt;</code></td>
<td><code>T</code></td>
<td><code>()</code></td>
</tr>
<tr>
<td>stream</td>
<td>items</td>
<td><code>stream&lt;T,C&gt;</code></td>
<td><code>T</code></td>
<td><code>C</code></td>
</tr>
</table>
</section>
</section>

<section>
<h3>Simple values</h3>
<p>
The basic type of a simple value is either one of the following
</p>
<ul>
<li>nil</li>
<li>boolean</li>
<li>int</li>
<li>float</li>
<li>decimal</li>
</ul>
<p>
or is a tagged data type.
</p>
<p>
All simple basic types are inherently immutable.
</p>

<pre
class="grammar">simple-type-descriptor :=
   nil-type-descriptor
   | boolean-type-descriptor
   | int-type-descriptor
   | floating-point-type-descriptor
   | tagged-data-type-descriptor
</pre>
<p>
The type descriptor for each simple basic type contains all the values of the
basic type.
</p>
<section>
<h4>Nil</h4>

<pre
class="grammar">nil-type-descriptor := nil-literal
nil-literal :=  <code>(</code> <code>)</code> | <code>null</code>
</pre>
<p>
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 <code>()</code>. The nil
value can also be written <code>null</code>, for compatibility with JSON; the
use of null should be restricted to JSON-related contexts.
</p>
<p>
The nil type is special, in that it is the only basic type that consists of a
single value. 
</p>
</section>
<section>
<h4>Boolean</h4>

<pre
class="grammar">boolean-type-descriptor := <code>boolean</code>
boolean-literal := <code>true</code> | <code>false</code>
</pre>
<p>
The boolean type consists of the values true and false.
</p>
</section>
<section>
<h4>Int</h4>

<pre
class="grammar">int-type-descriptor := <code>int</code>
int-literal := DecimalNumber | HexIntLiteral
DecimalNumber := <code>0</code> | NonZeroDigit Digit*
HexIntLiteral := HexIndicator HexNumber
HexNumber := HexDigit+
HexIndicator := <code>0x</code> | <code>0X</code>
HexDigit := Digit | <code>a</code> .. <code>f</code> | <code>A</code> .. <code>F</code>
NonZeroDigit := <code>1</code> .. <code>9</code>
</pre>
<p>
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).
</p>
<p>
The <a href="#byte_type"><code>byte</code> type</a> is a subtype of
<code>int</code>. The <code>lang.int</code> lang library module also
provides <a href="#built-in_subtypes">built-in subtypes</a> for signed and
unsigned integers representable in 8, 16 and 32 bits.
</p>

</section>
<section>
<h4>Floating point types</h4>

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

<section>
<h5>Float</h5>

<p>
The float type corresponds to IEEE 754-2008 64-bit binary (radix 2) floating
point numbers. A float value can be represented by either a
DecimalFloatingPointNumber with an optional FloatTypeSuffix, or by a
HexFloatingPointLiteral.
</p>
<p>
The multiple bit patterns that IEEE 754 treats as NaN are considered to be the
same value in Ballerina. Positive and negative zero of a floating point basic
type are distinct values, following IEEE 754, but are defined to have the same
shape, so that they will usually be treated as being equal.
</p>
<p>
IEEE-defined operations on float values must be performed using a
rounding-direction attribute of roundTiesToEven (which is the default IEEE
rounding direction, sometimes called <em>round to nearest</em>). All float
values, including the intermediate results of expressions, must use the value
space defined for the float type; implementations must not use extended
precision for intermediate results. This ensures that all implementations will
produce identical results. (This is the same as what is required by strictfp in
Java.)
</p>
</section>
<section>
<h5>Decimal</h5>

<p>
The decimal type corresponds to a subset of IEEE 754-2008 128-bit decimal (radix
10) floating point numbers. Any decimal value can be represented by a
DecimalFloatingPointNumber with an optional DecimalTypeSuffix.
</p>
<p>
A decimal value is a triple (<var>s</var>, <var>c</var>, <var>e</var>) where
</p>
<ul>
<li><var>s</var> is sign, either 0 or -1</li>
<li><var>c</var> is the coefficient, an unsigned integer that can be exactly
represented in 34 decimal digits</li>
<li><var>e</var> is the exponent, a signed integer</li>
</ul>
<p>
representing the mathematical value -1<sup><var>s</var></sup> &#xD7;
<var>c</var> &#xD7; 10<sup><var>e</var></sup>. The range for the exponent
<var>e</var> is implementation dependent, but must be at least the range
supported by the IEEE 754-2008 decimal128 format (which is -6176 to 6111
inclusive).
</p>
<p>
The decimal type corresponds to the ANSI X3.274 subset of IEEE 754-2008, which
has the following simplifications:
</p>
<ul>
<li>+0 and -0 are not distinguished; if the coefficent is zero, then the sign is
also constrained to be zero;</li>
<li>NaN, infinities and subnormals are not supported; operations that would
result in one of these values according to the normal rules of IEEE 754-2008
instead result in a panic.</li>
</ul>
<p>
Operations on the decimal type use the roundTiesToEven rounding mode, like the
float type.
</p>
<p>
The shape of a decimal value is its mathematical value. Thus two decimal values
have the same shape if they represent the same mathematical value, even if they
do so using different exponents.
</p>
</section>
</section>
<section>
<h4>Tagged data values</h4>

<p>
Tagged data types are used for well-known data types that are not
application-specific, but are widely supported across multiple protocols and
programming languages. Each of these data types has its own conventional string
syntax. The use of tagged data types allows programs to work with these data
types using their normal string syntax, while distinguishing the values as
belonging to a specific tagged data type.
</p>
<p>
Data tags are defined either by this specification or the Ballerina platform.
For each such data tag, there is a corresponding basic type. The definition of a
data tag specifies the set of values belonging to the corresponding basic type.
A tagged data value is a value belonging to one of these basic types. Every
tagged data value is plain data, immutable and has no storage identity. The
shape of a tagged data value is the value.
</p>
<p>
The definition of a data tag with corresponding basic type B specifies:
</p>
<ul>
<li>the name of the data tag; this is an unqualified identifier that is used
with the tagged-data-template-expr to construct a value of type B;</li>
<li>the set of values that B consists of;</li>
<li>an abstract parsing function, used at compile-time; a sequence of characters
into which <var>n</var> values can be interpolated is represented by an array of
<var>n</var> + 1 strings; the abstract parsing function accordingly takes an
array of <var>n</var> + 1 strings, with <var>n</var> &#x2065; 0, and returns
either an error or a function of <var>n</var> arguments that interpolates its
arguments into the result of the parse; the type of both the arguments and the
return value of the returned function is B;</li>
<li>an abstract function mapping from values of type B to strings;</li>
<li>a library module; method call expressions on values of type B will call
functions in this module.</li>
</ul>
<p>
Note that errors cannot happen during interpolation. The abstract parsing
function must therefore allow interpolations only in places where any valid
value of type B can be interpolated.
</p>
<p>
Most of the functionality of a tagged data type is provided by its library
module.
</p>

<pre
class="grammar">tagged-data-type-descriptor := qualified-identifier
</pre>
<p>
The qualified-identifier in a tagged-data-type-descriptor refers to a type that
is defined in a module that is part of the language library or standard library.
</p>
<p>
In this version of the Ballerina language, only the data tag <code>re</code>
is defined, with associated lang library module <code>lang.regexp</code>.
</p>

</section>

</section>
<section>
<h3>Sequence values</h3>

<pre
class="grammar">sequence-type-descriptor :=
   string-type-descriptor
   | xml-type-descriptor
</pre>
<p>
A sequence value belongs to one of the following two basic types:
</p>
<ul>
<li>string</li>
<li>xml</li>
</ul>
<p>
A sequence value consists of an ordered sequence of zero or more constituent
items, where the constituent items belong to the same basic type as the sequence
value itself. The <em>length</em> of a sequence value is the number of its
constituent items. Each constituent of a sequence value has an integer index
&#x2265; 0 and &lt; length. A sequence value is a <em>singleton</em> if its
length is 1. For each sequence basic type, there is an <em>empty</em> value,
which has length 0. As with other basic types, the sequence basic types are
disjoint with themselves and with other basic types. Thus the empty value for
string is distinct from the empty value for xml, and these are both distinct
from nil.
</p>
<p>
The values belonging to a sequence basic type B can be defined in terms of its
singleton values and a concatenation operation, by the following rules:
</p>
<ul>
<li>
the singleton values of B belong to B;
</li>
<li>
the empty value of B belongs to B;
</li>
<li>
if v<sub>1</sub> and v<sub>2</sub> belong to B, then the concatenation of
v<sub>1</sub> and v<sub>2</sub> belongs to B.
</li>
</ul>
<p>
The concatenation of any value v belonging to B with the empty sequence of B in
either order is v.
</p>
<p>
Note that for a sequence consisting of a single item v is the same thing as v. A
single item <em>is a</em> sequence. The type of the constituent items of a
sequence of basic type B is thus a subtype of B. This is a fundamental
difference between sequences and lists.
</p>
<p>
Only singleton values of a sequence type can have storage identity. When a
constituent of a sequence value has storage identity, what is stored in the
sequence value is a reference to the location where the constituent value is
stored rather than the constituent value itself.
</p>
<p>
A sequence value is iterable: the iteration sequence consists of the singleton
items of the sequence value in order and the iteration completion value is
always nil.
</p>

<section>
<h4>Strings</h4>

<pre
class="grammar">string-type-descriptor := <code>string</code>
string-literal := DoubleQuotedStringLiteral
DoubleQuotedStringLiteral := <code>"</code> (StringChar | StringEscape)* <code>"</code>
StringChar := ^ ( 0xA | 0xD | <code>\</code> | <code>"</code> )
StringEscape := StringSingleEscape | NumericEscape
StringSingleEscape := <code>\t</code> | <code>\n</code> | <code>\r</code> | <code>\\</code> | <code>\"</code>
</pre>
<p>
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.
</p>
<p>
String values do not have storage identity and so the string basic type is
inherently immutable.
</p>
<p>
There is a <a href="#built-in_subtypes">built-in subtype</a>
<code>string:Char</code> for single character strings.
</p>
</section>
<section>
<h4 id="XML">XML</h4>

<p>
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:
</p>
<ul>
<li>element</li>
<li>processing instruction</li>
<li>comment</li>
<li>text</li>
</ul>
<p>
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 <a href="#built-in_subtypes">built-in
subtypes</a> <code>xml:Element</code>, <code>xml:ProcessingInstruction</code>,
<code>xml:Comment</code> and <code>xml:Text</code> corresponding to the above
singletons; <code>xml:Text</code> also allows the empty xml value.
</p>
<pre
class="grammar">xml-type-descriptor := <code>xml</code> [type-parameter]
type-parameter := <code>&lt;</code> type-descriptor <code>&gt;</code>
</pre>
<p>
A shape belongs to type <code>xml</code> if its basic type is <code>xml</code>.
A type parameter of an xml-type-descriptor must be a subtype of
<code>xml</code>. A shape belongs to type <code>xml&lt;T&gt;</code> if all of
its constituent items belong to <code>T</code>. So, for example,
<code>xml&lt;xml:Element&gt;</code> is the type for xml values containing
only elements. Note that <code>xml&lt;xml&lt;<var>T</var>&gt;&gt;</code> is the
same as <code>xml&lt;<var>T</var>&gt;</code> and that
<code>xml&lt;xml:Text&gt;</code> is the same as <code>xml:Text</code>.
</p>
<p>
The name of an element is represented by a string. The attributes of an element
are represented by a value of type <code>map&lt;string&gt;</code>. The children
of an element is represented by a value of type <code>xml</code>.
</p>
<p>
Singleton element, processing instruction and comment values have storage
identity. Other xml values do not.
</p>
<p>
The <code>xml:Text</code> type is inherently immutable. This implies that both
text singletons and empty xml values always have their read-only bits on. The
<code>xml:Element</code>, <code>xml:ProcessingInstruction</code> and
<code>xml:Comment</code> 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. The attributes and children of an element are
reachable from the element. Thus, if the read-only bit of an
<code>xml:Element</code> is on, then the read-only bits of the mapping
representing its attributes and of the xml value representing its children are
also on.
</p>
<p>
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.
</p>
<section>
<h5>XML namespaces</h5>
<p>
The name of an element or attribute, which in the XML Information Set is
represented by a combination of the [namespace name] and [local name] properties
of an element information item (EII) or attribute information item (AII), is
represented by a single <em>expanded name</em> string. If the [namespace name]
property has no value, then the expanded name consists of just the value of the
[local name] property; otherwise, the expanded name is of the form:
</p>
<pre>
   {<var>namespace-uri</var>}<var>local-name</var>
</pre>
<p>
where <code><var>namespace-uri</var></code> and
<code><var>local-name</var></code> are the values of the [namespace name] and
[local name] properties respectively.
</p>
<p>
The attributes map for an element includes not only an entry for each AII in the
[attributes] property of the EII, but also an entry for each attribute in the
[namespace attributes] property. The key of the entry is the string representing
the name of the attribute, constructed from the AII item as described in the
previous paragraph. The name of every namespace attribute will thus start with
the string <code>{http://www.w3.org/2000/xmlns/}</code>.
</p>
<p>
The attributes map can also contain entries representing namespace attributes
synthesized from the [in-scope namespaces] property. There will be a synthesized
namespace attribute for every prefix other than <code>xml</code> that occurs as
a prefix of the EII or of an AII in the element's [attributes] property and for
which there is no declaration in the [namespace attributes] property. No
namespace attribute will be synthesized for the default namespace. (The
synthesized namespace attributes ensure that namespace prefixes will not be lost
if the element is extracted into a new context.)
</p>
<p>
An xml value can be converted to an XML information set for serialization. This
is done in the context of a set of namespace declarations that are in-scope from
the xml value's parent element, if any. The process of converting an xml element
singleton into an EII has the following stages.
</p>
<ol>
<li>The [namespace name] and [local name] properties of the EII are determined
from the element's expanded name.</li>
<li>An AII is constructed for each entry in the element's attribute map, with
the [namespace name] and [local name] properties of the AII determined from the
entry's key, which is the attribute's expanded name. Each AII is added to either
the [attributes] or [namespace attributes] property of the EII depending on the
AII's [namespace name] property. The [prefix] property of each AII in the
[namespace attributes] property can also be set at this point.</li>
<li>The [namespace attributes] property of the EII is pruned by removing an
AII with [normalized value] N if the AII is not a default namespace declaration,
and the in-scope namespace declarations include a declaration with namespace
name N, and either the EII or one of the AIIs has a [namespace name] property
equal to N. (In this case, the entry for the namespace attribute would get
synthesized when the information set is converted to an xml value.)</li>
<li>For each AII in the EII's [attributes] property that has a [namespace name]
property, a [prefix] property is assigned. If the namespace name is
<code>http://www.w3.org/XML/1998/namespace</code>, then use a prefix of
<code>xml</code>. If there is already a namespace declaration in the [namespace
attributes] that declares a prefix with that namespace name, then that prefix is
used. Otherwise if there is a namespace declaration in the in-scope namespaces
that declares a prefix with that namespace and it is not redeclared or
undeclared by the [namespace attributes], then that prefix is used. Otherwise
generate a prefix and add an AII to the [namespace attributes] to declare
it.</li>
<li>If the EII has no [namespace name] property, but a default namespace
declaration is in scope, then an <code>xmlns=""</code> AII is added to the
[namespace attributes] property to undeclare the default namespace.</li>
<li>If the EII has a [namespace name] property N, then we need
to ensure that there is an applicable namespace declaration:
<ol>
<li>if one of the [namespace attributes] declares N as the default namespace,
then nothing needs to be done;</li>
<li>similarly, if an in-scope namespace declaration declares N as the default
namespace, and the [namespace attributes] do not undeclare it, then nothing
needs to be done;</li>
<li>otherwise, try to find, in the same way as for an AII, a prefix P which is
already declared as N; if there is one, set the [prefix] property of the EII to
P;</li>
<li>otherwise, if the [namespace attributes] property does not contain a default
namespace declaration or undeclaration, generate a default namespace declaration
for N and add it to the [namespace attributes] property;</li>
<li>otherwise, generate a new prefix P, set the [prefix] property of the EII to
P, and add an AII to the [namespace attributes] to declare it.</li>
</ol>
</li>
<li>Generate the [in-scope namespaces] property for this EII, using the parent's
in-scope namespaces and the [namespace attributes].</li>
<li>Convert the children of the xml element, including the element children, to
a list of information items, in the context of this EII's in-scope
namespaces.</li>
</ol>

</section>

</section>

</section>
<section>
<h3>Structured values</h3>
<p>
Structured values are containers for other values, which are called their
members. There are three basic types of structured value: list, mapping and
table.
</p>
<p>
Structured values are usually mutable. Mutating a structured value changes which
values it contains. Structured values can also be constructed as immutable.
Immutability is deep: immutable structured values cannot contain mutable
structured values; if the read-only bit of a structured value is on, then the
read-only bit of each of its members is on.
</p>
<p>
The shape of the members of a structured value contributes to the shape of the
structured value. A structured type descriptor describe the shape of the
structured value in terms of the shapes of its members. Mutating a member of a
structured value can cause the shape of the structured value to change. A
structured value has an inherent type, which is a type descriptor which is part
of the structured value's runtime value. At runtime, the structured value
prevents any mutation that might lead to the structured value having a shape
that is not a member of its inherent type. Thus a structured value belongs to a
type if and only if its inherent type is a subtype of that type.
</p>
<p>
The inherent type of an immutable structured value is a singleton type with the
structured value's shape as its single member. Thus, an immutable structured
value belongs to a type if and only if the type contains the shape of the value.
</p>
<p>
Every structured value has a length, which is the number of its members.
All structured values are iterable: the iteration sequence consists of the
members of the structure and the completion type is always nil.
</p>
<p>
A structured value provides random access to its members using a key that
uniquely identifies each member within the structure. A key can be out-of-line,
meaning it is independent of the member, or in-line, meaning it is part of the
member. The <em>member type</em> for a key type K in a structured type T
consists of all shapes v such that there is a shape in T with key in K and shape
v. A type K is an <em>optional key type</em> for T if there is a shape v in T
and a key k in K such that v does not have a member k; a type that is not an
optional key type is a required key type.
</p>

<pre
class="grammar">structured-type-descriptor :=
   list-type-descriptor
   | mapping-type-descriptor
   | table-type-descriptor
</pre>
<p>
The following table summarizes the type descriptors for structured types.
</p>
<table>
  <tr>
   <td>Structured type</td>
   <td>list</td>
   <td>mapping</td>
   <td>table</td>
  </tr>
  <tr>
   <td>Key source</td>
   <td>out-of-line</td>
   <td>out-of-line</td>
   <td>in-line</td>
  </tr>
  <tr>
   <td>Key type</td>
   <td>integer</td>
   <td>string</td>
   <td>anydata</td>
  </tr>
  <tr>
   <td>Type descriptor with uniform member type</td>
   <td>array</td>
   <td>map</td>
   <td>table</td>
  </tr>
  <tr>
   <td>Type descriptor with separate member types</td>
   <td>tuple</td>
   <td>record</td>
   <td>-</td>
  </tr>
</table>

<section>
<h4>Lists</h4>
<p>
A list value is a container that keeps its members in an ordered list. The
number of members of the list is called the <em>length</em> 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
<em>n</em>, the indices of the members of the list, from first to last, are
0,1,...,<em>n</em> - 1. The shape of a list value is an ordered list of the
shapes of its members.
</p>
<p>
A list is iterable: the iteration sequence consists of the members of the
list in order and the iteration completion value is always nil.
</p>
<p>
The type of list values can be described by two kinds of type descriptors.
</p>

<pre
class="grammar">list-type-descriptor :=
   array-type-descriptor | tuple-type-descriptor
</pre>
<p>
The inherent type of a list value must be a <code>list-type-descriptor</code>.
The inherent type of a list value determines a type T<sub><em>i</em></sub> for a
member with index <em>i</em>. The runtime system will enforce a constraint that
a value written to index <em>i</em> will belong to type T<sub><em>i</em></sub>.
Note that the constraint is not merely that the value looks like
T<sub><em>i</em></sub>.
</p>
<p>
Both kinds of type descriptor are covariant in the types of their members.
</p>
<section>
<h5>Array types</h5>
<p>
An array type-descriptor describes a type of list value by specifying the type
that the value for all members must belong to, and optionally, a length.
</p>

<pre
class="grammar">array-type-descriptor := array-member-type-descriptor inferable-array-dimension array-dimension*
inferable-array-dimension := <code>[</code> [ inferable-array-length ] <code>]</code>
array-dimension := <code>[</code> [ array-length ] <code>]</code>
array-member-type-descriptor := type-descriptor <em>but not</em> array-type-descriptor
inferable-array-length := array-length | inferred-array-length
array-length := int-literal | constant-reference-expr
inferred-array-length := <code>*</code>
</pre>
<p>
A type <code>T[]</code> contains a list shape if all members of the list shape
are in <code>T</code>. A type <code>T[n]</code> contains a list shape if in
addition the length of the list shape is n.
</p>
<p>
When an <code>array-type-descriptor</code> includes multiple
array dimensions, th array dimensions are interpreted
so that the order of the dimensions in the <code>array-type-descriptor</code> is
consistent with the order of the dimensions in a
<code>member-access-expr</code>. Specifically, a type
<code>T[n<sub>1</sub>]...[n<sub>k - 1</sub>][n<sub>k</sub>]</code> is
interpreted as <code>(T[n<sub>k</sub>])[n<sub>1</sub>]...[n<sub>k -
1</sub>]</code>. Thus, for a value <code>v</code> of type <code>T[M][N]</code>,
a member-access-expr <code>v[i][j]</code> will evaluate to an value of type
<code>T</code> if and only if 0 &#x2264; <code>i</code> &#x2264; <code>M</code>
and 0 &#x2264; <code>j</code> &#x2264; <code>N</code>. An
<code>array-type-descriptor</code> is parsed to include all following
<code>array-dimension</code>s: an <code>array-type-descriptor</code> is not
recognized as <code>array-member-type-descriptor</code>.
</p>
<p>
A <code>constant-reference-expr</code> in an <code>array-length</code> must
evaluate to a non-negative integer. An array length of <code>*</code> means that
the length of the array is to be inferred from an initializer; this is allowed
when the array-type-descriptor specifies the type of variable for which an
initializer is specified, i.e. in a <code>local-init-var-decl-stmt</code>, a
<code>module-init-var-decl</code> or a <code>module-const-decl</code>; its
meaning is the same as if the length was specified explicitly.
</p>
<p>
Note also that <code>T[n]</code> is a subtype of <code>T[]</code>, and that if
<code>S</code> is a subtype of <code>T</code>, then <code>S[]</code> is a
subtype of <code>T[]</code>; this is a consequence of the definition of
subtyping in terms of subset inclusion of the corresponding sets of shapes.
</p>
<p>
The type of the values in the iteration sequence of a value belonging
<code>T[]</code> is <code>T</code>.
</p>
</section>
<section>
<h5>Tuple types</h5>
<p>
A tuple type descriptor describes a type of list value by specifying a separate
type for each member of the list.
</p>

<pre
class="grammar">tuple-type-descriptor :=
   <code>[</code> tuple-member-type-descriptors <code>]</code>
tuple-member-type-descriptors :=
   member-type-descriptor (<code>,</code> member-type-descriptor)* [<code>,</code> tuple-rest-descriptor]
   | [ tuple-rest-descriptor ]
member-type-descriptor := [annots] type-descriptor
tuple-rest-descriptor := type-descriptor <code>...</code>

</pre>
<p>
A tuple type descriptor T with m member type descriptors contains a list shape L
of length n if and only if:
</p>
<ul>
<li>m is less than or equal to n</li>
<li>the i-th member type descriptor of T contains the i-th member of L for each
i from 1 to m;</li>
<li>if n is greater than m, then T has a tuple-rest-descriptor
R<code>...</code>, and R contains the j-th member of L for each j from m + 1 to
n.</li>
</ul>
<p>
Note that a tuple type where all the <code>member-type-descriptor</code>s are
the same and there is no tuple-rest-descriptor is equivalent to an
array-type-descriptor with a length.
</p>
</section>
</section>
<section>
<h4>Mappings</h4>
<p>
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 <em>field</em> 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.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
The type of mapping values can be described by two kinds of type descriptors.
</p>

<pre
class="grammar">mapping-type-descriptor :=
   map-type-descriptor | record-type-descriptor
</pre>
<p>
The inherent type of a mapping value must be a
<code>mapping-type-descriptor</code>. The inherent type of a mapping value
determines a type T<sub><em>f</em></sub> for the value of the field with name
<em>f</em>. The runtime system will enforce a constraint that a value written to
field <em>f</em> will belong to type T<sub><em>f</em></sub>. Note that the
constraint is not merely that the value looks like T<sub><em>f</em></sub>.
</p>
<p>
Both kinds of type descriptor are covariant in the types of their members.
</p>
<p>
A mapping value is iterable: the iteration sequence consists of the members of
the mapping value and the iteration completion value is always nil. When the
inherent type of a mapping value is equivalent to a
<code>map-type-descriptor</code>, the order of iteration must correspond to the
order in which fields were added. In other cases, the order of the iteration
sequence is implementation-dependent.
</p>

<section>
<h5>Map types</h5>
<p>
A map type-descriptor describes a type of mapping value by specifying the type
that the value for all fields must belong to.
</p>

<pre
class="grammar">map-type-descriptor := <code>map</code> type-parameter
</pre>
<p>
A type <code>map&lt;T&gt;</code> contains a mapping shape <em>m</em> if every field
shape in <em>m</em> has a value shape that is in <code>T</code>.
</p>
<p>
The type of the values in the iteration sequence of a value belonging
<code>map&lt;T&gt;</code> is <code>T</code>.
</p>
<p>
If a type descriptor T has <a href="#lax_static_typing">lax static typing</a>,
then the type <code>map&lt;T&gt;</code> also has lax static typing.
</p>
</section>
<section>
<h5>Record types</h5>
<p>
A record type descriptor describes a type of mapping value by specifying a type
separately for the value of each field.
</p>

<pre
class="grammar">record-type-descriptor :=
   inclusive-record-type-descriptor | exclusive-record-type-descriptor
inclusive-record-type-descriptor :=
   <code>record</code> <code>{</code> field-descriptor* <code>}</code>
exclusive-record-type-descriptor :=
   <code>record</code> <code>{|</code> field-descriptor* [record-rest-descriptor] <code>|}</code>
field-descriptor :=
   individual-field-descriptor | record-type-inclusion
individual-field-descriptor :=
   metadata [<code>readonly</code>] type-descriptor field-name [<code>?</code> | (<code>=</code> default-expression)] <code>;</code>
field-name := identifier
default-expression := expression
record-type-inclusion := <code>*</code> type-reference <code>;</code>
record-rest-descriptor := type-descriptor <code>...</code> <code>;</code>
</pre>
<p>
Each <code>individual-field-descriptor</code> specifies an additional constraint
that a mapping value shape must satisfy for it to be a member of the described
type. The constraint depends on whether <code>?</code> is present:
</p>
<ul>
<li>if <code>?</code> is not present, then the constraint is that the mapping
value shape must have a field shape with the specified field-name and with a
value shape that is a member of the specified type-descriptor; this is called a
required field;</li>
<li>if <code>?</code> is present, then the constraint is that if the mapping
value shape has a field shape with the specified field-name, then its value
shape must be a member of the specified type-descriptor; this is called an
optional field.</li>
</ul>
<p>
If an <code>individual-field-descriptor</code> specifies <code>readonly</code>,
then there is also a constraint that the field has its read-only bit set.
Furthermore, the type of the field is the intersection of <code>readonly</code>
and the type specified by the type-descriptor.
</p>
<p>
The order of the <code>individual-field-descriptor</code>s within a
<code>record-type-descriptor</code> is not significant. Note that the delimited
identifier syntax allows the field name to be any non-empty string.
</p>
<p>
An exclusive-record-type-descriptor, which uses the <code>{|</code> and
<code>|}</code> delimiters, allows exclusively the fields described. More
precisely, for a mapping value shape and a record-type-descriptor, let the extra
field shapes be the field shapes of the mapping value shapes whose names are not
the same as field-name of any individual-field-descriptor; a mapping value shape
is a member of the type described by an exclusive-record-type-descriptor only if
either:
</p>
<ul>
<li>there are no extra fields shapes, or</li>
<li>there is a record-rest-descriptor <code>T...</code>, and the value shape of
every extra field shape is a member of <code>T</code>.</li>
</ul>
<p>
An inclusive-record-type-descriptor, which uses the <code>{</code> and
<code>}</code> delimiters, allows any mapping value that includes the fields
described, provided that the values of all other fields are plain data. A type
descriptor <code>record { F };</code> is thus equivalent to <code>record {| F;
anydata...; |}</code>, where <code>anydata</code> is defined <a
href="#anydata">below</a> as the type descriptor for plain data.
</p>
<p>
A record type descriptor that either is an inclusive-record-type-descriptor or
is an exclusive-record-type-descriptor with a record-rest-descriptor is called
<em>open</em>; a record type descriptor that is not open is called
<em>closed</em>.
</p>
<p>
If a record type descriptor is closed and every individual-field-descriptor
specifies <code>readonly</code>, then it describes a type that is a subtype of
<code>readonly</code>: a shape belongs to the type only if its read-only bit is
set.
</p>
<p>
A <code>default-expression</code> is an expression that specifies a default
value for the field, which is used when the record type descriptor is used to
construct a mapping value but no value is specified explicitly for the field.
The type descriptor contains a 0-argument function closure for each default
value. The closure is created from the expression when the type descriptor is
resolved. The expression must meet the requirements for an <a
href="#isolated_functions">isolated function</a>. The closure is evaluated to
create a field value each time the default is used in the construction of a
mapping value. The default value does not affect the type described by the type
descriptor. It is a compile-time error if a default-expression
contains a checking-expr with a checking-keyword of <code>check</code>,
i.e. if evaluation of the expression could complete abruptly with a check-fail.
</p>
<p>
A <code>record-type-inclusion</code> includes fields from a named record type.
The <code>type-reference</code> must reference a type described by a
<code>record-type-descriptor</code>. The <code>field-descriptor</code>s and any
<code>record-rest-descriptor</code> are included the type being defined; the
meaning is the same as if they had been specified explicitly. For default
values, the closure rather than the expression is copied in.
It is an error for an <code>record-type-descriptor</code> to directly or
indirectly include itself. An <code>individual-field-descriptor</code> in a
<code>record-type-descriptor</code> can override an
<code>individual-field-descriptor</code> of the same name in an included
<code>record-type-descriptor</code>, provided the type declared for the field in
the overriding field descriptor is a subtype of the type declared in the
overridden field descriptor. It is an error if a
<code>record-type-descriptor</code> has two or more
<code>record-type-inclusion</code>s that include an
<code>individual-field-descriptor</code> with the same name, unless those
<code>individual-field-descriptor</code>s are overridden by an
<code>individual-field-descriptor</code> in the including
<code>record-type-descriptor</code>. A <code>record-rest-descriptor</code> in
the including type overrides any <code>record-rest-descriptor</code> in the
included type. It is an error if a <code>record-type-descriptor</code> has two
or more <code>record-type-inclusion</code>s that include different
<code>record-rest-descriptor</code>s, unless those
<code>record-rest-descriptor</code>s are overridden by an
<code>record-rest-descriptor</code> in the including
<code>record-type-descriptor</code>. For the purposes of
resolving a <code>record-type-inclusion</code>, an including or included type
that is an <code>inclusive-record-type-descriptor</code> is treated as if it
were the equivalent <code>exclusive-record-type-descriptor</code> with an
explicit <code>record-rest-descriptor</code>.
</p>
</section>
</section>
<section>
<h4 id="tables">Tables</h4>
<p>
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.
</p>
<p>
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<sub>1</sub>,f<sub>2</sub>,...,f<sub>n</sub> where n is &#x2265; 2, then the
key value for a member r is a tuple with members
v<sub>1</sub>,v<sub>2</sub>,...,v<sub>n</sub> where v<sub>i</sub> is the value
of field f<sub>i</sub> 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<sub>i</sub> and r<sub>j</sub> in a table with i not equal to j, the
key value for r<sub>i</sub> must not be equal to the key value for
r<sub>j</sub>. Key values are compared for equality using the <a
href="#DeepEquals">DeepEquals</a> 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.
</p>
<p>
The shape of a table value is a triple consisting of
</p>
<ul>
<li>an ordered list containing for each table member, the shape of that member</li>
<li>the table's key sequence, and</li>
<li>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)</li>
</ul>

<pre
class="grammar">table-type-descriptor := <code>table</code> row-type-parameter [key-constraint]
row-type-parameter := type-parameter
key-constraint := key-specifier | key-type-constraint
key-specifier := <code>key</code> <code>(</code> [ field-name (<code>,</code> field-name)* ] <code>)</code>
key-type-constraint := <code>key</code> type-parameter
</pre>
<p>
The row-type-parameter specifies the shape of the table's members. A table type
<code>table&lt;<var>R</var>&gt; <var>KC</var> </code> contains a table shape if
and only if every table member shape belongs to <code><var>R</var></code> and
the table shape satisfies the key constraint <code><var>KC</var></code>. The
type specified by a row-type-parameter must be a subtype of
<code>map&lt;any|error&gt;</code>
</p>
<p>
In a table-type-descriptor <code>table&lt;<var>R</var>&gt;
key(<var>ks</var>)</code>, <code><var>R</var></code> and
<code><var>ks</var></code> must be consistent in the following sense: for each
field name f<sub>i</sub> in <code><var>ks</var></code>, f<sub>i</sub> must be a
required, read-only field of <code><var>R</var></code> with a type that is a
subtype of <code>anydata</code>. A table shape satisfies a key-constraint
<code>key(<var>ks</var>)</code> if and only if its key sequence is
<code><var>ks</var></code>. A table shape satisfies a key-constraint
<code>key&lt;K&gt;</code> if and and only if its set of key value shapes are a
subset of <code><var>K</var></code>. The shape of a keyless table satisfies the
key-constraint <code>key&lt;never&gt;</code>.
</p>
<p>
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.
</p>
<p>
A table is iterable: the iteration sequence consists of the members of the
table in order and the iteration completion value is always nil.
</p>

</section>
</section>
<section>
<h3>Behavioral values</h3>

<pre
class="grammar">behavioral-type-descriptor :=
   error-type-descriptor
   | function-type-descriptor
   | object-type-descriptor
   | future-type-descriptor
   | typedesc-type-descriptor
   | handle-type-descriptor
   | stream-type-descriptor
</pre>

<section>
<h4>Errors</h4>

<pre
class="grammar">error-type-descriptor := <code>error</code> [type-parameter]
</pre>
<p>
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.
</p>
<p>
The error type is inherently immutable. An error value contains the following
information:
</p>
<ul>
<li>a message, which is a string containing a human-readable message describing
the error</li>
<li>a cause, which is either nil or another error value that was the cause of
this error</li>
<li>a detail, which is an immutable mapping providing additional information about
the error</li>
<li>a stack trace, which is an immutable snapshot of the state of the execution
stack</li>
</ul>
<p>
The detail mapping must be a subtype of <code>map&lt;Cloneable&gt;</code>.
</p>
<p>
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
<code>error&lt;<var>T</var>&gt;</code> contains an error shape if
<code><var>T</var></code> contains the shape of its detail. The type
<code>error</code> contains a shape if its basic type is error.
</p>
<p>
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.
</p>
</section>

<section>
<h4 id="functions">Functions</h4>

<pre
class="grammar">function-type-descriptor :=
   function-quals <code>function</code> function-signature
   | [isolated-qual] <code>function</code>
function-quals :=
   transactional-qual [isolated-qual]
   | [isolated-qual] [transactional-qual]
isolated-qual := <code>isolated</code>
transactional-qual := <code>transactional</code>
function-signature := <code>(</code> param-list <code>)</code> return-type-descriptor
</pre>
<p>
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.
</p>

<pre
class="grammar">param-list :=
   required-params [<code>,</code> defaultable-params] [<code>,</code> included-record-params] [<code>,</code> rest-param]
   | defaultable-params [<code>,</code> included-record-params] [<code>,</code> rest-param]
   | included-record-params [<code>,</code> rest-param]
   | [rest-param]
required-params := required-param (<code>,</code> required-param)*
required-param := [annots] type-descriptor [param-name]
defaultable-params := defaultable-param (<code>,</code> defaultable-param)*
defaultable-param := [annots] type-descriptor [param-name] <code>=</code> (default-expression | inferred-typedesc-default) 
included-record-params := included-record-param (<code>,</code> included-record-param)*
included-record-param := [annots] <code>*</code> type-reference [param-name]
rest-param := [annots] type-descriptor <code>...</code> [param-name]
param-name := identifier
inferred-typedesc-default := <code>&lt;</code> <code>&gt;</code>
</pre>
<p>
A param-name can be omitted from a required-param, defaultable-param,
included-record-param or rest-param only when occuring in the function-signature
of a function-type-descriptor. The type-descriptor in a required-param or
defaultable-param must not be <code>never</code>.
</p>
<p>
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.
</p>
<p>
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, defaultable-param and included-record-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; for an
included-record-param, the type-descriptor is the type-reference; the
type-descriptor of the tuple-rest-descriptor, if present, is the same as the
type-descriptor of the rest-param.
</p>
<p>
An argument list consisting of values v<sub>1</sub>,..., v<sub>n</sub> conforms
to a param-list that has type P, if and only if for each i with 1 &#x2264; i &#x2264;
n, v<sub>i</sub> belongs to T<sub>i</sub>, where T<sub>i</sub> 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.
</p>
<p>
A defaultable-param is a parameter for which a default value is specified. An
expression can be used to specify the default value; this expression may refer
to previous parameters. Each such expression is turned into a closure that
computes the default value for the parameter using the values of previous
parameters, and this closure is part of the type descriptor for the function. It
is also possible for the default to be specified as <code>&lt;&gt;</code>; this
means that the default value is a <code>typedesc</code> value that is to be
inferred by the caller from the contextually expected type of the function call.
It is allowed only when the parameter name to which the default value applies is
referenced in the return-type-descriptor, as described below, and is allowed for
at most one parameter in a function. The caller of the function uses 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. If the
function-type-descriptor includes an isolated-qual, then an expression used as a
default-expression must meet the requirements for an <a
href="#isolated_functions">isolated function</a>.
</p>
<p>
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.
</p>
<p>
The type-reference in an included-record-param must refer to a type defined by a
record-type-descriptor. Specifying an included-record-param <code>*<var>T</var>
<var>p</var></code> is similar to specifying a required-param <code><var>T</var>
<var>p</var></code>. The difference is that the caller of the function may
specify the value for a field of an included-record-param using the field's name
as if it had been declared as a parameter. Any field of the
included-record-param not so specified is defaulted using the
record-type-descriptor. A field-descriptor is a <code>parameter field
descriptor</code> of a function if it is a field descriptor of a
record-type-descriptor referenced by an included-record-param of the function.
The field names of all the parameter field descriptors whose type is not
<code>never</code> must be distinct from each other and from the names of the
parameters. Whether a parameter is an included-record-param is part of the
function's type-descriptor, but does not affect the shape of the function and
thus does not affect whether a function value belongs to a function type.
</p>
<p>
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 <a href="#function_call">section on function calls</a>.
</p>
<pre
class="grammar">return-type-descriptor := [ <code>returns</code> [annots] type-descriptor ]
</pre>
<p>
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 <code>()</code>. Note that
the function definition does not have to explicitly return <code>()</code>; a
return statement or falling off the end of the function body will implicitly
return <code>()</code>.
</p>
<p>
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
<code>returns ()</code>. The type-descriptor in a return-type-descriptor may be
<code>never</code>.
</p>
<p>
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 <code>typedesc</code>. 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. If the default value for p is
<code>&lt;&gt;</code> and p occurs in the return-type-descriptor in a union p|T,
then for every basic type B, either the intersection of B and T must be empty,
or the intersection of typedesc&lt;B&gt; and the declared type of p must be
empty, or both. 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 <em>dependently-typed</em>. Functions with
dependently-types signatures can be declared and used within Ballerina, but
Ballerina does not yet provide a mechanism to define such functions.
</p>
<p>
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.
</p>
<p>
If a function-type-descriptor includes an <code>isolated-qual</code>, then a
function value belongs to the type only if the value's isolated bit is set; if
the function type does not include an <code>isolated-qual</code>, then whether a
function value belongs to the type is not affected by the value's isolated bit.
</p>
<p>
All function values belongs to a function-type-descriptor <code>function</code>;
a function value belongs to the function-type-descriptor <code>isolated
function</code> if and only if it is an isolated function.
</p>
<p>
In addition to a readonly bit and an isolated bit, a function value also has a
transactional bit. A function value with its transactional bit set can only be
called in a <a href="#transactions">transactional scope</a>; this is enforced by
the type system. A function value with its transactional bit not set belongs to
the type described by a function-type-descriptor with a function-signature only
if the function-type-descriptor does not include a <code>transactional</code>
qualifier. This means that a function-type-descriptor with a function-signature
but without a <code>transactional</code> qualifier is a subtype of the
corresponding function-type-descriptor with a <code>transactional</code>
qualifier. Note that the subtyping relationship for <code>transactional</code>
is in the opposite direction from <code>isolated</code>. A function value's
transactional bit does not affect whether it belongs to the type described by a
function-type-descriptor without a function-signature.
</p>
</section>
<section>
<h4>Objects</h4>
<p>
An object value encapsulates data with functions that operate on the data. An
object consists of named members, where each member is either a field or a
method. 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 <code>method-call-expr</code>; when a
method is invoked on an object, the function can access the object using the
<code>self</code> 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.
</p>
<p>
The type of object values can be described using an
<code>object-type-descriptor</code>, as specified in this section. It can also
be described using a <em>class</em>. 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.
</p>
<p>
The object basic type is selectively immutable. An object value has a read-only
bit, which is fixed when the object is constructed. An
<code>object-type-descriptor</code> does not describe whether the object's
read-only bit is set: whether a value belongs to the type described by an
<code>object-type-descriptor</code> is not affected by the object's read-only
bit. Whether an object is read-only can be described separately using a
<code>readonly</code> type descriptor, which can be combined with an
<code>object-type-descriptor</code> using the type intersection operator.
</p>

<pre
class="grammar">object-type-descriptor :=
   object-type-quals <code>object</code> <code>{</code>
      object-member-descriptor*
   <code>}</code>
object-type-quals :=
   isolated-qual [object-network-qual]
   | [object-network-qual [isolated-qual]]
object-member-descriptor :=
   object-field-descriptor
   | method-decl
   | remote-method-decl
   | resource-method-decl
   | object-type-inclusion
</pre>

<p>
If an isolated-qual is specified, then an object belongs to the described type
only if the object's isolated bit is set. If an isolated-qual is not specified,
then an object's isolated bit does not affect whether it belongs to the
described type.
</p>

<section>
<h5>Network interaction</h5>
<p>
Objects are the basis for Ballerina's network interaction primitives. There are
two special kinds of object for network interaction: client objects and service
objects. A client object supports network interaction with a remote system that
is originated by the Ballerina program. A service object supports network
interaction with a remote system that is originated by the remote system. An
object may be a client object or a service object or neither; it cannot be both
a client object and a service object. An object that is a client object or a
service object is a network interaction object.
</p>

<pre
class="grammar">object-network-qual := <code>client</code> | <code>service</code>
</pre>

<p>
If the <code>object-network-qual</code> is <code>client</code>, then an object
belongs to the type only if it is a client object. If the
<code>object-network-qual</code> is <code>service</code>, then an object belongs
to the type only if it is a service object. If <code>object-network-qual</code>
is not present, then an object belongs to the type regardless of whether it is a
client object or service object or neither. A <code>object-network-qual</code>
is not allowed in conjunction with <code>public</code>.
</p>

<p>
Network interaction objects can have, in addition to fields and methods, two
additional kinds of member: remote methods and resources; both of these are in a
different symbol space from fields and (non-remote) methods.
</p>

</section>

<section>
<h5>Fields</h5>

<pre
class="grammar">object-field-descriptor :=
   metadata [<code>public</code>] type-descriptor field-name <code>;</code>
</pre>
<p>
An <code>object-field-descriptor</code> describes a field of the object. The
<code>field-name</code> of an <code>object-field-descriptor</code> must be
distinct from the <code>field-name</code> of every other
<code>object-field-descriptor</code> in the <code>object-type-descriptor</code>
and from the <code>method-name</code> of every <code>method-decl</code> in the
<code>object-type-descriptor</code>.
</p>
<p>
If an object's read-only bit is set, then the read-only bit of the value of
every field must also be set and the value of a field cannot be changed after
the object has been constructed.
</p>
</section>

<section>
<h5>Methods</h5>

<pre
class="grammar">method-decl :=
   metadata [<code>public</code>] method-quals
   <code>function</code> method-name function-signature <code>;</code>
method-quals := function-quals
method-name := identifier | special-method-name
special-method-name := <code>map</code> | <code>join</code> | <code>start</code>
</pre>
<p>
A <code>method-decl</code> describes a method of the object. The
<code>method-name</code> of a <code>method-decl</code> must be distinct from the
<code>method-name</code> of every other <code>method-decl</code> in the
<code>object-type-descriptor</code> and from the <code>field-name</code> of
every <code>object-field-descriptor</code> in the
<code>object-type-descriptor</code>. Note that here is no method overloading.
The <code>method-name</code> in a <code>method-decl</code> must not be
<code>init</code>. The identifiers <code>map</code>, <code>join</code> and
<code>start</code>, which are usually reserved keywords, are allowed as method
names.
</p>

<p>
The <code>isolated-qual</code> together with the <code>function-signature</code>
give the function type of the method. An isolated method has the same access to
the object on which the method is invoked that it has to parameters.
</p>
</section>

<section>
<h5>Remote methods</h5>
<pre
class="grammar">remote-method-decl :=
   metadata remote-method-quals 
   <code>function</code> remote-method-name function-signature <code>;</code>
remote-method-quals :=
   remote-qual function-quals
   | isolated-qual [transactional-qual] remote-qual
   | transactional-qual [isolated-qual] remote-qual
   | isolated-qual remote-qual transactional-qual
   | transactional-qual remote-qual isolated-qual
remote-qual := <code>remote</code>
remote-method-name := identifier
</pre>
<p>
A <code>remote-method-decl</code> declares a remote method. An object can
include a <code>remote-method-decl</code> only if it is a network interaction
object. A remote method is a method for network interaction: a remote method of
a client object is for outbound network interaction; a remote method of a
service object is for inbound network interaction. The <code>remote-method-name</code>
of a <code>remote-method-decl</code> must be distinct from the
<code>remote-method-name</code> of every other <code>remote-method-decl</code> in the
<code>object-type-descriptor</code>. However, a <code>method-decl</code> and a
<code>remote-method-decl</code> can have the same name. A remote method cannot
be called using the normal method call syntax. A remote method of a client
object can only be invoked by a <code>client-remote-method-call-action</code>.
The return type of the remote method of a client object must not be
<code>never</code>. A remote method of a service object is invoked by a listener
object provided by a library module; Ballerina does not yet define a mechanism
to allow such a library module to be implemented completely in Ballerina.
</p>

</section>

<section>
<h5>Resources</h5>

<pre
class="grammar">resource-method-decl :=
   metadata resource-method-quals
   <code>function</code> resource-method-name resource-path function-signature <code>;</code>
resource-method-quals :=
   resource-qual function-quals
   | isolated-qual [transactional-qual] resource-qual
   | transactional-qual [isolated-qual] resource-qual
   | isolated-qual resource-qual transactional-qual
   | transactional-qual resource-qual isolated-qual
resource-qual := <code>resource</code>
resource-method-name := identifier
resource-path :=
   dot-resource-path
   | resource-path-segment (<code>/</code> resource-path-segment)* [<code>/</code> resource-path-rest-param]
   | resource-path-rest-param
dot-resource-path := <code>.</code>
resource-path-segment := resource-path-segment-name | resource-path-segment-param
resource-path-segment-name := identifier
resource-path-segment-param := <code>[</code>[annots] type-descriptor [param-name]<code>]</code>
resource-path-rest-param := <code>[</code>[annots] type-descriptor <code>...</code> [param-name]<code>]</code>
</pre>
<p>
As well as remote methods, a network interaction object may include members that
are resources. Resources support a more data-oriented style of network
interaction, which complements the RPC style supported by remote methods. A
resource of a client object is for outbound network interaction; a resource of a
service object is for inbound network interaction. A resource of a client object
can be accessed only using a <code>client-resource-access-action</code>. A
resource of a service object is accessed by a listener object provided by a
library module; Ballerina does not yet define a mechanism to allow such a
library module to be implemented completely in Ballerina.
</p>
<p>
Each resource is named within an object by a <em>resource path</em>, which
consists of a list of resource path segments. A resource path segment is most
commonly a string, but can be any value of type anydata. A resource has one or
more named methods. A resource method is thus uniquely identified within its
object by its path and method name. Each resource method corresponds to a way
that the resource can be accessed; the name <code>get</code> should be used for
a resource method that just fetches the resource. For a service object, the
supported resource method names are determined by the listener; a listener that
supports resources should always support the name <code>get</code>.
</p>
<p>
A <code>resource-method-decl</code> declares a resource method for one or more
resources. An object can include a <code>resource-method-decl</code> only if it
is a network interaction object.
</p>
<p>
A <code>resource-path</code> can be mapped onto a tuple type descriptor as
follows. A <code>dot-resource-path</code> maps to <code>[]</code> (an empty
tuple type). A <code>resource-path-segment-name</code> maps to a member type
descriptor that is a singleton string. A
<code>resource-path-segment-param</code> with type descriptor <code>T</code>
maps to a member type descriptor <code>T</code>. A
<code>resource-path-rest-param</code> with type descriptor <code>T</code> maps
to a tuple rest descriptor <code>T...</code>.
</p>
<p>
It is a compile error if a <code>object-type-descriptor</code> has two
<code>resource-method-decl</code>s with the same name and with
<code>resource-path</code>s that map to the same tuple type descriptor.
</p>
<p>
When a resource with path [s<sub>1</sub>,...,s<sub>m</sub>] of a service object
S has a method <code>get</code> with a return value that includes a service
object type, then this has the semantics that the service object S delegates
each resource with a path [s<sub>1</sub>,...,s<sub>m</sub>,...,s<sub>n</sub>] to
a resource [s<sub>m+1</sub>,...,s<sub>n</sub>] of the service object returned by
the <code>get</code> method of S. Accordingly, if the return type of a
<code>resource-method-decl</code> with a method name of <code>get</code> and a
<code>resource-path</code> <var>p</var> includes a service object type:
</p>
<ul>
<li>the return type must not allow anything other than service objects and
errors;</li>
<li>the <code>resource-path</code> must not end with a
<code>resource-path-rest-param</code>;</li>
<li>there must be no <code>resource-method-decl</code> that has a
<code>resource-path</code> with <var>p</var> as a prefix.</li>
</ul>
<p>
The set of resource method names <em>applicable</em> for a
<code>resource-method-decl</code> with <code>resource-method-name</code> m at a
resource path position is defined as follows:
</p>
<ul>
<li>if the position is not the last position of the resource path, then the
applicable set consists of just <code>get</code></li>
<li>otherwise, if the <code>resource-path</code> ends with a <code>resource-path-segment</code>,
then the applicable set consists of just m;</li>
<li>otherwise, the <code>resource-path</code> ends with
<code>resource-path-rest-param</code> and the applicable set consists of
<code>get</code> and m.</li>
</ul>
<p>
Two <code>resource-method-decl</code>s X and Y that map to tuple type descriptors
[X<sub>1</sub>,...,X<sub>m</sub>] and [Y<sub>1</sub>,...,Y<sub>n</sub>]
<em>diverge at position</em> i if and only if:
</p>
<ul>
<li>i &#x2264; m;</li>
<li>i &#x2264; n;</li>
<li>the intersection of the sets of resource method names applicable for X and Y
at position i is non-empty;</li>
<li>for all j &lt; i, X<sub>j</sub> is the same type as as Y<sub>j</sub>;</li>
<li>X<sub>i</sub> and Y<sub>i</sub> are not the same (to be the same, they must
both be a member-type-descriptor or both be a tuple-rest-descriptor, and the
types must be the same).</li>
</ul>
<p>
If two <code>resource-method-decl</code>s diverge at position i, then it is a
compile-time error unless the <code>resource-path</code> of at least one of them
maps to a tuple type descriptor that at position i has a
<code>member-type-descriptor</code> that denotes a singleton string.
</p>
<p>
A <code>resource-path-segment</code> that maps to a singleton string takes
priority over other types in the following sense. When a
<code>resource-method-decl</code> R has a resource path that has a
<code>resource-path-segment</code> at position i that maps to a
<code>member-type-descriptor</code> that denotes a type T that is not a
singleton string, then T is narrowed to a type T' by removing every singleton
string type S such that there is a <code>resource-method-decl</code> that
diverges from R at position i and has has a resource path that has a
<code>resource-path-segment</code> at position i that maps to a
<code>member-type-descriptor</code> that denotes S. The
<code>resource-method-decl</code> declares resources methods for resources that
whose corresponding path segment belongs to the narrowed type T' rather than T.
</p>
<p>
The return type of a resource method must not allow values belonging to the
function basic type and must not allow client object types.
</p>

</section>

<section>
<h5>Visibility</h5>
<p>
Each field and method of an object has a <em>visibility region</em>, which is
the region of code within which the field or method is visible and can be
accessed. The visibility region of a <code>remote-method-decl</code> or of
<code>object-field-descriptor</code> or <code>method-decl</code> that includes
<code>public</code> consists of all the modules of the program. Otherwise the
visibility region is the module containing this object type descriptor; this is
called module-level visibility.
</p>
</section>
<section>
<h5>Typing</h5>

<p>
The shape of an object consists of a read-only bit, an isolated bit, a network
interaction kind and an unordered collection of object field shapes and object
method shapes. A network interaction kind has one of three values: service,
client or empty. An object field shape or object method shape is a 4-tuple
consisting of the name of the field or method, the visibility region, a remote
flag and a shape for the value of the field or for the method's function.
</p>
<p>
An object type is inclusive, in a similar way to an
inclusive-record-type-descriptor: an object shape belongs to an object type if
it has at least the fields and methods described in the object-type-descriptor.
Thus all object values belong to the type <code>object { }</code>.
</p>
<p>
An object-type-descriptor that has a field with name f, visibility region R and
type T contains an object shape only if the object shape contains an object
field shape that has name f, visibility region R and a value shape that is
contained in T. An object-type-descriptor that has a method with name m,
visibility region R, remote qualifier r and function type T contains an object
shape only if the object shape contains an object method shape that has name m,
visibility region R, a remote flag that matches r and a function value that
belongs to type T.
</p>
<p>
Thus an object type T' is a subtype of an object type T only if for each field
or method f of T there is a corresponding field or method f' of T such that the
type of f' in T' is a subtype of the type of f in T and the visibility region of
f' in T' is the same as the visibility region of f in T. This implies that if an
object type descriptor T has fields or methods with module-level visibility,
then it is possible to define another object type descriptor that is a subtype
of T only within the same module as T.
</p>
 
</section>
<section>
<h5>Inclusion and type-ids</h5>

<pre
class="grammar">object-type-inclusion := <code>*</code> type-reference <code>;</code>
</pre>
<p>
Every type descriptor referenced directly or indirectly by a
<code>type-reference</code> in an <code>object-type-inclusion</code> must be an
<code>object-type-descriptor</code>, <code>distinct-type-descriptor</code>,
<code>intersection-type-descriptor</code> or
a class that has no <code>private</code> members and no <code>readonly</code> qualifier; the
referenced type descriptor will thus necessarily be definite and a subtype of
object. If a referenced object-type-descriptor or class has an
<code>isolated</code>, <code>service</code> or <code>client</code> qualifier
<var>Q</var>, then the referencing object-type-descriptor must also have the
qualifier <var>Q</var>. The <code>object-field-descriptor</code>s and
<code>method-decl</code>s from the referenced type are included in the type
being defined. A type-reference to a class is treated as a reference to the
class's type; only the types of the methods and fields are copied from the
referenced type. An <code>object-field-descriptor</code> or
<code>method-decl</code> in a <code>object-type-descriptor</code> can override
respectively an <code>object-field-descriptor</code> or <code>method-decl</code>
of the same name in an included <code>object-type-descriptor</code>, provided
the type declared for the field or method in the overriding descriptor is a
subtype of the type declared in the overridden descriptor. An
<code>object-field-descriptor</code> cannot override a <code>method-decl</code>,
nor can a <code>method-decl</code> override an
<code>object-field-descriptor</code>. It is an error if an
<code>object-type-descriptor</code> has two or more
<code>object-type-inclusion</code>s that include an
<code>object-field-descriptor</code> with the same name, unless those
<code>object-field-descriptor</code>s are overridden by an
<code>object-field-descriptor</code> in the including
<code>object-type-descriptor</code>. It is an error if an
<code>object-type-descriptor</code> has two or more
<code>object-type-inclusion</code>s that include <code>method-decl</code>s with
the same name but different <code>function-signature</code>s, unless those
<code>method-decl</code>s are overridden by a <code>method-decl</code> in the
including <code>object-type-descriptor</code>.
</p>
<p>
An object-type-descriptor is always definite. The set of type-ids induced by an
object-type-descriptor is the union of the set of type-ids induced by the type
descriptors that it includes. An induced type-id is primary in an
object-type-descriptor if and only if it is primary in any of the included type
descriptors. It is an error if the induced set of type-ids includes a non-public
type-id from another module.
</p>
<p>
It is an error for an <code>object-type-descriptor</code> to directly or
indirectly include itself.
</p>
</section>
</section>
<section>
<h4>Futures</h4>

<pre
class="grammar">future-type-descriptor := <code>future</code> [type-parameter]
</pre>
<p>
A future value refers to a named worker, which will return a value. A future
value belongs to a type <code>future&lt;T&gt;</code> if the return type of the
named worker is a subtype of T.
</p>
<p>
A value belongs to a type <code>future</code> (without the type-parameter)
if it has basic type future.
</p>
</section>
<section>
<h4>Type descriptors</h4>
<pre
class="grammar">typedesc-type-descriptor := <code>typedesc</code> [type-parameter]
</pre>
<p>
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 <var>t</var> belongs to a type typedesc&lt;<var>T</var>&gt; if
and only if the type described by <code>t</code> is a subtype of <var>T</var>.
The typedesc type is thus covariant with its type parameter.
</p>
<p>
Referencing an identifier defined by a type definition in an expression context
will result in a type descriptor value.
</p>

</section>
<section>
<h4>Handles</h4>
<pre
class="grammar">handle-type-descriptor := <code>handle</code>
</pre>
<p>
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.
</p>
<p>
A value belongs to a type <code>handle</code> if it has a basic type of handle.
</p>

</section>

<section>
<h4>Streams</h4>

<pre
class="grammar">stream-type-descriptor := <code>stream</code> [stream-type-parameters]
stream-type-parameters := <code>&lt;</code> type-descriptor [<code>,</code> type-descriptor]<code>&gt;</code>
</pre>
<p>
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
<code>stream&lt;T,C&gt;</code> if the values in the generated sequence all
belong to T and if the completion value belongs to C. The type
<code>stream&lt;T&gt;</code> is equivalent to <code>stream&lt;T,()&gt;</code>. A
value belongs to a type <code>stream</code> (without the type-parameter) if it
has basic type stream. A type <code>stream&lt;T,C&gt;</code> where C does not
include nil describes an unbounded stream.
</p>
<p>
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 <code>stream&lt;T,C&gt;</code> has a result
of type <code>C?</code>, where nil means that the close operation was
successful. The close operation is idempotent: performing the close operation on
a stream on which the close operation has already been performed has no effect.
When the generation of the sequence is complete, the stream automatically
performs the close operation to release resources used by the stream.
</p>
<p>
The type descriptor <code>stream&lt;T,C&gt;</code> works like a class, in that
it can be used with <code>new</code> to construct stream values that belong to
the type. The normal implementation of a <code>stream&lt;T,C&gt;</code> is a
wrapper around an object belonging to <a href="#StreamImplementor">object type
<code>StreamImplementor&lt;T,C&gt;</code></a>. The next and close operations on
the stream delegate to the next and close methods on the StreamImplementor.
</p>
<p>
The stream module of the <a href="#lang_library">lang library</a> provides
additional operations on stream that can be implemented in terms of the
primitive next and close operations.
</p>
<p>
A stream is iterable. A stream of type <code>stream&lt;T,C&gt;</code> has value
type <code>T</code> and completion type <code>C</code>. 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.
</p>
<p>
Note that in this version of Ballerina the stream type is not a class because
Ballerina does not yet support parameterized classes.
</p>
</section>

</section>
<section>
<h3>Other type descriptors</h3>

<pre
class="grammar">other-type-descriptor :=
   | type-reference
   | singleton-type-descriptor
   | any-type-descriptor
   | never-type-descriptor
   | readonly-type-descriptor
   | distinct-type-descriptor
   | union-type-descriptor
   | intersection-type-descriptor
   | optional-type-descriptor
   | anydata-type-descriptor
   | json-type-descriptor
   | byte-type-descriptor
   | <code>(</code> type-descriptor <code>)</code>
</pre>
<p>
It is important to understand that the type descriptors specified in this
section do not add to the universe of values. They are just adding new ways to
describe subsets of this universe.
</p>
<section>
<h4>Type reference</h4>
<pre
class="grammar">type-reference := identifier | qualified-identifier
</pre>

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

</section>
<section>
<h4>Singleton types</h4>

<pre
class="grammar">singleton-type-descriptor := simple-const-expr

</pre>
<p>
A singleton type is a type containing a single shape. A singleton type is
described using a 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.
</p>
</section>
<section>
<h4>Any type</h4>

<pre class="grammar">any-type-descriptor := <code>any</code>
</pre>
<p>
The type descriptor <code>any</code> 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 <code>any|error</code>. Note
that a structure with members that are errors belongs to the <code>any</code>
type.
</p>
<p>
The any-type-descriptor is not definite.
</p>
</section>
<section>
<h4>Never type</h4>

<pre class="grammar">never-type-descriptor := <code>never</code>
</pre>
<p>
The type descriptor <code>never</code> describes the type that does not contain
any shapes. No value ever belongs to the <code>never</code>.
</p>
<p>
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,
<code>xml&lt;never&gt;</code> describes the an xml type that has no
constituents, i.e. the empty xml value.
</p>
<p>
Note that for any type <code>T</code>, the type <code>T|never</code> is the same
as <code>T</code>.
</p>
</section>
<section>
<h4>Readonly type</h4>
<pre
class="grammar">readonly-type-descriptor := <code>readonly</code>
</pre>
<p>
A shape belongs to the type <code>readonly</code> if its read-only bit is on.
</p>
<p>
A value belonging to an inherently immutable basic type will always have its
read-only bit on. These basic types are:
</p>
<ul>
<li>all simple types
<ul>
<li>nil</li>
<li>boolean</li>
<li>int</li>
<li>float</li>
<li>decimal</li>
</ul>
</li>
<li>string</li>
<li>error</li>
<li>function</li>
<li>typedesc</li>
<li>handle</li>
</ul>
<p>
A value belonging to a selectively immutable basic type may have its read-only
bit on. These basic types are:
</p>
<ul>
<li>xml</li>
<li>list</li>
<li>mapping</li>
<li>table</li>
<li>object</li>
</ul>

</section>
<section>
<h4 id="distinct_types">Distinct types</h4>
<pre
class="grammar">distinct-type-descriptor := <code>distinct</code> type-descriptor
</pre>
<p>
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.
</p>
<p>
The type denoted by a distinct-type-descriptor <code><var>D</var></code>, where
<code><var>D</var></code> is <code>distinct <var>T</var></code>, and
<var>d</var> is the type-id of this occurrence of <code><var>D</var></code>,
contains a shape <var>s</var> of an object or error value if and only if both
<code><var>T</var></code> contains <var>s</var> and the set of type-ids of
<var>s</var> contains <var>d</var>. The set of type-ids induced by
<code><var>D</var></code> consists of <var>d</var> as the primary type-id and
the type-ids induced by <code><var>T</var></code> as the secondary type-ids. The
type <code><var>T</var></code> must be definite and must be a subtype of object
or a subtype of error. The type <code><var>D</var></code> is always definite.
Note that <code><var>D</var></code> is always a proper subtype of
<code><var>T</var></code>.
</p>

</section>
<section>
<h4>Union types</h4>

<pre
class="grammar">union-type-descriptor := type-descriptor <code>|</code> type-descriptor
</pre>
<p>
The set of shapes denoted by an union type <code>T1|T2</code> is the union of
the set of shapes denoted by <code>T1</code> and the set of shapes denoted by
<code>T2</code>. Thus, the type <code>T1|T2</code> contains a shape if and only
if either the type denoted by <code>T1</code> contains the shape or the type
denoted by <code>T2</code> contains the shape. A type descriptor
<code>T1|T2</code> is not a class and cannot be used with <code>new</code>,
even if one or both of T1 and T2 are classes.
</p>
<p>
A union type <code>T1|T2</code> is definite if and only if both <code>T1</code>
and <code>T2</code> are definite and the set of type-ids induced by
<code>T1</code> and <code>T2</code> are the same. If it is definite, then it
induces the same set of type-ids as <code>T1</code> and <code>T2</code>, and a
type-id is primary if it is primary in either <code>T1</code> or
<code>T2</code>.
</p>
</section>
<section>
<h4>Intersection types</h4>

<pre
class="grammar">intersection-type-descriptor := type-descriptor <code>&amp;</code> type-descriptor
</pre>
<p>
The set of shapes denoted by an intersection type  is the
intersection of the set of shapes denoted by <code>T1</code> and the set of
shapes denoted by <code>T2</code>. Thus, the type <code>T1&amp;T2</code>
contains a shape if and only if the types denoted by <code>T1</code> and
<code>T2</code> both contain the shape. It is a error to have an intersection
type that denotes an empty set of shapes. In an intersection type
<code>T1&amp;T2</code>, it is an error if <code>T1</code> and <code>T2</code>
are both function types unless there is a single function-type-descriptor that
denotes a type that is a subtype of both <code>T1</code> and <code>T2</code>.
A type descriptor <code>T1&amp;T2</code> is not a class and cannot be used
with <code>new</code>, even if one or both of T1 and T2 are classes.
</p>
<p>
An intersection type <code>T1&amp;T2</code> is definite if and only if both
<code>T1</code> and <code>T2</code> are definite. If it is definite, then it
induces the union of the set of type-ids induced by <code>T1</code> and
<code>T2</code>, and a type-id is primary if it is primary in either
<code>T1</code> or <code>T2</code>.
</p>
<p>
Intersection types are particularly useful in conjunction with
<code>readonly</code>. A set of readonly shapes can be described by
<code>readonly&amp;T</code>, where <code>T</code> describes the primary aspect
of the shape.
</p>
<p>
When T is either <code>R&amp;readonly</code> or <code>readonly&amp;R</code>,
where R is a record type descriptor, and a field in R has a default value with
closure C, then, if the return type of C belongs to <a
href="#Cloneable">Cloneable</a>, the field in T has a default value with a
closure that applies the <a href="#ImmutableClone">ImmutableClone</a> operation
to result of evaluating C; otherwise, the field in T does not have a default
value.
</p>
</section>

<section>
<h4>Optional types</h4>

<pre
class="grammar">optional-type-descriptor := type-descriptor <code>?</code>
</pre>
<p>
A type <code><var>T</var>?</code> means the union of <code><var>T</var></code>
and <code>()</code>. It is completely equivalent to
<code><var>T</var>|()</code>.
</p>
</section>

<section>
<h4 id="anydata">Anydata type</h4>

<pre
class="grammar">anydata-type-descriptor := <code>anydata</code>
</pre>
<p>
The type descriptor <code>anydata</code> describes the type of plain data. The
type <code>anydata</code> contains a shape if and only if it is the shape of a
value that is plain data. The <code>anydata</code> type can thus be defined as:
</p>

<pre
>  () | boolean | int | float | decimal
    | string | xml | regexp:RegExp
    | anydata[] | map&lt;anydata&gt; | table&lt;map&lt;anydata&gt;&gt;
</pre>

<p>
In the above, <code>regexp</code> refers to the lang library module
<code>lang.regexp</code>. Since there is only one tagged data type defined in
this version of Ballerina, all tagged data values belong to
<code>regexp:RegExp</code>.
</p>

</section>
<section>
<h4>JSON types</h4>

<pre
class="grammar">json-type-descriptor := <code>json</code>
</pre>
<p>
The <code>json</code> type is designed for processing data expression in JSON
format. It is a built-in name for a union defined as follows:
</p>
<pre>type json = () | boolean | int | float | decimal | string | json[] | map&lt;json&gt;;
</pre>
<p>
In addition, the <code>json</code> type is defined to have <a
href="#lax_static_typing">lax static typing</a>.
</p>

</section>

<section>
<h4 id="byte_type">Byte type</h4>

<pre class="grammar">byte-type-descriptor := <code>byte</code>
</pre>
<p>
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 <a href="#built-in_subtypes">built-in
subtype</a> <code>int:Unsigned8</code>.
</p>
</section>

</section>
<section>
<h3 id="built-in_object_types">Built-in object types</h3>
<p>
There are several object types that are built-in in the sense that the
language treats objects with these types specially. There are two kinds of
object type:
</p>
<ul>
<li>purely structural types; the name of the type is internal to this
specification and not exposed to the language;</li>
<li>distinct types; the name of the type is defined in a lang library
module.</li>
</ul>

<section>
<h4>Iterator</h4>
<p>
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
</p>

<pre
>    object {
       public function next() returns record {| T value; |}|C;
    }
</pre>
<p>
In this specification, we refer to this type as Iterator&lt;T,C&gt;.
</p>
<p>
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.
</p>
<p>
The <code>next()</code> method behaves as follows:
</p>
<ul>
<li>if the iteration has encountered an error, return an error value</li>
<li>otherwise, if the iterator has completed successfully by reaching the end
position without an error, return nil</li>
<li>otherwise
<ul>
<li>move the iterator to next position, and</li>
<li>return a record <code>{ value: v }</code> where v is the member of the
sequence between the previous position and the new position</li>
</ul>
</li>
</ul>
<p>
Mutation of a structured value during iteration is handled as follows. A call to
<code>next()</code> must panic if there has been any mutation to the structured
value since the iterator was created other than the following:</p>
<ul>
<li>removing a member of the structured value that a preceding call to the
iterator has already returned;</li>
<li>changing the member associated with an existing key.</li>
</ul>
<p>
In the latter case, <code>next()</code> must return the value associated with
the key at the point when <code>next()</code> is called.
</p>
<p>
Note that it is not possible for the <code>next()</code> 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.
</p>
</section>
<section>
<h4>Iterable</h4>
<p>
An object belongs to the object type Iterable&lt;T,C&gt; if it has a
method named <code>iterator</code> with no arguments and a return type that is
subtype of Iterator&lt;T,C&gt; and it belongs to the distinct type
<code>Iterable</code> defined in <code>lang.object</code>. An object that
belongs to Iterable&lt;T,C&gt; is iterable: the object returned by the
<code>iterator</code> method determines the iteration sequence and iteration
completion value.
</p>
</section>
<section>
<h4 id="StreamImplementor">StreamImplementor</h4>
<p>
An object belongs to the object type StreamImplementor&lt;T,C&gt; if it
belongs to Iterator&lt;T,C&gt; and also optionally has a method
<code>close()</code> with return value <code>C?</code>. This is equivalent to
belonging to the following type.
</p>

<pre
>    object {
       public isolated function next() returns record {| T value; |}|C;
    }
    | object {
       public isolated function next() returns record {| T value; |}|C;
       public isolated function close() returns C?;
    }
</pre>

<p>
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 <code>()</code>.
</p>

</section>
<section>
<h4>Listener</h4>
<p>
The object type Listener&lt;T,A&gt;, where T is a a subtype of <code>service
object {}</code> and A is a subtype of <code>string[]|string|()</code>, is
described by the following object type descriptor:
</p>

<pre>object {
   public function attach(T svc, A attachPoint) returns error?;
   public function detach(T svc) returns error?;
   public function start() returns error?;
   public function gracefulStop() returns error?;
   public function immediateStop() returns error?;
}
</pre>
<p>
The role of a Listener is to handle incoming network messages by making
calls on service objects as described in <a
href="#listeners_and_services">Listeners and services</a>. Each method is used
as follows:
</p>
<ul>
<li>the <code>attach</code> method is used to provide the Listener with a
service object that it can use to handle incoming network messages; the
<code>attachPoint</code> argument is used to identify which network messages the
service object should be used for;</li>
<li>the <code>detach</code> method tells the Listener to stop using a service
object that was previously provided using the <code>attach</code> method;</li>
<li>the <code>start</code> method tells the Listener to start handling incoming
network messages;</li>
<li>the <code>gracefulStop</code> and <code>immediateStop</code> messages tell
the Listener to stop handling incoming network messages;
<ul>
<li>in the case of <code>gracefulStop</code>, the listener should complete the
handling of any incoming messages that it has started to handle; in particular,
it should wait for the completion of any strands that it created to execute
service object methods;</li>
<li>in the case of <code>immediateStop</code>, the listener should not try to
complete the hanlding of any incoming messages that is has started to handle; in
particular, it should cancel any strands that it created to execute service
object methods.</li>
</ul>
</li>
</ul>
<p> 
Each method returns an error value if an error occurred, and return nil
otherwise. The listener object is responsible for creating and keeping track of
any strands that it needs.
</p>
<p>
A type is a <em>listener object type</em> if it is a subtype of the object type
Listener&lt;T,A&gt;, for some type T that is a subtype of <code>service object
{}</code> and some type A that is a subtype of <code>string[]|string|()</code>.
</p>
</section>
<section>
<h4>RawTemplate</h4>
<p>
The RawTemplate type describes the type of object constructed by a raw template
expression. The type is defined in <code>lang.object</code> as follows.
</p>
<pre>distinct object {
    public (readonly &amp; string[]) strings;
    public (any|error)[] insertions;
}
</pre>

</section>
<section>
<h4>RetryManager</h4>

<p>
Classes of type RetryManager are defined by the application to allow control
over retries performed by the retry statement and retry transaction statement
The object type RetryManager&lt;E&gt;, where E is a a subtype of
<code>error</code>, is described by the following object type descriptor:
</p>

<pre>object {
   public function shouldRetry(E e) returns boolean;
}
</pre>
<p>
Note that RetryManager&lt;E&gt; is contravariant in E i.e. RetryManager&lt;E&gt;
is a subtype of RetryManager&lt;E'&gt; if and only if E' is a subtype of E.
</p>

</section>

</section>
<section>
<h3>Abstract operations</h3>
<p>
These section specifies a number of operations that can be performed on values.
These operations are for internal use by the specification. These operations are
named in CamelCase with an initial upper-case letter to distinguish them from
functions in the lang library.
</p>
<section>
<h4 id="FillMember">FillMember</h4>
<p>
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.
</p>
<table>
<tr>
<th>Type descriptor</th>
<th>Filler value</th>
<th>When available</th>
</tr>
<tr>
<td><code>()</code></td>
<td><code>()</code></td>
<td></td>
</tr>
<tr>
<td><code>boolean</code></td>
<td><code>false</code></td>
<td></td>
</tr>
<tr>
<td><code>int</code></td>
<td><code>0</code></td>
<td></td>
</tr>
<tr>
<td><code>float</code></td>
<td><code>+0.0f</code></td>
<td></td>
</tr>
<tr>
<td><code>decimal</code></td>
<td><code>+0d</code></td>
<td></td>
</tr>
<tr>
<td><code>string</code></td>
<td><code>""</code></td>
<td></td>
</tr>
<tr>
<td>array or tuple type descriptor</td>
<td><code>[]</code></td>
<td>if that is a valid constructor for the type</td>
</tr>
<tr>
<td>map or record type descriptor</td>
<td><code>{ }</code></td>
<td>if that is a valid constructor for the type</td>
</tr>
<tr>
<td><code>readonly &amp; T</code></td>
<td>the filler value for T constructed as read-only</td>
<td>if that belongs to the type</td>
</tr>
<tr>
<td>table</td>
<td>empty table (with no rows)</td>
<td></td>
</tr>
<tr>
<td>object</td>
<td><code>new T()</code></td>
<td>if T is a class, where T is the type descriptor for the object, and the
static type of T's init method allows no arguments and does not include error</td>
</tr>
<tr>
<td>stream</td>
<td>empty stream</td>
<td></td>
</tr>
<tr>
<td><code>xml</code></td>
<td><code>xml``</code></td>
<td></td>
</tr>
<tr>
<td>built-in subtype of <code>xml</code></td>
<td><code>xml``</code></td>
<td>if this belongs to the subtype, i.e. if the subtype is
<code>xml:Text</code></td>
</tr>
<tr>
<td><code>regexp:RegExp</code></td>
<td><code>re``</code></td>
<td></td>
</tr>
<tr>
<td>singleton</td>
<td>the single value used to specify the type</td>
<td></td>
</tr>
<tr>
<td rowspan="2">union</td>
<td><code>()</code></td>
<td>if <code>()</code> is a member of the union</td>
</tr>
<tr>
<td>the filler value for basic type B</td>
<td>if all members of the union belong to a single basic type B,
and the filler value for B also belongs to the union</td>
</tr>
<tr>
<td><code>T?</code></td>
<td><code>()</code></td>
<td></td>
</tr>
<tr>
<td><code>any</code></td>
<td><code>()</code></td>
<td></td>
</tr>
<tr>
<td><code>anydata</code></td>
<td><code>()</code></td>
<td></td>
</tr>
<tr>
<td><code>byte</code></td>
<td><code>0</code></td>
<td></td>
</tr>
<tr>
<td>built-in subtype of <code>int</code></td>
<td><code>0</code></td>
<td></td>
</tr>
<tr>
<td><code>json</code></td>
<td><code>()</code></td>
<td></td>
</tr>
</table>

</section>
<section>
<h4 id="Cloning">Cloning</h4>
<p>
There are two cloning operations. Both of these operate on values belonging to the
Cloneable type defined as follows:
</p>
<pre>
public type Cloneable readonly|xml|Cloneable[]|map&lt;Cloneable&gt;|table&lt;map&lt;Cloneable&gt;&gt;;
</pre>
<p>
This type is defined in the lang.value module of the lang library. In this document,
the type will be referred to as <code>value:Cloneable</code>.
</p>

<section>
<h5 id="Clone">Clone</h5>
<p>
Clone(v) is defined for any value v that belongs to the type
<code>value:Cloneable</code>. It performs a deep copy, recursively copying all
structural values and their members and recursively copying all sequence values
and their constituents. Clone(v) for an immutable value v returns v. If v is of
a basic type that has an inherent type, Clone(v) has the same inherent type as
v. The graph of references of Clone(v) must have the same structure as that of
v. This implies that the number of distinct references reachable from Clone(v)
must be the same as the number of distinct references reachable from v. Clone(v)
must terminate even if v has cycles.
</p>
<p>
Clone(v) cannot be implemented simply by recursively calling Clone on all
members of v. Rather Clone must maintain a map that records the result of
cloning each reference value. When a Clone operation starts, this map as empty.
When cloning a reference value, it must use the result recorded in the map if
there is one.
</p>
<p>
The Clone operation is exposed by the <code>clone</code> function in the
lang.value module of the lang library.
</p>
</section>
<section>
<h5 id="ImmutableClone">ImmutableClone</h5>
<p>
ImmutableClone(v) is defined for any value v that belongs to the type
<code>value:Cloneable</code>. It performs a deep copy of v similar to Clone(v),
except that newly constructed values will be constructed as immutable and so
have their read-only bit on. Any immutable value is not copied. So the result
of Immutable always has its read-only bit on.
</p>
<p>
Like Clone, ImmutableClone must preserve graph structure, including cycles.
Conceptually the whole graph is constructed before being made immutable.
</p>
<p>
The ImmutableClone operation is exposed by the <code>cloneReadOnly</code>
function in the lang.value module of the lang library.
</p>
</section>
</section>
<section>
<h4 id="DeepEquals">DeepEquals</h4>
<p>
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.
</p>
<p>
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.
</p>
<p>
DeepEquals(Clone(x), x) is guaranteed to be true for any value of type anydata.
</p>
</section>
<section>
<h4>NumericConvert</h4>
<p>
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.
</p>
<table>
  <tr>
   <td>from \ to</td>
   <td>float</td>
   <td>decimal</td>
   <td>int</td>
  </tr>
  <tr>
   <td>float</td>
   <td>unchanged</td>
   <td>closest math value</td>
   <td rowspan="2">round, error for NaN or out of int range</td>
  </tr>
  <tr>
   <td>decimal</td>
   <td>closest math value</td>
   <td>unchanged</td>
  </tr>
  <tr>
   <td>int</td>
   <td>same math value</td>
   <td>same math value</td>
   <td>unchanged</td>
  </tr>
</table>
</section>
<section>
<h4 id="ToString">ToString</h4>
<p>
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.
</p>
<ul>
<li>expression style: produces a string that looks like a Ballerina expression; there are
two cases
<ul>
<li>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</li>
<li>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</li>
</ul>
</li>
<li>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</li>
<li>direct style: this does a direct conversion of the value to a string rather than producing
a string that describes the value
<ul>
<li>if v is a string, then the result of ToString(v,direct) is v</li>
<li>if v is XML, then the result of ToString(v,direct) is v in XML syntax</li>
<li>direct style falls back to informal style for basic types where there is no
other natural more direct conversion</li>
</ul>
</li>
</ul>
<p>
The following table summarizes the result of ToString(v,style) for each basic type.
</p>
<table>
  <tr>
   <td rowspan="2">Basic type of v
   </td>
   <td colspan="3">style
   </td>
  </tr>
  <tr>
   <td>expression
   </td>
   <td>informal
   </td>
   <td>direct
   </td>
  </tr>
  <tr>
   <td>nil
   </td>
   <td><code>()</code>
   </td>
   <td><code>null</code>
   </td>
   <td>
   </td>
  </tr>
  <tr>
   <td>true
   </td>
   <td colspan="3"><code>true</code>
   </td>
  </tr>
  <tr>
   <td>int
   </td>
   <td colspan="3"><code>2</code>
   </td>
  </tr>
  <tr>
   <td rowspan="3">float
   </td>
   <td colspan="3"><code>1.0</code>
   </td>
  </tr>
  <tr>
   <td><code>float:NaN</code>
   </td>
   <td colspan="2"><code>NaN</code>
   </td>
  </tr>
  <tr>
   <td><code>float:Infinity</code>
   </td>
   <td colspan="2"><code>Infinity</code>
   </td>
  </tr>
  <tr>
   <td rowspan="2">decimal
   </td>
   <td><code>1d</code>
   </td>
   <td colspan="2"><code>1</code>
   </td>
  </tr>
  <tr>
   <td><code>1.20d</code>
   </td>
   <td colspan="2"><code>1.20</code>
   </td>
  </tr>
  <tr>
   <td>string
   </td>
   <td colspan="2"><code>"xyz"</code>
   </td>
   <td><code>xyz</code>
   </td>
  </tr>
  <tr>
   <td>xml
   </td>
   <td><code>xml`&lt;d>t&lt;/d>`</code>
   </td>
   <td><code>`&lt;d>t&lt;/d>`</code>
   </td>
   <td><code>&lt;d>t&lt;/d></code>
   </td>
  </tr>
  <tr>
   <td>tagged data type
   </td>
   <td><code>re`xyz`</code>
   </td>
   <td><code>`xyz`</code>
   </td>
   <td><code>xyz</code>
   </td>
  </tr>
  <tr>
   <td rowspan="2">array
   </td>
   <td colspan="3"><code>[<var>X</var>,<var>Y</var>]</code>
   </td>
  </tr>
  <tr>
   <td><var>X</var>, <var>Y</var> expression style
   </td>
   <td colspan="2"><var>X</var>,<var>Y</var> informal style
   </td>
  </tr>
  <tr>
   <td rowspan="2">map
   </td>
   <td colspan="3"><code>{"x":<var>X</var>,"y":<var>Y</var>}</code>
   </td>
  </tr>
  <tr>
   <td><var>X</var>, <var>Y</var> expression style
   </td>
   <td colspan="2"><var>X</var>,<var>Y</var> informal style
   </td>
  </tr>
  <tr>
   <td rowspan="2">table
   </td>
   <td><code>table key(k) [<var>R<sub>1</sub></var>,<var>R<sub>2</sub></var>]</code>
   </td>
   <td colspan="2"><code>[<var>R<sub>1</sub></var>,<var>R<sub>2</sub></var>]</code>
   </td>
  </tr>
  <tr>
   <td><var>R<sub>1</sub></var>,<var>R<sub>2</sub></var> expression style
   </td>
   <td colspan="2"><var>R<sub>1</sub></var>,<var>R<sub>2</sub></var> informal style
   </td>
  </tr>
  <tr>
   <td rowspan="3">error
   </td>
   <td colspan="3"><code>error D<sub>1</sub>&amp;D<sub>2</sub> (M,C,F<sub>1</sub>=V<sub>1</sub>,F<sub>2</sub>=V<sub>2</sub>)</code>
   </td>
  </tr>
  <tr>
   <td>V<sub>1</sub>, V<sub>2</sub> expression style, D<sub>1</sub>,D<sub>2</sub>  in the form <code>{<var>module-id</var>}<var>local-id</var></code>, M expression style, C expression style
   </td>
   <td colspan="2">V<sub>1</sub>, V<sub>2</sub> informal style, just local id of D<sub>1</sub>,D<sub>2</sub>, M informal style, C informal style
   </td>
  </tr>
  <tr>
   <td colspan="3">D<sub>1</sub>,D<sub>2</sub> are type-ids, M is the error message, C is the error cause, F<sub>1</sub>=V<sub>1</sub>,F<sub>2</sub>=V<sub>2</sub> are field names and values of the error detail
   </td>
  </tr>
  <tr>
   <td>object w/o toString method
   </td>
   <td colspan="3"><code>object D1&amp;D2 U</code> where U is an identifier that uniquely identifies the object (objects will have the same identifier only if they are <code>===</code>)
   </td>
  </tr>
  <tr>
   <td rowspan="2">object with toString method
   </td>
   <td><code>object S</code>
   </td>
   <td colspan="2"><code>S</code>
   </td>
  </tr>
  <tr>
    <td colspan="3"><code>S</code> in direct style where S is the result of calling the toString method</td>
  </tr>
  <tr>
   <td>behavioural type other than error or object</td>
   <td colspan="3">identifier for behavioural type (<code>function</code>,
     <code>future</code>, <code>typedesc</code>, <code>stream</code> or <code>handle</code>) followed
     by implementation-dependent string
   </td>
  </tr>
  <tr>
   <td rowspan="2"><em>cycle detected</em>
   </td>
   <td><code>...[N]</code>
   </td>
   <td colspan="2"><code>...</code>
   </td>
  </tr>
  <tr>
   <td>N is 0-based index down path from root object to object where cycle is detected
   </td>
   <td colspan="2">
   </td>
  </tr>
</table>
</section>
<section>
<h4 id="ordering">Ordering</h4>
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
If C is any of the three abstract operations, and there is an ordered type to
which both x and y belong, then:
</p>
<ul>
<li>C(x, y) is LT if and only if C(y, x) is GT</li>
<li>C(x, y) is EQ if and only if C(y, x) is EQ</li>
<li>C(x, y) is UN if and only if C(y, x) is UN</li>
</ul>
<p>
The most straightforward ordered types are basic types where all the values of
the type can be put into an order. These types are nil, boolean, int, string. For
each of these three types, for any pair of values x, y belonging to the type
</p>
<ul>
<li>Compare(x, y) is EQ if x and y are the same value</li>

<li>Compare(x, y) is LT in the following cases: 
<ul>
<li>for int, if x is mathematically less than y</li>
<li>for boolean, if x is false and y is true</li>
<li>for string, if x is lexicographically less than y in Unicode code point
order, more precisely, if
<ul>
<li>x is an proper initial substring of y, or</li>
<li>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</li>  
</ul>
</li>  
</ul>
</li>
<li>CompareA(x,y), and CompareD(x,y) have the same value as Compare(x, y)</li>
</ul>
<p>
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.
</p>
<p>
The basic type float is also ordered. Compare(x,y) is as defined by IEEE
754-2008 clause 5.11. In particular:
</p>
<ul>
<li>the Compare operation does not distinguish +0 from -0 i.e.
Compare(-0.0,+0.0) is EQ</li>
<li>Compare(x, y) is UN if x or y or both is NaN</li>
</ul>
<p>
When x and y belong to type float, CompareA(x, y) and CompareD(x, y) differ from
Compare(x, y) as follows:
</p>
<ul>
<li>CompareA(NaN,NaN) and CompareD(NaN, NaN) are EQ</li>
<li>CompareA(x, NaN) is LT if x is not NaN</li>
<li>CompareD(NaN, x) is LT if x is not NaN</li>
</ul>
<p>
If type T is ordered, then type T? Is also ordered. Comparison operations
involving nil are defined as follows:
</p>
<ul>
<li>Compare((),()), CompareA((),()) and CompareD((),()) are all EQ</li>
<li>Compare(x,()) is UN if x is not ()</li>
<li>CompareA(x,()) is LT if x is not ()</li>
<li>CompareA((), x) is LT if x is not ()</li>
</ul>
<p>
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.
</p>
<p>
The following rules determine when a subtype of list is ordered:
</p>
<ul>
<li>[T...]  is ordered, if T is ordered;</li>
<li>[] is ordered;</li>
<li>[T, rest] is ordered if T is ordered and [rest] is ordered.</li>
</ul>
<p>
Each of the three abstract operations C are extended to apply to lists as
follows:
</p>
<ul>
<li>C([], []) is EQ;</li>
<li>C([], [y1,...]) is LT;</li>
<li>C([x1,x2,...],[y1, y2...]) is r unless r is EQ and otherwise C([x2,...],[y2,...]), where r is C(x1, y1).</li>
</ul>
</section>
</section>
<section>
<h3>Binding patterns, variables and identifiers</h3>
<section>
<h4>Binding patterns</h4>
<p>
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.
</p>

<pre
class="grammar">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 := <code>_</code>
list-binding-pattern := <code>[</code> list-member-binding-patterns <code>]</code>
list-member-binding-patterns :=
   binding-pattern (<code>,</code> binding-pattern)* [<code>,</code> rest-binding-pattern]
   | [ rest-binding-pattern ]
mapping-binding-pattern := <code>{</code> field-binding-patterns <code>}</code>
field-binding-patterns :=
   field-binding-pattern (<code>,</code> field-binding-pattern)* [<code>,</code> rest-binding-pattern]
   | [ rest-binding-pattern ] 
field-binding-pattern :=
   field-name <code>:</code> binding-pattern
   | variable-name
rest-binding-pattern := <code>...</code> variable-name
error-binding-pattern := <code>error</code> [error-type-reference] <code>(</code> error-arg-list-binding-pattern <code>)</code>
error-type-reference := type-reference
error-arg-list-binding-pattern :=
   error-message-binding-pattern [<code>,</code> error-cause-binding-pattern] [<code>,</code> 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 (<code>,</code> named-arg-binding-pattern)* [<code>,</code> rest-binding-pattern]
   | rest-binding-pattern
named-arg-binding-pattern := arg-name <code>=</code> binding-pattern
</pre>
<p>
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.
</p>
<p>
A binding pattern matches a value in any of the following cases.
</p>
<ul>
<li>a capture-binding-pattern always matches a value and causes the matched
value to be assigned to named variable;</li>
<li>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;</li>
<li>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 <code>...v</code>, 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 <code>v</code>;</li>
<li>a mapping-binding-pattern { f<sub>1</sub>: p<sub>1</sub>, f<sub>2</sub>:
p<sub>2</sub>, ..., f<sub>n</sub>: p<sub>n</sub>, r } matches a mapping value m
if each field-binding-pattern f<sub>i</sub>: p<sub>i</sub> matches m for each i
in 1 to n; if r is <code>...v</code> then a successful match causes a new
mapping value consisting of all fields other than f<sub>1</sub> to f<sub>n</sub>
to be assigned to <code>v</code>;</li>
<li>a field-binding-pattern f: p matches a mapping value m if
<ul>
<li>m contains a field f and p matches its value; or</li>
<li>m does not have a field f and p matches nil; this case is applied only when
the field-binding-pattern is used in a context where it is known at compile-time
that the field f is optional and cannot have the value nil;</li>
</ul>
</li>
<li>a field-binding-pattern consisting of just a variable-name <code>x</code>
is equivalent to a field-binding-pattern <code>x: x</code>;</li>
<li>an error-binding-pattern error ET(p<sub>m</sub>, p<sub>c</sub>,
f<sub>1</sub> = p<sub>1</sub>, f<sub>2</sub> = p<sub>2</sub>, ..., f<sub>n</sub>
= p<sub>n</sub>, r) matches an error value e if
<ul>
<li>e has a message that matches p<sub>m</sub>,</li>
<li>if p<sub>c</sub> is present, e has a cause that matches p<sub>c</sub>,</li>
<li>e has a detail record that has fields f<sub>1</sub>, f<sub>2</sub>, ... ,
f<sub>n</sub> such that p<sub>i</sub> matches the value of field f<sub>i</sub>
for each i in 1 to n,</li>
<li>if ET is present, the shape of e is in ET,</li>
<li>if r is <code>...v</code>, then a successful match causes a new mapping
value consisting of all fields of the detail record other than f<sub>1</sub>,
f<sub>2</sub>, ... , f<sub>n</sub> to be assigned to <code>v</code>;</li>
</ul>
</li>
</ul>
<p>
All the variables in a binding-pattern must be distinct e.g. [x, x] is not
allowed.
</p>
<p>
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.
</p>
<ul>
<li>for a capture-binding-pattern, the type descriptor is the type descriptor
for that variable;</li>
<li>for a wildcard-binding-pattern, the type descriptor is any</li>
<li>for a list-binding-pattern, the type descriptor is a tuple type descriptor;</li>
<li>for a mapping-binding-pattern, the type descriptor is a record type
descriptor;</li>
<li>for an error-binding-pattern, the type descriptor is an error type
descriptor.</li>
</ul>

</section>
<section>
<h4>Typed binding patterns</h4>

<pre
class="grammar">typed-binding-pattern := inferable-type-descriptor binding-pattern
inferable-type-descriptor := type-descriptor | <code>var</code>
</pre>
<p>
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
<code>var</code> is used instead of a type-descriptor, it means the type is
inferred.
</p>
<p>
There are two ways in which a typed-binding-pattern can be used.
</p>
<ul>
<li><em>Single use</em>. In the language syntax, this kind of use of a
typed-binding-pattern is usually followed by <code>=</code> (the only case where
it is not followed by <code>=</code> is when it follows <code>on fail</code>).
The typed-binding-pattern is matched once against the result of evaluating an
expression. When <code>var</code> is used, the type is inferred from the static
type of the expression (in the <code>on fail</code> case there can be multiple
expressions from which it is inferred); in this case, it is an error if the
intersection of <code>error</code> and the inferred type is non-empty, the
binding-pattern of the typed-binding-pattern is a capture-binding-pattern, and
the variable referenced in the capture-binding-pattern is not used. It is an
error if the type-descriptor in the typed-binding-pattern is
<code>never</code>.</li>
<li><em>Iterative use</em>. In the language syntax, this kind of use of a
typed-binding-pattern is followed by the <code>in</code> keyword. An iterator is
created from the result of evaluating an expression, and the
typed-binding-pattern is matched against each value returned by the iterator.
When <code>var</code> is used, the type is inferred to be T, where the static
type of the expression is an iterable type with value type T.</li>
</ul>
<p>
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.
</p>
<p>
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.
</p>
</section>
<section>
<h4>Variable and identifier scoping</h4>
<p>
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.
</p>
<p>
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
<code>public</code>, it can also be referenced from outside the module.
</p>
<p>
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:
</p>
<ul>
<li>the <em>main</em> symbol space includes identifiers for variables,
constants, types, functions and other identifiers that do not belong to any of
the other two symbol spaces;</li>
<li>the <em>prefix</em> symbol space contains prefixes declared by import
declarations and XML namespace declaration statements;</li>
<li>the <em>annotation tag</em> symbol space contains annotation tags declared
by annotation declarations.</li>
</ul>
<p>
The prefix symbol space is special in that it is associated with a source part
rather than a module.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>

<pre
class="grammar">qualified-identifier := module-prefix NoSpaceColon identifier
module-prefix := identifier | predeclared-prefix
</pre>
<p>
A <code>module-prefix</code> is a name that is used locally within the source of
a module to refer to another module. A <code>module-prefix</code> in a
qualified-identifier must refer to a <code>module-prefix</code> specified in an
import declaration in the same source part.
</p>

</section>
</section>
</section>
<section>
<h2 id="expressions">6. Expressions</h2>

<pre
class="grammar">expr-only := 
   literal
   | template-expr
   | structural-constructor-expr
   | object-constructor-expr
   | new-expr
   | variable-reference-expr
   | field-access-expr
   | optional-field-access-expr
   | xml-attribute-access-expr
   | annot-access-expr
   | member-access-expr
   | function-call-expr
   | method-call-expr
   | error-constructor-expr
   | anonymous-function-expr
   | let-expr
   | typeof-expr
   | unary-logical-expr
   | nil-lifted-expr
   | range-expr
   | relational-expr
   | is-expr
   | equality-expr
   | logical-expr
   | conditional-expr
   | xml-navigate-expr
   | transactional-expr

expression :=
   expr-only
   | type-cast-expr
   | checking-expr
   | trap-expr
   | query-expr
   | <code>(</code> expression <code>)</code>
</pre>
<p>
For simplicity, the expression grammar is ambiguous. The following table shows
the various types of expression in decreasing order of precedence, together with
associativity.
</p>
<table>
  <tr>
   <td><strong>Operator</strong></td>
   <td><strong>Associativity</strong></td>
  </tr>
  <tr>
   <td>
<code>m:x</code>
<br />
<code>x.k</code>
<br />
<code>x.@a</code>
<br />
<code>f(x)</code>
<br />
<code>x.f(y)</code>
<br />
<code>x[y]</code>
<br />
<code>new T(x)</code>
   </td>
   <td></td>
  </tr>
  <tr>
   <td>
<code>+x</code>
<br />
<code>-x</code>
<br />
<code>~x</code>
<br />
<code>!x</code>
<br />
<code>&lt;T&gt; x</code>
<br />
<code>typeof x</code>
<br />
<code>check x</code>
<br />
<code>checkpanic x</code>
   </td>
   <td></td>
  </tr>
  <tr>
   <td>
<code>x * y</code>
<br />
<code>x / y</code>
<br />
<code>x % y</code>
   </td>
   <td>left</td>
  </tr>
  <tr>
   <td><code>x + y</code>
<br />
<code>x - y</code>
   </td>
   <td>left</td>
  </tr>
  <tr>
   <td>
<code>x &lt;&lt; y</code>
<br />
<code>x &gt;&gt; y</code>
<br />
<code>x &gt;&gt;&gt; y</code>
   </td>
   <td>left</td>
  </tr>
  <tr>
   <td>
<code>x ... y</code>
<br />
<code>x ..&lt; y</code>
   </td>
   <td>non</td>
  </tr>
  <tr>
   <td>
<code>x &lt; y</code>
<br />
<code>x &gt; y</code>
<br />
<code>x &lt;= y</code>
<br />
<code>x &gt;= y</code>
<br />
<code>x is y</code>
<br />
<code>x !is y</code>
   </td>
   <td>non</td>
  </tr>
  <tr>
   <td>
<code>x == y</code>
<br />
<code>x != y</code>
<br />
<code>x === y</code>
<br />
<code>x !== y</code>
   </td>
   <td>left</td>
  </tr>
  <tr>
   <td><code>x &amp; y</code></td>
   <td>left</td>
  </tr>
  <tr>
   <td><code>x ^ y</code></td>
   <td>left</td>
  </tr>
  <tr>
   <td><code>x | y</code>
   </td>
   <td>left</td>
  </tr>
  <tr>
   <td><code>x &amp;&amp; y</code></td>
   <td>left</td>
  </tr>
  <tr>
   <td><code>x || y</code></td>
   <td>left</td>
  </tr>
  <tr>
   <td><code>x ?: y</code></td>
   <td>right</td>
  </tr>
  <tr>
   <td><code>x ? y : z</code></td>
   <td>right</td>
  </tr>
  <tr>
   <td>
<code>(x) => y</code>
<br />
<code>let x = y in z</code>
<br />
<code>from x in y select z</code>
<br />
<code>trap x</code>
   </td>
   <td>right</td>
  </tr>

</table>
<section>
<h3>Expression evaluation</h3>
<p>
When the evaluation of an expression completes normally, it produces a result,
which is a value. The evaluation of an expression may also complete abruptly.
There are two kinds of abrupt completion: check-fail and panic. With both kinds
of abrupt completion there is an associated value, which always has basic type
error.
</p>
<p>
The following sections describes how each kind expression is evaluated, assuming
that evaluation of subexpressions complete normally. Except where explicitly
stated to the contrary, expressions handle abrupt completion of subexpressions
as follows. If in the course of evaluating an expression E, the evaluation of
some subexpression E1 completes abruptly, then the evaluation of E also
completes abruptly in the same way as E1.
</p>
</section>
<section>
<h3>Static typing of expressions</h3>
<p>
A type is computed for every expression at compile time; this is called the
static type of the expression. The compiler and runtime together guarantee that
if the evaluation of an expression at runtime completes normally, then the
resulting value will belong to the static type. A type is also computed for
check-fail abrupt completion, which will be a (possibly empty) subtype of error;
however, for panic abrupt completion, no type is computed.
</p>
<p>
It is an error if the static type of an expression is <code>never</code>, except
in cases where the expression is one that this specification explicitly permits
to have static type <code>never</code> and the expression occurs in a context
where this specification explicitly permits an expression with static type
<code>never</code> to occur.
</p>
<p>
The detailed rules for the static typing of expressions are quite elaborate and
are not yet specified completely in this document.
</p>

<section>
<h4 id="lax_static_typing">Lax static typing</h4>
<p>
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 <code>json</code> 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.
</p>
<p>
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.
</p>
<p>
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 <code>json</code> is lax, and
<code>map&lt;T&gt;</code> is lax if T is lax. The only kinds of expression for
which lax typing rules are specified are field-access-expr,
optional-field-access-expr and checking-expr.
</p>

</section>
<section>
<h4>Contextually expected type</h4>
<p>
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 <em>contextually expected type</em>. 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.</p>
<p>
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 <em>applicable</em> 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.
</p>
<p>
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.
</p>
</section>
<section>
<h4>Precise and broad types</h4>
<p>
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.
</p>
<p>
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.
</p>
<p>
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 <code>"X"</code> is the
singleton type <code>"X"</code>, but the broad type is <code>string</code>.
</p>
</section>
<section>
<h4 id="singleton_typing">Singleton typing</h4>
<p>
The specification of a particular kind of compound expression may say that the
static type of the result of an expression E is a type T <em>modified by the
usual singleton typing rules</em>. This means that when all subexpressions of
the compound expression have a singleton type, then the static type of E is a
singleton subtype of T. This subtype is computed by evaluating the expression at
compile-time with operands whose values belong to the corresponding singleton
types.
</p>
</section>
<section>
<h4 id="nil_lifting">Nil lifting</h4>

<pre
class="grammar">nil-lifted-expr := 
  unary-numeric-expr
  | multiplicative-expr
  | additive-expr
  | shift-expr
  | binary-bitwise-expr
</pre>
<p>
A <code>nil-lifted-expr</code> supports nil lifting for its operands. This means
that the operators used in a <code>nil-lifted-expr</code> have two forms: an
underlying form and a lifted form. The underlying form of the operator is used
when the static type of the subexpressions for all operands does not allow nil;
this form of the operator is described in the section for each kind of operator.
The lifted form of the operator is used when the static type of the
subexpressions for one or more operands does allow nil; the semantics of this
form of the operator are derived from the underlying form as described in this
section.
</p>
<p>
A <code>nil-lifted-expr</code> is evaluated by evaluating the subexpressions for
every operand. If the result of any of these evaluations is nil, then the result
of the <code>nil-lifted-expr</code> is nil. Otherwise, the evaluation is
completed in the same way as with the underlying form of the operator.
</p>
<p>
The static types of the operand subexpressions with nil removed must be valid
for the underlying form of the operator. The static type of the
<code>nil-lifted-expr</code> is T<code>?</code>, where T is what the static type
of the <code>nil-lifted-expr</code> would be if nil was removed from the static
type of the operand subexpressions, except that the usual <a
href="#singleton_rules">singleton typing</a> rules are not applied in computing
T. (The singleton typing rules are applied to the static types before the
removal of nil and thus have no effect, because the lifted form of the operator
is never applicable when all operands have singleton type.)
</p>

</section>

<section>
<h4 id="isolated_expressions">Isolated expressions</h4>
<p>
Ballerina defines requirements for when an expression is <em>isolated</em>. If
an expression meets the requirements, then it is compile-time guaranteed that
the value of the expression will be an isolated root and will not be aliased.
</p>
<p>
If the static type of an expression is immutable, i.e. a subtype of
<code>readonly</code>, or an isolated object, i.e. a subtype of <code>isolated
object {}</code>, then the expression is isolated.
</p>
<p>
Also, an expression of one of the following syntactic kinds is isolated if all
its subexpressions are isolated (regardless of its static type):
</p>
<ul>
<li><code>list-constructor-expr</code></li>
<li><code>table-constructor-expr</code></li>
<li><code>mapping-constructor-expr</code></li>
<li><code>template-expr</code></li>
<li><code>type-cast-expr</code></li>
<li><code>checking-expr</code></li>
<li><code>trap-expr</code></li>
<li><code>conditional-expr</code></li>
</ul>
<p>
The section for each kind of expression will describe any alternative conditions
under which that kind of expression is also isolated.
</p>
</section>
</section>
<section>
<h3>Casting and conversion</h3>
<p>
Ballerina makes a sharp distinction between type conversion and type casting.
</p>
<p>
Casting a value does not change the value. Any value always belongs to multiple
types. Casting means taking a value that is statically known to be of one type,
and using it in a context that requires another type; casting checks that the
value is of that other type, but does not change the value.
</p>
<p>
Conversion is a process that takes as input a value of one type and produces as
output a possibly distinct value of another type. Note that conversion does not
mutate the input value.
</p>
<p>
Ballerina always requires programmers to make conversions explicit, even between
different types of number; there are no implicit conversions.
</p>
</section>
<section>
<h3>Constant expressions</h3>

<pre
class="grammar">const-expr := 
   literal
   | template-expr
   | structural-constructor-expr
   | constant-reference-expr
   | type-cast-expr
   | unary-logical-expr
   | nil-lifted-expr
   | range-expr
   | relational-expr
   | is-expr
   | equality-expr
   | logical-expr
   | conditional-expr
   | <code>(</code> const-expr <code>)</code>
</pre>
<p>
A value resulting from the evaluation of a <code>const-expr</code> always has
its read-only bit on.
</p>
<p>
Within a <code>const-expr</code>, any nested expression must also be a
const-expr.
</p>

<pre
class="grammar">constant-reference-expr := variable-reference-expr
</pre>
<p>
A <code>constant-reference-expr</code> must reference a constant defined with
<code>module-const-decl</code>.
</p>
<p>
A <code>const-expr</code> is evaluated at compile-time. Constructors called
within a <code>const-expr</code> construct their values as immutable. Note that
the syntax of const-expr does not allow for the construction of error values.
The result of a <code>const-expr</code> is always immutable.
</p>

<pre
class="grammar">simple-const-expr :=
  nil-literal
  | boolean-literal
  | [Sign] int-literal
  | [Sign] floating-point-literal
  | string-literal
  | constant-reference-expr
</pre>
<p>
A simple-const-expr is a restricted form of const-expr used in contexts where
various forms of constructor expression would not make sense. Its semantics are
the same as a const-expr.
</p>
</section>
<section>
<h3>Literals</h3>

<pre
class="grammar">literal :=
   nil-literal
   | boolean-literal
   | numeric-literal
   | string-literal
   | byte-array-literal
numeric-literal := int-literal | floating-point-literal
</pre>
<p>
A numeric-literal represents a value belonging to one of the basic types int,
float or decimal. The basic type to which the value belongs is determined in
three stages.
</p>
<ol>
<li>The syntactic form of numeric literal determines which of int, float and
decimal are candidates:
<ul>
<li>if the numeric-literal includes a <code>FloatTypeSuffix</code> or is a
<code>HexFloatingPointLiteral</code>, then the the only candidate is float;</li>
<li>if the numeric-literal includes a <code>DecimalTypeSuffix</code>, then the
only candidate is decimal;</li>
<li>otherwise, if the numeric-literal is a <code>floating-point-literal</code>,
the candidates are float and decimal;</li>
<li>otherwise, all three basic types are candidates.</li>
</ul>
</li>
<li>Any candidate basic type N such that the intersection of N with the
contextually expected type is empty is eliminated, unless this would eliminate
all candidates remaining after the first stage.</li>
<li>From remaining candidates, the first in the order int, float, decimal is
selected.</li>
</ol>
<p>
The precise type of a numeric-literal is the singleton type containing just the
shape of the value that the numeric-literal represents. The broad type is
the basic type of which the precise type is a subset.
</p>

<pre
class="grammar">byte-array-literal := Base16Literal | Base64Literal
Base16Literal := <code>base16</code> WS <code>`</code> HexGroup* WS <code>`</code>
HexGroup := WS HexDigit WS HexDigit
Base64Literal := <code>base64</code> WS <code>`</code> Base64Group* [PaddedBase64Group] WS <code>`</code>
Base64Group :=
   WS Base64Char WS Base64Char WS Base64Char WS Base64Char
PaddedBase64Group :=
   WS Base64Char WS Base64Char WS Base64Char WS PaddingChar
   | WS Base64Char WS Base64Char WS PaddingChar WS PaddingChar
Base64Char := <code>A</code> .. <code>Z</code> | <code>a</code> .. <code>z</code> | <code>0</code> .. <code>9</code> | <code>+</code> | <code>/</code>
PaddingChar := <code>=</code>
WS := WhiteSpaceChar*
</pre>
<p>
Let N be number of bytes encoded by the Base16Literal or Base64Literal. If the
applicable contextually expected type is a subtype of readonly or if the
byte-array-literal occurs within a const-expr, then the literal constructs a
list value with its read-only bit set; in this case, the static type of the
byte-array-literal is a singleton subtype of <code>readonly &amp;
byte[N]</code>. Otherwise, the static type of byte-array-literal is
<code>byte[N]</code>, and the inherent type of the list value created is also
<code>byte[N]</code>.
</p>
</section>
<section>
<h3>Template expressions</h3>
<p>
Template expressions make use of strings enclosed in backticks with interpolated
expressions.
</p>
<pre
class="grammar">BacktickString :=
  <code>`</code> BacktickItem* Dollar* <code>`</code>
BacktickItem :=
   BacktickSafeChar
   | BacktickDollarsSafeChar
   | Dollar* interpolation
interpolation := <code>${</code> expression <code>}</code>
BacktickSafeChar := ^ ( <code>`</code> | <code>$</code> )
BacktickDollarsSafeChar :=  <code>$</code>+ ^ ( <code>{</code> | <code>`</code> | <code>$</code>)
Dollar := <code>$</code>
</pre>

<pre
class="grammar">template-expr := 
   string-template-expr
   | xml-template-expr
   | tagged-data-template-expr
   | raw-template-expr
</pre>

<section>
<h4>String template expression</h4>

<pre
class="grammar">string-template-expr := <code>string</code> BacktickString
</pre>
<p>
A <code>string-template-expr</code> interpolates the results of evaluating
expressions into a literal string. The static type of the expression in each
interpolation must be a subtype of
<code>boolean|int|float|decimal|string</code>. Within a
<code>BacktickString</code>, every character that is not part of an
<code>interpolation</code> 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 <a href="#ToString">ToString</a> abstract
operation with the direct style. The result of evaluating the
<code>string-template-expr</code> 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 <code>BacktickString</code>.
</p>
<p>
The static type of the result of the string-template-expr is
<code>string</code>, modified by the usual <a href="#singleton_rules">singleton
typing</a> rules.
</p>
<p>
A literal <code>`</code> can be included in string template by using an
interpolation <code>${"`"}</code>.
</p>
</section>
<section>
<h4>XML template expression</h4>

<pre
class="grammar">xml-template-expr := <code>xml</code> BacktickString
</pre>
<p>
An XML template expression constructs an xml value as follows:
</p>
<ol>
<li>The backtick string is parsed to produce a string of literal characters with
interpolated expressions</li>
<li>The result of the previous step is parsed as XML content. More precisely, it
is parsed using the production <code>content</code> 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.</li>
<li>This infoset is then converted to an xml value, as described in the <a
href="#XML">XML type</a> 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.</li>
<li>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.</li>
<li>When the xml-template-expr is evaluated, the interpolated expressions are
evaluated in the order in which they occur in the <code>BacktickString</code>,
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. The contextually expected type for an interpolated expression that
occurs within an Attribute Information Item is string, and otherwise is xml;
this ensures that a query expr will work as expected. Note that if the static
type is not a subtype of the contextually expected type, it is not an error:
rather the value will be converted to a string.</li>
</ol>
<p>
An xml-template-expr occurring within a const-expr will construct an xml value
that has its read-only bit on.
</p>
</section>

<section>
<h4>Tagged data template expression</h4>

<pre
class="grammar">tagged-data-template-expr := data-tag BacktickString
data-tag := identifier
</pre>
<p>
A tagged-data-template-expr with data tag <var>t</var> constructs a tagged data
value of the basic type corresponding to <var>t</var>. The data-tag identifier
must be the name of a data tag by this specification or the Ballerina platform.
</p>
<p>
The BacktickString is parsed in two stages:
</p>
<ol>
<li>the BacktickString is parsed resulting in a sequence of literal characters
and interpolations, represented as an array of <var>n</var> expressions, one for
each interpolation, and an array of <var>n</var> + 1 strings, where the
interpolations occur between the strings;</li>
<li>the array of strings is parsed using the abstract parsing function defined
for the data tag; it is a compile-time error if the abstract parsing function
returns an error.</li>
</ol>
<p>
The static type of the expression in an interpolation must be the data tag's
basic type. When the tagged-data-template-expr is evaluated, each expression in
an interpolation is evaluated in order. The result of evaluating the
tagged-data-template-expr is the result of applying the function that was
created by the abstract parsing function at compile-time to the values resulting
from the evaluation of these expressions. Note that the result of evaluating a
tagged-data-template-expr cannot be an error.
</p>

</section>


<section>
<h4>Raw template expression</h4>

<pre
class="grammar">raw-template-expr := BacktickString
</pre>
<p>
A raw-template-expr constructs an object belonging to the abstract RawTemplate
object type.
</p>
<p>
A raw-template-expr is evaluated by
</p>
<ul>
<li>constructing an array <var>v</var> whose members are the result of
evaluating each interpolation's expression in the order in which they occur in
the BacktickString;</li>
<li>constructing an object with two fields
<ul>
<li>an <code>insertions</code> field with value <var>v</var></li>
<li>a <code>strings</code> 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 <var>v</var>.</li>
</ul>
</li>
</ul>
<p>
The result of the raw-template-expr is the newly constructed object.
</p>
<p>
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
<code>insertions</code> 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 <code>strings</code> and
<code>insertions</code> fields will be read-only if required by the contextually
expected type. The value of the <code>strings</code> field is constructed once
by the class. The value of the <code>insertions</code> is
constructed once for each evaluation of the raw-template-expr.
</p>

</section>
</section>

<section>
<h3>Structural constructors</h3>
<p>
Each basic type of structure has its own expression syntax for constructing a
value of the type.
</p>
<pre
class="grammar">structural-constructor-expr := list-constructor-expr | table-constructor-expr | mapping-constructor-expr
</pre>

<p>
An structural-constructor-expr occurring within a const-expr will construct a
structural value that has its read-only bit on.
</p>

<section>
<h4>List constructor</h4>

<pre
class="grammar">list-constructor-expr := <code>[</code> [ list-member-list ] <code>]</code>
list-member-list := list-member (<code>,</code> list-member)*
list-member := single-list-member | spread-list-member
single-list-member := expression
spread-list-member := spread | aggregated-variable-reference
spread := <code>...</code> expression
</pre>
<p>
A list-constructor-expr creates a new list value. It is a compile-time error if
the static type of the expression in a spread in a spread-list-member is not a
subtype of list. The list is constructed by processing each list-member in the
order specified as follows. If the list-member is a single-list-member, then the
expression in the list-member is first evaluated resulting in a value
<var>v</var> and <var>v</var> is added to the list being constructed. If the
list-member is a spread, then the expression in the spread is evaluated and each
member of the resulting list is added in order to the list being constructed. An
aggregated-variable-reference is handled like the <a
href="#aggregated_variables">equivalent</a> spread.
</p>
<p>
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 it is a compile-time error unless there is exactly one
member of the union that is a list type descriptor and that allows list shapes
of a length that the static types of the expressions in the list-member-list
make it possible for the constructed list to have; this list type descriptor is
used as the inherent type. If there is a spread, and the type of its
expression is not fixed length, then the minimum of the total number of members
that may be added to the list being constructed by this spread-list-member and
any previous list-member must be greater than or equal to the minimum length
required by the inherent type. The static type of the list-constructor-expr will
be the same as the inherent type.
</p>
<p>
If there is no contextually expected type, then the inherent type will be a
tuple-type-descriptor derived from the static type of each expression in the
list-member-list. Each single-list-member that does not have a preceding
spread-list-member contributes a member-type-descriptor to the
tuple-type-descriptor; the type of the member-type-descriptor will be the broad
type of the expression in the single-list-member. If there is a
spread-list-member, then a tuple-rest-descriptor <code>T...</code> is added
where T is the smallest type such that the broad type of the expression in every
other single-list-member is a subtype of <code>T</code>, and the type of the
expression in each spread-list-member is a subtype of <code>T[]</code>.
</p>
<p>
If the list-constructor-expr does not have a contextually expected type, then
the contextually expected type for the expression in a spread-list-member is
<code>(any|error)[]</code>, and the expression in a single-list-member does not
have a contextually expected type. Otherwise the contextually expected type for
each list-member is derived from the contextually expected type of the
list-constructor-expr. If there is a spread-list-member that is not the last
list-member in the list-member-list, then the contextually expected type used
from that point on is approximated with a tuple-rest-descriptor.
</p>
<p>
A member of a list can be filled in automatically if the <a
href="#FillMember">FillMember</a> 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 <var>k</var> members, provided that for
each <var>i</var> from <var>k</var> + 1 up to the fixed length of the list, the
<var>i</var>-th member can be filled in automatically.
</p>

</section>
<section>
<h4>Mapping constructor</h4>

<pre
class="grammar">mapping-constructor-expr := <code>{</code> [field (<code>,</code> field)*] <code>}</code>
field := 
  specific-field
  | computed-name-field
  | spread-field
specific-field :=
   [<code>readonly</code>] (field-name | string-literal) <code>:</code> value-expr
   | [<code>readonly</code>] variable-name
value-expr := expression
computed-name-field := <code>[</code> field-name-expr <code>]</code> <code>:</code> value-expr
field-name-expr := expression
spread-field := spread
</pre>
<p>
A mapping-constructor-expr creates a new mapping value. 
</p>
<p>
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
<code><var>x</var></code> is equivalent to a field <code><var>x</var>:
<var>x</var></code>.
</p>
<p>
The static type of the expression in a spread-field must allow only mapping
values, i.e. must be a subtype of <code>map&lt;any|error&gt;</code>. 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 <code>record { never
x?; }</code> cannot duplicate a specific field for <code>x</code>.
</p>
<p>
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.
</p>
<p>
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 <code>T...</code>, where <code>T</code> is the union of
the broad types of the value-expr in all such fields.
</p>
<p>
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-field-descriptor for that field.
</p>
<p>
If there is a specific-field with name <code><var>x</var></code> and there is a
contextually expected type that allows an <code><var>x</var></code> field but
does not allow a nil value for the <code><var>x</var></code> field, then the
static type of the value-expr for the <code><var>x</var></code> field may
include nil; if the result of evaluating the value-expr is nil, then no field
will be added to the constructed value.
</p>
<p>
Default values are added to the mapping value being constructed after fields
have been added for every specific-field and spread-field: if the inherent type
descriptor is a record type descriptor, then for each field-descriptor with name
<var>f</var> having a default-expression, if the mapping value so far
constructed does not have a field with name <var>f</var>, then the closure for
the default-expression is evaluated resulting in a value <var>v</var>, and
a field with name <var>f</var> and value <var>v</var> is added to the mapping
value.
</p>
<p>
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&lt;T&gt;,
where the T is the smallest type such that the inherent type is a subtype of
map&lt;T&gt;. The contextually expected type for a field-name-expr is string.
</p>
<p>
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.
</p>
<p>
When the inherent type is equivalent to a map-type-descriptor, the order in
which fields are added to mapping value being constructed (and thus the
iteration order of the fields) is the same as the order of the fields in the
mapping-constructor-expr, except that all fields specified by a
computed-named-field are added after all other fields.
</p>
<p>
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 <code>readonly</code> will
also be constructed with its read-only bit on. The read-only bit of the
mapping value or field will be set only after the mapping value has been fully
constructed, including any field specified by a computed-name-field.
</p>

</section>
<section>
<h4>Table constructor</h4>

<pre
class="grammar">table-constructor-expr := <code>table</code> [key-specifier] <code>[</code> [row-list] <code>]</code>
row-list := mapping-constructor-expr (<code>,</code> mapping-constructor-expr)*
</pre>
<p>
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.
</p>
<p>
For example,
</p>

<pre>table key(email) [
   { email: "sanjiva@weerawarana.org", firstName: "Sanjiva", lastName: "Weerawarana" },
   { email: "jjc@jclark.com", firstName: "James", lastName: "Clark" }
]
</pre>
<p>
The inherent type of the constructed table is a table type descriptor including
a key-specifier <code>table&lt;<var>T</var>&gt; key(<var>ks</var>)</code>, where
<code><var>T</var></code> is the member type and <code><var>ks</var></code> is
the key sequence. The inherent type is determined from the contextually expected
type together with the table-constructor-expr. The static type of the
table-constructor-expr will be the same as this inherent type.
</p>
<p>
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.
</p>
<p>
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
<a href="#tables">table type descriptor</a>. 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.
</p>
<p>
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 row-list; otherwise there is no contextually expected type
for these expressions.
</p>

</section>
</section>

<section>
<h3>Object construction</h3>
<p>
There are two kinds of expression that can be used to construct an object: with
an object constructor expression, the methods and fields of the constructed
object are defined within the expression; with a new expression, the methods and
fields come from a separate, named class definition.
</p>

<section>
<h4>Object constructor</h4>

<pre
class="grammar">object-constructor-expr :=
   [annots] object-type-quals <code>object</code> [type-reference] object-constructor-block
object-constructor-block := <code>{</code> object-member* <code>}</code>
object-member := object-field | method-defn | remote-method-defn | resource-method-defn
</pre>
<p>
The resulting of evaluating an <code>object-constructor-expr</code> is an
object. The <code>object-constructor-expr</code> must specify
<code>client</code> if any <code>method-defn</code> includes a
<code>remote-qual</code>.
</p>
<p>
The annotations applying to the <code>object-constructor-expr</code> and its
members are evaluated when the <code>object-constructor-expr</code> is
evaluated. This means that every object resulting from the evaluation of an
<code>object-constructor-expr</code> has its own type descriptor.
</p>
<p>
If there is a <code>type-reference</code>, then the referenced type is included
in the object's type in the same was as an <code>object-type-inclusion</code>,
and the type-ids of the constructed object are type-ids of the referenced type.
If there is no <code>type-reference</code>, then the applicable contextually
expected type T, if any, must be definite, and the type-ids of the constructed
object are the type-ids, if any, induced by T.
</p>
<p>
The <code>object-constructor-expr</code> is <em>implicitly read-only</em> if the
applicable contextually expected type is a subtype of readonly or if the
<code>type-reference</code> is present and references a type that is a subtype
of readonly. If the <code>object-constructor-expr</code> is <em>implicitly
read-only</em>, then the object will be constructed with its read-only bit on;
furthermore, in this case an <code>object-type-inclusion</code> is allowed to
directly or indirectly reference a readonly class.
</p>
<p>
The <code>object-constructor-expr</code> is <em>explicitly isolated</em> if
<code>object-type-quals</code> includes <code>isolated</code> or if the
type-reference is present and references an isolated object type. An
<code>object-constructor-expr</code> that is explicitly isolated will construct
an object with its isolated bit set.
</p>

<pre
class="grammar">object-visibility-qual := <code>public</code>|<code>private</code>
</pre>

<p>
A visibility qualifier of <code>private</code> can be used within an
<code>object-constructor-expr</code> expression; this means that the visibility
region consists of every method-defn-body in the object-constructor-expr.
</p>

<section>
<h5>Fields</h5>
<pre
class="grammar">object-field :=
   metadata [object-visibility-qual] [<code>final</code>]
   type-descriptor field-name [<code>=</code> field-initializer] <code>;</code>
field-initializer := expression
</pre>
<p>
An <code>object-field</code> declares and initializes a field of the object.
</p>
<p>
If a field does not specify a field-initializer, then there must be an
<code>init</code> method and the <code>init</code> method must initialize the
field. The field-initializer must meet the requirements for an isolated function
unless the <code>init</code> method is present and not declared as
<code>isolated</code>.
If the <code>init</code> method is not present, 
it is a compile-time error if the expression in an
individual-field-descriptor contains a checking-expr with a checking-keyword of
<code>check</code>, i.e. if evaluation of the expression could complete abruptly
with a check-fail.
If the <code>object-constructor-expr</code> is implicitly
read-only, then 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.
</p>
<p>
If <code>final</code> is present, then the field must be assigned to exactly
once, either by its initializer or in the <code>init</code> method.
</p>
<p>
An <code>object-constructor-expr</code> will construct an object with its
read-only bit set if every object-field is declared as <code>final</code> and
has a type-descriptor that is a subtype of <code>readonly</code>. In this case,
the static type of the <code>object-constructor-expr</code> will be intersected
with <code>readonly</code>.
</p>
<p>
An object field is <em>isolated</em> if it is declared as <code>final</code> and
has a type-descriptor that is a subtype of <code>readonly</code> or
<code>isolated object {}</code>, or if the <code>object-constructor-expr</code>
is implicitly read-only. An <code>object-constructor-expr</code> is
<em>implicitly isolated</em> if it is implicitly readonly or if every object
field is isolated. An <code>object-constructor-expr</code> that is implicitly
isolated will construct an object with its isolated bit set. In this case, the
static type of the <code>object-constructor-expr</code> will be intersected with
<code>isolated object {}</code>. If the <code>object-constructor-expr</code> is
explicitly isolated, then every <code>field-initializer</code> must be an
isolated expression and any field that is not isolated must be declared as
private.
</p>
</section>

<section>
<h5>Methods</h5>

<pre
class="grammar">method-defn :=
   metadata object-visibility-qual method-quals
   <code>function</code> method-name function-signature method-defn-body
</pre>

<p>
A <code>method-defn</code> defines a method of an object. 
</p>

<pre
class="grammar">method-defn-body := function-defn-body
</pre>
<p>
Within a <code>method-defn-body</code>, the fields and methods of the object are
not implicitly in-scope; instead the variable <code>self</code> is bound to the
object and can be used to access fields and methods of the object. The
<code>self</code> variable is implicitly final and cannot be modified. If the
<code>object-constructor-expr</code> is explicitly isolated, then the
<code>self</code> variable must be accessed only within the scope of a lock
statement, except when <code>self</code> is part of a
<code>field-access-expr</code> of the form <code>self.<var>f</var></code>, where
<code><var>f</var></code> is the name of an isolated field.
</p>
<p>
If <code>isolated-qual</code> is present, then the method has its isolated bit
set and its <code>method-defn-body</code> must satisfy the requirements for an
<a href="#isolated_functions">isolated function</a>.
</p>

</section>

<section>
<h5>Remote methods</h5>

<pre
class="grammar">remote-method-defn :=
   metadata remote-method-quals
   <code>function</code> remote-method-name function-signature method-defn-body
</pre>
<p>
A <code>remote-method-defn</code> defines a remote method. This is allowed only
when an <code>object-network-qual</code> is present in the
<code>object-constructor-expr</code>.
</p>

</section>

<section>
<h5 id="resources_defn">Resources</h5>

<pre
class="grammar">resource-method-defn :=
   metadata resource-method-quals
   <code>function</code> resource-method-name resource-path function-signature method-defn-body
</pre>

<p>
A <code>resource-method-defn</code> defines a resource method for one or more
resources. This is allowed only when an <code>object-network-qual</code> is
present in the <code>object-constructor-expr</code>. The semantics of
<code>resource-method-defn</code> extends the semantics of a
<code>resource-method-decl</code> by associating a function with each declared
resource method.
</p>
<p>
A network interaction object uses <code>resource-method-defn</code>s to provide
a resource access operation. The inputs to the resource access operation are a
string giving the resource method name, a list of values for the resource path,
and a list of values for the argument list. The operation looks up the function
associated with the resource method name and resource path, and then invokes the
function with the supplied argument list.
</p>
<p>
The list of values supplied for the resource path are used to bind parameters
specified in the <code>resource-path</code> before the function is invoked.
These parameters are in scope in the <code>method-defn-body</code>. A parameter
in a <code>resource-path-segment-param</code> will be bound to the value at the
corresponding position in the list; a parameter in a
<code>resource-path-rest-param</code> will be bound to a list of all the values
from the corresponding position onwards.
</p>
<p>
The resource access operation of a service object is responsible for
implementing the delegation semantics of a resource method that returns a
service object. A <code>resource-path</code> is <em>delegated</em> if it occurs
in a <code>resource-method-defn</code> with a <code>resource-method-name</code>
of <code>get</code> and a return value that includes a service object type that
has one or more resources. If a resource access operation has a resource path
<var>r</var>, which has a prefix <var>p</var> (which may be the entire path)
that is delegated, then the <code>get</code> method that provides the delegation
is first called with no arguments but with resource parameters bound as usual
resulting in a value <var>v</var>; if <var>v</var> is an error, then the result
of the resource access operation is <var>v</var>; otherwise a resource access
operation is performed on the <var>v</var> with the resource path being
<var>r</var> with <var>p</var> removed.
</p>

</section>

<section>
<h5>Initialization</h5>
<p>
A <code>method-defn</code> with a <code>method-name</code> of <code>init</code>
is used to initialize the object and is treated specially. The return type of
the <code>init</code> method must be a subtype of the union of error and nil,
and must contain nil; if <code>init</code> returns an error, it means that
initialization of the object failed.
If the evaluation of a <code>field-initializer</code> completes abruptly with a check-fail
with associated value <var>v</var>, then the <code>init</code> method
returns <var>v</var> before its <code>method-defn-body</code> is executed;
the return type of the <code>init</code> method must be consistent with this.
</p>
<p>
The parameter list of an <code>init</code> method within an
<code>object-constructor-expr</code> must be empty.
</p>
<p>
At any point in the body of a <code>init</code> 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
<code>init</code> method:
</p>
<ul>
<li>accesses a field at a point where it is potentially initialized, or</li>
<li>at a point where there is any potentially uninitialized field
<ul>
<li>returns nil, or</li>
<li>uses the <code>self</code> variable other than to access or modify the value of a field.</li>
</ul>
</li>
</ul>
<p>
If the <code>object-constructor-expr</code> is explicitly isolated, then a field
can only be assigned to by an <code>assignment-stmt</code> with a right hand
side that is an isolated expression. The requirement to access <code>self</code>
within a lock statement does not apply to the <code>init</code> method at any
point where there is any potentially uninitialized field.
</p>
<p>
The visibility of the <code>init</code> method cannot be <code>private</code>.
</p>
<p>
Any <code>init</code> method is not part of the shape of an object, and so does
not affect when an object value belongs to a type. The <code>init</code> method
can be called in a <code>method-call-expr</code> only when the expression
preceding the <code>.</code> is <code>self</code>.
</p>
<p>
A missing <code>init</code> method is equivalent to an isolated
<code>init</code> method with no parameters and an empty body (which will always
return nil).
</p>
</section>

</section>
<section>
<h4>New expression</h4>

<pre
class="grammar">new-expr := explicit-new-expr | implicit-new-expr
explicit-new-expr := <code>new</code> class-descriptor <code>(</code> arg-list <code>)</code>
class-descriptor := identifier | qualified-identifier | stream-type-descriptor
</pre>
<p>
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.
</p>
<p>
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 <code>init</code> 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 <code>init</code> method. If the result of
calling the <code>init</code> 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. The explicit-new-expr is isolated if the type of the
<code>init</code> is isolated and the expression for every argument in the
arg-list is isolated.
</p>
<p>
When the class-reference refers to a stream type <code>stream&lt;T,E&gt;</code>,
the arg-list must either be empty or be a single argument belonging to object
type StreamImplementor&lt;T,E?&gt;. 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. The explicit-new-expr is isolated if the the arg-list is
empty or if the expression for the single argument is isolated.
</p>
<p>
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 <code>init</code> method is
E?, where E is a subtype of error, then it has static type T|E.
</p>
<pre
class="grammar">implicit-new-expr := <code>new</code> [<code>(</code> arg-list <code>)</code>]
</pre>
<p>
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 <code>new</code> is equivalent to
<code>new()</code>. It is an error if the applicable contextually expected type
is not a class or stream type.
</p>
</section>
</section>
<section>
<h3>Variable reference expression</h3>

<pre
class="grammar">variable-reference-expr := variable-reference
variable-reference := identifier | qualified-identifier | xml-qualified-name
xml-qualified-name := xml-namespace-prefix NoSpaceColon identifier
</pre>
<p>
A variable-reference can refer to a variable, a parameter, a constant (defined
with a module constant declaration), a function, a type (defined with a module
type definition) or a class (defined with a module class definition).
</p>
<p>
When the variable reference has a prefix and the prefix has been declared using
an xmlns-decl rather than an import-decl, then the result of evaluating the
variable-reference-expr is a string of the form:
</p>
<pre>
   {<var>namespace-uri</var>}<var>local-name</var>
</pre>
<p>
where the namespace-uri comes from xml-namespace-uri specified in the
xmlns-decl, and the local-name comes from the identifier following the colon.
</p>
<p>
If the variable-reference references a type defined with a module type
definition or a class defined with a module class definition, then the result of
evaluating the variable-reference-expr is a typedesc value for that type or
class.
</p>
<p>
A variable-reference-expr is isolated if it refers to an identifier bound by a
let-expr to an expression that is isolated.
</p>
<p>
A variable-reference-expr that refers to a variable declared by a
module-var-decl that includes <code>isolated</code> is only allowed within a
lock-stmt.
</p>
<p>
A variable-reference-expr cannot refer to an <a
href="#aggregated_variables">aggregated variable</a>; an aggregated variable can
be referenced only by an aggregated-variable-reference.
</p>
</section>
<section>
<h3>Field access expression</h3>

<pre
class="grammar">field-access-expr := expression <code>.</code> field-name
</pre>
<p>
A field-access-expr is typically used to access a field of an object or a field
of a record. More generally, it can be used to access a member of an object or a
member of a mapping. The semantics depends on the static type T of expression. A
field-access-expr where T is a subtype of xml is interpreted as an
xml-required-attribute-access-expr.
</p>
<p>
If T is a subtype of the object basic type, then T must have a member with name
field-name. The field-access-expr is evaluated by first evaluating the
expression to get a value <var>obj</var>. If the member is a field, then the
result of the expression if the value of that field of <var>obj</var> and the
static type of the field-access-expr is the type of that field of T. If that
member is a method, then the result of the expression is a new function value
that when called will call the method with <code>self</code> bound to
<var>obj</var>; the isolated bit of the new function value is set if and only if
the isolated bits of both <var>obj</var> and the method are set; the type
descriptor of the new function value will have the same annotations as the type
descriptor of the method.
</p>
<p>
Let T' be the intersection of T and basic type mapping, let K be the singleton type
containing just the string field-name, and let M be the member type for K in T'.
</p>
<p>
If the following all apply:
</p>
<ul>
<li>the type descriptor for T is not lax;</li>
<li>T is a subtype of the mapping basic type (i.e. T' is the same as T);</li>
<li>K is not a required key type for T;</li>
<li>the type descriptor for T includes field-name as an
individual-field-descriptor (or, if the type descriptor is a union, at least one
member of the union does so);</li>
<li>M does not include nil;</li>
</ul>
<p>
then the field-access-expr is treated as an optional-field-access-expr.
Otherwise, the rest of this section applies.
</p>
<p>
The compile-time requirements on the field-access-expr depend on whether the
type descriptor describing T is lax:
</p>
<ul>
<li>if it is lax, then the only compile-time requirement is M is non-empty;</li>
<li>if it is not lax, then T must be a subtype of the mapping basic type and K
must be a required key type for T.</li>
</ul>
<p>
The static type of field-access-expr is M|E, where E is empty if K is a required
key type and T' is a subtype of T, and error otherwise (E can only be error in
the lax case.) In the lax case, if M is lax, then the static type of the
field-access-expr is lax even if E is an error.
</p>
<p>
A field-access-expr is evaluated as follows:
</p>
<ol>
<li>expression is evaluated resulting in a value <var>v</var></li>
<li>if <var>v</var> has basic type error, the result is <var>v</var> (this can
only happen in the lax case)</li>
<li>otherwise, if <var>v</var> does not have basic type mapping, the result is a
new error value (this can only happen in the lax case)</li>
<li>otherwise, if <var>v</var> does not have a member whose key is field-name,
the result is a new error value (this can only happen in the lax case)</li>
<li>otherwise, the result is the member of <var>v</var> whose key is
field-name.</li>
</ol>

</section>
<section>
<h3>Optional field access expression</h3>

<pre
class="grammar">optional-field-access-expr := expression <code>?.</code> field-name
</pre>
<p>
An optional-field-access-expr accesses a possibly undefined mapping member,
returning <code>()</code> if the member does not exist.
</p>
<p>
An optional-field-access-expr where the static type of <code>expression</code> is
a subtype of xml is interpreted as an xml-optional-attribute-access-expr.
</p>
<p>
Let T be the static type of expression, let T' be the intersection of T and
basic type mapping, let K be the singleton type containing just the string
field-name and let M be the member type of K in T'. The compile-time
requirements on the optional-field-access-expr depend on whether the type
descriptor describing T is lax:
</p>
<ul>
<li>if it is lax, then the only compile-time requirement is that M is
non-empty;</li>
<li>if it is not lax, then, in addition, T must be a subtype of the union of
<code>()</code> and the mapping basic type, and the type descriptor for T must
include <code>field-name</code> as an individual-field-descriptor (if the type
descriptor is a union, then this requirement must be satisfied by at least one
member of the union).</li>
</ul>
<p>
The static type of the optional-field-access-expr is M|N|E where
</p>
<ul>
<li>N is <code>()</code> if <code>()</code> is a subtype of T or K is not a
required key type for T', and empty otherwise;</li>
<li>E is <code>error</code> if T' is not a subtype of T?, and empty otherwise (E
can only be error in the lax case).</li>
</ul>

<p>
An optional-field-access-expr is evaluated as follows:
</p>
<ol>
<li>expression is evaluated resulting in a value <var>v</var></li>
<li>if <var>v</var> is <code>()</code>, the result is <code>()</code></li>
<li>otherwise, if <var>v</var> has basic type error, the result is <var>v</var>
(this can only happen in the lax case)</li>
<li>otherwise, if <var>v</var> does not have basic type mapping, the result is a
new error value (this can only happen in the lax case)</li>
<li>otherwise, if <var>v</var> does not have a member whose key is field-name,
the result is <code>()</code></li>
<li>otherwise, the result is the member of <var>v</var> whose key is
field-name.</li>
</ol>

</section>

<section>
<h3>XML attribute access expression</h3>

<pre
class="grammar">xml-attribute-access-expr := xml-required-attribute-access-expr | xml-optional-attribute-access-expr
xml-required-attribute-access-expr := expression <code>.</code> xml-attribute-name
xml-optional-attribute-access-expr := expression <code>?.</code> xml-attribute-name
xml-attribute-name := xml-qualified-name | qualified-identifier | identifier
</pre>

<p>
An XML attribute access expression provides convenient access to an attribute of
an XML element. It is a compile-time requirement that the static type of the
expression is a subtype of xml.
</p>
<p>
A string representing the name of the attribute is computed at compile-time from
the xml-attribute-name. When the xml-attribute-name is an identifier without a
prefix, the attribute name string is the identifier. When the xml-attribute-name
has a prefix, normally the xml-attribute-name is an xml-qualified-name, in which
the prefix is an xml-namespace-prefix declared using an xmlns-decl. In this
case, the xml-qualified-name is expanded at compile-time into an attribute name
string of the form
</p>
<pre>
   {<var>namespace-uri</var>}<var>local-name</var>
</pre>
<p>
where the namespace-uri comes from xml-namespace-uri specified in the
xmlns-decl, and the local-name comes from the identifier following the colon.
</p>
<p>
It is also allowed for the xml-attribute-name to be specified as a
qualified-identifier, in which the prefix is a module-prefix declared using an
import-decl. In this case the qualified-identifier must refer to a
module-const-decl of type string, and the attribute name string is the value of
the referenced constant. This allows e.g. <code>xml:lang</code> to work.
</p>
<p>
An xml-optional-attribute-access-expr is evaluated as follows. The expression is
evaluated resulting in an xml value <var>v</var>. If <var>v</var> is an empty
xml value, the result is <code>()</code>. Otherwise, if <var>v</var> is not a
singleton element, the result is an error. Otherwise, let <var>m</var> be that
element's attribute map and let <var>k</var> be the attribute name string
computed at compile-time from the xml-attribute-name. If <var>m</var> has a
member <var>s</var> with key <var>k</var>, the the result is <var>s</var>.
Otherwise, the result is <code>()</code>.
</p>
<p>
An xml-required-attribute-access-expr is evaluated the same as an
xml-optional-attribute-expr, except that for cases where the result of the
xml-optional-attribute-expr would be <code>()</code>, the result of the
xml-required-attribute-access-expr is an error.
</p>
<p>
The static type of an xml-required-attribute-access-expr is
<code>string|error</code> The static type of an
xml-optional-attribute-access-expr is <code>string|error|()</code>.
</p>

</section>
<section>
<h3>Annotation access expression</h3>

<pre
class="grammar">annot-access-expr := expression <code>.@</code> annot-tag-reference
</pre>
<p>
The annot-tag-reference must refer to an annotation tag declared with an
annotation declaration. The static type of expression must be a subtype of
<code>typedesc</code>.
</p>
<p>
An <code>annot-access-expr</code> is evaluated by first evaluating
<code>expression</code> resulting in a typedesc value <em>t</em>. If <em>t</em>
has an annotation with the tag referenced by <code>annot-tag-reference</code>,
then the result of the <code>annot-access-expr</code> is the value of that
annotation; otherwise, the result is nil.
</p>
<p>
The static type of the <code>annot-access-expr</code> is T? where T is the type
of the annotation tag.
</p>
</section>
<section>
<h3>Member access expression</h3>

<pre
class="grammar">member-access-expr := container-expression <code>[</code> (key-expression | multi-key-expression) <code>]</code>
container-expression := expression
key-expression := expression
multi-key-expression := expression (<code>,</code> expression)+
</pre>
<p>
A member-access-expr accesses a member of a structured value using its key,
or a constituent of a sequence value using its index.
</p>
<p>
The requirements on the static type of container-expression and key-expression are as
follows:
</p>
<ul>
<li>if the static type of container-expression is a subtype of string or of xml
or of basic type list, then the contextually expected type for key-expression is
int and the static type of key-expression must be a subtype of int;</li>
<li>if the static type of container-expression is a subtype of table, then the
contextually expected type for key-expression is <code><var>K</var></code> and
the static type of key-expression must be a subtype of
<code><var>K</var></code>, where the static type of container-expression is
<code>table&lt;<var>R</var>&gt; key&lt;<var>K</var>&gt;</code>;</li>
<li>otherwise the static type of container-expression must be a subtype of the
union of nil and basic type map; in this case the contextually expected type for
key-expression is string and the static type of key-expression must be a subtype
of string.</li>
</ul>
<p>
A multi-key-expression is allowed only when the static type of a
container-expression is a subtype of table. A multi-key-expression
<code>E<sub>1</sub>, E<sub>2</sub>,..., E<sub>n</sub></code> is equivalent to a
list-constructor-expr <code>[E<sub>1</sub>, E<sub>2</sub>,...,
E<sub>n</sub>]</code>.
</p>

<p>
A member-access-expr is evaluated as follows:
</p>
<ol>
<li>the container-expression is evaluated to get a value <var>c</var>;</li>
<li>the key-expression is evaluated to get a value <var>k</var>;</li>
<li>depending on the basic type of <var>c</var>
<ul>
<li>if it is string, and <var>k</var> is &lt; 0 or &#x2265; the length of
<var>c</var>, then the evaluation completes abruptly with a panic; otherwise,
the result is a string of length 1 containing the character with index
<var>k</var> in <var>c</var>;</li>
<li>if it is xml, and <var>k</var> is &lt; 0, then the evaluation completes
abruptly with a panic; if <var>k</var> is &#x2265; the length of <var>c</var>, then
the result is an empty xml value; otherwise, the result is a singleton xml
value containing the item with index <var>k</var> in <var>c</var>;</li>
<li>if it is list, and <var>k</var> is &lt; 0 or &#x2265; the length of
<var>c</var>, then the evaluation completes abruptly with a panic; otherwise,
the result is the member of <var>c</var> with index <var>k</var>;</li>
<li>if it is table, then if <var>c</var> does not contain a member with key
<var>k</var>, the result is <code>()</code>; otherwise, the result is the member
of <var>c</var> with key <var>k</var>.</li>
<li>if it is mapping, then if <var>c</var> is <code>()</code> or <var>c</var>
does not contain a member with key <var>k</var>, the result is <code>()</code>;
otherwise, the result is the member of <var>c</var> with key <var>k</var>.</li>
</ul>
</li>
</ol>
<p>
Let T the static type of container-expression. If T is a subtype of string, then
the static type of the member-access-expr is <a
href="#built-in_subtypes"><code>string:Char</code></a>, that is the subtype of
strings containing strings of length 1. If T is a subtype of xml&lt;M&gt;, then
the static type of the member-access-expr is M|E, where E is the type of the
empty xml value. If T is a subtype of table&lt;R&gt;, then the static type of
member-access-expr is R?. Otherwise, let K be the static type of key-expression
and let M be the member type of K in T; if T contains nil, or T is a subtype of
mapping and K is an optional key type for T, then the static type of the
member-access-expr is M?, otherwise the static type is M.
</p>

</section>
<section>
<h3 id="function_call">Function call expression</h3>

<pre
class="grammar">function-call-expr := function-reference <code>(</code> arg-list <code>)</code>
function-reference := variable-reference
arg-list :=
   positional-args [<code>,</code> other-args]
   | [other-args]
other-args := named-args | rest-arg
</pre>
<p>
A function-call-expr is evaluated by constructing an argument list and passing
the argument list to the function referred to by the variable-name. The argument
list will be used to bind the parameters of the function before the body of the
function is executed. If the function terminates normally, then the result of
the function-call-expr is the return value of the function; otherwise the
function-call-expr completes abruptly with a panic. The static type of the
function-call-expr is the return type of the function type; this type is
permitted to be <code>never</code>.
</p>
<p>
The function-reference must refer to a variable with function type. The type
descriptor of that function type is used to construct an argument list from the
specified arg-list. Note that it is the type descriptor of the declared type of
the variable that is used for this purpose, rather than the runtime type
descriptor of the referenced function value. The expressions occurring in the
arg-list are evaluated in the order in which they occur in the arg-list; the
contextually expected type for the expression comes from the static type
required for the expression as specified below.
</p>
<p>
If the function-reference is an unqualified identifier
<code><var>f</var></code>, the arg-list has a rest-arg and no positional-args,
and the rest-arg is an aggregated-variable-reference of type T, then the
function-reference is treated as referring to a function
<code><var>f</var></code> in a module lang.M of the lang library, where M is
selected as follows.
</p>
<ul>
<li>If T is a subtype of B[], where B is a basic type with with corresponding
langlib module lang.B and the module lang.B contains a function
<code><var>f</var></code>, then M is B. The module corresponding to each basic
type is listed in the <a href="#lang_library_modules">Lang library modules</a>
section.</li>
<li>Otherwise, M is <code>value</code>.</li>
</ul>
<p>
In this case, if the langlib function requires at least one argument, but T
allows the empty list, then the evaluation of the function-call-expr will first
check whether the aggregated-variable-reference refers to an empty list, and, if
so, the result of the function-call-expr will be nil; the return type of the
langlib function will accordingly be unioned with nil.
</p>
<pre
class="grammar">positional-args := positional-arg (<code>,</code> positional-arg)*
positional-arg := expression
</pre>
<p>
The result of evaluating the <var>i</var>-th positional-arg becomes the
<var>i</var>-th member of the argument list. The static type of the expression
for the <var>i</var>-th positional-arg must be a subtype of the type declared
for the <var>i</var>-th parameter that is not a rest-param, if there is such a
parameter; otherwise, there must be a rest-param and the static type must be a
subtype of the type declared for the rest-param.
</p>
<pre
class="grammar">named-args := named-arg (<code>,</code> named-arg)*
named-arg := arg-name <code>=</code> expression
arg-name := identifier
</pre>
<p>
The arg-name of every named-arg must be distinct. Each named-arg must correspond
to either a parameter that is not a rest-param or to a field of an
included-record-param. In the latter case, there are two possibilities.
</p>
<ul>
<li>The field is described by an individual-field-descriptor with a type that is not
<code>never</code>.</li>
<li>The field is described by a record-rest-descriptor, either explicitly as
part of an exclusive-record-type-descriptor or implicitly as part of an
inclusive-record-type-descriptor. In this case:
<ul>
<li>for every parameter name and every individual-field-descriptor of an
included-record-param with a type that is not <code>never</code>, the
record-type-descriptor must include an individual-field-descriptor that has type
<code>never</code> and is optional, and so disallows a field with that
name;</li>
<li>the record-type-descriptor must not include any other
individual-field-descriptor; and</li>
<li>there must be no other included-record-param with a
record-rest-descriptor.</li>
</ul>
</li>
</ul>
<p>
It is an error if there is a named-arg and a positional-arg that correspond to
the same parameter. If there is a named-arg or positional-arg corresponding to
an included-record-param, it is an error for a named-arg to specify a field of
that included-record-param. The static type of the expression of the named-arg
must be a subtype of the type declared for the corresponding parameter or
field-descriptor.
</p>
<pre
class="grammar">rest-arg := spread | aggregated-variable-reference
</pre>
<p>
The static type of the expression in a spread in a rest-arg must be either a
list type or a mapping type. If it is a list type, then the rest-arg is
equivalent to specifying each member of the list as a positional-arg. If it is a
mapping type, then the rest-arg is equivalent to specifying each field of the
mapping as a named-arg, with the name and value of the named-arg coming from the
name and value of the field. In either case, the static type of the expression
must be such as to ensure that the equivalent named-args or positional-args
would be valid. An aggregated-variable-reference is handled like the <a
href="#aggregated_variables">equivalent</a> spread.
</p>
<p>
If there is neither a named-arg nor a positional-arg for a parameter that is not
a rest-param, then a default value is computed for the parameter, if possible;
otherwise, it is an error. Default values are computed in parameter declaration
order.
</p>
<ul>
<li>If the parameter is a required-param, it is an error.</li>
<li>If the parameter is a defaultable-param, then the value for the parameter is
computed from the default value in the function's type descriptor.
<ul>
<li>If the default value for a defaultable-param was specifed
using an expression, then it is computed by calling the closure stored in the
type descriptor, passing it the previous arguments in the argument list.</li>
<li>If the default value for a defaultable-param was specified as
<code>&lt;&gt;</code>, then the value for the parameter will be a typedesc value
determined at compile-time from the contextually expected type of the
function-call-expr as follows. Let the name of the parameter for which a default
of <code>&lt;&gt;</code> was specified be <var>t</var>. Let the type of
<var>t</var> be typedesc&lt;<var>T</var>&gt;. Let the return type descriptor for
the function be <var>R</var>, which will have references to <var>t</var>. Let
the contextually expected type for the function-call-expr be <var>C</var>. Then
the default value is found by unifying <var>C</var> and <var>R</var>: the
default value is a typedesc value that describes the maximal type <var>S</var>,
such that <var>S</var> is a subtype of <var>T</var>, and <var>R</var> with
<var>S</var> substituted for <var>t</var> is a subtype of <var>C</var>.</li>
</ul>
</li>
<li>If the parameter is an included-record-param, then a new mapping value is
constructed for it using its record-type-descriptor. The mapping value will have
a field for each named-arg that corresponds to a field of this
included-record-param, with the name and value of the field coming from the name
and value of the named-arg. The mapping value will also have a field for each
individual-field-descriptor with a default-expr for which there was no
corresponding named-arg. It is an error if the record-type-descriptor has an
individual-field-descriptor that is not optional and has no default and there is
not corresponding named-arg.</li>
</ul>
<p>
A function-call-expr is isolated if the type of the function being called is
isolated and the expression for every argument is isolated. In addition, a call
to the <code>clone</code> or <code>cloneReadOnly</code> functions defined by the
lang.value module of the lang library is always isolated.
</p>
<p>
When there is a need to call a function value resulting from the evaluation of
an expression, the result of the expression evaluation can be assigned to a
variable and then the function called by using a reference to the variable.
</p>
</section>
<section>
<h3>Method call expression</h3>

<pre
class="grammar">method-call-expr := expression <code>.</code> method-name <code>(</code> arg-list <code>)</code>
</pre>
<p>
A <code>method-call-expr</code> either calls an object's method, calls an
object's field where the type of the field is a function or calls a function in
the lang library. The static type of the method-call-expr is the return type of
the function type of the function that is called; this type is permitted to be
<code>never</code>. The evaluation of the method-call-expr starts by evaluating
<code>expression</code> resulting in some value <var>v</var>. There is no
contextually expected type for <code>expression</code>.
</p>
<p>
If the static type of <code>expression</code> is a subtype of object, and the
object type includes a method named <code>method-name</code>, then the
<code>method-call-expr</code> is executed by calling that method on
<var>v</var>. The <code>arg-list</code> is used to construct an argument list
that is passed to the method in the same way as with a
<code>function-call-expr</code>. A <code>method-call-expr</code> cannot be used
to call a remote method. A remote method of a client object can be called by a
<code>client-remote-method-call-action</code>. In this case, a method-call-expr
is isolated if the expression preceding <code>.</code> is isolated, the
expression for each argument in the arg-list is isolated and the type of the
method being called is isolated.
</p>
<p>
Otherwise, if the static type of <code>expression</code> is a subtype of object,
and the object type includes a field named <code>method-name</code> with a
function type, then the <code>method-call-expr</code> is executed by calling the
value of that field. The <code>arg-list</code> is used to construct an argument
list that is passed to the method in the same way as with a
<code>function-call-expr</code>. In this case, a method-call-expr is isolated if
the type of the function is isolated and the expression for each argument in the
arg-list is isolated.
</p>
<p>
Otherwise, the <code>method-call-expr</code> will be turned into a call to a
function in the lang library <code>m:method-name(expression, arg-list)</code>,
where m is an automatically created module prefix for a module lang.M of the lang
library, where M is selected as follows.
</p>
<ul>
<li>If the static type of <code>expression</code> is a subtype of basic type
with corresponding langlib module lang.B and the module lang.B contains a
function <code>method-name</code>, then M is B. The module corresponding to each
basic type is listed in the <a href="#lang_library_modules">Lang library
modules</a> section.</li>
<li>Otherwise, M is <code>value</code>.</li>
</ul>
<p>
It is a compile-time error if the resulting function call does not satisfy all
the constraints that would apply if it has been written explicitly as a
<code>function-call-expr</code>. The <code>method-call-expr</code> expression is
isolated under the same conditions that the corresponding
<code>function-call-expr</code> would be isolated.
</p>
</section>
<section>
<h3>Error constructor</h3>

<pre
class="grammar">error-constructor-expr := <code>error</code> [error-type-reference] <code>(</code> error-arg-list <code>)</code>
error-arg-list := positional-arg [<code>,</code> positional-arg] (<code>,</code> named-arg)*
</pre>
<p>
An error constructor constructs a new error value. If an error-type-reference is
specified, it must denote a type that is a subtype of error; the effect is the
same as making the contextually expected type be that specified by the
error-type-reference. If there is no applicable contextually expected type, then
it is the same as if there were a contextually expected type of
<code>error</code>.
</p>
<p>
The applicable contextually expected type E must be definite. The type-ids of
the constructed error value are those induced by E. Note that it is allowed for
E to refer to an intersection-type-descriptor.
</p>
<p>
The first positional-arg is of type string and specifies the error message; the
second positional-arg, if present, is of type <code>error?</code>, with a
default of nil, and specifies the cause.
</p>
<p>
Evaluating the error-constructor-expr constructs a new detail mapping. Each
named-arg specifies a field of the error detail mapping; the static type of each
named-arg must be a subtype of <code>value:Cloneable</code>. The type descriptor
E implies a type descriptor D for the detail mapping. The arg-name of every
named-arg must be specified as the field-name of an individual-field-descriptor
occurring in D, unless there are no such field names. Fields with default
values will also be added to the detail record based on D in the same way as the
mapping-constructor-expr adds fields with default values based on the
contextually expected type. The contextually expected type for each named-arg is
determined from D in the same way as for a mapping-constructor-expr. The detail
mapping is constructed as immutable, with its members being the result of
applying the ImmutableClone abstract operation to the result of evaluating each
named-arg and every defaultable arg.
</p>
<p>
The stack trace in the constructed error value describes the execution stack at
the point where the error constructor was evaluated.
</p>

</section>
<section>
<h3>Anonymous function expression</h3>

<pre
class="grammar">anonymous-function-expr := explicit-anonymous-function-expr | infer-anonymous-function-expr
explicit-anonymous-function-expr := [annots] function-quals <code>function</code> function-signature (block-function-body|expr-function-body)
</pre>
<p>
Evaluating an anonymous-function-expr creates a closure, whose basic type is
function. With an explicit-anonymous-function-expr, the type of the function is
specified explicitly as usual with a function-signature. With an
infer-anonymous-function-expr, the type of the function is inferred.
</p>
<p>
If a variable-reference-expr within an anonymous-function-expr refers to a local
variable defined outside of the anonymous-function-expr, the closure will
capture a reference to that variable; the captured reference will refer to the
same storage as the original reference rather than to a copy.
</p>

<pre
class="grammar">infer-anonymous-function-expr := infer-param-list expr-function-body
infer-param-list :=
   identifier
   | <code>(</code>[identifier (<code>,</code> identifier)*]<code>)</code>
</pre>
<p>
An infer-anonymous-function-expr can only be used in a context where a function
type is expected. Both the types of the parameters and whether the function type
is <code>isolated</code> are inferred from the expected function type. The
function type will be inferred to be <code>transactional</code> if the
expr-function-body calls any functions with a transactional type.
The scope of the parameters is <code>expr-function-body</code>.
The static type of the infer-anonymous-function-expr will be a function type
whose return type is the static type of the <code>expression</code> in
<code>expr-function-body</code>. If the contextually expected type for the
<code>anonymous-function-expr</code> is a function type with return type T, then
the contextually expected type for <code>expression</code> in
<code>expr-function-body</code> is T.
</p>
</section>

<section>
<h3>Let expression</h3>

<pre
class="grammar">let-expr := <code>let</code> let-var-decl [<code>,</code> let-var-decl]* <code>in</code> expression
let-var-decl := [annots] typed-binding-pattern <code>=</code> expression
</pre>

<p>
A let-expr binds variables and then evaluates an expression with those variables in scope.
</p>
<p>
A let-expr <code>let T B = E<sub>1</sub> in E<sub>2</sub></code> is evaluated as
follows. E<sub>1</sub> is evaluated resulting in a value v. The typed binding
pattern T B is matched to v, causing assignments to the variables occuring in B.
Then E<sub>2</sub> is evaluated with those variables in scope; the resulting
value is the result of the let-expr.
</p>
<p>
A let-expr <code>let D<sub>1</sub>, D<sub>2</sub>,...,D<sub>n</sub> in E</code>
is transformed into <code>let D<sub>1</sub> in let D<sub>2</sub> in ... let
D<sub>n</sub> in E</code>.
</p>
<p>
The typed-binding-pattern is used unconditionally, meaning that it is a compile
error if the static types do not guarantee the success of the match. If the
typed-binding-pattern uses <code>var</code>, then the type of the variable is
inferred from the precise static type of the expression following
<code>=</code>.
</p>
<p>
Since expressions cannot modify variables, the variables bound in a let-var-decl
are implicitly final. A let-expr is isolated if the expression following
<code>in</code> is isolated; a reference in that expression to a variable bound
by a let-var-decl will be treated as isolated if the expression initializing the
variable in the let-var-decl is isolated.
</p>

</section>

<section>
<h3>Type cast expression</h3>

<pre
class="grammar">type-cast-expr := <code>&lt;</code> type-cast-param <code>&gt;</code> expression
type-cast-param := [annots] type-descriptor | annots
</pre>
<p>
A <code>type-cast-expr</code> casts the value resulting from evaluating
<code>expression</code> to the type described by the type-descriptor, performing
a numeric conversion if required.
</p>
<p>
Normally, the parameter for a type-cast-expr includes a type-descriptor.
However, it is also allowed for the parameter to consist only of annotations; in
this case, the only effect of the type cast is for the contextually expected
type for expression to be augmented with the specified annotations. The rest of
this subsection describes the normal case, where the type-cast-expr includes a
type-descriptor.
</p>
<p>
A type-cast-expr is evaluated by first evaluating <code>expression</code>
resulting in a value v. Let T be the type described by
<code>type-descriptor</code>. If v belongs T, then the result of the
type-cast-expr is v. Otherwise, if T includes shapes from exactly one basic
numeric type N and v belongs to another basic numeric type, then let n be
NumericConvert(N, v); if n is not an error and n belongs to T, then the result
of the type-cast-expr is n. Otherwise, the evaluation of the type-cast-expr
completes abruptly with a panic.
</p>
<p>
Let T be the static type described by <code>type-descriptor</code>, and let TE
be the static type of <code>expression</code>. Then the static type of the
<code>type-cast-expr</code> is the intersection of T and TE', where TE' is TE
with its numeric shapes transformed to take account of the possibility of the
numeric conversion specified in the previous paragraph.
It is a compile-time error to attempt to use a type cast to
<em>cast away</em> an error: if the intersection of TE and <code>error</code> is
non-empty, then the intersection of T and <code>error</code> must also be
non-empty. A <code>checkpanic</code> expression can be used instead to assert
that the result of an expression will never be an error.
</p>
<p>
The contextually expected type for <code>expression</code> is the intersection
of the contextually expected type of the <code>type-cast-expr</code> and the
type described by the <code>type-descriptor</code>.
</p>
<p>
Note that a <code>type-cast-expr</code> of <code>&lt;readonly&gt;</code> can be
used both to cause constructors withing the <code>expression</code> to construct
values with the read-only bit on and to verify that the value resulting from
the evaluation of <code>expression</code> has its read-only bit on.
</p>

</section>
<section>
<h3>Typeof expression</h3>

<pre
class="grammar">typeof-expr := <code>typeof</code> expression
</pre>
<p>
The result of a <code>typeof-expr</code> is a typedesc value for the runtime
type of v, where v is the result of evaluating <code>expression</code>.
</p>
<p>
The runtime type of v is the narrowest type to which v belongs.
</p>
<ul>
<li>When v is a simple value, the resulting typedesc will describe a type
consisting of a single shape, which is the shape of the value. The typedesc will
not have any annotations. Each evaluation of <code>typeof</code> with a simple
value produces a new typedesc value.</li>
<li>When v is a reference value, each evaluation of <code>typeof</code> with an
identical reference value produces an identical typedesc value. The type
descriptor resulting from <code>typeof</code> will be the same as the type
descriptor used to construct the value. For containers, this is the same as the
inherent type; when the container is immutable, it will be a singleton type. For
an object, this is the same as the type descriptor used with new. For an error,
this is the same as the type descriptor used in the functional-constructor-expr.
Any annotations that were attached to the type descriptor used to construct the
value will this be available on the constructed value.</li>
</ul>
<p>
The static type of <code>typeof-expr</code> is typedesc&lt;T&gt;, where T is the
static type of <code>expression</code>.
</p>
</section>
<section>
<h3>Unary expression</h3>

<section>
<h4>Unary numeric expression</h4>
<pre
class="grammar">unary-numeric-expr :=
   <code>+</code> expression
   | <code>-</code> expression
   | <code>~</code> expression
</pre>
<p>
The operators occurring in a <code>unary-numeric-expr</code> have both lifted
form, which is specified in the <a href="#nil_lifting">Nil lifting</a> section,
and an underlying form, which is specified in this section.
</p>
<p>
The unary <code>-</code> operator performs negation. The static type of the
operand must be a number; the static type of the result is the basic type of the
static type of the operand, modified by the usual <a
href="#singleton_typing">singleton typing</a> rules. The semantics for each
basic type are as follows:
</p>
<ul>
<li>int: negation for int is the same as subtraction from zero; a panic will
occur on overflow, which happens when the operand is -2<sup>63</sup>)</li>
<li>float, decimal: negation for floating point types corresponds to the negate
operation as defined by IEEE 754-2008 (this is not the same as subtraction from
zero);</li>
</ul>
<p>
If the contextually expected type for a <code>-</code> expression is T, then the
contextually expected type for the operand expressions is T', where a value v is
in T' if it belongs to int, decimal or float, and T contains a value with the
same basic type as v.
</p>
<p>
The unary <code>+</code> operator returns the value of its operand expression. The static
type of the operand must be a number, and the static type of the result is the
same as the static type of the operand expression, modified by the usual <a
href="#singleton_typing">singleton typing</a> rules.
</p>
<p>
The <code>~</code> operator inverts the bits of its operand expression. The
static type of the operand must be int, and the static type of the result is
int, modified by the usual <a href="#singleton_typing">singleton typing</a>
rules.
</p>
</section>

<section>
<h4>Unary logical expression</h4>
<pre
class="grammar">unary-logical-expr := <code>!</code> expression
</pre>
<p>
The <code>!</code> operator performs logical negation. The static type of the
operand expression must be boolean. The <code>!</code> operator returns true if
its operand is false and false if its operand is true. The static type of the
result is boolean, modified by the usual <a href="#singleton_typing">singleton
typing</a> rules.
</p>
</section>
</section>

<section>
<h3>Multiplicative expression</h3>

<pre
class="grammar">multiplicative-expr :=
   expression <code>*</code> expression
   | expression <code>/</code> expression
   | expression <code>%</code> expression
</pre>
<p>
The <code>*</code> operator performs multiplication; the <code>/</code> operator
performs division; the <code>%</code> operator performs remainder. These
operators have both lifted form, which is specified in the <a
href="#nil_lifting">Nil lifting</a> section, and an underlying form, which is
specified in this section.
</p>
<p>
The static type of each operand must be a subtype of <code>int</code>,
<code>float</code> or <code>decimal</code>. If the static type of both operands
is not a subtype of the same basic type, then either the second operand must be
a subtype of <code>int</code>, or the operator must be <code>*</code> and the
first operand must be a subtype of <code>int</code>; in either case, the
<code>int</code> operand is first converted to the type of the other operand.
</p>
<p>
The operation performed depends on the basic type of the operands as follows:
</p>
<ul>
<li>int
<ul>
<li><code>*</code> performs integer multiplication; a panic will occur on overflow</li>
<li><code>/</code> performs integer division, with any fractional part discarded
ie with truncation towards zero; a panic will occur on division by zero or
overflow, which happens if the first operand is -2<sup>63</sup> and the second
operand is -1</li>
<li><code>%</code> performs integer remainder consistent with integer division,
so that if <code><var>x</var>/<var>y</var></code> does not result in a panic,
then <code>(<var>x</var>/<var>y</var>)*<var>y</var> +
(<var>x</var>%<var>y</var>)</code> is equal to <code><var>x</var></code>; a
panic will occur if the second operand is zero; if the first operand is
-2<sup>63</sup> and the second operand is -1, then the result is 0</li>
</ul>
</li>
<li>float, decimal
<ul>
<li><code>*</code> performs the multiplication operation with the destination
format being the same as the source format, as defined by IEEE 754-2008; this
never causes a panic to occur</li>
<li><code>/</code> performs the division operation with the destination format
being the same as the source format, as defined by IEEE 754-2008; this never
causes a panic to occur</li>
<li><code>%</code> performs a remainder operation; the remainder is not the
IEEE-defined remainder operation but is instead a remainder operation analogous
to integer remainder; more precisely,
<ul>
<li>if <code><var>x</var></code> is NaN or <code><var>y</var></code> is NaN or
<code><var>x</var></code> is an infinity or <code><var>y</var></code> is a zero,
then <code><var>x</var> % <var>y</var></code> is NaN</li>
<li>for finite <code>x</code>, and infinite <code>y</code>, <code><var>x</var> %
<var>y</var></code> is <code><var>x</var></code></li>
<li>for finite <code><var>x</var></code> and finite non-zero
<code><var>y</var></code>, <code><var>x</var> % <var>y</var></code> is equal to
the result of rounding <code><var>x</var> - (<var>y</var> × <var>n</var>)</code>
to the nearest representable value using the roundTiesToEven rounding mode,
where <code><var>n</var></code> is the integer that is nearest to the
mathematical quotient of <code><var>x</var></code> and <code><var>y</var></code>
without exceeding it in magnitude; if the result is zero, then its sign is that
of <code><var>x</var></code></li>
<li>no exceptions are thrown</li>
</ul>
</li>
</ul>
</li>
</ul>
<p>
The static type of the result of a multiplicative-expr is the basic type of its
subexpressions, after conversion, modified by the usual <a href="#singleton_typing">singleton
typing</a> rules, except that the result type is always <code>float</code> in
the case where the operator is <code>/</code> and the right-hand operand is
singleton float <code>0.0</code>. (This is a consequence of the fact that
<code>0.0 == -0.0</code>, but <code>1.0/0.0 != 1.0/-0.0</code>.)
</p>
<p>
If the contextually expected type for a multiplicative-expr is T, then the
contextually expected type for both operand expressions is T', where a value v is
in T' if it belongs to int, decimal or float, and T contains a value with the
same basic type as v.
</p>
</section>
<section>
<h3>Additive expression</h3>

<pre
class="grammar">additive-expr :=
   expression <code>+</code> expression
   | expression <code>-</code> expression
</pre>
<p>
The <code>+</code> operator is used for both addition and concatenation; the
<code>-</code> operator is used for subtraction. These operators have both
lifted form, which is specified in the <a href="#nil_lifting">Nil lifting</a>
section, and an underlying form, which is specified in this section.
</p>
<p>
It is required that either:
</p>
<ul>
<li>the static type of both operand expressions is a subtype of the same basic
type, in which case the static type of the result will be this basic type,
modified by the usual <a href="#singleton_typing">singleton typing</a> rules;
or</li>
<li>the static type of one operand expression must be a subtype of xml and of
the other operand expression must be a subtype of string, in which case the
static type of the result is xml.</li>
</ul>
<p>
The semantics for each basic type is as follows:
</p>
<ul>
<li>int
<ul>
<li><code>+</code> performs integer addition; a panic will occur on
overflow</li>
<li><code>-</code> performs integer subtraction; a panic will occur on
overflow</li>
</ul>
</li>
<li>float, decimal
<ul>
<li><code>+</code> performs the addition operation with the destination format
being the same as the source format, as defined by IEEE 754-2008; this never
causes a panic to occur</li>
<li><code>-</code> performs the subtraction operation with the destination
format being the same as the source format, as defined by IEEE 754-2008; this
never causes a panic to occur</li>
</ul>
</li>
<li>string, xml
<ul>
<li>if both operands are a string, then the result is a string that is the
concatenation of the operands</li>
<li>if both operands are xml, then the result is a new xml value that is the
concatenation of the operands; this does not perform a copy on
the constituents of the operand values</li>
<li>if one operand is an empty string and one is xml, then
the result is the xml value operand</li>
<li>if one operand is a non-empty string and one is xml, then the string is
treated as if it were an xml singleton text value whose characters are the same
as the characters of the string;</li>
</ul>
</li>
</ul>
<p>
If the contextually expected type for an additive-expr is T, then the
contextually expected type for both operand expressions is T', where a value v is
in T' if it belongs to int, decimal, float, string or xml and T contains a value
with the same basic type as v.
</p>

</section>
<section>
<h3>Shift expression</h3>

<pre
class="grammar">shift-expr :=
   expression <code>&lt;&lt;</code> expression
   expression <code>&gt;&gt;</code> expression
   expression <code>&gt;&gt;&gt;</code> expression
</pre>
<p>
A shift-expr performs a bitwise shift. The shift operators have both lifted
form, which is specified in the <a href="#nil_lifting">Nil lifting</a> section,
and an underlying form, which is specified in this section.
</p>
<p>
Both operand expressions must have static type that is a subtype of int. The
left hand operand is the value to be shifted; the right hand value is the shift
amount; all except the bottom 6 bits of the shift amount are masked out (as if
by x &amp; 0x3F). Then a bitwise shift is performed depending on the operator:
</p>
<ul>
<li><code>&lt;&lt;</code> performs a left shift, the bits shifted in on the
right are zero</li>
<li><code>&gt;&gt;</code> performs a signed right shift; the bits shifted in on the
left are the same as the most significant bit</li>
<li><code>&gt;&gt;&gt;</code> performs a unsigned right shift, the bits shifted in on the
left are zero</li>
</ul>
<p>
If the operator is &gt;&gt; or &gt;&gt;&gt; and the left hand operand is a
subtype of <code>int:Unsigned<var>K</var></code> when <code><var>K</var></code>
is 8, 16 or 32, then the static type of the result is
<code>int:Unsigned<var>N</var></code> where <code><var>N</var></code> is the
smallest such <code><var>K</var></code>; otherwise, the static type of the
result is <code>int</code>. In all cases the static type of the result is
modified by the usual <a href="#singleton_typing">singleton typing</a> rules.
</p>
</section>
<section>
<h3>Range expression</h3>

<pre
class="grammar">range-expr :=
   expression <code>...</code> expression
   | expression <code>..&lt;</code> expression
</pre>
<p>
The result of a range-expr is a new object belonging to the object type
Iterable&lt;int,()&gt; that will iterate over a sequence of integers in increasing
order, where the sequence includes all integers n such that
</p>
<ul>
<li>the value of the first expression is less than or equal to n, and</li>
<li>n is
<ul>
<li>if the operator is <code>...</code>, less than or equal to the value of the
second expression</li>
<li>if the operator is <code>..&lt;</code>, less than the value of the second
expression</li>
</ul>
</li>
</ul>
<p>
It is a compile error if the static type of either expression is not a subtype
of int.
</p>
<p>
A range-expr is designed to be used in a foreach statement, but it can be used
elsewhere.
</p>
<p>
A range-expr is always isolated.
</p>
</section>
<section>
<h3>Relational expression</h3>

<pre
class="grammar">relational-expr :=
   expression <code>&lt;</code> expression
   | expression <code>&gt;</code> expression
   | expression <code>&lt;=</code> expression
   | expression <code>&gt;=</code> expression
</pre>
<p>
A relational-expr tests the relative order of two values. There must be an <a
href="#ordering">ordered</a> type to which the static type of both operands
belong. The static type of the result is boolean, modified by the usual <a
href="#singleton_typing">singleton typing</a> rules.
</p>
<p>
A relational-expr is evaluated by first evaluating the two expressions,
resulting in values x and y. The result of relational-expr is true if and only
if the result of the Compare(x,y) operation is
</p>
<ul>
<li>LT, if the operator is <code>&lt;</code></li>
<li>GT, if the operator is <code>&gt;</code></li>
<li>LT or EQ, if the operator is <code>&lt;=</code></li>
<li>GT or EQ, if the operator is <code>&gt;=</code></li>
</ul>
<p>
and otherwise false.
</p>
</section>
<section>
<h3>Type test expression</h3>

<pre
class="grammar">is-expr :=
   expression <code>is</code> type-descriptor
   | expression <code>!</code> <code>is</code> type-descriptor   
</pre>
<p>
An is-expr tests whether a value belongs to a type.
</p>
<p>
An is-expr is evaluated by evaluating the expression yielding a result v.
If the operator is <code>is</code>, then the result of the expression is true if
v belongs to the type denoted by the type-descriptor, and otherwise false. If
the operator is <code>!is</code>, then the result of the expression is false if
v belongs to the type denoted by the type-descriptor, and otherwise true.
</p>
</section>
<section>
<h3>Equality expression</h3>

<pre
class="grammar">equality-expr :=
   expression <code>==</code> expression
   | expression <code>!=</code> expression
   | expression <code>===</code> expression
   | expression <code>!==</code> expression
</pre>
<p>
An equality-expr tests whether two values are equal. For all four operators, it
is a compile time error if the intersection of the static types of the operands
is empty.
</p>
<p>
The === operator tests for exact equality. The !== operator results in the
negation of the result of the === operator. Two values v<sub>1</sub> and
v<sub>2</sub> are exactly equal if they have the same basic type T and
</p>
<ul>
<li>T is simple type, and  v<sub>1</sub> and v<sub>2</sub> are identical values
within the possible of values allowed for T;</li>
<li>T is a sequence type, and the length of v<sub>1</sub> is the same as the length of v<sub>2</sub> and
<ul>
<li>the length is 1, and either
<ul>
<li>v<sub>1</sub> and v<sub>2</sub> both have storage identity and that storage
identity is the same, or</li>
<li>v<sub>1</sub> and v<sub>2</sub> both do not have storage identity and the
shape of v<sub>1</sub> is the same as the shape of v<sub>2</sub></li>
</ul>
</li>
<li>the length is not 1, and every constituent of v<sub>1</sub> is exactly equal
as the corresponding constituent of v<sub>2</sub>;</li>
</ul>
</li>
<li>T is a structural or behavioural type, and the storage identity of
v<sub>1</sub> is the same as the storage identity of v<sub>2</sub>.</li>
</ul>
<p>
The == operator tests for deep equality. The != operator results in the negation
of the result of the == operator. For both == and !=, at least one of the operands must have a
static type that is a subtype of anydata. Two values v1, v2 are deeply equal if
DeepEquals(v1, v2) is true.
</p>
<p>
The static type of the result of expression is boolean; in the case of the ==
and != operators, the static type is modified by the usual <a
href="#singleton_typing">singleton typing</a> rules; in the case of the === and
!== operators, the static type is not so modified.
</p>
<p>
Note that === and == are the same for simple values except for floating point types.
</p>
<p>
For the float type, the operators differ as regards floating point zero: ==
treats positive and negative zero from the same basic type as equal whereas ===
treats them as unequal. Both == and === treat two NaN values from the same basic
type as equal. This means that neither of these operators correspond to
operations defined by IEEE 754-2008, because they do not treat NaN in the
special way defined for those operations.
</p>
<p>
For the decimal type, the operators differ in whether they consider the
precision of the value. For example, <code>1.0 == 1.00</code> is true but
<code>1.0 === 1.00</code> is false.
</p>

</section>
<section>
<h3>Binary bitwise expression</h3>

<pre
class="grammar">binary-bitwise-expr :=
   bitwise-and-expr
   | bitwise-xor-expr
   | bitwise-or-expr
bitwise-and-expr := expression <code>&amp;</code> expression
bitwise-xor-expr := expression <code>^</code> expression
bitwise-or-expr := expression <code>|</code> expression
</pre>
<p>
A binary-bitwise-expr does a bitwise AND, XOR, or OR operation on its operands.
These operators have both lifted form, which is specified in the <a
href="#nil_lifting">Nil lifting</a> section, and an underlying form, which is
specified in this section.
</p>
<p>
The static type of both operands must be a subtype of int. The static type of
the result is as follows:
</p>
<ul>
<li>for AND, if the type of either operand is a subtype of
<code>int:Unsigned<var>K</var></code> when <code><var>K</var></code> is 8, 16 or
32, then the static type of the result is <code>int:Unsigned<var>N</var></code>
where <code><var>N</var></code> is the smallest such <code><var>K</var></code>;
otherwise, the static type of the result is <code>int</code>;</li>
<li>for XOR or OR, if the type of both operands is a
subtype of <code>int:Unsigned<var>K</var></code> when <code><var>K</var></code>
is 8, 16 or 32, then the static type of the result is
<code>int:Unsigned<var>N</var></code> where <code><var>N</var></code> is the
smallest such <code><var>K</var></code>; otherwise, the static type of the result
is <code>int</code>.</li>
</ul>
<p>
In all cases, the static type of the result is modified by the usual <a
href="#singleton_typing">singleton typing</a> rules.
</p>
</section>

<section>
<h3>Logical expression</h3>

<pre
class="grammar">logical-expr := logical-and-expr | logical-or-expr
logical-and-expr := expression <code>&amp;&amp;</code> expression
logical-or-expr := expression <code>||</code> expression
</pre>

<p>
The static type of each expression in a logical-expr must be a subtype of
boolean.
</p>
<p>
A logical-and-expr is evaluated as follows:
</p>
<ol>
<li>the left-hand expression is evaluated, resulting in a value <var>x</var>;</li>
<li>if <var>x</var> is <code>false</code>, then the result of the
logical-and-expr is <var>x</var>, and the right-hand expression is not
evaluated;</li>
<li>otherwise, the result of the logical-and-expr is the result of evaluating
the right-hand expression.</li>
</ol>
<p>
A logical-or-expr is evaluated as follows:
</p>
<ol>
<li>the left-hand expression is evaluated, resulting in a value <var>x</var>;</li>
<li>if <var>x</var> is <code>true</code>, then the result of the
logical-or-expr is <var>x</var>, and the right-hand expression is not
evaluated;</li>
<li>otherwise, the result of the logical-or-expr is the result of evaluating
the right-hand expression.</li>
</ol>

<p>
The static type of the result of a logical-expr is boolean, modified by the
usual <a href="#singleton_typing">singleton typing</a> rules. Furthermore:
</p>
<ul>
<li>if the expression is a logical-and-expr and the static type of left-hand
expression is singleton false, then the static type of the result is singleton
false, regardless of the static type of the right-hand-expression;</li>
<li>if the expression is a logical-or-expr and the static type of left-hand
expression is singleton true, then the static type of the result is singleton
true, regardless of the static type of the right-hand-expression.</li>
</ul>

</section>

<section>
<h3>Conditional expression</h3>

<pre
class="grammar">conditional-expr :=
  ternary-conditional-expr
  | nil-conditional-expr
ternary-conditional-expr := expression <code>?</code> expression <code>:</code> expression
nil-conditional-expr := expression <code>?:</code> expression
</pre>
<p>
A ternary-conditional-expr C <code>?</code> T <code>:</code> F is evaluated as
follows:
</p>
<ol>
<li>evaluate C to get a value boolean value v;</li>
<li>if v is true, then the result is the result of evaluating T.</li>
<li>Otherwise, the result is the result of evaluating F.</li>
</ol>
<p>
In a ternary-conditional-expr C <code>?</code> T <code>:</code> F, the static
type of C must be a subtype of boolean, and the static type of the result is
determined from ther static types of C, T and F as follows:
</p>
<ol>
<li>if the static type of C is singleton true, then the static
type of the result is the static type of T;</li>
<li>if the static type of C is singleton false, then the static
type of the result is the static type of F;</li>
<li>otherwise, the static type of the result is the union of the static types of
T and F.</li>
</ol>
<p>
A nil-conditional-expr L <code>?:</code> R is evaluated as follows:
</p>
<ol>
<li>evaluate L to get a value v;</li>
<li>if v is not nil, then the result is v;</li>
<li>otherwise, the result is the result of evaluating R.</li>
</ol>
<p>
The static type of the result of L <code>?:</code> R is determined from the
static types of L and R as follows:
</p>
<ol>
<li>if the static type of L is nil, then the static type of
the result is the static type of R;</li>
<li>if the static type of L does not include nil, then the static type of
the result is the static type of L;</li>
<li>otherwise, the static type of the result is the union of the difference of
the static type of L and (), and the static type of R.</li>
</ol>
</section>

<section>
<h3>Checking expression</h3>

<pre
class="grammar">checking-expr := checking-keyword expression
checking-keyword := <code>check</code> | <code>checkpanic</code>
</pre>
<p>
Evaluates expression resulting in value v. If v has basic type error, then
</p>
<ul>
<li>if the checking-keyword is <code>check</code>, then the checking-expr
completes abruptly with a check-fail with associated value v;</li>
<li>if the checking-keyword is <code>checkpanic</code>, then the checking-expr
completes abruptly with a panic with associated value v.</li>
</ul>
<p>
If the static type of expression <code><var>Expr</var></code> is T|E, where E is
a subtype of error, then the static type of <code>check <var>Expr</var></code>
or <code>checkpanic <var>Expr</var></code> is T. However, if:
</p>
<ul>
<li>the checking-keyword is <code>check</code>,</li>
<li>the above rules would result in a compile-time error,</li>
<li>the static type of <code><var>Expr</var></code> is lax,</li>
<li>T is a subtype of <code>json</code>, and</li>
<li>there is a contextually expected type S, where S is a subtype of
<code>()|boolean|int|float|decimal|string</code>,</li>
</ul>
<p>
then instead <code>check <var>Expr</var></code> is treated as <code>check
<var>val</var>:ensureType(<var>Expr</var>, <var>s</var>)</code>, where
<code><var>s</var></code> is a typedesc value representing S and
<code><var>val</var></code> refers to the <code>value</code> module in langlib.
</p>
</section>
<section>
<h3>Trap expression</h3>
<p>
The trap expression stops a panic and gives access to the error value associated
with the panic.
</p>
<pre
class="grammar">trap-expr := <code>trap</code> expression
</pre>  
<p>
Semantics are:
</p>
<ul>
<li>Evaluate <code>expression</code> resulting in value v
<ul>
<li>If evaluation completes abruptly with panic with associated value e, then
result of trap-exp is e</li>
<li>Otherwise result of trap-expr is v</li>
</ul>
</li>
<li>If type of <code>expr</code> is T, then type of <code>trap expr</code> is
T|error. It is permitted for T to be <code>never</code>.</li>
</ul>
</section>

<section>
<h3>Query expression</h3>
<p>
Query expressions provide a language-integrated query feature using SQL-like
syntax.
</p>
<pre class="grammar">query-expr := query-select-expr | query-collect-expr
query-select-expr := [query-construct-type] query-pipeline select-clause [on-conflict-clause]
query-collect-expr := query-pipeline collect-clause
query-pipeline := from-clause intermediate-clause*
intermediate-clause :=
   from-clause
   | where-clause
   | let-clause
   | join-clause
   | limit-clause
   | order-by-clause
   | group-by-clause
</pre>
<p>
A query expression consists of a sequence of clauses. The semantics of clauses
is specified in terms of transforming a sequence of frames, where a frame is a
binding of variables to values. The input to each clause is a sequence of
frames.
</p>
<p>
The initial part of a query expression is a pipeline, where each clause outputs
a sequence of frames; the sequence of frames output by one clause become the
input to the next clause. As each clause in the pipeline is executed, it
iterates over its input frames and emits output frames. The pipeline is executed
lazily, with each clause pulling input from its preceding clause. The input to
the first clause is a single empty frame. The output of the pipeline is the
output of its last clause.
</p>
<p>
The remainder of the query expression says how to compute the result of the
query expression using the sequence of frames output by the query pipeline.
There are two kinds of query expression: query-select expressions and
query-collect expressions. In a query-select expression the pipeline is followed
by a <code>select</code> clause; in a query-collect expression, the pipeline is
followed by a <code>collect</code> clause.
</p>
<p>
The execution of certain intermediate clauses can result in the pipeline being
terminated prematurely. Specifically, when a <code>from</code> or
<code>join</code> clause is executed, it makes calls to the <code>next</code>
method of an Iterator object; if any of these calls return an error value
<var>e</var>, then the clause is said to <em>complete early</em> with error
value <var>e</var>. A query-select or query-collect expression will handle this
early completion by terminating the execution of the pipeline, as described
below.
</p>
<p>
Variables bound by the clauses of a query-pipeline are implicitly final, and
cannot be modified.
</p>

<section>
<h4>From clause</h4>
<pre class="grammar">from-clause := <code>from</code> typed-binding-pattern <code>in</code> expression
</pre>
<p>
A <code>from</code> clause is executed as follows:
</p>
<ul>
<li>for each input frame <var>f</var>
<ul>
<li>evaluate the <code>in</code> expression with <var>f</var> in scope resulting
in an iterable value <var>c</var>;</li>
<li>create an Iterator object <var>i</var> from <var>c</var></li>
<li>do the following in a loop <var>L</var>
<ul>
<li>call <code><var>i</var>.next()</code> resulting in a value <var>r</var>;</li>
<li>if <var>r</var> is an error, then complete execution of the from-clause
early with error <var>r</var>;</li>
<li>if <var>r</var> is <code>()</code>, stop loop <var>L</var>;</li>
<li>let <var>v</var> be <code><var>r</var>.value</code>;</li>
<li>emit a frame consisting of <var>f</var> augmented with the variables
resulting from binding typed-binding-pattern to <var>v</var>.</li>
</ul>
</li>  
</ul>
</li>  
</ul>
</section>

<section>
<h4>Where clause</h4>
<pre class="grammar">where-clause := <code>where</code><sub>NR</sub> expression
</pre>
<p>
A <code>where</code> clause is executed as follows:
</p>
<ul>
<li>for each input frame <var>f</var> 
<ul>
<li>execute the <code>expression</code> with <var>f</var> in scope resulting in
value <var>b</var>;</li>
<li>if <var>b</var> is true, emit <var>f</var>.</li>
</ul>
</li> 
</ul>
</section>

<section>
<h4>Let clause</h4>
<pre class="grammar">let-clause := <code>let</code> let-var-decl [<code>,</code> let-var-decl]* 
</pre>
<p>
A <code>let</code> clause consisting of a single let-var-decl is executed as follows:
</p>
<ul>
<li>for each input frame <var>f</var> 
<ul>
<li>evaluate the expression with <var>f</var> in scope resulting in a value <var>v</var>;</li>
<li>emit a frame consisting of <var>f</var> augmented with the result of binding
type-binding-pattern to <var>v</var>.</li>
</ul>
</li> 
</ul>
<p>
A <code>let</code> clause with more than one <code>let-var-decl</code> is
transformed into multiple <code>let</code> clauses: <code>let x<sub>1</sub> =
E<sub>1</sub>, x<sub>2</sub> = E<sub>2</sub></code> is transformed into
<code>let x<sub>1</sub> = E<sub>1</sub> let x<sub>2</sub> =
E<sub>2</sub></code>.
</p>
</section>

<section>
<h4>Join clause</h4>
<pre class="grammar">join-clause := [<code>outer</code><sub>NR</sub>] <code>join</code><sub>NR</sub> typed-binding-pattern <code>in</code> expression join-on-condition
join-on-condition := <code>on</code> expression <code>equals</code> expression
</pre>
<p>
A join clause performs an inner or left outer equijoin.
</p>
<p>
A <code>join</code> clause is executed as follows:
</p>
<ul>
<li>compute a mapping for the right side of the join; during this computation
variable bindings from input frames are not in scope:
<ul>
<li>create an empty mapping <var>m</var> that maps from keys to lists of frames
(using <a href="#DeepEquals">DeepEquals</a> to compare keys);</li>
<li>evaluate the expression following <code>in</code> resulting in an iterable
value <var>c</var>;</li>
<li>create an Iterator object <var>i</var> from <var>c</var>;</li>
<li>do the following in a loop <var>L</var>
<ul>
<li>call <code><var>i</var>.next()</code> resulting in a value <var>r</var>;</li>
<li>if <var>r</var> is an error, then complete execution of the join-clause
early with error <var>r</var>;</li>
<li>if <var>r</var> is <code>()</code>, stop loop <var>L</var>;</li>
<li>let <var>v</var> be <code><var>r</var>.value</code>;</li>
<li>let <var>f</var> be a frame with the result of binding the
typed-binding-pattern to <var>v</var>;</li>
<li>evaluate the expression to right of <code>equals</code> with <var>f</var>
in scope resulting in a value <var>k</var>;</li>
<li>add an entry to <var>m</var> with key <var>k</var> and and frame <var>f</var>;</li>
</ul>
</li>
</ul>
</li>
<li>for each input frame <var>f</var>
<ul>
<li>evaluate the expression to the left of <code>equals</code> with frame <var>f</var>
in scope resulting in a value <var>k</var>;</li>
<li>let <var>fs</var> be the list of frames for key <var>k</var> in <var>m</var>;</li>
<li>for each frame <var>f'</var> in <var>fs</var>
<ul>
<li>emit a frame consisting of <var>f</var> augmented with <var>f'</var>;</li>
</ul>
</li>
<li>if <code>outer</code> was specified and <var>fs</var> is empty, then emit a
single frame consisting of <var>f</var> augmented with a frame that binds every
variable occurring in typed-binding-pattern to <code>()</code>.
</li>
</ul>
</li>
</ul>
<p>
In the above, if <var>c</var> evaluates to a table, and the result of evaluating
the expression to the right of <code>equals</code> 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.
</p>
<p>
Variables bound by previous clauses are not in scope for the expression
following <code>in</code>, nor for the expression on the right of
<code>equals</code>. Variables bound by the typed-binding-pattern are not in
scope for the expression following <code>in</code>, nor for the expression on
the left of <code>equals</code>.
</p>
<p>
When <code>outer</code> is specified, the typed-binding-pattern is treated
specially: the inferable-type-descriptor in the typed-binding-pattern must be
<code>var</code>, and for each variable occurring in the typed-binding-pattern,
if the type that would be inferred usually for the variable would be
<var>T</var>, then the type inferred in this case will be
<var>T</var><code>?</code>.
</p>

</section>

<section>
<h4>Limit clause</h4>
<pre class="grammar">
limit-clause := <code>limit</code><sub>NR</sub> expression
</pre>
<p>
A <code>limit</code> clause limits the number of frames emitted by a query pipeline.
</p>
<p>
A <code>limit</code> clause is executed as follows:
</p>
<ul>
<li>evaluate expression resulting in a value <var>n</var>; variable bindings
from input frames are not in scope for this evaluation;</li>
<li>if <var>n</var> is less than zero, then panic;</li>
<li>for each input frame <var>f</var>, while <var>n</var> is greater than 0
<ul>
<li>decrement <var>n</var>;</li>
<li>emit <var>f</var>.</li> 
</ul>
</li> 
</ul>

<p>
The static type of expression must be a subtype of <code>int</code>.
</p>

</section>

<section>
<h4>Order by clause</h4>
<pre class="grammar">
order-by-clause := <code>order</code><sub>NR</sub> <code>by</code><sub>NR</sub> order-key [<code>,</code> order-key]*
order-key := expression [order-direction]
order-direction := <code>ascending</code> | <code>descending</code>
</pre>
<p>
The static type of the expression in an order-key must be an <a
href="#ordering">ordered</a> type. The order-direction is <code>ascending</code>
if not explicitly specified.
</p>
<p>
An <code>order-by</code> clause is executed by constructing a list
of entries, where each entry consists of:
</p>
<ul>
<li>a frame</li>
<li>a list of keys, one for each order-key in the order-by-clause, and</li>
<li>an integer index</li>
</ul>
<p>
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<sub>1</sub>,x<sub>2</sub>,...,x<sub>n</sub>], y be
[y<sub>1</sub>,y<sub>2</sub>,...,y<sub>n</sub>], and d be [d<sub>1</sub>,
d<sub>2</sub>,...,d<sub>n</sub>]. Then let r be
CompareK(x<sub>1</sub>,y<sub>1</sub>,d<sub>1</sub>). Then the result of
CompareKL(x,y,d) is:
</p>
<ul>
<li>r, if r is not EQ</li>
<li>otherwise, EQ, if n is 1</li>
<li>otherwise,
CompareKL([x<sub>2</sub>,...,x<sub>n</sub>],[y<sub>2</sub>,...,y<sub>n</sub>],[d<sub>2</sub>,...,d<sub>n</sub>]).</li>
</ul>
<p>
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.
</p>
<p>
An <code>order-by</code> clause is executed as follows:
</p>
<ul>
<li>create an empty list <var>E</var> of entries</li>
<li>for each input frame <var>f</var> add an entry to <var>E</var> in which
<ul>
<li>the frame is <var>f</var></li>
<li>the list of keys is a list of the results of evaluating each order-key's
expression with <var>f</var> in scope</li>
<li>the index is the length of <var>E</var></li>
</ul>
</li>
<li>sort <var>E</var> so that it is ordered correctly as described above</li>
<li>for each entry in <var>E</var>, emit the entry's frame</li>
</ul>

</section>

<section>
<h4 id="aggregated_variables">Aggregated variable bindings</h4>

<p>
Frames constructed by collect and group-by clauses can contain
<em>aggregated</em> variable bindings. The type of an aggregated variable
binding is always a list type; as usual, the
value bound to the variable belongs to this type. An aggregrated variable is
special in that it is only allowed to be referenced by an
aggregated-variable-reference; the semantics of such a reference are different
from the semantics of a variable-reference-expr.
</p>
<p>
An aggregated variable binding for a variable <var>x</var> is <em>aggregated
from</em> a sequence of frames <var>S</var>, by binding <var>x</var> to a list
with the same length as <var>S</var>, where the <var>i</var>-th member of the
list is the value bound to <var>x</var> in the <var>i</var>-th frame in
<var>S</var>. The type of the aggregated variable binding is derived from the
type <code><var>T</var></code> of <var>x</var> in S and the kind of clause
<var>C</var> that is constructing the binding. When <var>C</var> is a collect
clause, <var>S</var> can be empty and the type is <code><var>T</var>[]</code>.
When <var>C</var> is a group-by clause, <var>S</var> cannot be empty and so the
type is <code>[<var>T</var>,<var>T</var>...]</code>.
</p>

<pre class="grammar">aggregated-variable-reference := identifier
</pre>
<p>
A reference to an aggregated variable binding is <em>implicitly spread</em>: an
identifier <code><var>x</var></code> that refers to an aggregated variable
binding is treated like a spread <code>...<var>y</var></code>, where the
variable <code><var>y</var></code> has the same type and value as
<code><var>x</var></code> but is not aggregated.
</p>
<p>
The grammar shows this by using the aggregated-variable-reference production. A
reference to an aggregated variable is allowed only in a syntactic context where
the grammar allows an aggregated-variable-reference. In each such syntactic
context, the grammar also allows both a variable-reference-expr and a spread.
When a reference to an aggregated variable occurs in an allowed context, it
should be parsed as a aggregated-variable-reference rather than as a
variable-reference-expr, and should be transformed into the equivalent spread.
Any other reference to an aggregated variable should be parsed as a
variable-reference-expr, and then rejected as semantically incorrect.
</p>
</section>

<section>
<h4>Group by clause</h4>
<pre class="grammar">group-by-clause := <code>group</code><sub>NR</sub> <code>by</code><sub>NR</sub> grouping-key (<code>,</code> grouping-key)*
grouping-key :=
   variable-name
   | inferable-type-descriptor variable-name <code>=</code> expression
</pre>
<p>
A group-by-clause that uses an inferable-type-descriptor is transformed into a a
let-clause followed by a group-by-clause where every grouping-key is a
variable-name. For example:
</p>
<pre>group by var x1 = E1, var x2 = E2
</pre>
<p>
is transformed to
</p>
<pre>let x1 = E1, x2 = E2 group by x1, x2
</pre>
<p>
A group-by clause where every grouping-key is a variable-name is executed by
first partitioning the sequence of input frames <var>S</var> into a set
<var>P</var> of non-empty sequences of frames, such that:
</p>
<ul>
<li>every member <var>P</var> is a subsequence (not necessarily consecutive) of <var>S</var>;</li>
<li>every constituent of <var>S</var> is a constituent of exactly one member of <var>P</var>;</li>
<li>two constituents <var>f</var><sub>1</sub> and <var>f</var><sub>2</sub> of
<var>S</var> are constituents of the same member of <var>P</var> if and only if
for every variable <var>x</var> that is a grouping-key,
DeepEquals(<var>x</var><sub>1</sub>,<var>x</var><sub>2</sub>) is true, where
<var>x</var><sub>1</sub> is the value bound to <var>x</var> in
<var>f</var><sub>1</sub>, and <var>x</var><sub>2</sub> is the value bound to
<var>x</var> in <var>f</var><sub>2</sub>.</li>
</ul>
<p>
Next, for each sequence <var>G</var> in <var>P</var>, ordered by the order in
which the first constituent of <var>G</var> occurs in <var>S</var>, an output
frame is constructed from <var>G</var> and emitted. An output frame <var>g</var>
is constructed from a sequence of input frames <var>G</var> as follows. The same
variables are bound by <var>g</var> as are bound by <var>G</var>. For each
variable that is a grouping-key, the value and type in <var>g</var> will be the
same as the value and type in the first constituent of <var>G</var>. The binding
for every other variable is <a href="#aggregated_variables">aggregated from</a>
<var>G</var>.
</p>

</section>

<section>
<h4>Collect clause</h4>
<pre class="grammar">collect-clause := <code>collect</code><sub>NR</sub> expression
</pre>

<p>
A query-collect expression is used to perform aggregation. It is evaluated as
follows.
</p>

<ol>
<li>The query-pipeline is executed to produce a sequence of frames <var>S</var>.
If during this any clause completes early with error value <var>e</var>, then
the result of evaluating the query-collect-expr is <var>e</var>. In addition,
the normal rules apply if the execution of any clause results in the evaluation
of an expression completing abruptly.</li>
<li>A frame <var>f</var> is constructed. For each variable <var>x</var> that is
bound by <var>S</var>, <var>f</var> has a variable binding for <var>x</var> that
is <a href="#aggregated_variables">aggregated from</a> <var>S</var>.</li>
<li>The expression in the collect-clause is evaluated with <var>f</var> in scope
resulting in a value <var>v</var>.</li>
<li>The result of the query-collect expression is <var>v</var>.</li>
</ol>

<p>
The contextually expected type for the expression in the collect-clause is the
contextually expected type for the query-collect-expr.
</p>
</section>

<section>
<h4>Select clause</h4>

<pre class="grammar">
select-clause := <code>select</code><sub>NR</sub> expression
</pre>
<p>
When a query-select expression is evaluated, the <code>select</code> clause is
executed as follows, so as to emit a sequence of values:
</p>
<ul>
<li>for each frame <var>f</var> output by the query pipeline
<ul>
<li>evaluate the expression that follows <code>select</code> with <var>f</var>
in scope resulting in value <var>v</var></li>
<li>emit <var>v</var></li> 
</ul>
</li> 
</ul>
<p>
The sequence of values emitted by the execution of the <code>select</code>
clause is used to construct a value, which becomes the result of the
query-select-expr. The constructed result value must be one of the following
basic types:
</p>
<ul>
<li>list - the constructed list has a member for each emitted value; every
emitted value must belong to type T, where T[] is the type of the constructed
value;</li>
<li>mapping - the constructed mapping has a member for each emitted value; every
emitted value must belong to type [string, T], where map&lt;T&gt; is the type
of the constructed value; an emitted value <code>[<var>k</var>,
<var>v</var>]</code> results in adding a field with key
<code><var>k</var></code> and value <code><var>v</var></code>;</li>
<li>table - the constructed table has a member for each emitted value; every
emitted value must belong to type T, where table&lt;T&gt; is the type of the
constructed value;</li>
<li>string - the constructed string is the concatenation of the emitted values;
every emitted value must be of type string;</li>
<li>xml - the constructed xml value is the concatenation of the emitted values;
every emitted value must be of type xml;</li>
<li>stream - the stream generates the emitted values.</li>
</ul>
<p>
The clauses in a query-select-expr are executed either eagerly or lazily. If a
query-select-expr is constructing a stream, they are executed lazily; otherwise,
they are executed eagerly. When the clauses in a query-select-expr are being
executed eagerly, the execution happens during the evaluation of the
query-select-expr. When the clauses are being executed lazily, the evaluation of
the query-select-expr constructs a stream object without executing any of the
clauses; the clauses becomes closures, which are called later as a result of
next operations being performed on the stream.
</p>
<p>
With eager execution, if any clause completes early with error value
<var>e</var>, then the result of evaluating the query-select-expr is
<var>e</var>. In addition, the normal rules apply if the execution of any clause
results in the evaluation of an expression completing abruptly.
</p>
<p>
With lazy execution, when a next operation on the stream results in the
execution of a clause that completes early with error value <var>e</var>, then
that next operation returns <var>e</var>. Similarly, if the next operation
results in the evaluation of an expression within the query-select-expr
completing abruptly with a check-fail, the associated error value will be
returned as the result of the next operation; if the next operation results in
the evaluation of an expression within the query-select-expr completely abruptly
with a panic, then the next operation will complete abruptly with a panic.
</p>

<pre class="grammar">query-construct-type :=
  <code>map</code>
  | <code>table</code> key-specifier
  | <code>stream</code>
</pre>
<p>
If a query-construct-type is specified, then it determines the basic type of the
result. A query-select-expr that constructs a mapping must specify a
query-construct-type of <code>map</code>.
When constructing a table, the key-specifier specifies the key
sequence of the constructed table in the same way as with a
table-constructor-expr.
</p>
<p>
If no query-construct-type is specified, the applicable contextually expected
type determines the basic type of the value constructed. If there is no
contextually expected type, then the basic type of the value constructed is the
basic type of expression following <code>in</code>; it is a compile-time error
if the static type of this expression is not a subtype of one of the basic types
list, table, string, stream or xml.
</p>
<p>
When the query-select-expr is constructing a value of basic type list, mapping, table
or xml, and the applicable contextually expected type is a subtype of readonly,
then the query-select-expr will construct a value with its read-only bit set and the
static type of the query-select-expr will be a subtype of readonly. Furthermore, the
contextually expected type for the expression in the select-clause will also be
a subtype of readonly.
</p>
</section>

<section>
<h4>On conflict clause</h4>
<pre class="grammar">
on-conflict-clause := <code>on</code> <code>conflict</code><sub>NR</sub> expression
</pre>
<p>
During the execution of the select clause of query-select-expr that is
constructing a map or table, when value emitted by the select clause is added as
a new member of the map or table being constructed, it replaces any existing
member with the same key value; when a new member replaces an existing member,
it will have the same position in the order of members as the existing member.
This behavior may be controlled by an <code>on conflict</code> clause.
</p>
<p>
An <code>on conflict</code> clause is allowed only for a query-select-expr that
constructs a table with a key sequence or a map. The expression is evaluated
when the <code>select</code> clause emits a value that conflicts with a previous
value, in the sense that both values have the same key value in the map or
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 <code>error?</code>. If the result
of evaluating the expression is an error <var>e</var>, then the result of
evaluating the query-select-expr is <var>e</var>. 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 <code>on conflict</code> clause.
</p>
<p>
Note that the expression in an on-conflict-clause may have side-effects; for
example, it may call a function that logs an error.
</p>
</section>

</section>
<section>
<h3>XML navigation expression</h3>
<p>
XML navigation expressions allow for convenient navigation of XML element structure,
in a similar way to XPath.
</p>

<pre
class="grammar">xml-navigate-expr := xml-filter-expr | xml-step-expr
</pre>
<section>
<h4>XML name pattern</h4>
<pre
class="grammar">xml-name-pattern := xml-atomic-name-pattern [<code>|</code> xml-atomic-name-pattern]*

xml-atomic-name-pattern :=
  <code>*</code>
  | identifier
  | xml-namespace-prefix NoSpaceColon identifier
  | xml-namespace-prefix NoSpaceColon <code>*</code>
</pre>

<p>
An XML name pattern matches a string specifying the name of an XML element.
</p>
<p>
An xml-atomic-name-pattern that is <code>*</code> matches any name.
</p>
<p>
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.
</p>
</section>
<section>
<h4>XML filter expression</h4>
<pre
class="grammar">xml-filter-expr := expression <code>.&lt;</code> xml-name-pattern <code>&gt;</code>
</pre>
<p>
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
<code>xml&lt;xml:Element&gt;</code>.
</p>
</section>
<section>
<h4>XML step expression</h4>
<p>
An xml-step-expr provides access to the children or descendants of an element,
similar to a location path in XPath.
</p>
<pre
class="grammar">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 := <code>/*</code>
xml-element-children-step := <code>/&lt;</code> xml-name-pattern <code>&gt;</code>
xml-element-descendants-step := <code>/**/&lt;</code> xml-name-pattern <code>&gt;</code>

xml-step-extend :=
   <code>.&lt;</code> xml-name-pattern <code>&gt;</code>
   | <code>[</code> expression <code>]</code>
   | <code>.</code> method-name <code>(</code> arg-list <code>)</code>
</pre>
<p>
The production for xml-step-expr is ambiguous with the productions for
member-access-expr and method-call-expr: this must be resolved by preferring the
parse that includes as much as possible in the xml-step-expr.
</p>
<p>
The static type of the expression must be a subtype of xml.
</p>
<p>
An xml-step-expr that starts with an xml-all-children-step
</p>
<pre>
   <var>E</var> /* <var>X</var>
</pre>
<p>
is equivalent to
</p>
<pre>
   xml:map(xml:elements(<var>E</var>), v => xml:getChildren(v) <var>X</var>)
</pre>
<p>
where <code>v</code> is a variable name not used in <code><var>X</var></code>.
</p>
<p>
An xml-step-expr that starts with an xml-element-children-step
</p>
<pre>
   <var>E</var> /&lt; <var>NP</var> &gt; <var>X</var>
</pre>
<p>
is equivalent to
</p>
<pre>
   xml:map(xml:elements(<var>E</var>), v => xml:getChildren(v) .&lt;<var>NP</var>&gt; <var>X</var>)
</pre>
<p>
where <code>v</code> is a variable name not used in <code><var>X</var></code>.
</p>
<p>
An xml-step-expr that starts with an xml-element-descendants-step
</p>
<pre>
   <var>E</var> /**/&lt; <var>NP</var> &gt; <var>X</var>
</pre>
<p>
is equivalent to
</p>
<pre>
   xml:map(xml:elements(<var>E</var>), v => xml:getDescendants(v) .&lt;<var>NP</var>&gt; <var>X</var>)
</pre>
<p>
where <code>v</code> is a variable name not used in <code><var>X</var></code>.
</p>
</section>
</section>
<section>
<h3>Transactional expression</h3>

<pre
class="grammar">transactional-expr := <code>transactional</code>
</pre>
<p>
A <code>transactional-expr</code> evaluates to true if the expression is being
evaluated in transaction mode and false otherwise.
</p>

</section>

</section>
<section>
<h2 id="actions_statements">7. Actions and statements</h2>
<section>
<h3>Actions</h3>

<pre
class="grammar">action :=
   start-action
   | wait-action
   | send-action
   | receive-action 
   | flush-action
   | client-remote-method-call-action
   | client-resource-access-action
   | query-action
   | commit-action

action-or-expr :=
   expr-only
   | action
   | type-cast-action-or-expr
   | checking-action-or-expr
   | trap-action-or-expr
   | query-action-or-expr
   | <code>(</code> action-or-expr <code>)</code>

type-cast-action-or-expr := <code>&lt;</code> type-cast-param <code>&gt;</code> action-or-expr
checking-action-or-expr := checking-keyword action-or-expr
trap-action-or-expr := <code>trap</code> action-or-expr
</pre>
<p>
Actions are an intermediate syntactic category between expressions and
statements. Actions are similar to expressions, in that they yield a value.
However, an action cannot be nested inside an expression; it can only occur as
part of a statement or nested inside other actions. This is because actions are
shown in the sequence diagram in the graphical syntax.
</p>
<p>
As with the grammar for expression, the grammar for action-or-expr is ambiguous.
The precedence for action-or-expr is the same as for expression, with the
addition that the <code>-&gt;</code> operator used in a
client-remote-method-call-action has the same precedence as the <code>.</code>
operator used in a method-call-expr.
</p>
<p>
An action is evaluated in the same way as an expression. Static typing for
actions is the same as for expressions.
</p>
<p>
A <code>type-cast-action-or-expr</code>, <code>checking-action-or-expr</code> or
<code>trap-action-or-expr</code> is evaluated in the same way as a
<code>type-cast-expr</code>, <code>checking-expr</code> or
<code>trap-expr</code> respectively.
</p>

<pre
class="grammar">query-action-or-expr := query-select-action-or-expr | query-collect-action-or-expr
query-select-action-or-expr := [query-construct-type] query-action-pipeline select-action-clause [on-conflict-clause]
query-collect-action-or-expr := query-action-pipeline collect-action-clause
query-action-pipeline := from-action-clause intermediate-action-clause*
intermediate-action-clause :=
   from-action-clause
   | let-action-clause
   | join-action-clause
   | where-clause
   | limit-clause
   | order-by-clause
   | group-by-clause

from-action-clause := <code>from</code> typed-binding-pattern <code>in</code> action-or-expr
let-action-clause := <code>let</code> let-action-var-decl [<code>,</code> let-action-var-decl]*
let-action-var-decl := [annots] typed-binding-pattern <code>=</code> action-or-expr
join-action-clause := [<code>outer</code><sub>NR</sub>] <code>join</code><sub>NR</sub> typed-binding-pattern <code>in</code> action-or-expr join-on-condition
select-action-clause := <code>select</code><sub>NR</sub> action-or-expr
collect-action-clause := <code>collect</code><sub>NR</sub> action-or-expr
</pre>
<p>
A <code>query-action-or-expr</code> is a <code>query-expr</code> in which
certain subexpressions are allowed to be an <code>action-or-expr</code>. It is
evaluated in the same way as a <code>query-expr</code>.
</p>

</section>
<section>
<h3>Threads and strands</h3>

<p>
Ballerina's concurrency model supports both threads and coroutines. A Ballerina
program is executed on one or more threads. A thread may run on a separate core
simultaneously with other threads, or may be pre-emptively multitasked with
other threads onto a single core.
</p>
<p>
Each thread is divided into one or more <em>strands</em>. No two strands
belonging to the same thread can run simultaneously. Instead, all the strands
belonging to a particular thread are cooperatively multitasked. Strands within
the same thread thus behave as coroutines relative to each other. A strand
enables cooperative multitasking by <em>yielding</em>. When a strand yields,
the runtime scheduler may suspend execution of the strand, and switch its thread
to executing another strand. The following actions cause a strand to yield:
</p>
<ul>
<li>worker-receive-action</li>
<li>wait-action</li>
<li>flush-action</li>
<li>sync-send-action</li>
</ul>
<p>
In addition, any function with an external-function-body can potentially yield;
it should only do so if it performs a system call that would block or calls a
Ballerina function that itself yields. The <code>sleep</code> function in
<code>lang.runtime</code> will make the strand yield. Other functions in the
lang library do not themselves yield, although if they call a function passed as
an argument, that function may result in yielding.
</p>
<p>
There are two language constructs whose execution causes the creation of new
strands: named-worker-decl and start-action. Except in the cases explicitly
allowed by this specification, the new strand must be part of the same thread as
the current strand. An implementation may also allow annotations to be used to
indicate that the newly created strand should be in a separate thread from the
current strand.
</p>

</section>
<section>
<h3>Function bodies</h3>

<section>
<h4>Function parameters</h4>
<p>
Before the block-function-body of a function-defn is executed, the parameters
declared in the function-signature of the function-defn are initialized from the
argument list that was constructed by the function-call-expr. 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 list 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.
</p>
<p>
The parameters are in scope for the block-function-body. They are implicitly
final: they can be read but not modified.
</p>
</section>

<section>
<h4>Workers</h4>

<pre
class="grammar">block-function-body :=
   <code>{</code> [default-worker-init named-worker-decl+] default-worker <code>}</code>
default-worker-init := statement*
default-worker := statement*
named-worker-decl :=
   [annots] [transactional-qual] <code>worker</code> worker-name return-type-descriptor statement-block [on-fail-clause]
worker-name := identifier
</pre>
<p>
A worker represents a single strand of a function invocation. A statement
is always executed in the context of a current worker. A worker is in one of
three states: active, inactive or terminated. When a worker is in the
terminated state, it has a termination value. A worker terminates either
normally or abnormally. An abnormal termination results from a panic, and in
this case the termination value is always an error. If the termination value of
a normal termination is an error, then the worker is said to have terminated
with failure; otherwise the worker is said to have terminated with success. Note
that an error termination value resulting from a normal termination is
distinguished from an error termination value resulting from an abnormal
termination.
</p>
<p>
A function always has a single default worker, which is unnamed. The strand for
a function's default worker is the same as the strand of the worker on which
function was called. When a function is called, the current worker becomes
inactive, and a default worker for the called function is started. When the
default worker terminates, the function returns to its caller, and the caller's
worker is reactivated. Thus only one worker in each strand is active at any
given time. If a function's default worker terminates normally, then its
termination value provides the return value of the function. If a function's
default worker terminates abnormally, then the evaluation of the function call
expression completes abruptly with a panic and the worker's termination value
provides the associated value for the abrupt completion of the function call.
The function's return type is the same as the return type of the function's
default worker.
</p>
<p>
A function also has zero or more named workers. Each named worker runs on its
own new strand. The strand can run on a separate thread from the default worker if the
function is isolated. The termination of a function is independent of the termination
of its named workers. The termination of a named worker does not automatically
result in the termination of its function. When a function's default worker
terminates, causing the function to terminate, the function does not
automatically wait for the termination of its named workers.
</p>
<p>
A named worker has a return type. If the worker terminates normally, the
termination value will belong to the return type. If the return type of a worker
is not specified, it defaults to nil as for functions.
</p>
<p>
A named-worker is a transactional scope only if it is declared as
<code>transactional</code>. This is allowed only if the block-function-body is a
transactional scope, i.e. if it is the body of a function declared as
<code>transactional</code>.
</p>
<p>
When a function has named workers, the function's default worker executes in
three stages, as follows:
</p>
<ol>
<li>The statements in default-worker-init are executed.</li>
<li>All the named workers are started. Each named worker executes its
statement-block on its strand.</li>
<li>The statements in default-worker are executed. This happens without waiting
for the termination of the named workers started in stage 2.</li>
</ol>
<p>
Parameters and variables declared in default-worker-init are in scope within
named workers, whereas variables declared in default-worker are not.
</p>
<p>
The execution of a worker's statements may result in the execution of a
statement that causes the worker to terminate. For example, a return statement
causes the worker to terminate. If this does not happen, then the worker
terminates as soon as it has finished executing its statements. In this case,
the worker terminates normally, and the termination value is nil. In other
words, falling off the end of a worker is equivalent to <code>return;</code>,
which is in turn equivalent to <code>return ();</code>.
</p>
<p>
The scope of a worker-name in a named-worker-decl that is part of a
block-function-body is the entire block-function-body with the exception of the
default-worker-init. When a worker-name is in scope, it can be used in a
variable-reference-expr. The result of evaluating such a variable reference is a
future value that refers to the value to be returned by that named worker. The
static type of the result is future&lt;T&gt;, where T is the return type of the
worker.
</p>
<p>
A strand can initiate a wait on another strand by using a wait-action with a
value of type future. Only one wait on a strand can succeed; this wait receives
the value returned by the strand. Any other waits on that strand fail. It is a
compile-time error if for any named worker it is possible for the name of that
worker to be evaluated as a variable-reference more than once for any execution
of that worker. This ensures that wait operations that use just a worker-name to
identify the strand to wait on cannot fail at runtime.
</p>
<p>
In the above, function includes method, and function call includes method call.
</p>
</section>

<section>
<h4>Expression-bodied functions</h4>

<pre
class="grammar">expr-function-body := <code>=></code> expression
</pre>

<p>
An expr-function-body is used for an expression-bodied function, that is a
function whose body is specified by an expression. An expr-function-body of the
form <code>=> <var>E</var></code> is short for a block-function-body <code>{
return <var>E</var >}</code>.
</p>

</section>

<section>
<h4>Functions with external bodies</h4>

<pre
class="grammar">external-function-body := <code>=</code> [annots] <code>external</code> 
</pre>

<p>
An <code>external-function-body</code> means that the implementation of the
function is not provided in the Ballerina source module. A function-defn-body
with a function-signature that is dependently-typed must be an
external-function-body.
</p>

</section>
<section>
<h4 id="isolated_functions">Isolated functions</h4>
<p>
The body of a function or method declared as <code>isolated</code> must meet the
following requirements.
</p>
<ul>
<li>Only isolated functions can be called:
<ul>
<li>in a function-call-expr, the function-reference must refer to a function
whose static type is isolated;</li>
<li>in a method-call-expr, the method-name must refer to a method or
function whose static type is isolated;</li>
<li>in a new-expr or object-constructor-expr, the init method that is called
must be declared as isolated (a missing init method is equivalent is implicitly
isolated).</li>
</ul>
</li>
<li>Non-isolated module-level state can only be read in two cases, specifically
a variable-reference can refer to an an identifier declared by a
module-var-decl or listener-decl only if:
<ul>
<li>the identifier is declared by a module-var-decl that includes
<code>final</code> or <code>configurable</code> but does not include
<code>isolated</code>, or is declared by a listener-decl or a service-decl,
and</li>
<li>the static type of the variable is a subtype of <code>isolated object
{}</code> or of <code>readonly</code> (which will always be the case if the
identifier is declared as <code>configurable</code>).</li>
</ul>
</li>
<li>Non-isolated module-level state cannot be mutated: an identifier in a
variable-reference-lvexpr or in a capture-binding-pattern in a
destructuring-assignment-stmt must not refer to a variable defined by a
module-var-decl that does not include <code>isolated</code>.</li>
<li>A variable reference to a captured variable must refer to variables that are
both final (either explicitly or implicitly) and have a static type that is a
subtype of <code>readonly|isolated object {}</code>, where a variable reference
is captured if it occurs within an anonymous-function-expr or named-worker-decl
and refers to a variable declared within the function but outside of that
anonymous-function-expr or named-worker-decl.</li>
<li>A start-action is allowed only if its call-action-or-expression is isolated.</li>
</ul>
<p>
If an isolated function has an <code>external-function-body</code>, then the
above requirements also apply to the external implementation as regards its
access to the mutable state of the Ballerina program, in the sense that it must
only access the mutable state that is reachable from the parameters passed to
the function. In addition, the function should have well-defined behaviour if it
is called concurrently on multiple strands.
</p>
</section>
</section>
<section>
<h3>Statements</h3>

<pre
class="grammar">statement := 
   action-stmt
   | local-var-decl-stmt
   | xmlns-decl-stmt
   | assignment-stmt
   | compound-assignment-stmt
   | destructuring-assignment-stmt
   | call-stmt
   | checking-stmt
   | if-else-stmt
   | regular-compound-stmt
   | continue-stmt
   | break-stmt
   | stmt-with-on-fail
   | fail-stmt
   | rollback-stmt
   | panic-stmt
   | return-stmt
   | fork-stmt
</pre>

<pre
class="grammar">
regular-compound-stmt :=
   do-stmt
   | match-stmt
   | foreach-stmt
   | while-stmt
   | lock-stmt
   | retry-stmt
   | transaction-stmt
   | retry-transaction-stmt
</pre>
<p>
A <code>regular-compound-stmt</code> can be combined with an
<code>on-fail-clause</code> to make a <code>stmt-with-on-fail</code>.
</p>

<section>
<h4>Statement execution</h4>
<p>
The execution of a statement completes in one of three ways:
</p>
<ul>
<li>it may complete normally;</li>
<li>it may complete by terminating the current worker; or</li>
<li>it may complete by transferring control within the same worker.</li>
</ul>
<p>
When the execution of a statement involves the evaluation of an action or an
expression, and that evaluation completes abruptly, then, except where
explicitly stated to the contrary, the execution of the statement completes as
follows.
</p>
<ul>
<li>If the abrupt completion is a check-fail with associated value e, then
control flow is transferred as if by a <code>fail-stmt</code> with an expression
that evaluates to e.</li>
<li>If the abrupt completion is a panic with associated value e, then the
current worker is terminated as if by a <code>panic-stmt</code> with an
expression that evaluates to e.</li>
</ul>
<p>
The following sections describe for each kind of statement any other cases in
which the execution of that kind of statement does not completely normally.
</p>
</section>

<section>
<h4>Statement blocks</h4>
<pre
class="grammar">
statement-block := <code>{</code> statement* <code>}</code>
</pre>
<p>
A <code>statement-block</code> is executed by executing its
<code>statement</code>s sequentially. This means that when the execution of one
<code>statement</code> completes normally, the immediately following
<code>statement</code> is executed. However, when the executon
<code>statement</code> does not complete normally, then none of the following
<code>statement</code>s in the <code>statement-block</code> are executed. The
execution of the <code>statement-block</code> completes normally if and only if
the execution of all of its <code>statement</code>s completes normally.
</p>
</section>

<section>
<h4>Unreachability</h4>
<p>
A statement is <em>reachable</em> if the analysis described in this section
determines that there is a possibility that the statement will be executed. It
is a compile error if a <code>statement</code> other than a
<code>panic-stmt</code> is not reachable.
</p>
<p>
The analysis proceeds by determining recursively for each statement whether it
is possible for the statement to complete normally, assuming that the statement
is reachable. Each <code>statement</code> in a <code>statement-block</code>
after the first <code>statement</code> is reachable only if it is possible for
all of the preceding <code>statement</code>s to complete normally.
</p>
<p>
When the execution of a statement or a transfer of control is conditional on the
result of evaluating an expression, then the analysis assumes that it is
possible for the statement to be executed or control to be transferred, unless
the static type of the expression makes it impossible. Similarly, when the
evaluation of a subexpression is conditional on the result of previously
evaluating another subexpression, then the analysis assumes that the second
evaluation is possible unles the static type of the first subexpression makes it
impossible.
</p>
</section>

</section>


<section>
<h3>Fork statement</h3>

<pre
class="grammar">fork-stmt := <code>fork</code> <code>{</code> named-worker-decl+ <code>}</code>
</pre>
<p>
The fork statement starts one or more named workers, which run in parallel with
each other, each in its own new strand. The strand can run on a separate thread
from the current worker if the fork-stmt occurs in an isolated function.
</p>
<p>
Variables and parameters in scope for the fork-stmt remain in scope within the
workers (similar to the situation with parameters and workers in a function
body).
</p>
<p>
The scope of the worker-name in a named-worker-decl that is part of a fork-stmt
consists of both other workers in the same fork-stmt and the block containing
the fork-stmt starting from the point immediately after the fork-stmt. Within
its scope, the worker-name can be used in a variable-reference-expr in the same
way as the worker-name of a named-worker-decl that is part of a
block-function-body.
</p>
</section>
<section>
<h3>Start action</h3>

<pre
class="grammar">start-action := [annots] <code>start</code> call-action-or-expr
call-action-or-expr :=
   function-call-expr
   | method-call-expr
   | client-remote-method-call-action
   | client-resource-access-action
</pre>

<p>
The keyword <code>start</code> causes the following function or method
invocation to be executed on a new strand. The arguments for the function or
method call are evaluation on the current strand. A start-action returns a value
of basic type future immediately. If the static type of the call expression or
action <code><var>C</var></code> is T, then the static type of <code>start
<var>C</var></code> is future&lt;T&gt;; it is permitted for T to be
<code>never</code>.
</p>
<p>
A call-action-or-expr is <em>isolated</em> if the function or method it calls
has a type that is isolated and the expression for every argument is an <a
href="#isolated_expressions">isolated expression</a>; for this purpose, the
object whose method is called by the method-call-expr or
client-remote-method-call-action is treated as an argument. When a start-action
has a call-action-or-expr that is isolated then
</p>
<ul>
<li>the start-action is allowed in an isolated function, and</li>
<li>the strand created by the start-action may run in a separate thread from the
current thread.</li>
</ul>

</section>
<section>
<h3>Wait action</h3>
<p>
A wait-action waits for one or more strands to terminate, and gives access to
their termination values.
</p>

<pre
class="grammar">wait-action :=
   single-wait-action
   | multiple-wait-action
   | alternate-wait-action

wait-future-expr := expression <em>but not</em> mapping-constructor-expr
</pre>
<p>
A wait-future-expr is used by a wait-action to refer to the worker to be waited
for. Its static type must be future&lt;T&gt; for some T. As elsewhere, a
wait-future-expr can use an in-scope worker-name in a variable-reference-expr to
refer to named worker.
</p>
<p>
Evaluation of a wait-action performs a wait operation on the future value that
results from evaluating a wait-future-expr. This wait operation may complete
normally or abruptly. The wait operation initiates a wait for the strand that
the future refers to. If the wait fails, then the wait operation completes
normally and the result is an error. If the wait succeeds, and the strand
completed normally, then the wait operation completes normally, and the result
is the termination value of the strand. If the wait succeeds, but the strand
completed abnormally, then the wait operation completes abruptly with a panic
and the associated value is the termination value of the strand.
</p>
<p>
In addition to a static type, a wait-future-expr has a compile-time <em>eventual
type</em>. If a wait-future-expr is a variable-reference-expr referring to the
worker-name of a named worker with return type T, then the eventual type of the
wait-future-expr is T. Otherwise, the eventual of a wait-future-expr with static
type future&lt;T&gt; is T|error. The result of a wait operation that completes
normally will belong to the eventual type of the wait-future-expr, since the
compiler ensures that a wait for a wait-future-expr that is a variable reference
to a named worker cannot fail.
</p>
<p>
Note that it is only possible to wait for a named worker, which will start its
own strand. It is not possible to wait for a function's default worker, which
runs on an existing strand.
</p>
<p>
A mapping-constructor-expr is not recognized as a wait-future-expr (it would not
type-check in any case).
</p>
<section>
<h4>Single wait action</h4>

<pre
class="grammar">single-wait-action := <code>wait</code> wait-future-expr
</pre>
<p>
A single-wait-action waits for a single future.
</p>
<p>
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.
</p>
<p>
The static type of the single-wait-action is the eventual type of the
wait-future-expr.
</p>
</section>
<section>
<h4>Multiple wait action</h4>

<pre
class="grammar">multiple-wait-action := <code>wait</code> <code>{</code> wait-field (<code>,</code> wait-field)* <code>}</code>
wait-field :=
  variable-name
  | field-name <code>:</code> wait-future-expr
</pre>
<p>
A multiple-wait-action waits for multiple futures, returning the result as a
record.
</p>
<p>
A wait-field that is a variable-name <code>v</code> is equivalent to a
wait-field <code>v: v</code>, where <code>v</code> must be the name of an
in-scope named worker.
</p>
<p>
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.
</p>
<p>
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.
</p>
</section>
<section>
<h4>Alternate wait action </h4>

<pre
class="grammar">alternate-wait-action := <code>wait</code> wait-future-expr (<code>|</code> wait-future-expr)+
</pre>
<p>
An alternate-wait-action waits for one of multiple futures to terminate.
</p>
<p>
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.
</p>
<p>
The static type of the alternate-wait-action is the union of the eventual type
of all of its wait-future-exprs.
</p>
</section>
</section>
<section>
<h3>Worker message passing</h3>
<p>
Messages can be sent between workers. A message is a value, which must belong to
<code>value:Cloneable</code>.
</p>
<p>
Messages can only be sent between workers that are peers of each other. A
function's default worker and its named workers are peers of each other. The
workers created in a fork-stmt are also peers of each other. The workers created
in a fork-stmt are not peers of a function's default worker nor of its named
workers.
</p>

<pre
class="grammar">peer-worker := worker-name | <code>function</code>
</pre>
<p>
A worker-name refers to a worker named in a named-worker-decl, which must be in
scope; <code>function</code> refers to the function's default worker. The
referenced worker must be a peer worker.
</p>
<p>
Each worker maintains a separate queue for each peer worker to which it sends
messages; thus for each queue a sending worker and a receiving worker, which
must be distinct. A queue has an array of slots together with two integers
<var>w</var> and <var>r</var> that index into the array. Each slot is either
empty or contains a message. The length of each queue's array is determined at
compile-time. When a message is sent, the sending worker writes it to a slot in
the queue. The receiving worker receives the message by reading it from a slot.
Each slot is written to at most once and is read from at most once.
The slots in a queue's array are written to in increasing order,
and are read from in increasing order.
The <var>w</var> and <var>r</var> indices are used to coordinate the sending and
receiving worker: <var>w</var> is incremented by the sending worker as it writes
messages to successive slots in the array; <var>r</var> is incremented by the
receiving worker as it reads messages from successive slots in the array.
The minimum value <var>w</var> and <var>r</var> is 0, and the maximum
is the length of the array of slots.
</p>
<p>
A message is sent by a send-action and received by a receive-action. The index
of the slot used by each send-action and receive-action is determined at compile
time. This allows the connection between the send-action and the receive-action
to be shown in the sequence diagram.
There is a one-to-one correspondence between slots and send-actions; there is
a many-to-one correspondence between slots and receive-actions.
It is a compile-time error if a send-action or receive-action occurs in a
syntactic context, such as within the body of a foreach statement, where it
could be executed more than once.
</p>
<p>
There are four types determined at compile-time for each slot:
</p>
<ul>
<li>a message type: if a message v is written to the slot, then v belongs to the
slot's message type</li>
<li>a no message type: if it is possible for the index <var>w</var> of the queue
to be &gt; <var>i</var> while the slot with index <var>i</var> is empty, then
the no message type of the slot with index <var>i</var> is
<code>error:NoMessage</code>, otherwise it is empty;</li>
<li>a send failure type: this is the type of termination failure in the sending
worker that caused the corresponding message not to be sent; more precisely, for
any slot index <var>i</var>, if it is possible for <var>i</var> to be &#x2265;
the index <var>w</var> of the queue at the time when the sending worker
completes normally with termination value <var>e</var>, then <var>e</var>
belongs to the send failure type of the slot with index <var>i</var>; it is a
compile-time error if the send failure type is not a (possibly empty) subtype of
error;</li>
<li>a receive failure type: this is the type of termination failure in the
receiving worker that caused the corresponding message not to be received; more
precisely, for any slot index <var>i</var>, if it is possible for <var>i</var>
to be &#x2265; the index <var>r</var> of the queue at the time when the
receiving worker completes normally with termination value <var>e</var>, then
<var>e</var> belongs to the receive failure type of the slot with index
<var>i</var>; it is a compile-time error if the receive failure type is not a
(possibly empty) subtype of error</li>
</ul>
<p>
The sections below on <a href="#sending_messages">Sending messages</a> and
<a href="#receiving_messages">Receiving messages</a> describe
how the sending worker and receiving worker respectively increment the <var>w</var>
and <var>r</var> indices of a queue.
Note that the <var>w</var> index of a queue is updated to the length of the queue's
slot array upon successful termination of the sending worker, but the <var>r</var>
index is <em>not</em> similarly updated by the receiving worker.
The overall effect of this in conjunction with the typing rules is that
a send-action may occur in a conditional context where it may never be executed
but a receive-action may not.
</p>

<section>
<h4 id="sending_messages">Sending messages</h4>

<pre
class="grammar">send-action := async-send-action | sync-send-action
</pre>

<p>
A send-action sends a message to the worker that is identified by peer-worker. A
send-action with peer-worker R occurring within worker W is associated with the
queue with sending worker W and receiving worker R. There is a one-to-one
correspondence between the slots in a queue and the send-actions associated with
that queue. The order of the slots in the queue is the same as the syntactic
order of the send-actions.
</p>
<p>
An async-send-action sends a message without waiting for it to be received by
the receiving worker. A flush-action on a queue waits until the receiving worker
has received all messages that have been send to the queue. A sync-send-action
is equivalent to an async-send-action followed by a flush-action.
</p>
<p>
It is possible that a send-action is not evaluated. This can happen when the
worker containing the send-action terminates with an error or abnormally. It can
also happen when the send-action occurs within a conditional or match statement;
in this case, when there is no longer a possibility that the send-action will be
evaluated, the <code>w</code> index in queue needs to be incremented past the
index of the corresponding slot so as to ensure that a corresponding
receive-action does not wait any longer than necessary. This is achieved by
performing a <em>queue update</em> for every queue for whenever execution of the
sending worker reaches specific points. A queue update is performed for a worker
at a particular execution point by setting the <var>w</var> index to the least
<var>k</var> such that <var>k</var> is &gt; <var>i</var> for every <var>i</var>
where the send-action corresponding to the slot with index <var>i</var> is
syntactically before the execution point. There is a queue update execution
point immediately before every statement that might result in the worker's
strand yielding. A final queue update is also performed if the worker terminates
successfully, by setting <var>w</var> to the length of the queue's array.
</p>
<p>
If a worker W is about to terminate normally, and any final queue updates have
been performed, then for each queue for which W is the sending worker, W waits
until either the receiving worker has terminated or the <var>r</var> index is
&#x2265; the <var>w</var> index. If after waiting, the <var>r</var> index is
still &lt; the <var>w</var> index in some queue with receiving worker R, 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.
</p>


<section>
<h5>Async send action</h5>
<pre
class="grammar">async-send-action := expression <code>-&gt;</code> peer-worker <code>;</code>
</pre>

<p>
The evaluation of a async-send-action starts by evaluating the expression, resulting
in a value <code><var>v</var></code>; the Clone abstract operation is then
applied to <code><var>v</var></code> resulting in value
<code><var>c</var></code>. This value <code><var>c</var></code> is then written
to the slot in the associated queue corresponding to the send-action. The index
<var>w</var> in the queue is set to 1 greater than the index of that slot in the
queue. The result of an async-send-action is always <code>()</code>.
</p>
<p>
The static type of the <code>expression</code> must be a subtype of
<code>value:Cloneable</code>. The contextually expected type used to interpret
<code>expression</code> is the contextually expected type from the corresponding
receive-action.
</p>
<p>
If the slot corresponding to an async-send-action has a non-empty receive
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.
</p>
</section>
<section>
<h5>Flush action</h5>

<pre
class="grammar">flush-action := <code>flush</code> [peer-worker]
</pre>
<p>
A flush-action with peer-worker R occurring within worker W is associated with the
queue with sending worker W and receiving worker R. Evaluating
the flush-action flushes the queue up to index
<var>i</var> where <var>i</var> is the number of send-actions in W that syntactically
precede the flush-action. More precisely, the evaluation of a flush-action waits
until either the index <var>r</var> of the queue is &#x2265;
<var>i</var> or the receiving worker has terminated. It then completes as
follows:
</p>
<ul>
<li>if index <var>r</var> of the queue is &#x2265; <var>i</var>, then normally with
result <code>()</code></li>
<li>otherwise
<ul>
<li>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;</li>
<li>if the receiving worker terminated abnormally, then abruptly with a panic,
with the associated value being the termination value of the receiving worker.</li>
</ul>
</li>
</ul>
<p>
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 receive failure type of the slot corresponding to that
async-send-action. Otherwise, the static type of the flush-action is nil.
</p>
<p>
If a peer-worker is not specified in the flush-action, 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.
</p>
</section>
<section>
<h5>Sync send action</h5>
<pre
class="grammar">sync-send-action := expression <code>-&gt;&gt;</code> peer-worker
</pre>
<p>
A sync-send-action <code><var>E</var> -> <var>R</var></code> is equivalent to an
async-send-action <code><var>E</var> ->> <var>R</var></code> followed by a
flush-action <code>flush <var>R</var></code>. The static type of the
sync-send-action is the static type of the flush-action.
</p>
</section>
</section>

<section>
<h4 id="receiving_messages">Receiving messages</h4>

<pre
class="grammar">receive-action := single-receive-action | multiple-receive-action | alternate-receive-action
</pre>
<p>
Each receive-action has one or more references to peer workers. A reference to a
peer-worker W occurring in receive-action within worker R is associated with the
queue with sending worker W and receiving worker R. There is a one-to-one
correspondence between the slots in a queue and the references to
receive-actions associated with that queue. The order of the slots in the queue
is the same as the syntactic order of the references to peer workers.
</p>
<p>
A slot with index <var>i</var> in its queue becomes <em>ready</em> when the
index <var>w</var> of the queue is &gt; <var>i</var>. A value can be
<em>received from</em> a slot with index <var>i</var> in a queue as follows. If
the slot is empty, then the receive operation fails; otherwise, the value
received is the value contained in the slot; in either case, the
<var>r</var> index in the queue is set to <var>i</var> + 1.
</p>

<section>
<h5>Single receive action</h5>

<pre
class="grammar">single-receive-action := <code>&lt;-</code> peer-worker
</pre>
<p>
A single-receive-action receives a message from a single worker,
and accordingly has a reference to single peer worker.
</p>
<p>
A single-receive-action associated with a slot is evaluated by waiting until the
slot is ready or the sending worker has terminated. Then
</p>
<ul>
<li>if the slot is ready, a value is received from the slot and the evaluation
completes normally, with the result being
<ul>
<li>if the receive operation fails, a new value of type <code>error:NoMessage</code>;</li>
<li>otherwise, the value received from the slot;</li>
</ul>
</li>
<li>otherwise, the evaluation completes as follows:
<ul>
<li>if the sending worker terminated with failure, then normally with the result
being the the termination value of the sending worker, which will be an error;</li>
<li>if the sending worker terminated abnormally, then abruptly with a panic,
with the associated value being the termination value of the sending worker.</li>
</ul>
</li>
</ul>
<p>
The static type of the single-receive-action is T|N|F where T is message type of
the associated slot, N is its no message type, and F is its send failure type.
</p>
</section>
<section>
<h5>Multiple receive action</h5>

<pre
class="grammar">multiple-receive-action :=
   <code>&lt;-</code>  <code>{</code> receive-field (<code>,</code> receive-field)* <code>}</code>
receive-field :=
   peer-worker
   | field-name <code>:</code> peer-worker
</pre>
<p>
A multiple-receive-action receives a message from multiple workers.
</p>
<p>
A peer-worker can occur at most once in a multiple-receive-action.
</p>
<p>
A receive-field consisting of a peer-worker <code>W</code> is equivalent to a
field <code>W:W</code>.
</p>
<p>
A multiple-receive-action is evaluated by waiting until the slot associated
with every peer worker is ready. If, while waiting for a slot, the sending worker
for the queue of that slot terminates, then the evaluation of the
multiple-receive-action completes as follows
</p>
<ul>
<li>if the sending worker terminated with failure, then normally with the result
being the the termination value of the sending worker, which will be an error;</li>
<li>if the sending worker terminated abnormally, then abruptly with a panic,
with the associated value being the termination value of the sending worker.</li>
</ul>
<p>
Otherwise, a value is received from every slot. If any of these receive
operations fail, then the evaluation of the multiple-receive action completes
normally with the result being a new value of type <code>error:NoMessage</code>,
Otherwise, the evaluation completes normally with the result being a new record
value, with one field for each receive-field, where the value of the field is
the value received from the slot.
</p>
<p>
The contextually expected typed for the multiple-receive-action determines a
contextually expected type for each receive-field, in the same way as for a
mapping constructor. The contextually expected type for each receive-field
provides the contextually expected type for the expression in the corresponding
send-action.
</p>
<p>
The static type of multiple-receive-action is R|N|F where
</p>
<ul>
<li>R is a record type, where R is determined in the same way as for a mapping
constructor, where the static type of each field comes from the message type of
the slot and the contextually expected type is the contextually expected type of
the multiple-receive-action</li>
<li>N is the union of the no message types of the slots</li>
<li>F is the union of the send failure types of the slots</li>
</ul>
</section>
<section>
<h5>Alternate receive action</h5>

<pre
class="grammar">alternate-receive-action := <code>&lt;-</code> peer-worker (<code>|</code> peer-worker)+
</pre>

<p>
An alternate-receive-action receives a message from one of multiple peer-workers.
</p>
<p>
As with other receive actions, each reference to a peer worker is associated with a slot in
a queue. An alternate-receive-action is evaluated by repeatedly waiting until either
</p>
<ul>
<li>a sending worker terminates abnormally with a panic; in this, case the
evaluation completes abruptly with a panic, with the associated value being the
termination value of the sending worker;</li>
<li>a slot <var>k</var> is ready, and is not empty, and the value in the slot is
not an error; in this case, a value is received from every slot;
the result or failure of these receive operations
is ignored except for slot <var>k</var>; the evaluation completes normally, with
the result being the value received from slot <var>k</var>; or</li>
<li>all sending workers have terminated normally; in this case also, a value is
received from every slot and the evaluation completes normally with the result
of the alternative-receive-action being as follows
<ul>
<li>if the receive operation of every slot fails, then a new value of type
<code>error:NoMessage</code>;</li>
<li>otherwise, the result of the first receive operation that did not fail,
(in this case, that result will be an error value).</li>
</ul>
</li>
</ul>
<p>
The static type of the alternative-receive-action is T|N|F, where T is union of
message type of the associated slots, N is the intersection of the no message
types of the slots and F is the union the send failure type of the slots.
</p>

</section>
</section>
</section>

<section>
<h3>Outbound network interaction</h3>

<p>
A client object is a stub that allows a worker to send network messages to a
remote system according to some protocol. A local variable declared with client
object type will be depicted as a lifeline in the function's sequence diagram.
</p>

<section>
<h4>Remote methods</h4>
<p>
The remote methods of the client object correspond to distinct network messages
defined by the protocol for the role played by the client object. The return
value of a remote method represents the protocol's response. A
client-remote-method-call-action is depicted as a horizontal arrow from the
worker lifeline to the client object lifeline.
</p>

<pre
class="grammar">client-remote-method-call-action := expression <code>-&gt;</code> remote-method-name <code>(</code> arg-list <code>)</code>
</pre>
<p>
Calls a remote method of a client object. This works the same as a method call
expression, except that it is used for a client object method with the
<code>remote</code> qualifier.
</p>

</section>

<section>
<h4>Resources</h4>

<pre
class="grammar">client-resource-access-action :=
   expression <code>-&gt;</code> <code>/</code> [resource-access-path] [<code>.</code> resource-method-name] [<code>(</code> arg-list <code>)</code>]

resource-access-path :=
   resource-access-path-segments [<code>/</code> resource-access-rest-segment]
   | resource-access-rest-segment

resource-access-path-segments :=
   resource-access-path-segment (<code>/</code> resource-access-path-segment )* 

resource-access-path-segment :=
   resource-path-segment-name
   | computed-resource-access-path-segment

computed-resource-access-path-segment := <code>[</code> expression <code>]</code>

resource-access-rest-segment := <code>[</code> spread <code>]</code>
</pre>
<p>
A <code>client-resource-access-action</code> performs a <a
href="#resources_defn">resource access operation</a> on a client object. An
omitted <code>resource-method-name</code> defaults to <code>get</code>; if the
parentheses and the <code>arg-list</code> are omitted, then they default to
<code>()</code>, with arguments being defaulted as usual.
</p>
<p>
A <code>client-resouce-access-action</code> is evaluated by:
</p>
<ul>
<li>evaluating the code expression preceding the <code>-&gt;</code> resulting in
a client object <var>c</var>;</li>
<li>evaluating the <code>resource-access-path</code> to get a list of values
<var>p</var>
<ul>
<li>a <code>resource-access-path</code> that is just <code></code> makes <var>p</var> be
an empty list</li>
<li>a <code>resource-path-segment-name</code> appends a string to <var>p</var></li>
<li>a <code>computed-resource-access-path-segment</code> is evaluated and the
result is appended to <var>p</var>;</li>
<li>a <code>resource-access-rest-segment</code> is evaluated and every member
of the result, which must be a list, is appended to <var>p</var>;</li>
</ul>
</li>
<li>evaluating the <code>arg-list</code> to get an argument list
<var>a</var>;</li>
<li>invoking the resource access operation on the <var>c</var> using the
<code>resource-method-name</code>, <var>p</var> and <var>a</var>, resulting in a value
<var>v</var>.</li>
</ul>
<p>
The result of the <code>client-resource-access-action</code> is <var>v</var>.
</p>
<p>
The static type of the client object must contain a resource with specified
method name for every list value that may be constructed by the evaluation of
the <code>resource-access-path</code>. The argument list and result value are
typed using the intersection of the function types allowed for the method name
with any of the resource paths.
</p>

</section>
</section>
<section>
<h3>Query action</h3>
<pre
class="grammar">query-action := query-action-pipeline do-clause
do-clause := <code>do</code> statement-block
</pre>
<p>
The clauses in the query-pipeline of query-action are executed in the same way
as the clauses in the query-pipeline of a query-expr.
</p>
<p>
The query-action is executed as follows. For each input frame <var>f</var>
emitted by the query-pipeline, execute the statement-block with <var>f</var> in
scope. If a clause in the query-pipeline completes early with error
<var>e</var>, the result of the query-action is <var>e</var>. Otherwise, the
result of the query-action is nil.
</p>

</section>

<section>
<h3>Local variable declaration statements</h3>

<pre
class="grammar">local-var-decl-stmt :=
   local-init-var-decl-stmt
   | local-no-init-var-decl-stmt
local-init-var-decl-stmt :=
   [annots] [<code>final</code>] typed-binding-pattern <code>=</code> action-or-expr <code>;</code>
</pre>
<p>
A <code>local-var-decl-stmt</code> is used to declare variables with a scope
that is local to the block in which they occur.
</p>
<p>
The scope of variables declared in a <code>local-var-decl-stmt</code> starts
immediately after the statement and continues to the end of the statement block
in which it occurs.
</p>
<p>
A local-init-var-decl-stmt is executed by evaluating the action-or-expr
resulting in a value, and then matching the typed-binding-pattern to the value,
causing assignments to the variables occurring in the typed-binding-pattern. The
typed-binding-pattern is used unconditionally, meaning that it is a compile
error if the static types do not guarantee the success of the match. If the
typed-binding-pattern uses <code>var</code>, then the type of the variables is
inferred from the static type of the action-or-expr; if the
local-init-var-decl-stmt includes final, the precise type is used, and otherwise
the broad type is used. If the typed-binding-pattern specifies a
type-descriptor, then that type-descriptor provides the contextually expected
type for action-or-expr.
</p>
<p>
If <code>final</code> is specified, then the variables declared must not be
assigned to outside the local-init-var-decl-stmt.
</p>

<pre
class="grammar">local-no-init-var-decl-stmt :=
   [annots] [<code>final</code>] type-descriptor variable-name <code>;</code>
</pre>
<p>
A local variable declared <code>local-no-init-var-decl-stmt</code> must be
definitely assigned at each point that the variable is referenced. This means
that the compiler must be able to verify that the local variable will have been
assigned before that point. If <code>final</code> is specified, then the
variable must not be assigned more than once. The <code>type-descriptor</code>
must not be <code>never</code>.
</p>
</section>
<section>
<h3 id="conditional_variable_type_narrowing">Conditional variable type narrowing</h3>
<p>
Usually the type of a reference to a variable is determined by the variable's
declaration, either explicitly specified by a type descriptor or inferred from
the static type of the initializer. However, the language also recognizes two
kinds of case where the way a local variable or parameter is used means that is
known at compile-time that within a particular region of code the value of the
variable will belong to a type that is narrower than the declared type. In these
cases, references to the variable within particular regions of code will have a
static type that is narrower that the variable type. One kind of case, which is
described in this section, is when a variable is used in a boolean expression in
a conditional context. This is sometimes called <em>occurrence typing</em>. The
other kind of case is when a variable is used in a match statement; this is
described in the <a href="#match_statement">Match statement</a> section.
</p>
<p>
Type narrowing makes use of the <em>read-only difference</em> between two types,
which is defined as follows. We use the notation T
&#x2212;<sub><em>ro</em></sub> S for the read-only difference of T and S. T
&#x2212;<sub><em>ro</em></sub> S is computed separately for each uniform type.
Let T<sup>U</sup> be the subset of T belonging to uniform type U, i.e. the
intersection of T and U. For a uniform type U that is immutable, T<sup>U</sup>
&#x2212;<sub><em>ro</em></sub> S<sup>U</sup> is the same as T<sup>U</sup> -
S<sup>U</sup> (set difference); for a uniform type U that is mutable,
T<sup>U</sup> &#x2212;<sub><em>ro</em></sub> S<sup>U</sup> is empty if
T<sup>U</sup> is a subset of S<sup>U</sup>, and T<sup>U</sup> otherwise. T
&#x2212;<sub><em>ro</em></sub> S is the union for every uniform type U of
T<sup>U</sup> &#x2212;<sub><em>ro</em></sub> S<sup>U</sup>. This definition of
read-only difference ensures that if a value x belongs to T but not does not
belong to S, then x belongs to T &#x2212;<sub><em>ro</em></sub> S.
</p>
<p>
Given an expression E with static type boolean, and a variable x with static
type Tx, we define how to determine
</p>
<ul>
<li>a narrowed type for x implied by truth of E, and</li>
<li>a narrowed type for x implied by falsity of E.</li>
</ul>
<p>
based on the syntactic form of E as follows.
</p>
<ul>
<li>If E has the form x <code>is</code> T, then
<ul>
<li>the narrowed type for x implied by truth of E is the intersection of Tx and
T</li>
<li>the narrowed type for x implied by falsity of E is Tx
&#x2212;<sub><em>ro</em></sub> T</li>
</ul>
</li>
<li>If E has the form x <code>==</code> E<sub>1</sub> or E<sub>1</sub>
<code>==</code> x where the static type of E<sub>1</sub> is an expression whose
static type is a singleton simple type T<sub>1</sub>, then
<ul>
<li>the narrowed type for x implied by truth of E is the intersection of Tx and
T<sub>1</sub></li>
<li>the narrowed type for x implied by falsity of E is Tx
&#x2212;<sub><em>ro</em></sub> T<sub>1</sub></li>
</ul>
</li>
<li>If E has the form x <code>!=</code> E<sub>1</sub> or E<sub>1</sub>
<code>!=</code> x where the static type of E<sub>1</sub> is an expression whose
static type is a singleton simple type T<sub>1</sub>, then
<ul>
<li>the narrowed type for x implied by truth of E is Tx
&#x2212;<sub><em>ro</em></sub> T<sub>1</sub></li>
<li>the narrowed type for x implied by falsity of E is the intersection of Tx
and T<sub>1</sub></li>
</ul>
</li>
<li>If E has the form <code>!</code>E<sub>1</sub>, then
<ul>
<li>the narrowed type for x implied by truth of E is the narrowed type for x
implied by falsity of E<sub>1</sub></li>
<li>the narrowed type for x implied by falsity of E is the narrowed type for x
implied by truth of E<sub>1</sub></li>
</ul>
</li>
<li>If E has the form E<sub>1</sub> <code>&amp;&amp;</code> E<sub>2</sub>
<ul>
<li>the narrowed type for x implied by truth of E is the intersection of
T<sub>1</sub> and T<sub>2</sub>, where T<sub>1</sub> is the narrowed type for x
implied by the truth of T<sub>1</sub> and T<sub>2</sub> is the narrowed type for
x implied by the truth of T<sub>2</sub></li>
<li>the narrowed type for x implied by falsity of E is
T<sub>1</sub>|T<sub>2</sub>, where T<sub>1</sub> is the narrowed type for x
implied by the falsity of E<sub>1</sub>, and T<sub>2</sub> is the intersection
of T<sub>3</sub> and T<sub>4</sub>, where T<sub>3</sub> is the narrowed type for
x implied by the truth of E<sub>1</sub> and T<sub>4</sub> is the narrowed type
for x implied by the falsity of E<sub>2</sub></li>
</ul>
</li>
<li>If E has the form E<sub>1</sub> <code>||</code> E<sub>2</sub>, then
<ul>
<li>the narrowed type for x implied by truth of E is
T<sub>1</sub>|T<sub>2</sub>, where T<sub>1</sub> is the narrowed type for x
implied by the truth of E<sub>1</sub>, and T<sub>2</sub> is the intersection of
T<sub>3</sub> and T<sub>4</sub>, where T<sub>3</sub> is the narrowed type for x
implied by the falsity of E<sub>1</sub> and T<sub>4</sub> is the narrowed type
for x implied by the truth of E<sub>2</sub></li>
<li>the narrowed type for x implied by falsity of E is the intersection of
T<sub>1</sub> and T<sub>2</sub>, where T<sub>1</sub> is narrowed type for x
implied by the falsity of E<sub>1</sub> and T<sub>2</sub> is the narrowed type
for x implied by the falsity of E<sub>2</sub></li>
</ul>
</li>
<li>If E has any other form, then
<ul>
<li>the narrowed type for x implied by the truth of E is Tx</li>
<li>the narrowed type for x implied by the falsity of E is Tx</li>
</ul>
</li>
</ul>
<p>
Narrowed types implied by the truth or falsity of an expression apply to regions
of code as follows:
</p>
<ul>
<li>in an expression E<sub>1</sub> <code>||</code> E<sub>2</sub>, the narrowed
types implied by the falsity of E<sub>1</sub> apply within E<sub>2</sub></li>
<li>in an expression E<sub>1</sub> <code>&amp;&amp;</code> E<sub>2</sub>, the
narrowed types implied by the truth of E<sub>1</sub> apply within
E<sub>2</sub></li>
<li>in an expression E<sub>1</sub> <code>?</code> E<sub>2</sub> <code>:</code>
E<sub>3</sub>, the narrowed types implied by the truth of E<sub>1</sub> apply
within E<sub>2</sub> and the narrowed types implied by the falsity of
E<sub>1</sub> apply within E<sub>3</sub></li>
<li>in a statement <code>if</code> E<sub>1</sub> B<sub>1</sub> <code>else</code>
B<sub>2</sub>, the narrowed types implied by the truth of E<sub>1</sub> apply
within B<sub>1</sub> and the narrowed types implied by the falsity of
E<sub>1</sub> apply within B<sub>2</sub></li>
<li>in a statement <code>while</code> E B, the narrowed types implied by the truth of E
apply with B</li>
<li>in a match-clause P <code>if</code> E <code>=></code> B, the narrowed types
implied by the truth of E apply within B</li>
<li>in a query-expr or query-action, the narrowed types implied by the truth of
the expression in a where-clause apply within all following clauses in that
query-expr or query-action</li>
</ul>
<p>
Given a statement or statement-block S, and a variable x that is in-scope for S
and has static type Tx, we define how to determine a narrowed type for x implied
by the normal completion of S as follows.
</p>
<ul>
<li>When it is not possible for S to complete normally, then the narrowed type for x implied by the normal completion of S is never (the empty type).</li>
<li>If S has the form <code>{</code> S<sub>1</sub> S<sub>2</sub> ...
S<sub>n</sub> <code>}</code>, then the narrowed type for x implied by the normal
completion of S is the narrowed type for x implied by the normal completion of
S<sub>n</sub>.</li>
<li>If S has the form <code>do</code> B, the narrowed type for x implied by the
normal completion of S is the narrowed type for x implied by the normal
completion of B.</li>
<li>If S has the form <code>if</code> E B<sub>1</sub> <code>else</code>
B<sub>2</sub>, the narrowed type for x implied by the normal completion of S is
the union of T<sub>1</sub> and T<sub>2</sub>, where T<sub>1</sub> is the
narrowed type for x implied by the normal completion of B<sub>1</sub> and
T<sub>2</sub> is the narrowed type for x implied by the normal completion of
B<sub>2</sub>. (The truth or falsity of E may imply a narrowed type for x that
applies in B<sub>1</sub> or B<sub>2</sub>, which may affect the narrowed type
for x implied by the normal completion of B<sub>1</sub> or B<sub>2</sub>.)</li>
<li>Otherwise, the narrowed type for x implied by the completion of S is Tx.</li>
</ul>
<p>
The narrowed types implied by the normal completion of a statement are applied
within a statement-block as follows: in a statement-block <code>{</code>
S<sub>1</sub> S<sub>2</sub> ... Sn <code>}</code>, for each i in 2,..., n, the
narrowed types implied by the normal completion of S<sub>i - 1</sub> apply to
S<sub>i</sub>.
</p>
<p>
In the above rules, a if-else-stmt without an <code>else</code> clause is
treated as if it had an <code>else</code> followed by an empty statement-block,
and <code>else if</code> clause is treated like a nested if-else-stmt.
</p>
<p>
A narrowed type for a variable x implied by an expression in which x occurs
ceases to apply in a region of code where there is a possibility at runtime that
x has been assigned to since the evaluation of the expression. It is an error if
this results in the type of a variable reference being affected by assignments
that lexically follow the variable reference. Specifically, when a variable x is
narrowed outside a while-stmt, foreach-stmt or query-action S, an assignment to
x within S must not result in the possibility of x having being assigned to when
the statement-block of S completes normally or when a continue-stmt is executed.
</p>

</section>
<section>
<h3 id="XML_namespace_declaration_statement">XML namespace declaration statement</h3>

<pre
class="grammar">xmlns-decl-stmt := xmlns-decl
xmlns-decl := <code>xmlns</code> xml-namespace-uri [ <code>as</code> xml-namespace-prefix ] <code>;</code>
xml-namespace-uri := simple-const-expr
xml-namespace-prefix := identifier
</pre>
<p>
An <code>xmlns-decl</code> is used to declare a XML namespace. If there is
an <code>xml-namespace-prefix</code>, then the in-scope namespaces that are used
to perform namespace processing on an <code>xml-template-expr</code> will include a
binding of that prefix to the specified <code>xml-namespace-uri</code>;
otherwise the in-scope namespaces will include a default namespace with the
specified <code>xml-namespace-uri</code>.
</p>
<p>
An <code>xml-namespace-prefix</code> declared by an <code>xmlns-decl</code>
is in the same symbol space as a <code>module-prefix</code> declared by an
<code>import-decl</code>. This symbol space is distinct from a module's main
symbol space used by other declarations. An <code>xmlns-decl</code> in a
<code>xmlns-decl-stmt</code> declares the prefix within the scope of the current
block.
</p>
<p>
The prefix <code>xmlns</code> is predeclared as
<code>http://www.w3.org/2000/xmlns/</code> and cannot be redeclared.
</p>
<p>
The static type of the <code>simple-const-expr</code> must be a subtype of
string.
</p>
</section>
<section>
<h3>Assignment</h3>

<p>
There are three kinds of assignment statement:
</p>
<ul>
<li>an ordinary assignment statement, which is usually called simply an
assignment statement,</li>
<li>a compound assignment statement, and</li>
<li>a destructuring assignment statement.</li>
</ul>
<p>
The first two of these build on the concept of an <em>lvalue</em>, whereas the
last one builds on the concept of a binding pattern.
</p>

<section>
<h4>Lvalues</h4>

<p>
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:
</p>
<ul>
<li>a variable;</li>
<li>a specific named field of an object;</li>
<li>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.</li>
</ul>
<p>
Note that an lvalue cannot refer to a member of a table.
</p>

<p>
An lvalue that is both defined and initialized refers to a storage location that
holds a value:
</p>
<ul>
<li>an lvalue referring to a variable is always defined but may be
uninitialized;</li>
<li>an lvalue referring to a specific named field of an object is always defined
but may not be initialized until the <code>init</code> method returns</li>
<li>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.</li>
</ul>

<pre
class="grammar">lvexpr :=
   variable-reference-lvexpr
   | field-access-lvexpr
   | member-access-lvexpr
</pre>

<p>
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.
</p>
<p>
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.
</p>
<p>
An lvalue supports four operations: store, remove, read and filling-read.
</p>
<p>
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.
</p>
<ol>
<li>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.</li>
<li>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).</li>
<li>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.</li>
</ol>
<p>
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.
</p>
<p>
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
&gt; n, then each member with index i for each &#x2264; i &lt; 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.
</p>
<p>
An lvalue that refers to a member of a mapping value supports a remove
operation, which removes any member with the specific key referred to by the
lvalue. The removal may be impermissible because it the inherent type of the
mapping value requires a member with this key or because the mapping value is
immutable. As with a store operation, a remove operation must be verified at
runtime to ensure that it is not impermissible; an attempt to perform an
impermissible remove operation will result in a panic at runtime. Performing the
remove operation on a member that is not present has no effect, but is not an
error.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>

<pre class="grammar">variable-reference-lvexpr := variable-reference
</pre>
<p>
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.
</p>
<p>
A variable-reference-lvexpr that refers to a variable declared by a
module-var-decl that includes <code>isolated</code> is only allowed within a
lock-stmt.
</p>

<pre class="grammar">field-access-lvexpr := lvexpr <code>.</code> field-name
</pre>

<p>
The static type of lvexpr must be either a subtype of the mapping basic type
or a subtype of the object basic type.
</p>
<p>
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.
</p>
<p>
In the case where the static type of lvexpr is a subtype of the mapping basic
type, the semantics are as follows.
</p>
<ul>
<li>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 <code>field-name</code> as an individual-field-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.</li>
<li>
It is evaluated as follows:
<ol>
<li>evaluate lvexpr to get lvalue <var>lv</var>;</li>
<li>perform a filling-read operation on <var>lv</var> to get mapping value
<var>m</var>;</li>
<li>the result is an lvalue referring to the member of <var>m</var> with the
specified field-name.</li>
</ol>
</li>
<li>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.</li>
</ul>

<pre class="grammar">member-access-lvexpr := lvexpr <code>[</code> expression <code>]</code>
</pre>
<p>
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.
</p>
<p>
It is evaluated as follows:
</p>
<ol>
<li>evaluate expression to get a string or int <var>k</var>;</li>
<li>evaluate lvexpr to get lvalue <var>lv</var>;</li>
<li>perform a filling-read operation on <var>lv</var> to get a list or mapping value
<var>v</var>;</li>
<li>the result is an lvalue referring to the member of <var>c</var> with key
<var>k</var>.</li>
</ol>
<p>
The static type of the member-access-lvexpr 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-lvexpr is potentially undefined if K is an optional
key type for T.
</p>

</section>
<section>
<h4>Assignment statement</h4>

<pre
class="grammar">assignment-stmt := lvexpr <code>=</code> action-or-expr <code>;</code>
</pre>
<p>
An assignment-stmt stores the value that results from evaluating action-or-expr
in the storage location referred to by lvexpr. When lvexpr is potentially
undefined and has a static type that does not include nil, then a value of nil
means to remove the member referred to by the lvexpr.
</p>
<p>
The static type of action-or-expr must be a subtype of the union of nil and the
static type of lvexpr. If the static type of action-or-expr allows nil, but the
static type of lvexpr does not allow nil, then lvexpr must refer to a member of
a mapping value and must be be potentially undefined. 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.
</p>
<p>
An assignment-stmt is executed at as follows:
</p>
<ol>
<li>execute action-or-expr to get a value <var>v</var>;</li>
<li>evaluate lvexpr to get an lvalue <var>lv</var>;</li>
<li>if <var>v</var> is nil but the static type of lvexpr does not allow nil,
then perform the remove operation on <var>lv</var>; otherwise, perform the store
operation on <var>lv</var> with value <var>v</var>.</li>
</ol>

</section>
<section>
<h4>Compound assignment statement</h4>

<pre
class="grammar">compound-assignment-stmt := lvexpr CompoundAssignmentOperator action-or-expr <code>;</code>
CompoundAssignmentOperator := BinaryOperator <code>=</code>
BinaryOperator := <code>+</code> | <code>-</code> | <code>*</code> | <code>/</code> | <code>&amp;</code> | <code>|</code> | <code>^</code> | <code>&lt;&lt;</code> | <code>&gt;&gt;</code> | <code>&gt;&gt;&gt;</code>
</pre>
<p>
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.
</p>
<p>
Let T1 be the static type of lvexpr, and let T2 be the static type of
action-expr. Let E be an expression E1 BinaryOperator E2, where E1 has type T1
and E2 has type T2. E must be valid according to the static typing rules
applicable to the underlying form of the BinaryOperator (not the lifted form
described in the <a href="#nil_lifting">Nil lifting</a> section). Let T be the
static type of E according to those rules. It is a compile error if T is not a
subtype of T1.
</p>
<p>
A compound-assignment-stmt is executed as follows:
</p>
<ol>
<li>execute action-or-expr to get a value <var>v2</var>;</li>
<li>evaluate lvexpr to get an lvalue <var>lv</var>;</li>
<li>if <var>lv</var> is undefined, panic (<var>lv</var> must refer to an
undefined member of a list)</li>
<li>perform the read operation on <var>lv</var> to get a value
<var>v1</var></li>
<li>perform the operation specified by BinaryOperator on operands <var>v1</var>
and <var>v2</var>, resulting in a value <var>v3</var></li>
<li>perform the store operation on <var>lv</var> with value <var>v3</var>.</li>
</ol>

</section>
<section>
<h4>Destructuring assignment statement</h4>

<pre
class="grammar">destructuring-assignment-stmt :=
   binding-pattern-not-variable-reference <code>=</code> action-or-expr <code>;</code>
binding-pattern-not-variable-reference :=
   wildcard-binding-pattern
   | list-binding-pattern
   | mapping-binding-pattern
   | error-binding-pattern
</pre>
<p>
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.
</p>
<p>
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.
</p>
<p>
A binding pattern within a destructuring assignment must not refer to a variable
declared by a module-var-decl that includes <code>isolated</code>.
</p>
<p>
Note that a destucturing-assignment-stmt with a wildcard-binding-pattern can
be used to ensure that a a variable has been narrowed as expected.
</p>
<pre>
type T X|Y|Z;
function foo(T v) {
   if v is X {
       handleX(v);
   }
   else if v is Y {
       handleY(v);
   }
   else {
     Z _ = v;
     handleOther(v);
   }
}
</pre>
<p>
If <code>T</code> is subsequently modified to add another possibility in
addition to <code>X</code>, <code>Y</code> and <code>Z</code>, then
<code>foo</code> will get a compile error.
</p>
</section>
</section>
<section>
<h3>Action statement</h3>

<pre class="grammar">action-stmt := action <code>;</code>
</pre>
<p>
An action-stmt is a statement that is executed by evaluating an action and
discarding the resulting value, which must be nil. It is a compile-time error if
the static type of an action in an action-stmt is not nil.
</p>
</section>
<section>
<h3>Call statement</h3>

<pre
class="grammar">call-stmt := call-expr <code>;</code>
call-expr := function-call-expr | method-call-expr
</pre>
<p>
A call-stmt is executed by evaluating call-expr as an expression and discarding
the resulting value, which must be nil. The static type of the call-expr in a
call-stmt must be either <code>()</code> or <code>never</code>. If it is
<code>never</code>, then it is possible for the call-stmt to complete normally.
</p>
</section>
<section>
<h3>Checking statement</h3>

<pre
class="grammar">checking-stmt := checking-action-or-expr <code>;</code>
</pre>
<p>
A checking-stmt is executed by evaluating checking-action-or-expr as an
expression and discarding the resulting value, which must be nil. The static
type of the checking-action-or-expr in a checking-stmt must be <code>()</code>.
</p>
</section>
<section>
<h3>Conditional statement</h3>

<pre
class="grammar">if-else-stmt :=
   <code>if</code> expression statement-block 
   [ <code>else</code> <code>if</code> expression statement-block ]* 
   [ <code>else</code> statement-block ]
</pre>
<p>
The if-else statement is used for conditional execution.
</p>
<p>
The static type of the expression following <code>if</code> must be boolean.
When an expression is true then the corresponding statement block is executed
and the if statement completes. If no expression is true then, if the else block
is present, the corresponding statement block is executed.
</p>
</section>
<section>
<h3>Do statement</h3>
<pre
class="grammar">do-stmt := <code>do</code> statement-block
</pre>
<p>
A <code>do-stmt</code> is executed by executing its
<code>statement-block</code>.
</p>
</section>
<section>
<h3 id="match_statement">Match statement</h3>

<pre
class="grammar">match-stmt := <code>match</code> match-target <code>{</code> match-clause+ <code>}</code>
match-target := action-or-expr
match-clause :=
  match-pattern-list [match-guard] <code>=></code> statement-block
match-guard := <code>if</code> match-guard-expr
</pre>
<p>
A match statement selects a statement block to execute based on which patterns a
value matches.
</p>
<p>
A match-stmt is executed as follows:
</p>
<ol>
<li>the match-target is evaluated resulting in some value v, called the
<em>target value</em>;</li>
<li>for each match-clause in order:
<ol>
<li>a match of match-pattern-list against v is attempted</li>
<li>if the attempted match fails, the execution of the match-stmt continues to
the next match-clause</li>
<li>if the attempted match succeeds, then the variables in match-pattern are
created</li>
<li>if there is a match-guard, then the expression in match-guard is executed
resulting in a value b</li>
<li>if b is false, then the execution of the match-stmt continues to the next
match-clause</li>
<li>otherwise, the statement-block in the match-clause is executed</li>
<li>execution of the match-stmt completes</li>
</ol>
</li>
</ol>
<p>
The scope of any variables created in a match-pattern-list of a match-clause is
both the match-guard, if any, and the statement-block in that match-clause. The
static type of the expression in match-guard must be a subtype of boolean.
</p>

<pre
class="grammar">match-guard-expr := expression
</pre>
<p>
A match-guard-expr must not include a <code>function-call-expr</code> or
<code>method-call-expr</code> unless either
</p>
<ul>
<li>the static type of the <code>action-or-expr</code> following
<code>match</code> is a subtype of <code>readonly</code>; or</li>
<li>the function or method being called is <code>isolated</code> and the static
type of every argument to the function or method is a subtype of
<code>readonly</code>; in the case of a method-call-expr, the static type of the
object whose method is being called must also be a subtype of
<code>readonly</code>.</li>
</ul>

<section>
<h4>Match patterns</h4>
<pre
class="grammar">match-pattern-list := 
  match-pattern (<code>|</code> match-pattern)*
</pre>
<p>
A match-pattern-list can be matched against a value. An attempted match can
succeed or fail. A match-pattern-list is matched against a value by attempting
to match each match-pattern until a match succeeds.
</p>
<p>
All the match-patterns in a given match-pattern-list must bind the same set of
variables.
</p>

<pre
class="grammar">match-pattern :=
  <code>var</code> binding-pattern
   | wildcard-match-pattern
   | const-pattern
   | list-match-pattern
   | mapping-match-pattern
   | error-match-pattern
</pre>
<p>
A match-pattern combines the destructuring done by a binding-pattern with the
ability to match a constant value.
</p>
<p>
Note that an identifier can be interpreted in two different ways within a
match-pattern:
</p>
<ul>
<li>in the scope of a <code>var</code>, an identifier names a variable which is
to be bound to a part of the matched value when a pattern match succeeds;</li>
<li>outside the scope of a var, an identifier references a constant that a value
must match for the pattern match to succeed.</li>
</ul>
<p>
A match-pattern must be linear: a variable that is to be bound cannot occur more
than once in a match-pattern.
</p>

<pre
class="grammar">const-pattern := simple-const-expr
</pre>
<p>
A const-pattern denotes a single value. Matching a const-pattern denoting a
value p against a value v succeeds if DeepEquals(p,v) is true. The static type
of the simple-const-expr in a const-pattern must be a subtype of anydata.
Successfully matching a const-pattern does not cause any variables to be
created.
</p>
<p>
Matching a wildcard-match-pattern against a value succeeds if the value belongs to
type any, in other words if the basic type of the value is not error.
</p>

<pre
class="grammar">wildcard-match-pattern := <code>_</code>
list-match-pattern := <code>[</code> list-member-match-patterns <code>]</code>
list-member-match-patterns :=
   match-pattern (<code>,</code> match-pattern)* [<code>,</code> rest-match-pattern]
   | [ rest-match-pattern ]
mapping-match-pattern := <code>{</code> field-match-patterns <code>}</code>
field-match-patterns :=
   field-match-pattern (<code>,</code> field-match-pattern)* [<code>,</code> rest-match-pattern]
   | [ rest-match-pattern ] 
field-match-pattern := field-name <code>:</code> match-pattern
rest-match-pattern := <code>...</code> <code>var</code> variable-name
error-match-pattern := <code>error</code> [error-type-reference] <code>(</code> error-arg-list-match-pattern <code>)</code>
error-arg-list-match-pattern :=
   error-message-match-pattern [<code>,</code> error-cause-match-pattern] [<code>,</code> error-field-match-patterns]
   | [error-field-match-patterns]
error-message-match-pattern := simple-match-pattern
error-cause-match-pattern := simple-match-pattern | error-match-pattern
simple-match-pattern :=
   wildcard-match-pattern
   | const-pattern
   | <code>var</code> variable-name
error-field-match-patterns :=
   named-arg-match-pattern (<code>,</code> named-arg-match-pattern)* [<code>,</code> rest-match-pattern]
   | rest-match-pattern
named-arg-match-pattern := arg-name <code>=</code> match-pattern
</pre>

<p>
Matching a <code>mapping-match-pattern</code> against a mapping value succeeds
if and only every <code>field-match-pattern</code> matches against a field of
the value. The variable in the <code>rest-match-pattern</code>, if specified, is
bound to a new mapping that contains just the fields for which that did not
match a <code>field-match-pattern</code>.
</p>
<p>
For every match pattern, there is a set of shapes that the pattern matches. The
type corresponding to the match pattern is the type containing these shapes. The
value matches the pattern if and only if it looks like the type. A mutable value
thus can match the pattern without belonging to the corresponding type. However,
an immutable value that matches the pattern will always belong to the type.
In particular, for the match of an <code>error-match-pattern</code> with an
<code>error-type-reference</code> against an error value to succeed, the
error value must belong to the referenced error type.
</p>
</section>

<section>
<h4>Match clause reachability and narrowing</h4>
<p>
This section uses the <em>read-only intersection</em> between two types, which
is defined analogously to the read-only difference used for conditional variable
type narrowing as follows. We use the notation T &amp;<sub>ro</sub> S for the
read-only intersection of T and S. T &amp;<sub>ro</sub> S is computed separately
for each uniform type. Let T<sup>U</sup> be the subset of T belonging to uniform
type U, i.e. the intersection of T and U. For a uniform type U that is
immutable, T<sup>U</sup> &amp;<sub>ro</sub> S<sup>U</sup> is the same as
T<sup>U</sup> &amp; S<sup>U</sup>; for a uniform type U that is mutable,
T<sup>U</sup> &amp;<sub>ro</sub> S<sup>U</sup> is empty if T<sup>U</sup> &amp;
S<sup>U</sup> is empty, and T<sup>U</sup> otherwise. T &amp;<sub>ro</sub> S is
the union for every uniform type U of T<sup>U</sup> &amp;<sub>ro</sub>
S<sup>U</sup>. Note that the read-only intersection operation is not
commutative.
</p>
<p>
A <code>match-clause</code> is defined to be <em>unguarded</em> if it does not
have a <code>match-guard</code> or if the static type of the expression in the
<code>match-guard</code> is singleton true.
</p>
<p>
For each <code>match-clause</code> C, we can compute a type L that the target
value must <em>look like</em> if the <code>statement-block</code> of C is
executed. L is computed as the difference of a positive type P and negative type
N, where
</p>
<ul>
<li>P is the union of the types corresponding to the match patterns in the
<code>match-pattern-list</code> of C, and</li>
<li>N is the union of the types corresponding to the match patterns in the
<code>match-pattern-list</code> of every unguarded <code>match-clause</code>
that precedes C.</li>
</ul>
<p>
Let T be the static type of the <code>match-target</code>. If the intersection
of T and L is empty, then it is not possible for the
<code>match-pattern-list</code> of C to match, and accordingly the statements in
the statement-block of C are not reachable. If the <code>match-target</code> is
a <code>variable-reference</code>, then the type of the referenced variable is
narrowed to T &amp;<sub>ro</sub> L within the <code>match-guard</code>, if any,
and the <code>statement-block</code> of C. If there is a
<code>match-guard</code>, then the type narrowing described in <a
href="#conditional_variable_type_narrowing">Conditional variable type
narrowing</a> is in addition applied to the <code>statement-block</code>
</p>
<p>
A <code>match-stmt</code> is <em>exhaustive</em> if and only if the static type
of the <code>match-target</code> is a subtype of union of the type corresponding
to the match patterns of the <code>match-pattern-list</code> of every unguarded
match clause. A <code>match-stmt</code> that is exhaustive can complete normally
only if at least one of its <code>statement-block</code>s can complete normally.
</p>
</section>
</section>
<section>
<h3>Loops</h3>
<section>
<h4>Foreach statement</h4>

<pre
class="grammar">foreach-stmt :=
   <code>foreach</code> typed-binding-pattern <code>in</code> action-or-expr statement-block
</pre>
<p>
A foreach statement iterates over an iterable value, executing a statement block
once for each value in the iterable value's iteration sequence. The static type
of action-or-expr must be an iterable type with an iteration completion type of
nil.
</p>
<p>
The scope of any variables created in typed-binding-pattern is statement-block. These
variables are implicitly final.
</p>
<p>
In more detail, a foreach statement executes as follows:
</p>
<ol>
<li>evaluate the action-or-expr resulting in a value c</li>
<li>create an iterator object i from c as follows
<ol>
<li>if c is a basic type that is iterable, then i is the result of calling
c.iterator()</li>
<li>if c is an object and c belongs to Iterable&lt;T,()&gt; for some T, then i is the
result of calling c.iterator()</li>
</ol>
</li>
<li>call i.next() resulting in a value n</li>
<li>if n is nil, then the execution of the foreach statement completes normally</li>
<li>match typed-binding-pattern to n.value causing assignments to any variables
that were created in typed-binding-pattern</li>
<li>execute statement-block with the variable bindings from step 5 in scope; in the
course of so doing
<ol>
<li>the execution of a break-stmt causes execution of the foreach statement to
complete normally</li>
<li>the execution of a continue-stmt causes a transfer of control to step 3</li>
</ol>
</li>
<li>go back to step 3</li>
</ol>
<p>
In step 2, the compiler will give an error if the static type of expression is
not suitable for 2a or 2b.
</p>
<p>
In step 5, the typed-binding-pattern is used unconditionally, and the compiler
will check that the static types guarantee that the match will succeed. If the
typed-binding-pattern uses var, then the type will be inferred from the type of
<code>action-or-expr</code>.
</p>
</section>
<section>
<h4>While statement</h4>

<pre
class="grammar">while-stmt := <code>while</code> expression statement-block
</pre>
<p>
A while statement repeatedly executes a statement block so long as a
boolean-valued expression evaluates to true.
</p>
<p>
In more detail, a while statement executes as follows:
</p>
<ol>
<li>evaluate expression;</li>
<li>if expression evaluates to false, terminate execution of the while
statement;</li>
<li>execute statement-block; in the course of so doing
<ol>
<li>the execution of a break-stmt results in the execution of the
while statement completing normally</li>
<li>the execution of a continue-stmt causes a transfer of control to
step 1</li>
</ol>
</li>
<li>go back to step 1.</li>
</ol>
<p>
The static type of <code>expression</code> must be a subtype of boolean.
</p>
</section>
<section>
<h4>Continue statement</h4>

<pre
class="grammar">continue-stmt := <code>continue</code> <code>;</code>
</pre>
<p>
A continue statement is only allowed if it is lexically within a while-stmt or a
foreach-stmt. Execution a continue statement results in a transfer of control
that causes the execution of the outermost statement-block in the nearest
enclosing while-stmt or foreach-stmt to complete normally.
</p>
</section>
<section>
<h4>Break statement</h4>

<pre class="grammar">break-stmt := <code>break</code> <code>;</code>
</pre>
<p>
A break statement is only allowed if it is lexically within a while-stmt or a
foreach-stmt. Execution of a break statement results in a transfer of control
that causes the execution of nearest enclosing while-stmt or foreach-stmt to
complete normally.
</p>
</section>
</section>

<section>
<h3 id="lock_statement">Lock statement</h3>
<pre
class="grammar">lock-stmt := <code>lock</code> statement-block
</pre>

<p>
A lock-stmt executing in the context of some strand must execute its statement-block
in such a way that the effect on the state of the program is consistent with the
execution of the statement-block not being interleaved with the execution of a
lock-stmt on any other strand.
</p>
<p>
A naive implementation can simply acquire a single, program-wide, recursive mutex
before executing a lock statement, and release the mutex after completing the
execution of the lock statement. A more sophisticated implementation can perform
compile-time analysis to infer a more fine-grained locking strategy that will
have the same effects as the naive implementation.
</p>
<p>
It is not allowed to start a new strand within a lock. More precisely, when a
strand has started but not yet completed the execution of a lock-stmt, the
execution of a named-worker-decl or a start-action on that strand will result in
a panic. It is a compile-time error for a named-worker-decl or start-action to
occur lexically within a lock-stmt. The compiler may also give a compile-time
error if a function definition contains a named-worker-decl or start-action, and
there is a function call lexically within the lock-stmt that might result
directly or indirectly in a call to that defined function.
</p>
<p>
It is a compile-time error if a lock-stmt contains a sync-send-action or a receive-action.
</p>
<p>
There are two cases where a variable is restricted to be used only within a
lock statement:
</p>
<ul>
<li>when the variable is an isolated module-level variable; since isolated
module-level variables are not allowed to be public, this restriction applies to
all functions in the module;</li>
<li>when the variable is <code>self</code> within an isolated object and
<code>self</code> occurs in a field-access-expr <code>self.<var>x</var></code>,
unless the field <code><var>x</var></code> is isolated; since non-isolated
fields are required to be private, this restriction applies only to the object's
methods.</li>
</ul>
<p>
When a lock statement contains one of the above two cases of restricted variable
usage, the lock statement is subject to the following additional requirements,
which maintain the invariant that the restricted variable is an isolated root.
</p>
<ul>
<li>Only one such variable can occur in the lock statement.</li>
<li>A function or method can be called in the lock statement only if the type of
the function is isolated.</li>
<li>Transferring values out of the lock statement is constrained: the expression
following a return statement must be an isolated expression; an assignment to a
variable defined outside the lock statement is allowed only if left-hand side is
just a variable name and the right hand side is an isolated expression. An
assignment to the restricted variable is not subject to this constraint.
</li>
<li>Transferring values into the lock statement is constrained: a
variable-reference-expr within the lock statement that refers to a variable or
parameter defined outside the lock statement is allowed only if the
variable-reference-expr occurs within an expression that is isolated. A
variable-reference-expr that refers to the restricted variable is not subject to
this constraint. Within a non-isolated object, <code>self</code> behaves like a
parameter.
</li>
</ul>

</section>

<section>
<h3>Fail and retry</h3>
<p>
The execution of a statement can fail either as the result of <code>check</code>
expression or action, or from an explicit <code>fail</code> statement. When
execution of a statement fails, control flow transfers to the nearest lexically
enclosing failure-handling statement. The failure handling statements are
stmt-with-on-fail, retry-stmt, transaction-stmt and retry-transaction-stmt. If
there is no such statement, it terminates the current worker normally. Note that
failure is completely distinct from panic.
</p>
<p>
When execution fails there is an associated error value, which is passed to the
failure-handling statement if there is one. If there is no failure-handling
statement, then the error value becomes the return value of the worker. The
possible failure control flows are known at compile-time, as are the types of
the associated error values. For every statement, the type of the error value
associated with a failure causing control to transfer out of the block is
determined at compile-time. This is in contrast with panics, for which the type
of associated error value is not known at compile-time.
</p>

<section>
<h4>Fail statement</h4>
<pre
class="grammar">fail-stmt := <code>fail</code> expression <code>;</code>
</pre>
<p>
Executing a fail-stmt will cause control flow to transfer to the nearest
lexically enclosing failure handling statement.
</p>
<p>
The static type of the expression must be a subtype of error. Execution of the
fail-stmt evaluates the expression; the resulting error value is passed to the
failure handling statement or becomes the termination value of the current
worker.
</p>

</section>
<section>
<h4>On fail clause</h4>
<pre
class="grammar">stmt-with-on-fail := regular-compound-stmt on-fail-clause
on-fail-clause := <code>on</code> <code>fail</code> [typed-binding-pattern] statement-block
</pre>
<p>
A <code>stmt-with-on-fail</code> is executed by executing the
<code>regular-compound-stmt</code>. A <code>check</code> expression or action,
or a <code>fail</code> statement may cause control to transfer to the
<code>on-fail-cause</code>. If so, the <code>statement-block</code> is executed;
otherwise the <code>statement-block</code> is not executed.
When the regular-compound-stmt is itself a failure handling statement,
then only failure of that regular-compound-stmt itself causes control to
transfer to the <code>on-fail-clause</code>; a failure <em>within</em> that
regular-compound-stmt will be handled by that regular-compound-statement.
</p>
<p>
An <code>on-fail-clause</code> attached to a <code>named-worker-decl</code> is a
shorthand for a <code>named-worker-decl</code> with a statement block that is a
<code>do-stmt</code> with that <code>on-fail-clause</code>: <code>worker
<var>X</var> { <var>Y</var> } on fail <var>Z</var></code> is equivalent to
<code>worker <var>X</var> { do { <var>Y</var> } on fail <var>Z</var> }</code>.
</p>
<p>
If there is a <code>typed-binding-pattern</code>, then it is matched to the
associated error value, binding the variables occurring within the
<code>typed-binding-pattern</code>; the <code>statement-block</code> is executed
with these bindings in scope. The static type of the associated error value is
determined from the static type of the relevant <code>check</code> expressions
and actions, and <code>fail</code> statements. It is a compile error unless the
match of the <code>typed-binding-pattern</code> with the associated error value
is guaranteed to succeed by the static type of the associated error value.
</p>
</section>

<section>
<h4>Retry statement</h4>
<pre
class="grammar">retry-stmt := <code>retry</code> retry-spec statement-block
retry-spec := [type-parameter] [ <code>(</code> arg-list <code>)</code> ]
</pre>
<p>
The type-parameter in a retry-spec specifies a class, which must be a subtype of
RetryManager&lt;F&gt;, where F is the failure type of the statement-block; this
implies that the parameter type of the class's shouldRetry method must be a
supertype of F. The arg-list in a retry-spec specifies parameters to be passed
to the class's <code>init</code> method; as with <code>new</code>, the arg-list
can be omitted if the class's <code>init</code> method has no required
arguments.
</p>
<p>
A retry-stmt is executed as follows:
</p>
<ol>
<li>Create an object r of type RetryManager by calling <code>new T(A)</code>,
where T and A are the type-descriptor in the type-parameter and the arg-list
respectively.</li>
<li>Execute the statement-block.</li>
<li>If the execution failed with associated error e, then call
<code>r.shouldRetry(e)</code>. If the result is true, go back to the previous
step. If the result is false, then continue with the fail.</li>
</ol>
<p>
If the type-parameter is omitted, it defaults to
<code>DefaultRetryManager</code> defined in langlib error module.
</p>

</section>

</section>

<section>
<h3 id="transactions">Transactions</h3>

<p>
Ballerina provides language support for distributed transactions. A global
transaction consists of one or more transaction branches, where a branch
corresponds to work done by a single strand of a Ballerina program that is part
of the global transaction. Every transaction branch is uniquely identified by an
XID, which consists of an identifier of the global transaction and an identifier
of a branch with the global transaction.
</p>
<p>
At runtime, there is a mapping from each strand to a transaction stack, which is
a stack of transaction branches. A strand is in <em>transaction mode</em>, if
its transaction stack is non-empty; the top of a strand's transaction stack is
the current transaction branch for that strand.
</p>
<p>
Static checking is based on the idea of a transactional scope: this is a lexical
region of the program where it is known that at runtime the strand executing the
region will always be in transactional mode. A function with the
<code>transactional</code> qualifier can only be called in a transactional
scope; this includes function calls using <code>start</code>.
</p>
<p>
A running instance of a Ballerina program includes a transaction manager. This
may run in the same process as the Ballerina program or in a separate process.
It should not be connected over an unreliable network. The transaction manager
of a program is responsible for managing the transaction branches of all the
program's strands.
</p>
<p>
When a global transaction involves multiple Ballerina programs, there must be a
network protocol that allows that transaction managers for each Ballerina
program to communicate. The protocol must also allow a remote method or resource
method on a service object to be informed of the global transaction, if any, to
which it belongs. When a listener object determines that a remote method or
resource method of a service object is to be a part of a global transaction
manager, then it will create a new transaction branch, join it to the global
transaction and push that on the transaction stack for the strand on which the
method is called; if the method is declared as <code>transactional</code>, the
listener will not call the method unless it can do this. Similarly, the protocol
must allow a remote method on a client object that is called in transaction mode
to send information about the global transaction of which it is part; if the
method is declared as <code>transactional</code>, then as usual the method can
only be called in transaction mode; it also implies that the client object
implementation is transaction-aware, and that the recipient of the message sent
by the remote method must join the global transaction. A global transaction can
combine Ballerina programs with programs written in other programming languages
provided they agree on this network protocol.
</p>
<p>
A strand in transaction mode can register commit or rollback handlers with the
transaction manager; the handlers are functions which will be called by the
transaction manager when the decision has been made whether to commit or
rollback the global transaction to which the current transaction branch belongs.
</p>
<p>
Note that internal storage in Ballerina is not transactional. Rolling back a
transaction does <em>not</em> automatically restore the mutable values are
variables to their state when the transaction started. It is up to the
programmer to do this using commit or rollback handlers.
</p>
<p>
When a new strand is created by a named-worker-decl that includes a
<code>transactional</code> qualifier or by using <code>start</code> to call a
function with a <code>transactional</code> qualifier, a new transaction branch
will be created and joined to the global transaction; this transaction branch
will be pushed onto transaction stack for the newly created strand.
</p>
<p>
Ballerina also has the concept that a transaction may be part of a sequence of
retries, where the last transaction can complete with either a rollback or
commit, and the preceding transactions all completed with a rollback.
</p>

<section>
<h4>Transaction manager</h4>

<p>
The semantics of Ballerina's transactional language features are defined in
terms of the following abstract operations on the transaction manager. These
operations cover only the interface between the application and the transaction
manager, not the interface between the resource manager and the application.
These operations are all performed by a Ballerina program in the context of a
strand. The transaction manager supports additional operations, which are
defined in the langlib transaction module.
</p>

<section>
<h5>Begin operation</h5>
<p>
The Begin operation starts a global transaction and pushes a transaction branch
for the new global transaction onto the current strand's transaction stack. This
transaction branch is the initiating branch of the global transaction. The
current strand will be in transaction mode.
</p>
<p>
The Begin operation has an optional parameter that contains information about
the previous transactions in a sequence of retries.
</p>
</section>

<section>
<h5>Commit operation</h5>
<p>
The Commit operation is only called in transaction mode, and when the current
transaction branch is the initiating branch of a global transaction. The Commit
operation always removes the topmost transaction branch from the strand's transaction
stack. The Commit operation initiates a commit of the global transaction that
the current transaction branch belongs to.
</p>
<p>
When the commit is initiated, the transaction manager runs a two-phase commit
protocol if necessary. First, it requests each participant to prepare to commit
and waits for the participants to respond. There are two possibilities. If it
receives a response from each participant that it is prepared to commit, then
the transaction manager will make a decision to commit. If it receives a
response from any participant that it cannot commit or it gives up waiting for a
response from any participant, then the transaction manager will make a decision
to rollback; in this case, it will create an error value for the cause of the
rollback.
</p>
<p>
Once the transaction manager has made a decision whether to commit, it calls the
handlers that were registered with it for for the branches of the global
transaction that it is managing; the commit handlers are called if the decision
was to commit and the rollback handlers are called if the decision was to
rollback. The error value for the cause of the rollback will be passed as an
argument to the call of each rollback handler. At this point, the Commit
operation can return. The transaction manager will also communicate its decision
to the transaction's participants, which will result in them running commit or
rollback handlers for their branches.
</p>
<p>
The Commit operation has an optional parameter which is a RetryManager object or
nil, which defaults to nil. If this parameter is non-nil and the decision is to
rollback, then the transaction manager will call the RetryManager object's
shouldRetry method, record the result and then pass it as the willRetry
parameter to any rollback handlers.
</p>
<p>
If the transaction manager decided to rollback, then the Commit operation
returns the error value for the reason for the rollback. Otherwise, it returns
nil.
</p>

</section>

<section>
<h5>Rollback operation</h5>
<p>
The Rollback operation is only called in transaction mode, and when the current
transaction branch is the initiating branch of a global transaction. The
Rollback operation always removes the topmost transaction from the strand's
transaction stack. The Rollback operations initiates a commit of the global
transaction that the current transaction branch belongs to. The transaction
manager calls the rollback handlers that were registered with it for the
branches of the global transaction that it is managing. The Rollback operation
has a parameter which is either an error value or nil; this is passed as an
argument to any rollback handlers.
</p>
<p>
The Rollback operation also has an optional parameter which is a RetryManager object
or nil, which defaults to nil. If this parameter is non-nil, then the
transaction manager will call the RetryManager object's shouldRetry method,
record the result and then pass it as the willRetry parameter to any rollback
handlers.
</p>

</section>
</section>

<section>
<h4>Transaction statement</h4>

<p>
A transaction is performed using a transaction statement. The semantics of the
transaction statement guarantees that every transaction manager Begin operation
will be paired with a Rollback or Commit operation.
</p>
<pre
class="grammar">transaction-stmt := <code>transaction</code> statement-block
</pre>
<p>
The statement-block must contain at least one commit-action. In addition, the
compiler must be able to verify that any exit out of the statement-block that is
neither a panic nor a fail will have executed a commit-action or
rollback-stmt.
</p>
<p>
A transaction-stmt is executed as follows:
</p>
<ul>
<li>Perform the transaction Begin() operation.</li>
<li>Execute the statement-block. While executing the statement-block, any panic
does not immediately terminate the current worker; rather control is transferred
back to the transaction-stmt, so that the transaction-stmt can handle it as
described in the next step.</li>
<li>If the new transaction that was begun is still the current transaction, then
the statement-block must have failed or panicked. In this case, perform a
Rollback(e) operation, where e is the error associated with the fail or panic,
and then continue with the fail or panic.</li>
</ul>
<p>
The statement-block of a transaction-stmt is a transactional scope, except for
any statements that could potentially be executed after the execution of a
commit-action or rollback-stmt.
</p>
<p>
It is an error for a transactional-stmt to appear in a transactional scope.
However, it is not an error if the current strand is in transaction mode when a
transaction-stmt is executed: in this case, the Begin() operation performed by
the transaction-stmt will, as usual, start a new transaction, which will be
completely independent of any existing transactions.
</p>
</section>


<section>
<h4>Retry transaction statement</h4>

<pre
class="grammar">retry-transaction-stmt := <code>retry</code> retry-spec transaction-stmt
</pre>
<p>
A retry-transaction-stmt is the same as a retry-stmt containing a
transaction-stmt, except as follows.
</p>
<ul>
<li>When a transaction is retried, information about the previous transaction is
passed as a parameter to the Begin() operation.</li>
<li>If the transaction committed successfully, but the statement-block of the
transaction-stmt failed, then the transaction-stmt will not be retried.</li>
<li>The RetryManager is passed as a parameter to the Commit() and Rollback()
operations and the shouldRetry method is then called by those operations, so
that the result is available to the rollback handlers. The transaction manager
records the result of calling shouldRetry, and this is used to determine whether
to retry.</li>
</ul>
</section>

<section>
<h4>Commit action</h4>

<pre
class="grammar">commit-action := <code>commit</code>
</pre>
<p>
A <code>commit-action</code> is only allowed if it is lexically within the
<code>statement-block</code> of a <code>transaction-stmt.</code>
</p>
<p>
Evaluating the <code>commit-action</code> performs the transaction manager
Commit() operation; the result of this operation is the result of the
<code>commit-action</code>. The type of the result is
<code>transaction:Error?</code>. Note that the commit action does not alter the
flow of control.
</p>

</section>

<section>
<h4>Rollback statement</h4>

<pre
class="grammar">rollback-stmt := <code>rollback</code> [expression] <code>;</code>
</pre>
<p>
A <code>rollback-stmt</code> is only allowed if it is lexically within the
<code>statement-block</code> of a <code>transaction-stmt.</code>
</p>
<p>
The <code>rollback-stmt</code> performs the transaction manager Rollback(e)
operation, where e is the result of executing the <code>expression</code>, if
present, and nil otherwise. Note that like the commit action, the rollback
statement does not alter the flow of control.
</p>

</section>

</section>
<section>
<h3>Panic statement</h3>

<pre
class="grammar">panic-stmt := <code>panic</code> expression <code>;</code>
</pre>
<p>
A panic statement terminates the current worker abnormally. The result of
evaluating <code>expression</code> provides the termination value of the worker.
</p>
<p>
The static type of <code>expression</code> must be a subtype of error.
</p>
</section>

<section>
<h3>Return statement</h3>

<pre
class="grammar">return-stmt := <code>return</code> [ action-or-expr ] <code>;</code>
</pre>
<p>
A return statement terminates the current worker normally.The result of
evaluating the action-or-expr provides the termination value of the worker. If
action-or-expr is omitted, then the termination value is nil.
</p>
</section>


</section>
<section>
<h2 id="module_level">8. Module-level declarations</h2>
<p>
Each source part in a Ballerina module must match the production
<code>module-part</code>.
</p>
<p>
The import declarations must come before other declarations; apart from this,
the order of the definitions and declarations at the top-level of a module is
not constrained.
</p>

<pre
class="grammar">module-part := import-decl* other-decl*
other-decl :=
   listener-decl
   | service-decl
   | function-defn
   | module-type-defn
   | module-class-defn
   | module-var-decl
   | module-const-decl
   | module-enum-decl
   | module-xmlns-decl
   | annotation-decl
</pre>
<section>
<h3>Import declaration</h3>

<pre
class="grammar">import-decl := <code>import</code> [org-name <code>/</code>] module-name [<code>as</code> import-prefix] <code>;</code>
import-prefix := module-prefix | <code>_</code>
org-name := import-identifier
module-name := import-identifier (<code>.</code> import-identifier)*
import-identifier := RestrictedIdentifier
</pre>
<p>
If org-name is omitted, it is defaulted from the organization of the importing
module.
</p>
<p>
An import-prefix of <code>_</code> causes the module to be imported without
making its symbols available via a module-prefix. In this case, the effect of
importing the module will be just to cause the module to be included in the
program and initialized. It is an error for a source-part to import a module
using a module-prefix and then not to use that module-prefix.
</p>
<p>
A <code>module-prefix</code> declared by an <code>import-decl</code> is in the
same symbol space as a <code>xmlns-namespace-prefix</code> declared by an
<code>xmlns-decl</code>. This symbol space is distinct from a module's main
symbol space used by other declarations.
</p>
<p>
It is an error for a module to directly or indirectly import itself. In other
words, the directed graph of module imports must be acyclic.
</p>
<pre
class="grammar">predeclared-prefix :=
   <code>boolean</code>
   | <code>decimal</code>
   | <code>error</code>
   | <code>float</code>
   | <code>function</code>
   | <code>future</code>
   | <code>int</code>
   | <code>map</code>
   | <code>object</code>
   | <code>stream</code>
   | <code>string</code>
   | <code>table</code>
   | <code>transaction</code>
   | <code>typedesc</code>
   | <code>xml</code>
</pre>
<p>
A reserved keyword <code><var>t</var></code> that is a predeclared-prefix is
predeclared as referring to the <code>lang.<var>t</var></code> lang library
module, but this can be overridden by an import-decl that imports a module using
that prefix. A predeclared-prefix can be used as a module-prefix without using a
QuotedIdentifier.
</p>

</section>

<section>
<h3>Module and program execution</h3>
<p>
A Ballerina program consists of one or more modules; one of these modules is
distinguished as the <em>root</em> module. The source code for a module uses
import declarations to identify the modules on which it depends directly. At
compile-time, a root module is specified, and the modules comprising the program
are inferred to be those that the root module imports directly or indirectly.
The directed graph of module imports must be acyclic.
</p>
<p>
Program execution may terminate successfully or unsuccessfully. Unsuccessful
program termination returns an error value. Program execution consists of two
consecutive phases: an initialization phase and a listening phase.
</p>
<p>
Module initialization is performed by calling an initialization function, which
is synthesized by the compiler for each module. Module initialization can fail,
in which case the initialization function returns an error value. The
initialization phase of program execution consists of initializing each of the
program's modules. If the initialization of a module is unsuccessful, then
program execution immediately terminates unsuccessfully, returning the error
value returned by the initialization function.
</p>
<p>
The initialization of a program's modules is ordered so that a module will not
be initialized until all of the modules on which it depends have been
initialized. (Such an ordering will always be possible, since the graph of
module imports is required to be acyclic.) The order in which modules are
initialized follows the order in which modules are imported so far as is
consistent with the previous constraint.
</p>
<p>
A module's initialization function performs expression evaluation so as to
initialize the identifiers declared in the module's declarations; if evaluation
of an expression completes abruptly, then the module initialization function
immediately returns the error value associated with the abrupt completion. If a
module defines a function named <code>init</code>, then a module's
initialization function will end by calling this function; if it terminates
abruptly or returns an error, then the module's initialization function will
return an error value. Note that the <code>init</code> function of the root
module will be the last function called during a program's initialization phase.
</p>
<p>
This specification does not define any mechanism for processing the program
command-line arguments typically provided by an operating system. The Ballerina
standard library provides a function to retrieve these command-line arguments.
In addition, the Ballerina platform provides a convenient mechanism for
processing these arguments. This works by generating a new command-line
processing module from the specified root module. The <code>init</code>
function of the generated module retrieves the command-line arguments, parses
them, and calls a public function of the specified root module (typically the
<code>main</code> function). The parsing of the command-line arguments is
controlled by the declared parameter types, annotations and names of the public
functions. The generated module, which imports the specified root module,
becomes the new root module.
</p>
<p>
A configuration is supplied as input to program execution. A
<em>configuration</em> consists of mapping from names of configurable
module-level variables to values. The values in a configuration always belong to
the type <code>anydata&amp;readonly</code>. The value for a variable in the
configuration is used during module initialization to initialize the variable
instead of the value specified in the module. A configurable module-level
variable may require that a configuration include a value for it. Except for
this requirement, a configuration may be empty. Before initializing any module,
the initialization phase must check that there is a value of the correct type
supplied for every configurable module-level variable that requires
configuration. If not, the module initialization phase terminates unsuccessfull.
</p>
<p>
If the initialization phase of program execution completes successfully, then
execution proceeds to the listening phase, which is described in the next
section. The termination of the listening phase, which may be successful or
unsuccessful, terminates the program execution.
</p>
</section>

<section>
<h3 id="listeners_and_services">Listeners and services</h3>

<p>
Service objects support network interaction using remote methods and resource
methods. Listeners provide the interface between the network and service
objects. A listener object receives network messages from a remote process
according to some protocol and translates the received messages into remote
methods calls or resource accesses of service objects that have been attached to
the listener object. It is up to the listener object to determine how this
translation happens. A resource path segment may correspond to something that at
the protocol level is not a string. For example, in HTTP a path segment is
natively a sequence of bytes. In this case, the listener should be able to
convert this native representation into a string, for example, by using UTF-8
decoding. The type of the listener object constrains the type of a service that
can be attached to the listener. (This constraint cannot yet be fully expressed
by Ballerina's type system.)
</p>
<p>
A service object's remote or resource method uses its return value to indicate
to the listener what further handling of the network message is needed. An error
return value is used to indicate that the method encountered some sort of error
in handling the network message. When a service object is returned, it means
that the listener should use that service object to further handle the network
message. When no further handling is needed, the return value should be nil.
</p>
<p>
The return value can also be used to supply a response to the network message.
This has the limitation that the method cannot control what happens if there is
an error in sending a response. It also has the limitation that it cannot handle
complex message exchange patterns, although returning multiple responses to a
single request can be modelled by returning a stream. A listener object can
avoid these limitations by passing a client object as a parameter to the service
object's remote or resource method; the service object then makes calls on the
remote methods of the client object in order to send a response back to the
client.
</p>
<p>
The methods defined by the Listener object type allow for the
management of the lifecycle of a listener object and its attached services. A
listener declaration registers a listener object with a module, so that it can
be managed by the module. The runtime state of each module includes a list of
listener objects that have been registered with the module. A listener object
that has been registered with a module is called a <em>module listener</em>
</p>
<p>
If at the start of the listening phase of program execution there are no module
listeners, then program execution is terminated gracefully.
Otherwise, the <code>start</code> method of each module listener is called; if
any of these calls returns an error value, then the listening phase terminates
unsuccessfully with this error value as its return value.
</p>
<p>
The listening phase of program execution continues until either the program
explicitly exits, by calling a standard library function, or the user explicitly
requests the graceful or immediate termination of the program using an
implementation-dependent operating system facility (such as a signal on a POSIX
system). In the latter case, the <code>gracefulStop</code> or
<code>immediateStop</code> method of each registered listener will be called
before termination. In the case of graceful termination, functions registered
with <code>runtime:onGracefulStop</code> are also called.
</p>

<section>
<h4>Listener declaration</h4>

<pre
class="grammar">listener-decl :=
   metadata
   [<code>public</code>] <code>listener</code> [type-descriptor] variable-name <code>=</code> expression <code>;</code>
</pre>
<p>
A <code>listener-decl</code> 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.
</p>
<p>
When a listener-decl is initialized as part of module initialization, its
expression is evaluated. If expression evaluation completes abruptly or the
result of the expression is an error, then module initialization fails.
Otherwise the variable is initialized with the result of the evaluation.
</p>
<p>
If the type-descriptor is present, it specifies the static type of the variable.
The static type of <code>expression</code> must be equivalent to a union L|E,
where L is a listener object type and E is subtype of error, which may be
<code>never</code>; if the type-descriptor is not present, then L is used as the
static type of the variable.
</p>

</section>

<section>
<h4>Service declaration</h4>

<pre
class="grammar">service-decl :=
   metadata [isolated-qual]
   <code>service</code> [type-descriptor] [attach-point] <code>on</code> expression-list object-constructor-block [<code>;</code>]
attach-point := absolute-resource-path | string-literal
absolute-resource-path :=
   root-resource-path
   | (<code>/</code> resource-path-segment-name)+
root-resource-path := <code>/</code>

expression-list := expression (<code>,</code> expression)*
</pre>
<p>
A <code>service-decl</code> creates a service object and attaches it to one or more
listeners. 
</p>
<p>
The static type S for the constructed service object is specified by the
type-descriptor if present, and otherwise is the union of a type inferred from
each expression in the expression list as follows. Each expression in the
expression-list must have a type Listener&lt;T,A&gt;|E where T is a subtype of
<code>service object {}</code>, A is a subtype of
<code>string[]|string|()</code> and E is a subtype of <code>error</code>; the
inferred type is T. The object-constructor-block has the same semantics as in an
object-constructor-expr with a <code>service</code> qualifier and a
type-reference that refers to S. If the service-decl includes
<code>isolated</code>, then it is equivalent to an object-constructor-expr with
an <code>isolated</code> qualifier as well as a <code>service</code> qualifier.
</p>
<p>
The <code>attach-point</code> determines the second argument passed to the
<code>attach</code> method: if the <code>attach-point</code> is absent, then the
argument is nil; if it is a <code>string-literal</code>, then the argument is a
string; otherwise, it is an <code>absolute-resource-path</code> and the argument
is an array of strings, with one string for each
<code>resource-path-segment-name</code>. Attaching service objects
<var>s</var><sub>1</sub>,...,<var>s</var><sub><var>n</var></sub> with absolute
resource paths <var>p</var><sub>1</sub>,...,<var>p</var><sub><var>n</var></sub>
is equivalent to attaching a single service object with <var>n</var>
<code>get</code> resource methods to <code>/</code>, where the <var>i</var>-th
resource method has a path <var>p</var><sub>i</sub> (an
<code>absolute-resource-path</code> is turned into a
<code>relative-resource-path</code> with the same
<code>resource-path-segment-name</code>s) and returns
<var>s</var><sub><var>i</var></sub>.
</p>
<p>
A service-decl is initialized as part of module initialization as follows. The
object-constructor-block is evaluated as in an object-constructor-expr resulting
in a service object <code><var>s</var></code>. Then for each expression in
expression-list:
</p>
<ol>
<li>the expression is evaluated resulting in a value which is either an error or
an object <code><var>obj</var></code> belonging to a listener object type;</li>
<li>if it is an error, module initialization fails;</li>
<li>otherwise, <code><var>obj</var></code> is registered as a module listener
(registering the same object multiple times is the same as registering it
once);</li>
<li><code><var>s</var></code> is then attached to <code><var>obj</var></code>
using <code><var>obj</var></code>'s <code>attach</code> method;</li>
<li>if the call to <code>attach</code> fails, then module initialization
fails.</li>
</ol>
</section>


<section>
<h4>Isolated inference</h4>

<p>
A listener object can use the isolated bit of a service object and of a service
object's remote method to determine whether it is safe to make concurrent calls
to the remote object or the remote method.
</p>
<p>
The compiler may infer that a service object or a service object's remote method
is isolated even it is not explicitly declared as such. In doing so, it analyzes
a module to determine whether there is a set of declarations and definitions in
the module, where each of them is a <code>service-decl</code>,
<code>object-constructor-expr</code>,
<code>module-var-decl</code>, <code>module-class-defn</code>
<code>function-defn</code> or <code>method-defn</code>, and none of them
explicitly specifies an <code>isolated</code> qualifier, such that if all them
explicitly specified an <code>isolated</code> qualifier, then they all would
meet the requirements for <a href="#isolated_functions">isolated functions</a>
and isolated objects. If so, then the isolated bit of values resulting from them
is set in the same way as if <code>isolated</code> qualifiers had been
explicitly specified. The analysis should not infer a function or method to be
<code>isolated</code> if that would be inconsistent with an annotion supported
by the implementation that provides control over which thread is used for a strand
created for named-worker-decl or start-action.
</p>
<p>
This inference is purely an optimization to improve service concurrency and is
subject to two constraints. First, any inferences do not affect the static types
visible to other modules. Second, anything explicitly declared as
<code>isolated</code> must satisfy the requirements of this specification
without without relying on inference.
</p>

</section>
</section>

<section>
<h3>Function definition</h3>

<pre
class="grammar">function-defn := 
   metadata
   [<code>public</code>] function-quals
   <code>function</code> identifier function-signature function-defn-body
function-defn-body :=
   block-function-body [<code>;</code>]
   | expr-function-body <code>;</code>
   | external-function-body <code>;</code>
</pre>
<p>
If a module has a function-defn with an identifier of <code>init</code>, it is
called called automatically by the system at the end of the initialization of
that module; if this call returns an error, then initialization of the module
fails. The following special requirements apply to the <code>init</code>
function of a module: it must not be declared <code>public</code>; its return
type must both be a subtype of <code>error?</code> and contain <code>()</code>;
it must have no parameters.
</p>
<p>
If the function-quals includes <code>transactional</code>, then
expr-function-body and the block-function-body are transactional scopes.
</p>

</section>

<section>
<h3>Module type definition</h3>

<pre
class="grammar">module-type-defn :=
   metadata
   [<code>public</code>] <code>type</code> identifier type-descriptor <code>;</code>
</pre>

<p>
A module-type-defn binds the identifier to the specified type descriptor. The
binding is in the main symbol space. The type-descriptor is resolved as part of
module initialization.
</p>

</section>

<section>
<h3>Module class definition</h3>
<p>
A class is a type descriptor that in addition to describing an object type also
defines 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.
</p>

<pre
class="grammar">module-class-defn :=
   metadata
   [<code>public</code>] class-type-quals <code>class</code> identifier <code>{</code>
      class-member*
  <code>}</code> [<code>;</code>]
class-type-quals := (<code>distinct</code> | <code>readonly</code> | isolated-qual | object-network-qual)*
class-member :=
   object-field
   | method-defn
   | remote-method-defn
   | resource-method-defn
   | object-type-inclusion
</pre>
<p>
It is an error for a keyword to appear more than once in
<code>class-type-quals</code>.
</p>
<p>
As in an object constructor expression, a visibility qualifier of
<code>private</code> can be used within a class definition; this means that the
visibility region consists of all method definitions in the class definition. If
class has private fields or methods, then it is not possible to define another
object type descriptor that is a subtype of the class's type.
</p>
<p>
If <code>class-type-quals</code> contains <code>readonly</code>, then an object
constructed using the class will have its read-only bit set; the effective type
of each field is thus the intersection of the specified type and
<code>readonly</code>; furthermore, an object shape belongs to the class's type
only if its read-only bit is set.
</p>
<p>
If <code>class-type-quals</code> contains <code>isolated</code>, then the
defined object type is an isolated type, and an object constructed using the
type will have its isolated bit set. An <code>object-field</code> or
<code>method-defn</code> occurring as a <code>class-member</code> in an isolated
class is subject to same requirements as when it occurs as an
<code>object-member</code> in an <code>object-constructor-expr</code> that is
explicitly isolated.
</p>
<p>
If an <code>object-type-inclusion</code> references a type-descriptor that is a
class, then only the type of the class is included: the definitions of the
methods and any initializers for the fields are not included. If a class uses an
object-type-inclusion to include an object type T, then each method declared in
T must be defined in the class using a <code>method-defn</code> with the same
visibility. If T has a method or field with module-level visibility, then C must
be in the same module. If the class is readonly (i.e.
<code>class-type-quals</code> includes <code>readonly</code>), then an
<code>object-type-inclusion</code> in the class is allowed to directly or
indirectly reference a <code>readonly</code> class or <code>readonly</code> type
descriptor.
</p>
<p>
If <code>class-type-quals</code> contains <code>distinct</code>, then the
primary type-id of the class will the type-id of that occurrence of
<code>distinct</code>, and the secondary type-ids will be the union of the
type-ids of the included object types. If <code>class-type-quals</code> does not
contain <code>distinct</code>, then the type-ids of the class come from the
included object types in the same way as with an object type descriptor.
</p>
<p>
An object of a class is initialized by:
</p>
<ol>
<li>allocating storage for the object</li>
<li>initializing each field with its initializer, if it has one</li>
<li>initializing the methods of the object using the class's method definitions</li>
<li>calling the class's <code>init</code> method, if there is one</li>
</ol>
<p>
The parameter list of an <code>init</code> method within an
<code>module-class-defn</code> is not required to be empty, unlike within an
<code>object-constructor-expr</code>.
</p>

</section>

<section>
<h3>Module variable declaration</h3>

<pre
class="grammar">module-var-decl := module-init-var-decl | module-no-init-var-decl
</pre>
<p>
A module-var-decl declares a variable. The scope of variables declared in a
module-var-decl is the entire module. The variable may be initialized in the
declaration or within the module's <code>init</code> function. If
<code>final</code> is specified, then it is not allowed to assign to the
variable after it is initialized.
</p>
<pre
class="grammar">
module-init-var-decl := metadata [<code>public</code>] module-init-var-quals typed-binding-pattern <code>=</code> module-var-init <code>;</code>
module-init-var-quals := (<code>final</code> | isolated-qual)* | <code>configurable</code>
module-var-init := expression | <code>?</code>
</pre>
<p>
A module-init-var-decl declares and initializes a variable. It is an error for a
keyword to appear more than once in <code>module-init-var-quals</code>. If the
typed-binding-pattern uses <code>var</code>, then the type of the variables is
inferred from the static type of <code>expression</code>; if the module-var-decl
includes <code>final</code> or <code>configurable</code>, the precise type is
used, and otherwise the broad type is used. If the typed-binding-pattern
specifies a type-descriptor, then that type-descriptor provides the contextually
expected type for action-or-expr.
</p>
<p>
If the module-init-var-decl includes <code>public</code>, then the
typed-binding-pattern must not use <code>var</code>.
</p>
<p>
If a module-init-var-decl includes an isolated-qual, then the variable declared
is isolated. In this case, <code>public</code> must not be specified, the
binding-pattern in the typed-binding-pattern must be just a variable-name, and
the expression must be an isolated expression. A variable declared as an
isolated variable can be accessed only within a lock-stmt. When an isolated-qual
occurs in a position where the grammar would allow it to be parsed as part of
module-init-var-quals or typed-binding-pattern, the former parse is used.
</p>
<p>
If <code>configurable</code> is specified, then the initializer specified in the
module-var-init may be overridden at the time of module initialization by a
value supplied when the program is run. If such a value is supplied, then the
expression in the module-var-init is not evaluated and the variable is
initialized with the supplied value instead. A module-var-init of <code>?</code>
is allowed only when <code>configurable</code> is specified and means that a
configurable value must be supplied for this variable. If
<code>configurable</code> is specified, then the typed-binding-pattern must use
an explicit type-descriptor rather than <code>var</code> and the binding-pattern
must be just a variable-name. The type specified by the type-descriptor must be
a subtype of <code>anydata</code>. A variable declared as
<code>configurable</code> is implicitly final, and cannot be assigned to outside
the declaration. The static type of a variable declared as
<code>configurable</code> is implicitly <code>readonly</code>: the type
specified in the type-descriptor is intersected with <code>readonly</code>. A
configurable variable can thus always be referenced within an isolated function.
</p>

<pre
class="grammar">module-no-init-var-decl := metadata [<code>public</code>] [<code>final</code>] type-descriptor variable-name <code>;</code>
</pre>
<p>
A module variable declared with <code>module-no-init-var-decl</code> must be
initialized in the module's <code>init</code> function. It must be definitely
assigned at each point that the variable is referenced. If <code>final</code> is
specified, then the variable must not be assigned more than once. The
<code>type-descriptor</code> must not be <code>never</code>.
</p>

</section>
<section>
<h3>Module constant declaration</h3>

<pre
class="grammar">module-const-decl :=
   metadata
   [<code>public</code>] <code>const</code> [type-descriptor] identifier <code>=</code> const-expr <code>;</code>
</pre>
<p>
A module-const-decl declares a compile-time constant. A compile-time constant is
an named immutable value, known at compile-time. A compile-time constant can be
used like a variable, and can also be referenced in contexts that require a
value that is known at compile-time, such as in a type-descriptor or in a
match-pattern.
</p>
<p>
The type of the constant is the intersection of <code>readonly</code> and the
singleton type containing just the shape of the value named by the constant. The
type of the constant determines the static type of a variable-reference-expr
that references this constant.
</p>
<p>
If type-descriptor is present, then it provides the contextually expected type
for the interpretation of const-expr. It is a compile-time error if the static
type of const-expr is not a subtype of that type. The type-descriptor must
specify a type that is a subtype of anydata and must not be <code>never</code>.
Note that the type-descriptor does not specify the type of the constant,
although the type of the constant will all be a subtype of the type specified by
the type-descriptor.
</p>
</section>

<section>
<h3>Module enumeration declaration</h3>

<pre
class="grammar">module-enum-decl :=
   metadata
   [<code>public</code>] <code>enum</code> identifier <code>{</code> enum-member (<code>,</code> enum-member)* <code>}</code> [<code>;</code>]
enum-member := metadata identifier [<code>=</code> const-expr]
</pre>
<p>
A module-enum-decl provides a convenient syntax for declaring a union of string constants.
</p>
<p>
Each enum-member is defined as compile-time constant in the same way as if it
had been defined using a module-const-decl. The result of evaluating the
const-expr must be a string. If the const-expr is omitted, it defaults to be the
same as the identifier.
</p>
<p>
The identifier is defined as a type in the same was as if it had been defined by
a module-type-defn, with the type-descriptor being the union of the constants
defined by the members.
</p>
<p>
If the module-enum-decl is public, then both the type and the constants are public.
</p>
<p>
So for example:
</p>
<pre>
public enum Color {
  RED,
  GREEN,
  BLUE
}
</pre>
<p>
is exactly equivalent to:
</p>
<pre>
public const RED = "RED";
public const GREEN = "GREEN";
public const BLUE = "BLUE";
public type Color RED|GREEN|BLUE;
</pre>
</section>

<section>
<h3>Module XML namespace declaration</h3>
<pre
class="grammar">module-xmlns-decl := xmlns-decl
</pre>

<p>
A <code>module-xmlns-decl</code> declares an XML namespace prefix with module
scope. It applies only to the source part in which it occurs, as with an
import-decl.
</p>
<p>
The semantics of xmlns-decl are described in the <a
href="#XML_namespace_declaration_statement">XML namespace declaration
statement</a> section.
</p>

</section>


</section>
<section>
<h2 id="metadata">9. Metadata</h2>
<p>
Ballerina allows metadata to be attached to a construct by specifying the
metadata before the construct.
</p>

<pre
class="grammar">metadata := [DocumentationString] [annots]
</pre>
<p>
There are two forms of metadata: documentation and annotations.
</p>
<section>
<h3>Annotations</h3>

<pre
class="grammar">annots := annotation+
annotation := <code>@</code> annot-tag-reference annot-value
</pre>
<p>
Annotations provide structured metadata about a particular construct. Multiple
annotations can be applied to a single construct. An annotation consists of a
tag and a value.
</p>

<pre
class="grammar">annotation-decl :=
   metadata
   [<code>public</code>] [<code>const</code>] <code>annotation</code> [type-descriptor] annot-tag 
   [<code>on</code> annot-attach-points] <code>;</code>
annot-tag := identifier
</pre>
<p>
An annotation-decl declares an annotation tag. Annotations tags are in a
separate symbol space and cannot conflict with other module level declarations
and definitions. The annotation tag symbol space is also distinct from the
symbol space used by module prefixes and XML namespace prefixes.
</p>
<p>
The type-descriptor specifies the type of the annotation tag. The type must be a
subtype of one of the following three types: <code>true</code>,
<code>map&lt;value:Cloneable&gt;</code>,
<code>map&lt;value:Cloneable&gt;[]</code>. If the type-descriptor is omitted,
then the type is <code>true</code>.
</p>

<pre
class="grammar">annot-tag-reference := qualified-identifier | identifier
annot-value := [mapping-constructor-expr]
</pre>
<p>
An annot-tag-reference in an annotation must refer to an annot-tag declared in
an annotation declaration. When an annot-tag-reference is a
qualified-identifier, then the module-prefix of the qualified-identifier is
resolved using import declarations into a reference to a module, and that module
must contain an annotation-decl with the same identifier. An annot-tag-reference
that is an identifier rather than a qualified-identifier does <em>not</em> refer
to an annotation defined within the same module. Rather the compilation
environment determines which identifiers can occur as an
annotation-tag-reference, and for each such identifier which module defines that
annotation tag.
</p>
<p>
Each annotation has a value. For every construct that has an annotation with a
particular tag, there is also an <em>effective value</em> for that annotation
tag, which is constructed from the values of all annotations with that tag that
were attached to that construct. The effective value belongs to the type
declared for the annotation tag. The type of the annotation tag determines the
type of the annotation value and whether multiple annotations with the same tag
on a single construct are allowed. For an annotation tag declared with type T,
if T is M[] for some type mapping type M, then the type of the annotation value
is M, multiple annotations are allowed, and the effective value is an array of
the values for each annotation; otherwise the type of the annotation value is T,
multiple annotations are not allowed, the effective value is the value of the
single annotation.
</p>
<p>
If the type of the annotation value is <code>true</code>, then a
mapping-constructor-expr is not allowed, and the annotation value is
<code>true</code>. Otherwise the type of the annotation value must be a mapping
type M; if a mapping-constructor-expr is not specified, then it defaults to
<code>{ }</code>; the mapping-constructor-expr must have static type M and the
annotation value is the result of evaluating the mapping-constructor-expr with M
as the contextually expected type.
</p>
<p>
If the annotation-decl for a tag specifies <code>const</code>, then a
mapping-constructor-expr in annotations with that tag must be a const-expr and
is evaluated at compile-time with the semantics of a const-expr. Otherwise, the
mapping-constructor-expr is evaluated when the annotation is evaluated and the
ImmutableClone abstract operation is applied to the result.
</p>
<p>
An annotation applied to a module-level declaration is evaluated when the module
is initialized. An annotation applied to a service constructor is evaluated when
the service constructor is evaluated. An annotation occurring within a type
descriptor is evaluated when the type descriptor is resolved.
</p>

<pre
class="grammar">annot-attach-points := annot-attach-point (<code>,</code> annot-attach-point)*
annot-attach-point :=
   dual-attach-point
   | source-only-attach-point
dual-attach-point := [<code>source</code>] dual-attach-point-ident
dual-attach-point-ident :=
   <code>type</code>
   | <code>class</code>
   | [<code>object</code>|<code>service</code> <code>remote</code>] <code>function</code>
   | <code>parameter</code>
   | <code>return</code>
   | <code>service</code>
   | [<code>object</code>|<code>record</code>] <code>field</code>
source-only-attach-point := <code>source</code> source-only-attach-point-ident
source-only-attach-point-ident :=
   <code>annotation</code>
   | <code>external</code>
   | <code>var</code>
   | <code>const</code>
   | <code>listener</code>
   | <code>client</code>
   | <code>worker</code>
</pre>
<p>
The <code>annot-attach-points</code> specify the constructs to which an
annotation can be attached.
</p>
<p>
When an attachment point is prefixed with <code>source</code>, then the
annotation is attached to a fragment of the source rather than to any runtime
value, and thus is not available at runtime. If any of the attachment points
specify <code>source</code>, the annotation-decl must specify
<code>const</code>.
</p>
<p>
When an attachment point is not prefixed with source, then the annotation is
accessible at runtime by applying the annotation access operator to a typedesc
value.
</p>
<p>
The available attachment points are described in the following table.
</p>
<table>
  <tr>
   <td><strong>Attachment point name</strong></td>
   <td><strong>Syntactic attachment point(s)</strong></td>
   <td><strong>Attached to which type descriptor at runtime</strong></td>
  </tr>
  <tr>
   <td>type</td>
   <td>module-type-defn, module-enum-decl, type-cast-expr</td>
   <td>defined type</td>
  </tr>
  <tr>
   <td>class</td>
   <td>module-class-defn</td>
   <td>defined type (which will be type of objects constructed using this class)</td>
  </tr>
  <tr>
   <td>function</td>
   <td>function-defn, method-decl, method-defn, anonymous-function-expr</td>
   <td>type of function</td>
  </tr>
  <tr>
   <td>object function</td>
   <td>method-decl, method-defn</td>
   <td>type of function</td>
  </tr>
  <tr>
   <td>service remote function</td>
   <td>method-defn with remote qualifier on service object</td>
   <td>type of function, on service value</td>
  </tr>
  <tr>
   <td>return</td>
   <td>return-type-descriptor</td>
   <td>indirectly to type of function</td>
  </tr>
  <tr>
   <td>parameter</td>
   <td>required-param, defaultable-param, included-record-param, rest-param</td>
   <td>indirectly to type of function</td>
  </tr>
  <tr>
   <td>service</td>
   <td>service-decl, object-constructor-expr with service qualifier</td>
   <td>type of service</td>
  </tr>
  <tr>
   <td>field</td>
   <td>individual-field-descriptor, member-type-descriptor, object-field-descriptor</td>
   <td>type of mapping, list or object</td>
  </tr>
  <tr>
   <td>object field</td>
   <td>object-field-descriptor, object-field</td>
   <td>type of object</td>
  </tr>
  <tr>
   <td>record field</td>
   <td>individual-field-descriptor</td>
   <td>type of mapping</td>
  </tr>
  <tr>
   <td>listener</td>
   <td>listener-decl</td>
   <td>none</td>
  </tr>
  <tr>
   <td>var</td>
   <td>module-var-decl, local-var-decl-stmt, let-var-decl</td>
   <td>none</td>
  </tr>
  <tr>
   <td>const</td>
   <td>module-const-decl, enum-member</td>
   <td>none</td>
  </tr>
  <tr>
   <td>annotation</td>
   <td>annotation-decl</td>
   <td>none</td>
  </tr>
  <tr>
   <td>external</td>
   <td>external-function-body</td>
   <td>none</td>
  </tr>
  <tr>
   <td>worker</td>
   <td>named-worker-decl, start-action</td>
   <td>none</td>
  </tr>
</table>
</section>
<section>
<h3>Documentation</h3>
<p>
A documentation string is an item of metadata that can be associated with
module-level Ballerina constructs and with method declarations. The purpose of
the documentation strings for a module is to enable a programmer to use the
module. Information not useful for this purpose should be provided in in
comments.
</p>
<p>
A documentation string has the format of one or more lines each of which has a
<code>#</code> optionally preceded by blank space.
</p>
<p>
The documentation statement is used to document various Ballerina constructs.
</p>

<pre
class="grammar">DocumentationString := DocumentationLine +
DocumentationLine := BlankSpace* <code>#</code> [Space] DocumentationContent
DocumentationContent := (^ 0xA)* 0xA
BlankSpace := Tab | Space
Space := 0x20
Tab := 0x9
</pre>
<p>
A <code>DocumentationString</code> is recognized only at the beginning of a
line. The content of a documentation string is the concatenation of the
<code>DocumentationContent</code> of each <code>DocumentationLine</code> in the
<code>DocumentationString</code>. Note that a single space following the # is
not treated as part of the DocumentationContent.
</p>
<p>
The content of a <code>DocumentationString</code> is parsed as Ballerina
Flavored Markdown (BFM). BFM is also used for a separate per-module
documentation file, conventionally called <code>Module.md</code>.
</p>
</section>
<section>
<h3>Ballerina Flavored Markdown</h3>
<p>
Ballerina Flavored Markdown is GitHub Flavored Markdown, with some additional
conventions.
</p>
<p>
In the documentation string attached to a function or method, there must be
documentation for each parameter, and for the return value if the return value
is not nil. The documentation for the parameters and a return value must consist
of a Markdown list, where each list item must have the form <code>ident -
doc</code>, where ident is either the parameter name or return, and doc is the
documentation of that parameter or of the return value.
</p>
<p>
The documentation for an object must contain a list of fields rather than
parameters. Private fields should not be included in the list.
</p>
<p>
BFM also provides conventions for referring to Ballerina-defined names from
within documentation strings in a source file. An identifier in backticks
<code>`X`</code>, when preceded by one of the following words:
</p>
<ul>
<li><code>type</code></li>
<li><code>service</code></li>
<li><code>variable</code></li>
<li><code>var</code></li>
<li><code>annotation</code></li>
<li><code>module</code></li>
<li><code>function</code></li>
<li><code>parameter</code></li>
</ul>
<p>
is assumed to be a reference to a Ballerina-defined name of the type indicated
by the word. In the case of <code>parameter</code>, the name must be unqualified
and be the name of a parameter of the function to which the documentation string
is attached. For other cases, if the name is unqualified it must refer to a
public name of the appropriate type in the source file's module; if it is a
qualified name M:X, then the source file must have imported M, and X must refer
to a public name of an appropriate type in M. BFM also recognizes
<code>`f()`</code> as an alternative to <code>function `f`</code>. In both
cases, f can have any of the following forms (where `m` is a module import, `x` is a
function name, `T` is an object type name, and `y` is a method name):
</p>

<pre
>    x()
    m:x()
    T.y()
    m:T.y()
</pre>
<p>
Example
</p>

<pre
>    # Adds parameter `x` and parameter `y`
    # + x - one thing to be added
    # + y - another thing to be added
    # + return - the sum of them
    function add (int x, int y) returns int { return x + y; }
</pre>

<p>
The Ballerina platform may define additional conventions, in particular relating
to headings with particular content. For example, a heading with a content of
<code>Deprecated</code> can be used to provide information about the deprecation
of the name to which the documentation string is attached.
</p>

</section>
</section>

<section>
<h2 id="data_tags">10. Data tags</h2>
<section>
<h3>Regular expressions (preview)</h3>

<p>
The <code>re</code> data tag is used for regular expressions. The lang library
module for the corresponding basic type is <code>lang.regexp</code>.
</p>
<p>
The syntax and semantics of Ballerina regular expressions are based on Perl.
Ballerina supports a subset of Perl regular expressions that includes the most
commonly used features and is interoperable across multiple regular expression
engines. The supported syntax is defined by the <code>RegExp</code> grammar
given below.
</p>

<pre
class="grammar">RegExp := ReDisjunction

ReDisjunction := ReSequence (<code>|</code> ReSequence)*
ReSequence := ReTerm*
ReTerm :=
   ReAtom [ReQuantifier]
   | ReAssertion
ReAssertion := <code>^</code> | <code>$</code>

ReQuantifier := ReBaseQuantifier [<code>?</code>]

ReBaseQuantifier :=
   <code>*</code>
  | <code>+</code>
  | <code>?</code>
  | <code>{</code> Digit+ [<code>,</code> Digit*] <code>}</code>

ReAtom :=
   ReLiteralChar
   | ReEscape
   | <code>.</code>
   | <code>[</code> [<code>^</code>] [ReCharSet] <code>]</code> 
   | <code>(</code> [<code>?</code> ReFlagsOnOff <code>:</code>] ReDisjunction <code>)</code>

ReLiteralChar := ^ ReSyntaxChar

ReSyntaxChar :=
  <code>^</code> | <code>$</code> | <code>\</code> | <code>.</code> | <code>*</code> | <code>+</code> | <code>?</code>
  | <code>(</code> | <code>)</code> | <code>[</code> | <code>]</code> | <code>{</code> | <code>}</code> | <code>|</code>

ReEscape :=
   NumericEscape
   | ControlEscape
   | ReQuoteEscape
   | ReUnicodePropertyEscape
   | ReSimpleCharClassEscape

ReQuoteEscape := <code>\</code> ReSyntaxChar
ControlEscape := <code>\r</code> | <code>\n</code> | <code>\t</code>

ReSimpleCharClassEscape := <code>\</code> ReSimpleCharClassCode

ReSimpleCharClassCode := <code>d</code> | <code>D</code> | <code>s</code> | <code>S</code> | <code>w</code> | <code>W</code>

ReUnicodePropertyEscape := <code>\</code> (<code>p</code> | <code>P</code>) <code>{</code> ReUnicodeProperty <code>}</code>

ReUnicodeProperty :=  ReUnicodeScript | ReUnicodeGeneralCategory

ReUnicodeScript := <code>sc=</code> ReUnicodePropertyValue

ReUnicodePropertyValue := ReUnicodePropertyValueChar+

ReUnicodePropertyValueChar := AsciiLetter | Digit | <code>_</code>

ReUnicodeGeneralCategory := [<code>gc=</code>] ReUnicodeGeneralCategoryAbbr

ReUnicodeGeneralCategoryAbbr :=
  <code>L</code> [ <code>u</code> | <code>l</code> | <code>t</code> | <code>m</code> | <code>o</code> ]
  | <code>M</code> [ <code>n</code> | <code>c</code> | <code>e</code> ]
  | <code>N</code> [ <code>d</code> | <code>l</code> | <code>o</code> ]
  | <code>S</code> [ <code>m</code> | <code>c</code> | <code>k</code> | <code>o</code> ]
  | <code>P</code> [ <code>c</code> | <code>d</code> | <code>s</code> | <code>e</code> | <code>i</code> | <code>f</code> | <code>o</code> ]
  | <code>Z</code> [ <code>s</code> | <code>l</code> | <code>p</code> ]
  | <code>C</code> [ <code>c</code> | <code>f</code> | <code>o</code> | <code>n</code> ]

ReCharSetAtom :=
  ReCharSetAtomNoDash
  | <code>-</code>

ReCharSetAtomNoDash :=
  ReCharSetLiteralChar
  | ReEscape
  | <code>\-</code>

ReCharSetLiteralChar := ^ (<code>\</code> | <code>]</code> | <code>-</code>)

ReCharSet :=
  ReCharSetAtom
  | ReCharSetRange [ReCharSet]
  | ReCharSetAtom ReCharSetNoDash

ReCharSetRange := ReCharSetAtom <code>-</code> ReCharSetAtom

ReCharSetNoDash :=
  ReCharSetAtom
  | ReCharSetRangeNoDash [ReCharSet]
  | ReCharSetAtomNoDash ReCharSetNoDash
  
ReCharSetRangeNoDash := ReCharSetAtomNoDash <code>-</code> ReCharSetAtom

ReFlagsOnOff := ReFlagsOn [<code>-</code> ReFlagsOff]
ReFlagsOn := ReFlag*
ReFlagsOff := ReFlag*
ReFlag :=
  ReMultilineFlag
  | ReDotAllFlag
  | ReIgnoreCaseFlag
  | ReCommentFlag

ReMultilineFlag := <code>m</code>
ReDotAllFlag := <code>s</code>
ReIgnoreCaseFlag := <code>i</code>
ReCommentFlag := <code>x</code>
</pre>
<p>
Note that <code>ReUnicodeGeneralCategoryAbbr</code> omits <code>Cs</code>, which
is used for surrogate code points, since these cannot occur in a Ballerina
string.
</p>
<p>
The abstract parsing function that is part of the data tag definition behaves as
follows. The argument string values are concatenated into a single string with a
distinct token inserted between them to represent the interpolation point. The
resulting string is parsed against the above <code>RegExp</code> grammar with
the interpolation point token being an additional possibility allowed for
<code>ReAtom</code>. The abstract parsing function returns a function that will
behave equivalently to parsing the original string with
<code>(?:<var>r<sub>i</sub></var>)</code> inserted at interpolation point
<code><var>i</var></code>, where <code><var>r</var><sub>i</sub></code> is the
string representation of the interpolated regular expression.
</p>
<p>
The most rigorous specification of the semantics of Perl-style regular
expressions is in the ECMAScript language specification. For this reason, the
semantics of Ballerina regular expressions are defined by reference to the
ECMAScript language specification, specifically ECMAScript 2022. The syntax of
Ballerina regular expressions has been chosen to be a subset of ECMAScript
regular expression syntax with one exception: regular expression flags, which in
ECMAScript are specified in the regular expression literal following the closing
<code>/</code>, are in Ballerina specified in the regular expression itself
(using the same syntax as Perl).
</p>
<p>
The semantics of a Ballerina regular expression are as specified by ECMAScript
subject to the following points:
</p>
<ul>
<li>the version of ECMAScript used is ECMAScript 2022 (ECMA-262, 13th edition);</li>
<li>Ballerina uses the semantics defined by ECMAScript for when Unicode mode, as set by the
<code>u</code> flag, is in effect (ECMAScript regular expressions work differently depending
on whether Unicode mode is in effect or not);</li>
<li>the semantics of <code>\p</code> and <code>\P</code>, and of the
<code>i</code> flag depend on the version of Unicode being used; this version of
Ballerina uses Unicode version 10;</li>
<li>regular expression constructs that depend on the definition of a line
terminator or whitespace use the Ballerina definitions of those rather than the
ECMAScript definitions; specifically
<ul>
<li><code>.</code> matches any character other than 0xA or 0xD;</li>
<li><code>\s</code> matches any character allowed by the
<code>WhiteSpaceChar</code> production; as in ECMAScript, <code>\S</code>
matches any character not matched by <code>\s</code>;</li>
</ul>
</li>
<li>the semantics of <code>ReFlagsOnOff</code> (which is not supported in ECMAScript) are as follows:
<ul>
<li>the flags are modified within the parenthesized group containing the
<code>ReFlagsOnOff</code>, with those in <code>ReFlagsOn</code> being turned on,
and those in <code>ReFlagsOff</code> being turned off;</li>
<li>it is an error for any flag to be specified more than once within
<code>ReFlagsOnOff</code>;</li>
<li>the meaning of the <code>m</code>, <code>s</code> and <code>i</code> flags are as
in ECMAScript;</li>
<li>the meaning of the <code>x</code> flag is as in Perl: when this flag is in
effect, any character in the regular expression that matches to the
<code>WhiteSpaceChar</code> production, but is not within an
<code>ReCharSet</code> is ignored; in addition, comments starting with
<code>#</code> and continuing to the end of the line are ignored.</li>
</ul>
</li>
</ul>

<p>
ECMAScript specifies how to compile a regular expression in the above syntax
into an abstract function that takes as arguments an input string and an index
into the input string, and returns a value saying whether the regular expression
matches the input string starting at the index, and, if it does, the index where
the match ended, and for each capturing group, the start and end index, if any,
within the input string where the capturing group matched. This abstract
function corresponds directly to the <code>matchGroupsAt</code> function in the
<code>lang.regexp</code> module. The <code>matchAt</code>, <code>find</code>,
<code>findGroups</code>, <code>findAll</code> and <code>findAllGroups</code>
functions can be defined straightforwardly in terms of the
<code>matchGroupsAt</code> function. The <code>fullMatchGroup</code> function
can be implemented by first appending `$` to the regular expression so as to
anchor any match to the end of the input string (the multiline flag is initially
off, so `$` matches only at the end of input), and then using the ECMAScript
abstract function with a start index of 0. The <code>isFullMatch</code> function
can be implemented straightforwardly in terms of the <code>fullMatchGroup</code>
function.
</p>

</section>

</section>

<section>
<h2 id="lang_library">11. Lang library</h2>

<p>
Modules in the <code>ballerina</code> organization with a module name starting
with <code>lang.</code> are reserved for use by this specification. These
modules are called the <em>lang library</em>.
</p>

<section>
<h3>Generic types</h3>
<p>
Modules in the lang library can make use generic typing. Since generic typing
has not yet been added to Ballerina, the source code for the modules use an
annotation to describe generic typing as follows. When a module type definition
has a <code>@typeParam</code> annotation, it means that this type serves as a
type parameter when it is used in a function definition: all uses of the type
parameter in a function definition refer to the same type; the definition of the
type is an upper bound on the type parameter. A parameter of a function
definition can be annotated with an <code>@isolatedParam</code> annotation; this
is allowed when the function is declared as isolated and the type of the
parameter is a function type; the meaning is that when the function is called in
a context that requires it to be isolated, then the argument supplied for the
parameter must also be isolated. In effect, the function is parameterized with
the isolated qualifier.
</p>
<p>
<strong>Note</strong> We plan to provide full support for generic types in
a future version of this specification.
</p>
</section>

<section>
<h3 id="built-in_subtypes">Built-in subtypes</h3>
<p>
A module in the lang library can provide types that are <em>built-in</em> in the
sense that their meaning is defined by this specification. Each such built-in
type is a subtype of a single basic type; a built-in type that is a subtype of a
basic type <code><var>B</var></code> is provided by the module
<code>lang.<var>B</var></code>.
</p>
<p>
The built-types provided by lang library modules are described in the following
table.
</p>

<table>
<tr>
<th>Basic type</th>
<th>Type name</th>
<th>Criteria for <em>v</em> to belong to type</th>
</tr>
<tr>
<td rowspan="6">int</td>
<td>Unsigned8</td>
<td>0 &#x2264; <em>v</em> &#x2264; 255</td>
</tr>
<tr>
<td>Signed8</td>
<td>-128 &#x2264; <em>v</em> &#x2264; 127</td>
</tr>
<tr>
<td>Unsigned16</td>
<td>0 &#x2264; <em>v</em> &#x2264; 65,535</td>
</tr>
<tr>
<td>Signed16</td>
<td>-32,768 &#x2264; <em>v</em> &#x2264; 32,767</td>
</tr>
<tr>
<td>Unsigned32</td>
<td>0 &#x2264; <em>v</em> &#x2264; 4,294,967,295</td>
</tr>
<tr>
<td>Signed32</td>
<td>-2,147,483,648 &#x2264; <em>v</em> &#x2264; 2,147,483,647</td>
</tr>
<tr>
<td>string</td>
<td>Char</td>
<td><em>v</em> has length 1</td>
</tr>
<tr>
<td rowspan="4">xml</td>
<td>Element</td>
<td><em>v</em> is an element singleton</td>
</tr>
<tr>
<td>ProcessingInstruction</td>
<td><em>v</em> is a processing instruction singleton</td>
</tr>
<tr>
<td>Comment</td>
<td><em>v</em> is a comment singleton</td>
</tr>
<tr>
<td>Text</td>
<td><em>v</em> is either the empty xml value or a text singleton</td>
</tr>
</table>
<p>
Each built-in type has a type definition in the module that provides it. The
type descriptor of the type definition is the corresponding basic type. The type
definition has a <code>@builtinSubtype</code> annotation, which indicates that
the meaning of the type name is built-in, as specified in the above table,
rather than coming from its type descriptor. It is an error to use the
<code>@builtinSubtype</code> annotation except in a lang library module.
</p>
<p>
So, for example, the <code>lang.int</code> module would include the definition:
</p>
<pre>
@builtinSubtype
type Signed32 int;
</pre>
<p>
Semantically, these types behave like a predefined type that can be referenced
by an unqualified name, such as <code>byte</code>. Syntactically, these types
are referenced by a <code>type-reference</code> in the same way as if their
definitions were not built-in. A built-in type <code>T</code> which is a subtype
of basic type <code>B</code> can be referenced by a type-reference
<code>M:T</code>, where <code>M</code> is a module-prefix referring to module
<code>ballerina/lang.B</code>.
</p>
<p>
For convenience, this specification refers to the built-in subtype T provided by
the module for basic type B as B:T. For example, in this specification
<code>int:Signed32</code> refers to the <code>Signed32</code> built-in subtype
of <code>int</code>, which is provided by the <code>lang.int</code> module.
</p>
<p>
The <code>int:Unsigned8</code> type is equivalent to the predefined
<code>byte</code> type.
</p>
</section>

<section>
<h3 id="lang_library_modules">Lang library modules</h3>
<p>
The lang library consists of the following modules. With the exception of the
<code>lang.value</code>, <code>lang.transaction</code> and
<code>lang.runtime</code> modules, each corresponds to a basic type.
</p>

<section>
<h4 id="lang.array"><code>lang.array</code> module</h4>

<p>The <code>lang.array</code> module corresponds to basic type list.</p>

<p class="langlib"><a href="./lib/array.bal" type="text/plain">array.bal</a></p>

</section>

<section>
<h4 id="lang.boolean"><code>lang.boolean</code> module</h4>

<p>The <code>lang.boolean</code> module corresponds to basic type boolean.</p>

<p class="langlib"><a href="./lib/boolean.bal" type="text/plain">boolean.bal</a></p>

</section>

<section>
<h4 id="lang.decimal"><code>lang.decimal</code> module</h4>

<p>The <code>lang.decimal</code> module corresponds to basic type decimal.</p>

<p class="langlib"><a href="./lib/decimal.bal" type="text/plain">decimal.bal</a></p>

</section>

<section>
<h4 id="lang.error"><code>lang.error</code> module</h4>

<p>The <code>lang.error</code> module corresponds to basic type error.</p>

<p class="langlib"><a href="./lib/error.bal" type="text/plain">error.bal</a></p>

</section>

<section>
<h4 id="lang.float"><code>lang.float</code> module</h4>

<p>The <code>lang.float</code> module corresponds to basic type float.</p>

<p class="langlib"><a href="./lib/float.bal" type="text/plain">float.bal</a></p>

</section>

<section>
<h4 id="lang.function"><code>lang.function</code> module</h4>

<p>The <code>lang.function</code> module corresponds to basic type function.</p>

<p class="langlib"><a href="./lib/function.bal" type="text/plain">function.bal</a></p>

</section>

<section>
<h4 id="lang.future"><code>lang.future</code> module</h4>

<p>The <code>lang.future</code> module corresponds to basic type future.</p>

<p class="langlib"><a href="./lib/future.bal" type="text/plain">future.bal</a></p>

</section>

<section>
<h4 id="lang.int"><code>lang.int</code> module</h4>

<p>The <code>lang.int</code> module corresponds to basic type int.</p>

<p class="langlib"><a href="./lib/int.bal" type="text/plain">int.bal</a></p>

</section>

<section>
<h4 id="lang.map"><code>lang.map</code> module</h4>

<p>The <code>lang.map</code> module corresponds to basic type mapping.</p>

<p class="langlib"><a href="./lib/map.bal" type="text/plain">map.bal</a></p>

</section>

<section>
<h4 id="lang.object"><code>lang.object</code> module</h4>

<p>The <code>lang.object</code> module corresponds to basic type object.</p>

<p class="langlib"><a href="./lib/object.bal" type="text/plain">object.bal</a></p>

</section>

<section>
<h4 id="lang.regexp"><code>lang.regexp</code> module (preview)</h4>

<p>The <code>lang.regexp</code> module corresponds to the basic type for the
tagged data type with tag <code>re</code>.</p>

<p class="langlib"><a href="./lib/regexp.bal" type="text/plain">regexp.bal</a></p>

</section>

<section>
<h4 id="lang.stream"><code>lang.stream</code> module</h4>

<p>The <code>lang.stream</code> module corresponds to basic type stream.</p>

<p class="langlib"><a href="./lib/stream.bal" type="text/plain">stream.bal</a></p>

</section>

<section>
<h4 id="lang.string"><code>lang.string</code> module</h4>

<p>The <code>lang.string</code> module corresponds to basic type string.</p>

<p class="langlib"><a href="./lib/string.bal" type="text/plain">string.bal</a></p>

</section>

<section>
<h4 id="lang.table"><code>lang.table</code> module</h4>

<p>The <code>lang.table</code> module corresponds to basic type table.</p>

<p class="langlib"><a href="./lib/table.bal" type="text/plain">table.bal</a></p>

</section>

<section>
<h4 id="lang.typedesc"><code>lang.typedesc</code> module</h4>

<p>The <code>lang.typedesc</code> module corresponds to basic type typedesc.</p>

<p class="langlib"><a href="./lib/typedesc.bal" type="text/plain">typedesc.bal</a></p>

</section>

<section>
<h4 id="lang.xml"><code>lang.xml</code> module</h4>

<p>The <code>lang.xml</code> module corresponds to basic type xml.</p>

<p class="langlib"><a href="./lib/xml.bal" type="text/plain">xml.bal</a></p>

</section>

<section>
<h4 id="lang.transaction"><code>lang.transaction</code> module</h4>

<p>The <code>lang.transaction</code> module supports transactions.</p>

<p class="langlib"><a href="./lib/transaction.bal" type="text/plain">transaction.bal</a></p>

</section>

<section>
<h4 id="lang.runtime"><code>lang.runtime</code> module</h4>

<p>The <code>lang.runtime</code> module provides functions related to the
language runtime that are not specific to a particular basic type.</p>

<p class="langlib"><a href="./lib/runtime.bal" type="text/plain">runtime.bal</a></p>

</section>

<section>
<h4 id="lang.value"><code>lang.value</code> module</h4>

<p>The <code>lang.value</code> module provides functions that work on values of
more than one basic type..</p>

<p class="langlib"><a href="./lib/value.bal" type="text/plain">value.bal</a></p>

</section>

</section>

</section>
<section class="appendix">
<h2 id="references">A. References</h2>
<ul>
<li>Unicode</li>
<li>XML</li>
<li>JSON</li>
<li>ECMAScript 2022 (ECMA-262 13th Edition)</li>
<li>RFC 3629 UTF-8</li>
<li>IEEE 754-2008</li>
<li>GitHub Markdown</li>
</ul>
</section>
<section class="appendix">
<h2 id="changes">B. Changes since previous releases</h2>
<section>
<h3>Summary of changes from 2023R1 to 2024R1</h3>
<ol>
<li>Isolated inference can infer <code>isolated</code> for an object constructor expression.</li>
<li>A query-select-expr can construct a stream without explicitly specifying
the <code>stream</code> keyword.</li>
<li>It is no longer allowed for a lock statement to contain a sync-send-action or a receive-action.</li>
<li>A <code>retry</code> or <code>transaction</code> statement may now have an <code>on fail</code>
clause.</li>
<li>A named worker declaration may now have an <code>on fail</code> clause.</li>
<li>The compile-time requirement that a send-action must always be executed
unless its containing worker terminates with an error or panic has been
removed.</li>
<li>An alternate-receive-action has been added.</li>
</ol>
</section>
<section>
<h3>Summary of changes from 2022R4 to 2023R1</h3>
<ol>
<li>Query expressions now support grouping and aggregation, using new
<code>group by</code> and <code>collect</code> clauses.</li>
<li>Keywords that start clauses of a query expression, except for
<code>from</code> and <code>let</code>, are no longer reserved (and so can be
used as identifier names).</li>
<li>Functions useful for aggregation have been added to langlib:
<code>int:avg</code>, <code>float:avg</code>, <code>decimal:avg</code>,
<code>boolean:some</code>, <code>boolean:every</code>, <code>value:count</code>,
<code>value:first</code>, <code>value:last</code>.</li>
<li>A <code>join</code> clause in a query expression can contain remote method
calls and other actions.</li>
<li>Clarify that the <code>self</code> variable in a method is implicitly
final.</li>
<li>Regexp type has a filler value.</li>
<li>Readonly record types can have defaults.</li>
</ol>
</section>

<section>
<h3>Summary of changes from 2022R3 to 2022R4</h3>
<ol>
<li>Regular expressions have been added as a new data type. This
feature has preview status in this release.</li>
<li>When an optional field cannot have the value nil, the field
can be manipulated conveniently by treating nil as representing the
absence of the field: this works for constructors, binding patterns
and assignment.</li>
<li>A <code>byte-array-literal</code> can construct a read-only value.</li>
<li>An optional semi-colon is now allowed after top-level definitions and
method definitions that are currentlty terminated by <code>}</code>.</li>
<li>An <code>int:range</code> langlib function allows convenient iteration 
over integer sequences with steps other than 1.</li>
</ol>
</section>
<section>
<h3>Summary of changes from 2022R2 to 2022R3</h3>
<ol>
<li>Client objects can declare resource methods, which can be accessed using new
<code>client-resource-access-action</code> syntax. Resource methods are now part
of the type of network interaction objects and can be specified in object type
descriptors.</li>
<li>The <code>isolated</code> feature can now be used to identify cases where
a strand created by <code>start</code> or a named worker can be run safely on
a separate thread.</li>
<li>The variable declaration in an <code>on fail</code> clause is now
optional.</li>
<li>Query expressions producing xml values will now work properly when used as
interpolated expressions in XML templates.</li>
<li>Query expressions may be used to construct maps.</li>
<li>Query expressions can now construct readonly values.</li>
<li>Annotations are now allowed on members of tuple type descriptors.</li>
<li>The <code>call</code> function has been added to <code>lang.function</code>
to allow for dynamically calling a function.</li>
<li>An <code>onGracefulStop</code> function has been added to
<code>lang.runtime</code>.</li>
<li>The grammar now allows an action such as a remote method call to occur
inside a query.</li>
<li>A <code>check</code> expression is now allowed as a statement, provided that
its type is nil.</li>
</ol>
</section>

<section>
<h3>Summary of changes from 2022R1 to 2022R2</h3>
<ol>
<li>The <code>*</code>, <code>/</code> and <code>%</code> operators now allow
operands to mix numeric types in specific cases: <code>*</code> allows the case
where either operand is an <code>int</code>; <code>/</code> and <code>*</code>
allow the case where the right operand is an <code>int</code>.</li>
<li>It is no longer an error for a <code>panic-stmt</code> to be
unreachable.</li>
<li>The <code>toExpString</code> and <code>toFixedString</code>
functions have been added to <code>lang.float</code>.</li>
<li>The <code>padStart</code>, <code>padEnd</code>, <code>padZero</code>
functions have been added to <code>lang.string</code>.</li>
<li>The <code>quantize</code> function has been added to
<code>lang.decimal</code>.</li>
<li>The <code>some</code> and <code>every</code> functions have been added to
<code>lang.array</code>.</li>
<li>The <code>round</code> function in <code>lang.float</code> and
<code>lang.decimal</code> now takes an optional argument controlling the number
of digits after the decimal point.</li>
<li>The length of an array type is allowed to be <code>*</code> only when it is
the outermost array and there is an initializer from which it can be
inferred.</li>
<li>A list constructor can use <code>...E</code> as in an argument list.</li>
</ol>
</section>
<section>
<h3>Summary of changes from 2021R1 to 2022R1</h3>
<ol>
<li>Maps are required to preserve insertion order.</li>
<li>The static typing rules for <code>==</code> and <code>!=</code> have been
relaxed to require only one operand to be <code>anydata</code>.</li>
<li>The identifiers of organizations and modules refererenced in import
declarations are restricted to ASCII alpha-numberic characters with underscores
separating words.</li>
<li>Floating pointer literals are not allowed to end with a trailing dot.</li>
<li>No white space is allowed within a qualified name.</li>
<li>Add the <code>!is</code> operator.</li>
<li>Allow <code>null</code> as a type descriptor.</li>
<li>An object type is not allowed to include a class with private members.</li>
<li>Conditional variable type narrowing from the condition of a while statement
is applied to the body of a while statement.</li>
<li>Conditional variable type narrowing is now done for a <code>where</code> clause in a
query expression or action.</li>
<li>A function call is only allowed with an expression in a match-guard when
there is no possibility that it can mutate the value being matched.</li>
<li>The interpretation of multiple dimensions in an array-type-descriptor has
been changed to make the order of dimensions in the type-descriptor consistent
with the order of dimensions in an expression that accesses the array.</li>
<li>The static type of an expression now has singleton type when all its
subexpressions have singleton type.</li>
<li>Unreachable statements are now an error.</li>
<li>Conditional variable type narrowing is now smarter. In particular, the types
of variables can be narrowed in statements following an <code>if</code>
statement that contains <code>return</code>.</li>
<li>Variable type narrowing in a match statement has been improved to work
better for types that are partially readonly.</li>
<li>Many expressions now perform nil lifting.</li>
<li>The rules for determining the basic type of a numeric literal have been
revised to work better in the case where the contextually expected type allows
two of the three possible numeric basic types.</li>
<li>Restrictions have been introduced on assigning within a loop to a variable
whose type has been narrowed outside the loop.</li>
<li>Optional fields can be accessed using the <code>.</code> operator as well as
the <code>?.</code> operator, when the type of the accessed field does not allow
nil.</li>
</ol>
</section>
<section>
<h3>Summary of changes from 2020R1 to 2021R1</h3>
<ol>
<li>There has been a major change to how objects works. All object type
descriptors are what was previously called <em>abstract</em>: they declare
methods but do not define them. Objects are now created either by using an
object constructor expression, which includes method definitions, or by applying
<code>new</code> to the name of a class defined by a class definition. The
methods and fields of an object are in a single symbol space. Classes and
object constructors can declare fields as final.</li>
<li>Services have become service objects that work in a similar way to client
objects; resource methods on service objects have become remote methods. Remote
methods are in a separate symbol space from regular methods. There is a new
concept for resource methods.</li>
<li>The <code>readonly</code> type has been added. Fields of records can also be
declared as <code>readonly</code>.</li>
<li>Functions, objects and module-level variables can be declared as
<code>isolated</code>; this works in conjunction with <code>readonly</code> to
support concurrency safety.</li>
<li>Module-level variables can be public, provided they are not isolated.</li>
<li>Intersection types have been added.</li>
<li>Distinct types have been added; these provide the functionality of nominal
types with the framework of a structural type system.</li>
<li>The error type has been revised to take advantage of distinct types. Instead
an error value having a reason string for categorizing the error and separate
message string in the detail record, an error value has a message string in the
error and distinct types are used for categorizing. The cause has also moved
from the detail record into the error value.</li>
<li>The syntax for an error constructor that uses a user-defined type name now
includes the <code>error</code> keyword before the type name.</li>
<li>Language-defined abstract object types now make use of distinct types,
instead of using names prefixed with double underscore.</li>
<li>The <code>__init</code> method of object and the <code>__init</code> function
of modules have been renamed to <code>init</code>.</li>
<li>Module variables can be initialized in the module's <code>init</code>
function.</li>
<li>The table type has been redesigned to be more consistent with other
structural types and no longer has preview status.</li>
<li>Enum declarations have been added.</li>
<li>The return type of a function with an external body can depend on the value
of a parameter of typedesc type, which can be defaulted from the contextually
expected type.</li>
<li>Query expressions support some new clauses: <code>join</code> clause,
<code>order by</code> clause, <code>limit</code> clause and <code>on
conflict</code> clause.</li>
<li>The relational operators (<code>&lt; &lt;= &gt; &gt;=</code>) have been
extended to apply to more than just numeric types.</li>
<li>Raw template expressions have been added.</li>
<li>The ability to specify the visibility of parameter names has been removed: a
parameter can always be specified by name as well as position; a parameter
cannot be declared as <code>public</code>.</li>
<li>Local type definitions have been removed.</li>
<li>The <code>fail</code> statement has been added, along with a <code>on
fail</code> clause for compound statements. If a <code>check</code> expression
or action fails, it behaves like a <code>fail</code> statement rather than a
<code>return</code> statement.</li>
<li>The language has a concept of configurability: module level variables can be
specified to be <code>configurable</code>, which allows their initial values to
be specified at runtime.</li>
<li>An import declaration can no longer specify a version.</li>
<li>The stream type no longer has Preview status.</li>
<li>Module prefixes for the langlib modules that correspond to keywords are
predeclared.</li>
<li>Backslash escapes can be used in identifiers without needing an initial
single quote.</li>
<li>Language support for transactions has been added.</li>
<li>The <code>error&lt;*&gt;</code> feature has been removed, because it does
not work well with distinct error types.</li>
<li>In message passing between workers, the function's default worker is now
referenced using the <code>function</code> keyword rather than the
<code>default</code> keyword.</li>
<li>Make <code>trap</code> expression have lower precedence.</li>
</ol>
</section>
<section>
<h3>Summary of changes from 2019R3 to 2020R1</h3>
<ol>
<li>Query expressions and query actions have been added. This is the first stage
of language-integrated query.</li>
<li>The stream basic type has been added.</li>
<li>Let expressions have been added.</li>
<li>The XML design has been refined and no longer has Preview status.
<ul>
<li>The various kinds of xml item (e.g. element and text) are subtypes of the
<code>xml</code> type.</li>
<li>The <code>xml</code> type can have a type parameter specifying the item
types.</li>
<li>Iteration over xml values exposes characters as text items rather than strings</li>
<li>Adjacent characters in XML content are chunked into a single text item.</li>
<li>The meaning of <code>===</code> for xml has changed.</li>
<li>The item of an xml sequence value x with index i can be accessed using an
expression x[i].</li>
<li>The syntax <code>x@</code> for accessing the attributes of an XML element has
been removed.</li>
</ul>
</li>
<li>The <code>lock</code> statement has been added.</li>
<li>When a list constructor or mapping constructor is used without a
contextually expected type, we now infer a tuple or record type rather than an
array or map type.</li>
<li>The syntax for Unicode escapes in strings has changed from
<code>\u[<em>CodePoint</em>]</code> to <code>\u{<em>CodePoint</em>}</code> so as
to align with ECMAScript. Although this is an incompatible change, the previous
syntax was not implemented.</li>
<li>The <code>never</code> type has been added.</li>
<li>Lang library modules can now provide built-in subtypes of existing basic
types.</li>
<li>There is a lang.boolean lang lib module.</li>
</ol>
</section>
<section>
<h3>Summary of changes from 2019R2 to 2019R3</h3>
<ol>
<li>An import declaration can use <code>as _</code> to include a module in the
program without using its symbols.</li>
<li>The specification of experimental features has been moved to a separate
document.</li>
<li>A wait-action can result in an error value when applied to a future that is
not a named worker.</li>
</ol>
</section>

<section>
<h3>Summary of changes from 2019R1 to 2019R2</h3>
<ol>
<li>The concept of a built-in method has been replaced by the concept of a lang
library. A method call on a value of non-object type is now treated as a
convenient syntax for a call to a function in a module of the lang library. The
design of the many of the existing built-in methods has been changed to fit in
with this. There are many functions in the lang library that were not previously
available as built-in methods.</li>
<li>A mapping value is now iterable as a sequence of its members (like list),
rather than as a sequence of key-value pairs. The <code>entries</code> lang library
function allows it to be iterated as a sequence of key-value pairs.</li>
<li>The basic type <code>handle</code> has been added.</li>
<li>The <code>table&lt;T&gt;</code> type descriptor shorthand has been brought
back.</li>
<li>There is now a variation on <code>check</code> called
<code>checkpanic</code>, which panics rather than returns on error.</li>
<li>A range-expr now returns an object belonging to the Iterable abstract object
type, rather than a list.</li>
<li>The decimal type now uses a simplified subset of IEEE 754-2008 decimal
floating point.</li>
<li>The status of XML-related features has been changed to preview.</li>
<li>The ability to define a method outside the object type has been
removed.</li>
<li>The UnfrozenClone operation has been removed.</li>
<li>The Freeze operation has been replaced by the ImmutableClone operation.</li>
<li>The semantics of field access, member access and assignment are now
fully specified.</li>
<li>A <code>?.</code> operator has been added for access to optional fields.</li>
<li>A type-cast-expr can include annotations.</li>
<li>The error detail record must belong to type Detail defined in the lang
library.</li>
<li>The compile-time requirement that the inherent type of a variable-length
list must allow members to be filled-in has been removed; this is instead caught
at run-time.</li>
<li>Parameter names now have public or module-level visibility, which determines
when a function call can use the parameter name to specify an argument.</li>
<li>A type descriptor <code>record { }</code> is open to <code>anydata</code>
rather than <code>anydata|error</code>.</li>
<li>Calls using <code>start</code> are treated as actions, and so are not
allowed within expressions.</li>
<li>There is a new syntax for allowing arbitrary strings as identifiers to
replace the old delimited identifier syntax <code>^"<var>s</var>"</code>.</li>
</ol>

</section>
<section>
<h3>Summary of changes from 0.990 to 2019R1</h3>
<p>
The specification has switched to a new versioning scheme. The <var>n</var>-th
version of the specification released in year 20<var>xy</var> will be labelled
20<var>xy</var>R<var>n</var>.
</p>
<ol>
<li>Tuples types now use square brackets, rather than parentheses, as do tuple
binding patterns and tuple match patterns. Array constructors and tuple
constructors are now unified into list constructors, which use square brackets.
Tuple types can have zero members or one member, and can use <code>T...</code>
syntax allow trailing members of a specified type.</li>
<li>The way that record type descriptors express openness has changed. Instead
of the <code>!...</code> syntax, there are two flavours of record type
descriptor, which use different delimiters: <code>record {| |}</code> allows any
mapping that has exclusively the specified fields, whereas <code>record {
}</code> allows any mapping that includes the specified fields; the former can
use the <code>T...</code> syntax, whereas the latter cannot. The
<code>!...</code> is no longer allowed for record binding patterns and record
match patterns.</li>
<li>The syntax for an array with an array length that is inferred has changed
from <code>T[!...]</code> to <code>T[*]</code>.</li>
<li>A type descriptor of <code>error&lt;*&gt;</code> can be used to specify an
error type whose subtype is inferred.</li>
<li>A new expression can no longer be used to create values of structural types;
it is only allowed for objects.</li>
<li>Symbolic string literals <code>'ident</code> have been removed (compile time
constants provide a more convenient approach).</li>
<li><code>untaint</code> expression has been removed (this will be handled by
annotations instead).</li>
<li>The syntax for named arguments in a function call has reverted to
<code>arg=</code> from <code>arg:</code>, since the latter caused syntactic
ambiguities.</li>
<li>The syntax for error constructors specifies fields of the error detail
separately as named arguments, rather than specifying the error detail as a
single argument; the syntax for binding patterns and match patterns for error
values has also changed accordingly.</li>
<li>The error reason argument can be omitted from an error constructor if it
can be determined from the contextually expected type.</li>
<li>The syntax for annotation declarations has been revised; the places where
annotations are allowed has been revised to match the possible attachment
points.</li>
<li>An <code>.@</code> binary operator has been added for accessing annotations
at runtime.</li>
<li>A unary <code>typeof</code> operator has been added.</li>
<li>The <code>typedesc</code> type now takes an optional type parameter.</li>
<li>The type parameters for <code>future</code> and <code>stream</code> are now
optional.</li>
<li>The syntax for a function with an external implementation has changed to use
<code>=external</code> in place of the curly braces.</li>
<li>A numeric literal can use a suffix of <code>d</code> or <code>f</code> to
indicate that it represents a value belonging to the decimal or float type
respectively.</li>
<li>Record type descriptors may now specify a default value for fields.</li>
<li>Providing a default value for a parameter no longer affects whether a function
call must supply the argument for that parameter positionally or by name. Instead
the argument for any parameter can be supplied either positionally or by name.
To avoid ambiguity, all arguments specified positionally must be specified before
arguments specified by name.</li>
<li>Expressions specifying the default value for function parameters are not
compile time constants, and are evaluated each time they are used to supply a
missing argument.</li>
<li>In the argument list of a function or method call, positional arguments are
now required to be specified before named arguments.</li>
<li>Types may now be defined within a block.</li>
</ol>
</section>
<section>
<h3>Summary of changes from 0.980 to 0.990</h3>
<p>
<strong>Structural types and values</strong>
</p>
<ol>
<li>Concepts relating to typing of mutable structural values have been changed
in order to make type system sound.</li>
<li>The <code>match</code> statement has been redesigned.</li>
<li>The <code>but</code> expression has been removed.</li>
<li>The <code>is</code> expression for dynamic type testing has been added.</li>
<li>The type-cast-expr &lt;T&gt;E now performs unsafe type casts.The only
conversions it performs are numeric conversions.</li>
<li>The <code>anydata</code> type has been added, which is a union of simple and
structural types.</li>
<li>Records are now by default open to <code>anydata|error</code>, rather than
<code>any</code>.</li>
<li>Type parameters for built-in types (map, stream, future), which previously
defaulted to any, are now required.</li>
<li>The type parameter for json (e.g. json&lt;T&gt;) is not allowed any more.</li>
<li>Type for table columns are restricted to subtype of anydata|error.</li>
<li>There are now two flavors of equality operator: == and != for deep equality
(which is allowed only for <code>anydata</code>), and ===  and !== for exact
equality.</li>
<li>There is a built-in clone operation for performing a deep copy on values of
type anydata.</li>
<li>There is a built-in freeze operation for making structural values deeply
immutable.</li>
<li>Compile-time constants (which are always a subtype of anydata and frozen)
have been added.</li>
<li>Singleton types have been generalized: any compile-time constant can be made
into a singleton value.</li>
<li>Variables can be declared final, with a similar semantic to Java.</li>
<li>Errors are now immutable.</li>
<li>Module variables are not allowed to be public: only compile-time constants
can be public.</li>
</ol>
<p>
<strong>Error handling</strong>
</p>
<ol>
<li>The <code>any</code> type no longer includes <code>error</code>.</li>
<li><code>check</code> is now an expression.</li>
<li>Exceptions have been replaced by panics
<ol>
<li>the <code>throw</code> statement has been replaced by the <code>panic</code>
statement</li>
<li>the<code> try</code> statement has been replaced by the <code>trap</code>
expression</li>
</ol>
</li>
<li>Object constructors (which could not return errors) have been replaced by
<code>__init</code> methods (which can return errors).</li>
</ol>
<p>
<strong>Concurrency</strong>
</p>
<ol>
<li>Workers in functions have been redesigned. In particular, workers now have a
return value.</li>
<li>The <code>done</code> statement has been removed.</li>
<li>The fork/join statement has been redesigned.</li>
<li>A syntactic category between expression and statement, called action, has
been added.</li>
<li>A synchronous message send action has been added.</li>
<li>A flush action has been added to flush asynchronously sent messages.</li>
<li>A wait action has been added to wait for a worker and get its return value.</li>
<li>Futures have been unified with workers. A future&lt;T&gt; represents a value to
be returned by a named worker.</li>
<li>Error handling of message send/receive has been redesigned.</li>
</ol>
<p>
<strong>Endpoints and services</strong>
</p>
<ol>
<li>Client endpoints have been replaced by client objects, and actions on client
endpoints have been replaced by remote methods on client objects. Remote methods
are called using a remote method call action, which replaces the action
invocation statement.</li>
<li>Module endpoint declaration has been replaced by module listener
declaration, which uses the Listener built-in object type.</li>
<li>The service type has been added as a new basic type of behavioral value,
together with service constructor expressions for creating service values.</li>
<li>Module service definitions have been redesigned.</li>
</ol>
<p>
<strong>Miscellaneous changes</strong>
</p>
<ol>
<li>Public/private visibility qualifiers must be repeated on an outside method
definition.</li>
</ol>
</section>
<section>
<h3>Summary of changes from 0.970 to 0.980</h3>
<ol>
<li>The decimal type has been added.</li>
<li>There are no longer any implicit numeric conversions.</li>
<li>The type of a numeric literal can be inferred from the context.</li>
<li>The error type is now a distinct basic type.</li>
<li>The byte type has been added as a predefined subtype of int; blobs have been
replaced by arrays of bytes.</li>
<li>The syntax of string templates and xml literals has been revised and
harmonized.</li>
<li>The syntax of anonymous functions has been revised to provide two
alternative syntaxes: a full syntax similar to normal function definitions and a
more convenient arrow syntax for when the function body is an expression.</li>
<li>The cases of a match statement are required to be exhaustive.</li>
<li>The + operator is specified to do string and xml concatenation as well as
addition.</li>
<li>Bitwise operators have been added (<code>&lt;&lt;</code>, <code>>></code>,
<code>>>></code>, <code>&amp;</code>, <code>|</code>, <code>^</code>,
<code>~</code>) rather than = after the argument name.</li>
<li>In a function call or method call, named arguments have changed to use
<code>:</code></li>
<li>A statement with <code>check</code> always handles an error by returning it,
not by throwing it.</li>
<li><code>check</code> is allowed in compound assignment statements.</li>
<li>Method names are now looked up differently from field names; values of types
other than objects can now have built-in methods.</li>
<li>The <code>lengthof</code> unary expression has been removed; the length
built-in method can be used instead.</li>
<li>The semantics of &lt;T&gt;expr have been specified.</li>
<li>The value space for tuples and arrays is now unified, in the same way as the
value space for records and maps was unified. This means that tuples are now
mutable. Array types can now have a length.</li>
<li>The <code>next</code> keyword has been changed to <code>continue</code>.</li>
<li>The syntax and semantics of destructuring is now done in a consistent way
for the but expression, the match statement, the foreach statement,
destructuring assignment statements and variable declarations.</li>
<li>The implied initial value is not used as a default initializer in variable
declarations. A local variable whose declaration omits the initializer must be
initialized by an assignment before it is used. A global variable declaration
must always have an initializer. A new expression can be used with any reference
type that has an implicit initial value.</li>
<li>Postfix increment and decrement statements have been removed.</li>
<li>The <code>...</code> and <code>..&lt;</code> operators have been added for
creating integer ranges; this replaces the foreach statement's special treatment
of integer ranges.</li>
<li>An object type can be declared to be abstract, meaning it cannot be used
with <code>new</code>.</li>
<li>By default,  a record type now allows extra fields other than those
explicitly mentioned; <code>T...</code> requires extra fields to be of type T
and <code>!...</code> disallows extra fields.</li>
<li>In a mapping constructor, an expression can be used for the field name by
enclosing the expression in square brackets (as in ECMAScript).</li>
<li>Integer arithmetic operations are specified to throw an exception on
overflow.</li>
<li>The syntax for documentation strings has changed.</li>
<li>The deprecated construct has been removed (data related to deprecation will
be provided by an annotation; documentation related to deprecation will be part
of the documentation string).</li>
<li>The order of fields, methods and constructors in object types is no longer
constrained.</li>
<li>A function or method can be defined as <code>extern</code>. The
<code>native</code> keyword has been removed.</li>
</ol>
</section>
</section>
<section class="appendix">
<h2 id="planned_future_functionality">C. Planned future functionality</h2>

<p>
The vision for the Ballerina language includes a range of functionality
that is not yet included in this specification.
</p>

<ul>
<li><em>Security</em> will combine language and platform features to make
programs secure by default.</li>
<li><em>Date/time basic types</em> will provide one or more basic types related
to date and time.</li>
<li><em>Event stream processing</em> will build on the <code>stream</code> type
to allow queries over timestamped sequences of events</li>
<li><em>Generic types</em> will provide types that can be instantiated with one
or more type parameters.</li>
<li><em>Flexible message passing</em> will support patterns of communication
between workers/strands, where the number of messages is not fixed and/or
workers are not peers.</li>
<li><em>Long-running processes</em> will allow the execution of a program to be
automatically suspended and then later resumed upon the occurrence of particular
external events.</li>
<li><em>Reliable messaging</em> will allow for sending messages across the
network with some guarantees about reliability.</li>
</ul>

<p>
<a
href="https://github.com/ballerina-platform/ballerina-spec/blob/master/lang/proposals/README.md">Proposals</a>
for new language features relating to this and other functionality are
maintained in the specification's GitHub repository.
</p>

</section>

<section class="appendix">
<h2 id="contributors">D. Other contributors</h2>
<p>
The following contributed to establishing the design principles of the language:
</p>
<ul>
<li>Frank Leymann, <a href="mailto:frank.leymann@iaas.uni-stuttgart.de">frank.leymann@iaas.uni-stuttgart.de</a></li>
<li>Srinath Perera, <a href="mailto:srinath@wso2.com">srinath@wso2.com</a></li>
<li>Kasun Indrasiri, <a href="mailto:kasun@wso2.com">kasun@wso2.com</a></li>
</ul>
<p>
The following also contributed to the language in a variety of ways (in
alphabetical order):
</p>
<ul>
<li>Shafreen Anfar, <a href="mailto:shafreen@wso2.com">shafreen@wso2.com</a></li>
<li>Afkham Azeez, <a href="mailto:azeez@wso2.com">azeez@wso2.com</a></li>
<li>Anjana Fernando, <a href="mailto:anjana@wso2.com">anjana@wso2.com</a></li>
<li>Chanaka Fernando, <a href="mailto:chanakaf@wso2.com">chanakaf@wso2.com</a></li>
<li>Joseph Fonseka, <a href="mailto:joseph@wso2.com">joseph@wso2.com</a></li>
<li>Paul Fremantle, <a href="mailto:paul@wso2.com">paul@wso2.com</a></li>
<li>Antony Hosking, <a href="mailto:antony.hosking@anu.edu.au">antony.hosking@anu.edu.au</a></li>
<li>Tyler Jewell, <a href="mailto:tylerjewell@gmail.com">tylerjewell@gmail.com</a></li>
<li>Anupama Pathirage, <a href="mailto:anupama@wso2.com">anupama@wso2.com</a></li>
<li>Manuranga Perera, <a href="mailto:manu@wso2.com">manu@wso2.com</a></li>
<li>Supun Thilina Sethunga, <a href="mailto:supuns@wso2.com">supuns@wso2.com</a></li>
<li>Sriskandarajah Suhothayan, <a href="mailto:suho@wso2.com">suho@wso2.com</a></li>
<li>Isuru Udana, <a href="mailto:isuruu@wso2.com">isuruu@wso2.com</a></li>
<li>Rajith Lanka Vitharana, <a href="mailto:rajithv@wso2.com">rajithv@wso2.com</a></li>
<li>Mohanadarshan Vivekanandalingam, <a href="mailto:mohan@wso2.com">mohan@wso2.com</a></li>
<li>Lakmal Warusawithana, <a href="mailto:lakmal@wso2.com">lakmal@wso2.com</a></li>
<li>Ayoma Wijethunga, <a href="mailto:ayoma@wso2.com">ayoma@wso2.com</a></li>
</ul>
</section>
</body>
</html>