diff --git a/doc/TypeScript Language Specification (Change Markup).docx b/doc/TypeScript Language Specification (Change Markup).docx index aa9f495d04e..bb4be4fac1c 100644 Binary files a/doc/TypeScript Language Specification (Change Markup).docx and b/doc/TypeScript Language Specification (Change Markup).docx differ diff --git a/doc/TypeScript Language Specification (Change Markup).pdf b/doc/TypeScript Language Specification (Change Markup).pdf index 6292c8f091a..0cffd20b7c7 100644 Binary files a/doc/TypeScript Language Specification (Change Markup).pdf and b/doc/TypeScript Language Specification (Change Markup).pdf differ diff --git a/doc/TypeScript Language Specification.docx b/doc/TypeScript Language Specification.docx index 93536e02aee..8197adfd119 100644 Binary files a/doc/TypeScript Language Specification.docx and b/doc/TypeScript Language Specification.docx differ diff --git a/doc/TypeScript Language Specification.pdf b/doc/TypeScript Language Specification.pdf index 4a122d9e148..203269c3f24 100644 Binary files a/doc/TypeScript Language Specification.pdf and b/doc/TypeScript Language Specification.pdf differ diff --git a/doc/header.md b/doc/header.md deleted file mode 100644 index 3cf5b569800..00000000000 --- a/doc/header.md +++ /dev/null @@ -1,2 +0,0 @@ -# TypeScript Language Specification - diff --git a/doc/spec.md b/doc/spec.md index 0f26275eb3a..627838d2b14 100644 --- a/doc/spec.md +++ b/doc/spec.md @@ -1349,16 +1349,33 @@ class G { // Introduce type parameter T Types are specified either by referencing their keyword or name, or by writing object type literals, array type literals, tuple type literals, function type literals, constructor type literals, or type queries.   *Type:* +   *PrimaryOrUnionType* +   *FunctionType* +   *ConstructorType* + +  *PrimaryOrUnionType:* +   *PrimaryType* +   *UnionType* + +  *PrimaryType:* +   *ParenthesizedType*    *PredefinedType*    *TypeReference*    *ObjectType*    *ArrayType*    *TupleType* -   *UnionType* -   *FunctionType* -   *ConstructorType*    *TypeQuery* +  *ParenthesizedType:* +   `(` *Type* `)` + +Parentheses are required around union, function, or constructor types when they are used as array element types, and parentheses are required around function or constructor types in union types. For example: + +```TypeScript +(string | number)[] +((x: string) => string) | (x: number) => number) +``` + The different forms of type notations are described in the following sections. ### 3.6.1 Predefined Types @@ -1461,36 +1478,24 @@ The members of an object type literal are specified as a combination of property An array type literal is written as an element type followed by an open and close square bracket.   *ArrayType:* -   *ElementType* *[no LineTerminator here]* `[` `]` - -  *ElementType:* -   *PredefinedType* -   *TypeReference* -   *ObjectType* -   *ArrayType* -   *TupleType* -   *TypeQuery* +   *PrimaryType* *[no LineTerminator here]* `[` `]` An array type literal references an array type (section [3.3.2](#3.3.2)) with the given element type. An array type literal is simply shorthand notation for a reference to the generic interface type 'Array' in the global module with the element type as a type argument. -In order to avoid grammar ambiguities, array type literals permit only a restricted set of notations for the element type. Specifically, an *ArrayType* cannot start with a *UnionType*, *FunctionType* or *ConstructorType*. To use one of those forms for the element type, an array type must be written using the 'Array<T>' notation. For example, the type +When union, function, or constructor types are used as array element types they must be enclosed in parentheses. For example: ```TypeScript -() => string[] +(string | number)[] +(() => string))[] ``` -denotes a function returning a string array, not an array of functions returning string. The latter can be expressed using 'Array<T>' notation +Alternatively, array types can be written using the 'Array<T>' notation. For example, the types above are equivalent to ```TypeScript +Array Array<() => string> ``` -or by writing the element type as an object type literal - -```TypeScript -{ (): string }[] -``` - ### 3.6.5 Tuple Type Literals A tuple type literal is written as a sequence of element types, separated by commas and enclosed in square brackets. @@ -1512,28 +1517,22 @@ A tuple type literal references a tuple type (section [3.3.3](#3.3.3)). A union type literal is written as a sequence of types separated by vertical bars.   *UnionType:* -   *ElementType* `|` *UnionOrElementType* - -  *UnionOrElementType:* -   *UnionType* -   *ElementType* +   *PrimaryOrUnionType* `|` *PrimaryType* A union typle literal references a union type (section [3.3.4](#3.3.4)). -In order to avoid grammar ambiguities, union type literals permit only a restricted set of notations for the element types. Specifically, an element of a *UnionType* cannot be written as a *FunctionType* or *ConstructorType*. To include function or constructor types in a union type the function or constructor types must be written as object type literals. For example +When function or constructor types are included in union types they must be enclosed in parentheses. For example: ```TypeScript -() => string | () => number +((x: string) => string) | ((x: number) => number) ``` -denotes a function whose return value is either a string or a function returning number, whereas +Alternatively, function or constructor types in union types can be written using object literals: ```TypeScript -{ (): string } | { (): number } +{ (x: string): string } | { (x: number): number } ``` -denotes either a function returning string or a function returning number. - ### 3.6.7 Function Type Literals A function type literal specifies the type parameters, regular parameters, and return type of a call signature. @@ -2221,8 +2220,8 @@ The resulting type an array literal expression is determined as follows: The rules above mean that an array literal is always of an array type, unless it is contextually typed by a type with numerically named properties (such as a tuple type). For example ```TypeScript -var a = [1, 2]; // Array -var b = ["hello", true]; // Array +var a = [1, 2]; // number[] +var b = ["hello", true]; // (string | boolean)[] var c: [number, string] = [3, "three"]; // [number, string] ``` @@ -5170,16 +5169,26 @@ This appendix contains a summary of the grammar found in the main document. As d    *Type*   *Type:* +   *PrimaryOrUnionType* +   *FunctionType* +   *ConstructorType* + +  *PrimaryOrUnionType:* +   *PrimaryType* +   *UnionType* + +  *PrimaryType:* +   *ParenthesizedType*    *PredefinedType*    *TypeReference*    *ObjectType*    *ArrayType*    *TupleType* -   *UnionType* -   *FunctionType* -   *ConstructorType*    *TypeQuery* +  *ParenthesizedType:* +   `(` *Type* `)` +   *PredefinedType:*    `any`    `number` @@ -5216,15 +5225,7 @@ This appendix contains a summary of the grammar found in the main document. As d    *MethodSignature*   *ArrayType:* -   *ElementType* *[no LineTerminator here]* `[` `]` - -  *ElementType:* -   *PredefinedType* -   *TypeReference* -   *ObjectType* -   *ArrayType* -   *TupleType* -   *TypeQuery* +   *PrimaryType* *[no LineTerminator here]* `[` `]`   *TupleType:*    `[` *TupleElementTypes* `]` @@ -5237,11 +5238,7 @@ This appendix contains a summary of the grammar found in the main document. As d    *Type*   *UnionType:* -   *ElementType* `|` *UnionOrElementType* - -  *UnionOrElementType:* -   *UnionType* -   *ElementType* +   *PrimaryOrUnionType* `|` *PrimaryType*   *FunctionType:*    *TypeParametersopt* `(` *ParameterListopt* `)` `=>` *Type*