From 0bb6afdf72ee0ff7ee5f908729731b780c95b5c9 Mon Sep 17 00:00:00 2001
From: James Clark
Every value has a read-only bit. If the read-only bit is set, it means that the
value is not mutable. A value's read-only bit cannot be changed after the value
-is constructed. Some basic types are inherently immutable: the read-only bit is
-always set for a value that belongs to an inherently immutable basic type. All
-simple types are inherently immutable. Other 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 set and values that do not have
-the read-only bit set. All structured types are selectively immutable. Finally,
-some basic types are inherently mutable: the read-only bit is never set for a
-value belonging to an inherently mutable basic type.
+is constructed. Immutability is deep: the values contained in a structured value
+that has its read-only bit set will all have their read-only bits set. Some
+basic types are inherently immutable: the read-only bit is always set for a
+value that belongs to an inherently immutable basic type. All simple types are
+inherently immutable. Other 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 set and values that do not have the read-only bit
+set. All structured types are selectively immutable. Finally, some basic types
+are inherently mutable: the read-only bit is never set for a value belonging to
+an inherently mutable basic type.
A shape is divided into two aspects: the primary aspect and
the read-only aspect. A value's read-only bit is a part of the
read-only aspect of the value's shape. The read-only bit of values
contained in a structured value is part of the read-only aspect of those values
-and of the read-only aspectof the structured value. Everything about a shape
+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.
@@ -620,6 +622,13 @@
+Type descriptors other than
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
@@ -709,6 +718,9 @@ Type system fundamentals
Type descriptors
readonly
describes types using only the
+primary aspect of shape: whether a value belongs to the type is not affected by
+the read-only aspect of the value's shape. The readonly
type uses
+only the read-only aspect: whether a value belongs to the readonly
+type depends only on the read-only aspect of the value's shape.
+Simple values
The type descriptor for each simple basic type contains all the values of the
basic type.
+All simple basic types are inherently immutable. +
simple-type-descriptor := @@ -1017,7 +1029,7 @@XML
The name of an element is represented by a string. The attributes of an element -are represented by a value of type
map<string>
. The content +are represented by a value of typemap<string>
. The children of an element is represented by a value of typexml
.@@ -1025,15 +1037,15 @@
XML
identity. Other xml values do not.-An xml value is immutable if and only if all its constituent singletons are -immutable. A text singleton is inherently immutable, since it does not have -storage identity. The other singleton types are usually mutable, but can be -constructed as immutable in two ways. First, an xml value constructed by a -compile-time constant expression is immutable. Second, an immutable, deep copy -can be made of a structure by using the ImmutableClone abstract operation. Element -immutability is deep: the content of an immutable XML element is always -immutable. +The
xml:Text
type is inherently immutable. This implies that both +text singletons and empty xml values always have their read-only bits set. The +xml:Element
,xml:ProcessingInstruction
and +xml:Comment
types are selectively immutable. The read-only bit of a +xml value with length greater than one is set if and only if the read-only bit +of all its constituent items is set. Immutability of xml values is deep: if the +read-only bit anxml:Element
is set, then the read-only bits of the +mapping representing its attributes and of the xml value representing its +children are also set.Note that although the mutable constituents of mutable xml value can be mutated, @@ -1144,38 +1156,32 @@
XML namespaces
Structured values
-There are three basic types of structured value: list, mapping and table. -
--A structured value is either mutable or immutable; whether it is mutable or -immutable is fixed when the value is constructed and cannot be changed -thereafter. Immutability is deep: an immutable structured value cannot refer to -a mutable structured value. The error basic type is inherently immutable: a -value of the error basic type is always immutable. Structured values of other -basic types are usually mutable, but can be constructed as immutable in two -ways. First, a structural value constructed by a compile-time constant -expression is always immutable. Second, an immutable, deep copy can be made of a -structure by using the ImmutableClone abstract -operation. +Structured values are containers for other values, which are called their +members. 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. There are three basic +types of structured value: list, mapping and table.
-Values of the container basic types are containers for other values, which are -called their members. The shape of the members of a container value contribute -to the shape of the container. Mutating a member of a container can thus cause -the shape of the container to change. +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 set, then the +read-only bit of each of its members is set.
-A type descriptor for a container basic type describe the shape of the container -in terms of the shapes of its members. A container has an inherent type, which -is a type descriptor which is part of the container's runtime value. At runtime, -the container prevents any mutation that might lead to the container having a -shape that is not a member of its inherent type. Thus a container value belongs -to a type if and only if that its inherent type is a subtype of that type. +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 values'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 that its inherent type is a +subtype of that type.
-The inherent type of an immutable container is a singleton type with the -container's shape as its single member. Thus, an immutable container value -belongs to a type if and only if the type contains the shape of the value. +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.
Each member of a container has a key that uniquely identifies it within the @@ -1346,7 +1352,6 @@
Mappings
sequence is implementation-dependent, but implementations are encouraged to preserve and use the order in which the fields were added. -The type of mapping values can be described by two kinds of type descriptors.
@@ -1577,9 +1582,11 @@Error
inferred-error-type-param :=*
-An error value belongs to the error basic type, which is used only for -representing errors. The error type is inherently immutable. An error value -contains the following information: +An error value is used to represent an error. Errors are a distinct basic type: +a value belongs to the error basic type if and only if it is an error. This +means that errors are clearly distinguished from other values. Many constructs +in Ballerina give special treatment to error values. The error type is +inherently immutable. An error value contains the following information:
ImmutableClone(v) is defined for any value v that belongs to the type
anydata|readonly
. It performs a deep copy of v similar to Clone(v),
-except that newly constructed values are constructed as immutable. Any immutable
-value is not copied.
+except that newly constructed values will be constructed as immutable and so
+have their read-only bit set. Any immutable value is not copied. So the result
+of Immutable always has its read-only bit set.
Like Clone, ImmutableClone must preserve graph structure, including cycles. @@ -3267,7 +3275,7 @@
In most cases, the precise type and the broad type of an expression are the @@ -3340,6 +3348,10 @@
(
const-expr )
+A value resulting from the evaluation of a const-expr
always has
+its read-only bit set.
+
Within a const-expr
, any nested expression must also be a
const-expr. A functional-constructor-expr
within a
const-expr
must not construct an error value.
@@ -3480,6 +3492,10 @@
+An list-constructor-expr occurring within a const-expr will construct a list value +that has its read-only bit set. +
+An mapping-constructor-expr occurring within a const-expr will construct a mapping value +that has its read-only bit set. +
+A table-constructor-expr occurring within a const-expr will construct a table +value that has its read-only bit set. +
+xml
BacktickString
-An XML template expression creates an xml value as follows: +An XML template expression constructs an xml value as follows:
+An xml-template-expr occurring within a const-expr will construct an xml value +that has its read-only bit set. +
-A member-access-expr accesses a member of a container value using its key, +A member-access-expr accesses a member of a structured value using its key, or a constituent of a sequence value using its index.
-The requirements on the static type of container-expr and key-expression are as +The requirements on the static type of container-expression and key-expression are as follows:
+A functional-constructor-expr occurring within a const-expr will construct a +value with its read-only bit set. +
-The type-descriptor
provides the contextually expected type for
-expression
.
+The contextually expected type for expression
is the intersection
+of the contextually expected type of the type-cast-expr
and the
+type described by the type-descriptor
.
+Note that a type-cast-expr
of <readonly>
can be
+used both to cause constructors withing the expression
to construct
+values with the read-only bit set and to verify that the value resulting from
+the evaluation of expression
has its read-only bit set.
+
-The type of the constant is 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.
+The type of the constant is the intersection of readonly
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.
If type-descriptor is present, then it provides the contextually expected type