4.2.1White Space

Whitespace separates tokens and improves the legibility of the source text. TypeLang does not distinguish between horizontal whitespace and line terminators, and a Comment stands wherever whitespace stands, save for the one place the presence of the whitespace itself is read (see Ignored Tokens).

4.2.2Comments

A TypeLang source document MAY contain comments. A line comment begins with either the // or # marker and continues up to, but not including, the next LineTerminator (or the end of the source, whichever occurs first). A block comment begins with /* and continues up to and including the next */.

Comments are Ignored and have no bearing on the meaning of a document.

4.3.1Punctuators

TypeLang documents use punctuation to describe structure. Several punctuators share a leading character (for example, : and ::; . in ...); in every such case, the longest matching punctuator is taken.

4.3.2Names

A NameToken is the raw lexical unit that is later assembled, together with the namespace separator, into the syntactic Name production (see Names and Namespaces); the two are distinct non-terminals of, respectively, the lexical and the syntactic grammar. A NameToken MUST begin with a Letter or an underscore (_) and MAY continue with any Letter, Digit, underscore, or dash (-). The only difference from the PHP identifier grammar is that the dash character is additionally permitted in any non-leading position.

A source text is read as a sequence of bytes rather than of codepoints, and every byte of a character outside of ASCII falls in the 0x80 to 0xFF range a Letter covers. A name MAY therefore be written in any script.

Проект\Тип

A NameToken is always the longest possible valid sequence; it MUST NOT be followed by a NameContinue character.

ExampleTypeName

Dashes are accepted in any non-leading position, which is what makes built-in type names such as non-empty-string and array-key expressible:

non-empty-string

The reserved words true, false and null are also valid as a fragment of a NameToken, provided the NameToken is not equal to one of those reserved words on its own (see Reserved Words):

true-type

Counter-example. A NameToken cannot begin with a Digit or a dash.

Counter Example № 142type

ParseException: Syntax error, unexpected "type"

4.3.3Reserved Words

The words true, false and null are literal keywords (see Literal Tokens), and is and not are the conditional operator keywords (see Conditional Types). Each is matched only when not immediately followed by a NameContinue character. The three literal keywords are matched case-insensitively, while is and not are matched the one way they are spelled.

Wherever the source contains one of these words, it is scanned as the corresponding literal or operator token and MUST NOT be scanned as a NameToken. It remains an Identifier all the same (see Names and Namespaces), so a reserved word is shadowed rather than forbidden: it stands as a name wherever the token it is scanned as denotes no type of its own.

A literal keyword standing alone, in a position where a type is expected, is read as the LiteralType it denotes and not as the NamedType it would otherwise be (see Primary Types):

TrUe

Behind a namespace separator or another segment, where no literal is expected, the same word is a name segment. This makes \true a reference to a type literally named true, distinct from the true literal:

\true

The conditional operator keywords denote no type of their own, so nothing shadows them, and a bare is or not is an ordinary named type:

not

4.3.4Variable

A Variable token begins with a dollar sign ($) followed by a sequence matching the body of a NameToken, save for the dash a variable cannot carry. Variables are used to name callable parameters (see Callable Types) and as operands in conditional types (see Conditional Types).

The special variable $this is recognised as a distinct token and additionally denotes the current object type when used as a primary type (see Primary Types).

4.4.1Boolean

The case-insensitive words true and false denote the two values of the PHP bool type. Case is not significant: true, TRUE and TruE all denote the same value.

4.4.2Null

The case-insensitive word null denotes the PHP null value. As with booleans, case is not significant.

4.4.3Integer

An integer literal denotes a value of the PHP int type. Binary, octal, decimal and hexadecimal radixes are supported, each optionally prefixed with a Sign. A NegativeSign makes the denoted value negative; a leading + denotes the same value the absence of a Sign does. Underscores (DigitSeparator) MAY appear as visual separators; they carry no meaning and do not affect the denoted value. A DigitSeparator MUST stand between two digits, and therefore may neither lead a run of digits, nor trail one, nor stand beside another DigitSeparator.

Decimal. A decimal literal other than a lone 0 MUST NOT begin with a zero, which is the mark of an OctalIntLiteral.

1_000_000

Binary. Prefixed with 0b or 0B; digits are 0 and 1 only.

0b1010_1101

Octal. Prefixed with 0o or 0O or, as octal has been written since long before that prefix, with a leading 0 alone; digits are 0 through 7 only. A 0123 denotes the same value a 0o123 does.

0o42

04_23

Counter-example. A leading zero makes a literal an octal, so a digit outside the octal radix may not follow one.

Counter Example № 208

ParseException: Syntax error, unexpected "8"

Hexadecimal. Prefixed with 0x or 0X; digits are 0 through 9 and a through f, in either case.

0xDEAD_BEEF

Counter-example. A radix may only contain digits valid for that radix.

Counter Example № 30b101042

ParseException: Syntax error, unexpected "42"

4.4.4Float

A floating-point literal denotes a value of the PHP float type. It MUST contain either a decimal point or an exponent, or both, and MAY be prefixed with a Sign.

Either the leading run of digits (before the decimal point) or the trailing run (after it) MAY be omitted, but not both:

0.9

.9

1.

Scientific notation uses the case-insensitive e indicator followed by a decimal exponent, which takes a Sign of its own:

10e-2

10e+2

Every run of digits a float is written of accepts the DigitSeparator under the same rule an integer does, and, unlike a DecimalIntLiteral, MAY begin with a zero:

2_3.4_5e-6_7

Counter-example. A lone decimal point is not a valid float.

Counter Example № 4.

ParseException: Syntax error, unexpected "."

4.4.5String

A string literal denotes a value of the PHP string type. Strings are delimited by single (') or double (") quotes. A delimiter, and the backslash itself, may be escaped by a preceding backslash.

'I am a single-quoted string with an escaped \' quote'

"I am a double-quoted string with an escaped \" quote"

The two forms differ in how they treat backslash escapes. A single-quoted string MUST be interpreted verbatim: the only meaningful escapes are \' and \\, and every other backslash MUST be preserved literally. A double-quoted string MUST interpret the full set of EscapeSequence productions described below.

5.3.1Union Types

A union type is a sequence of two or more member types separated by the pipe character (|). It denotes a value that satisfies at least one of its members.

A | B | C

5.3.2Intersection Types

An intersection type is a sequence of two or more member types separated by the ampersand character (&). It denotes a value that simultaneously satisfies every member.

A & B & C

Because intersection binds more tightly than union, the two constructors may be combined to express disjunctive and conjunctive normal forms, with parentheses used for the opposite grouping:

(A & B) | C

(A | B) & C

5.3.3Nullable Types

A nullable type is written with a leading question mark (?) and is shorthand for the union of its operand with null; that is, ?T denotes the same set of values as T | null.

?Example

Counter-example. The question mark must precede the type; a trailing question mark is not a nullable type.

Counter Example № 5Example?

ParseException: Syntax error, unexpected "?"

5.4.1List Syntax

An empty pair of square brackets ([]) forms the legacy list (array) syntax. It is equivalent to wrapping the operand in a list, and may be repeated to describe nested lists.

User[]

User[][]

The legacy list syntax accepts no key type between the brackets; for that, use offset access or the modern array<…> generic. A User[int] is a well-formed document all the same — an offset access type (see below) rather than a list, since int is a valid Type. It is the absence of a type between the brackets that selects the list reading:

User[int]

5.4.2Offset Access

A pair of square brackets enclosing a Type forms an offset access type, which denotes the type of the element addressed by that offset within the operand (typically a shape or an array).

T['offset']

T[U]

array{int, string}[0]

Because the offset is itself an arbitrary Type, any type — including objects, shapes, or conditional types — MAY be used as a key:

T<U>[object{key: int, ...}]

Counter-example. Each offset is enclosed in a single pair of brackets.

Counter Example № 6Collection[[Some]]

ParseException: Syntax error, unexpected "["

5.8.1Template Argument Hints

A template argument MAY carry a single leading hint: a NameToken placed before the argument’s type. Hints are used by tooling — for example, to express call-site variance with identifiers such as in, out, covariant, or contravariant.

HashMap<array-key, covariant Request>

At the lexical level, Whitespace MUST stand directly behind the hint; this separation is what distinguishes a hint from the start of the argument’s own type, and a Comment does not stand in its place (see Ignored Tokens). Each argument may carry at most one hint.

Counter-example. A hint is a single NameToken. A second one reads as the bound of a template parameter, and a parameter list belongs to a callable, so the statement is refused where the ( it would go on with is missing.

Counter Example № 9HashMap<array-key, some covariant Request>

ParseException: Syntax error, unexpected end of input

Counter-example. A hint cannot be a reserved word: true, false, null, is and not are always scanned as the corresponding literal or operator token (see Reserved Words) and never as a NameToken.

Counter Example № 10HashMap<is Request>

ParseException: Syntax error, unexpected ">"

5.10.1Global Constants

Syntactically, an unqualified reference to a global constant is indistinguishable from, and MUST be parsed as, an ordinary named type (see Primary Types):

JSON_THROW_ON_ERROR

pcov\version

Whether a given NamedType denotes a global constant, a class, an interface, or something else entirely is a semantic concern that this specification leaves to the implementation.

5.10.2Class Constants

A reference to a class constant is a Name (the class), the :: separator, and an Identifier (the constant). The constant segment is a single identifier and cannot itself be namespaced.

ClassName::CONSTANT_NAME

Path\To\ClassName::ANOTHER_CONSTANT_NAME

Counter-example. The constant part may not contain a namespace separator.

Counter Example № 11ClassName::SOME\ANY

ParseException: Syntax error, unexpected "\"

5.10.3Constant Masks

A constant mask denotes a family of constants whose names are written of the same segments, in the same order, with a Wildcard standing wherever the name is left unsaid. A mask MUST contain at least one Wildcard, and its segments and wildcards alternate, so two wildcards in a row denote nothing a single one does not.

A global constant mask matches every global constant the segments describe:

JSON_*

The name of a global constant MAY be left unsaid from its very beginning, and the namespace it belongs to MAY be written in front of it. A Name standing in front of a MaskTail carries the namespace and, in its last segment, the leading segment of the mask; a Name separated from the mask by a \ is a namespace whole, and the mask then matches every constant that namespace holds:

*_SUFFIX

Path\To\JSON_*

Path\To\*

A class constant mask matches every constant of a class the segments describe; the leading segment MAY be omitted entirely, in which case the mask matches every constant of the class:

Path\To\ClassName::PREFIX_*

Path\To\ClassName::*_SUFFIX

Path\To\ClassName::PREFIX_*_SUFFIX

Path\To\ClassName::*

Counter-example. A global mask must have at least one segment of a name, whether it stands in front of a wildcard or behind it; a lone asterisk, which would match every constant there is, is not a type.

Counter Example № 12*

ParseException: Syntax error, unexpected end of input

Counter-example. Two wildcards in a row are not a mask.

Counter Example № 13Path\To\ClassName::PREFIX_**

ParseException: Syntax error, unexpected "*"

6.1.1Shape Fields

A shape field is either explicit (a key, a colon, and a value type) or implicit (a value type alone, whose key is assigned positionally). A shape key may be a bare identifier, an integer literal, a string literal, or a constant reference — that is, a ClassConstant or a ConstantMask.

array{ name: First, count: Second }

array{ 1: First, 42: Second }

array{ "name-some": First, "escape\nchars": Second }

array{ First, Second }

array{ Path\To\ClassName::CONSTANT_NAME: First, JSON_*: Second }

Mixed keys are not permitted. A single shape MUST use either explicit keys throughout or implicit keys throughout.

Counter Example № 14array{ named: First, Second }

ParseException: Cannot mix explicit and implicit shape keys

Duplicate explicit keys are not permitted. No two explicit fields of the same shape may denote the same key, regardless of which of the five key forms each uses.

Counter Example № 15array{ 1: int, 2: int, 1: string }

ParseException: Duplicate key "1"

6.1.2Optional Fields

An explicit field MAY be marked optional by placing a question mark before the colon. An optional key (key?: Type) states that the field may be absent; this is distinct from an optional value (key: ?Type), which states that the field is always present but its value may be null.

array{ key?: Type }

array{ key: ?Type }

6.1.3Unsealed Shapes

By default, a shape is sealed: it describes its container exactly, and no additional elements are permitted. A trailing ellipsis (...) makes the shape unsealed, allowing elements beyond those listed.

array{ key: Type, ... }

An unsealed shape MAY also stand alone, describing a container constrained only by its (absent) field list:

array{ ... }

An unsealed marker MAY carry template arguments that describe the type of the additional elements — and, optionally, of their keys — using the same angle-bracket syntax as generics:

array{ user: User, ...<string, object> }

6.2.1Template Parameters

A callable type MAY declare the template parameters it introduces, written as a <...> list between the name and the parameter list. Each parameter is an Identifier followed by as many bounds as are put on it.

A parameter accepts three kinds of limit, each of which MUST be written at most once. The two bounds MAY be written in either order, while a TemplateDefault MUST be written last: a bound standing behind it belongs to the Type of the default rather than to the parameter.

• An UpperBound narrows the parameter from above: the argument is to be a subtype of the given Type. Its two operators denote the same thing, and a conforming implementation MUST retain the one that was written.
• A LowerBound bounds the parameter from below: the argument is to be a supertype of the given Type.
• A TemplateDefault is the Type the parameter takes when no argument is supplied. It bounds nothing.

Each operator is matched the one way it is spelled, so an OF bounds nothing an of does.

callable<T>(T): T

callable<T of Some>(T): T

Closure<T of Some, U super Any, V = int>(T, U): V

callable<T of Some super Any = int>(T): void

Counter-example. A word that bounds nothing is not an operator.

Counter Example № 16callable<T whatever Some>(): void

ParseException: Template parameter cannot be bounded with "whatever", expected one of "of", "as" or "super"

Counter-example. Neither is a word that is spelled the way an operator is spelled, but written in a case of its own.

Counter Example № 17callable<T OF Some>(): void

ParseException: Template parameter cannot be bounded with "OF", expected one of "of", "as" or "super"

Counter-example. Each kind of limit is written at most once.

Counter Example № 18callable<T of Some as Any>(): void

ParseException: Template parameter cannot have more than one upper bound

Counter-example. A bound does not stand behind a default.

Counter Example № 19callable<T = int of Some>(): void

ParseException: Template parameter default must be written last, since a bound behind it reads as a bound of the default itself

A <...> list is written the same way whether it declares template parameters or supplies template arguments, and only the ( that follows a parameter list tells them apart. A list that no ( follows is therefore a list of template arguments, which describes no bounds.

Counter-example. Bounds belong to a callable alone.

Counter Example № 20Collection<T of Some>

ParseException: Syntax error, unexpected end of input

6.2.2Callable Parameters

A parameter is described by its type, optionally followed by the reference and the variadic markers, by a name and by the default marker — in that order and in no other. The type is the only required part.

callable(Type)

callable(Type $name)

Counter-example. A parameter given by name alone, without a type, is not permitted.

Counter Example № 21callable($name)

ParseException: Syntax error, unexpected ")"

Named Parameters. A name beginning with $ MAY follow the parameter’s type, permitting the argument to be passed by name, exactly as in PHP.

callable(A $a, B, C)

Output Parameters. An ampersand (&) placed after the parameter type marks the parameter as passed by reference (an output parameter).

callable(T&)

callable(T &$name)

Counter-example. The ampersand must follow the type; it must not precede it.

Counter Example № 22callable(&T)

ParseException: Syntax error, unexpected "&"

Optional Parameters. A trailing = marks a parameter as optional: the caller MAY omit the corresponding argument.

callable(T=)

callable(T &$name=)

Variadic Parameters. An ellipsis (...) placed after the parameter type marks the parameter as variadic. Where a parameter carries both markers, the ampersand comes first.

callable(T ...$name)

callable(T &...$name)

Counter-example. The ellipsis must follow the type; it must not precede it.

Counter Example № 23callable(...T)

ParseException: Syntax error, unexpected "..."

Counter-example. A variadic parameter is already optional and therefore must not additionally carry a default marker.

Counter Example № 24callable(T ...$name=)

ParseException: Cannot have variadic param with a default