Union types

spec.md

@@ -60,12 +60,14 @@ interact with the environment.
     * [Bytes literals](#bytes-literals)
     * [Special tokens](#special-tokens)
   * [Data types](#data-types)
+    * [object](#object)
     * [None](#none)
     * [Booleans](#booleans)
     * [Integers](#integers)
     * [Floating-point numbers](#floating-point-numbers)
     * [Strings](#strings)
     * [Bytes](#bytes)
+    * [Unions](#unions)
     * [Lists](#lists)
     * [Tuples](#tuples)
     * [Dictionaries](#dictionaries)
@@ -538,12 +540,14 @@ TODO: define indent, outdent, semicolon, newline, eof
 These are the main data types built in to the interpreter:
 
 ```text
+object                 # the parent type of all Stalark values
 None                   # the type of None
 bool                   # True or False
 int                    # a signed integer of arbitrary magnitude
 float                  # an IEEE 754 double-precision floating-point number
 str                    # a text string, with Unicode encoded as UTF-8 or UTF-16
 bytes                  # a byte string
+A|B                    # A union type
 <!-- TODO: re-review collections and function types when this TODO is removed -->
 list[E]                # a fixed-length sequence of values
 tuple[A,B,...]         # a fixed-length sequence of values, unmodifiable
@@ -559,18 +563,21 @@ which the interpreter is embedded, and those data types may
 participate in basic operations of the language such as arithmetic,
 comparison, indexing, and function calls.
 
-<!-- We needn't mention the stringIterable type here. -->
-
-Some operations can be applied to any Starlark value.  For example,
-every value has a type string that can be obtained with the expression
-`type(x)`, and any value may be converted to a string using the
-expression `str(x)`, or to a Boolean truth value using the expression
-`bool(x)`.  Other operations apply only to certain types.  For
+Other operations apply only to certain types.  For
 example, the indexing operation `a[i]` works only with strings, bytes values, lists,
 and tuples, and any application-defined types that are _indexable_.
 The [_value concepts_](#value-concepts) section explains the groupings of
 types by the operators they support.
 
+<!-- We needn't mention the stringIterable type here. -->
+
+### object
+
+Some operations can be applied to any Starlark value. For example,
+every value has a type string that can be obtained with the expression
+`type(x)`, and any value may be converted to a string using the
+expression `str(x)`, or to a Boolean truth value using the expression
+`bool(x)`.
 
 ### None
 
@@ -871,6 +878,14 @@ TODO: ord, chr.
 TODO: string.elems(), string.elem_ords(), string.codepoint_ords()
 ```
 
+### Unions
+
+Some functions may accept parameters of multiple types. In this
+case parameter is annotated with a union type `A|B`.
+
+User functions are limited to optional types, that is `None|A`,
+where `A` is another type.
+
 ### Lists
 
 A list is a mutable sequence of values.
@@ -3224,6 +3239,8 @@ If the iterable is empty, it returns `True`.
 
 ### bool
 
+`bool(x: object, /) -> bool`
+
 `bool(x)` interprets `x` as a Boolean value---`True` or `False`.
 With no argument, `bool()` returns `False`.
 
@@ -3333,6 +3350,8 @@ See https://github.com/bazelbuild/starlark/issues/47.
 
 ### float
 
+`float(x: str|bool|int|float, /) -> float`
+
 `float(x)` interprets its argument as a floating-point number.
 
 If x is a `float`, the result is x.
@@ -3354,6 +3373,8 @@ With no argument, `float()` returns `0.0`.
 
 ### getattr
 
+`getattr(x: object, name: str, default: object = Unbound, /) -> Any`
+
 `getattr(x, name[, default])` returns the value of the attribute (field or method) of x named `name`
 if it exists. If not, it either returns `default` (if specified) or raises an error.
 
@@ -3369,6 +3390,8 @@ provided `default` value instead of failing.
 
 ### hasattr
 
+`hasattr(x: object, name: str, /) -> bool`
+
 `hasattr(x, name)` reports whether x has an attribute (field or method) named `name`.
 
 ### hash
@@ -3392,6 +3415,8 @@ s[0]*31^(n-1) + s[1]*31^(n-2) + ... + s[n-1]
 
 ### int
 
+`int(x: str|bool|int|float, /, base: int = 10) -> int`
+
 `int(x[, base])` interprets its argument as an integer.
 
 If `x` is an `int`, the result is `x`.
@@ -3544,6 +3569,8 @@ number.
 
 ### repr
 
+`repr: (x: object, /) -> str`
+
 `repr(x)` formats its argument as a string.
 
 All strings in the result are double-quoted.
@@ -3614,6 +3641,8 @@ sorted(["two", "three", "four"], key=len, reverse=True)    # ["three", "four", "
 
 ### str
 
+`str(x: object, /) -> str`
+
 `str(x)` formats its argument as a string.
 
 If x is a string, the result is x (without quotation).
@@ -3639,6 +3668,8 @@ With no arguments, `tuple()` returns the empty tuple.
 
 ### type
 
+`type(x: object, /) -> str`
+
 `type(x)` returns a string describing the type of its operand.
 
 The returned description of the type is following: