[spec] Restore *ArrayInitializer*

It was merged with ArrayLiteral in #3215 (oops).

Fixes Bugzilla 24634 - Parse error initializing array from expression with StructInitializer.

Add examples.

Author: ntrel

spec/arrays.dd

@@ -107,16 +107,22 @@ int[]* e;     // pointer to dynamic array of ints
 ---------
 )
 
-$(H2 $(LNAME2 literals, Array Literals))
+$(H2 $(LNAME2 literals, Array Initializers & Literals))
 
+    $(P An $(GLINK ArrayInitializer) initializes a dynamic or static array:)
 ---
 auto a1 = [1,2,3];  // type is int[], with elements 1, 2, and 3
 auto a2 = [1u,2,3]; // type is uint[], with elements 1u, 2u, and 3u
 int[2] a3 = [1,2];  // type is int[2], with elements 1, and 2
 ---
-    $(P `[]` is an empty array literal.)
 
-    $(P See $(DDSUBLINK spec/expression, array_literals, Array Literals).)
+    $(P An $(DDSUBLINK spec/expression, array_literals, array literal) is an expression:)
+---
+void f(int[] a);
+
+f([1, 2]); // pass 2 elements
+f([]); // pass an empty array
+---
 
 $(LEGACY_LNAME2 usage)
 $(H2 $(LNAME2 assignment, Array Assignment))
@@ -1010,8 +1016,23 @@ $(H3 $(LNAME2 void-initialization, Void Initialization))
         $(REF uninitializedArray, std,array).
         )
 
+$(H3 $(LNAME2 array-initializers, Array Initializers))
+
+$(GRAMMAR
+$(GNAME ArrayInitializer):
+    $(D [) $(I ArrayElementInitializers)$(OPT) $(D ])
 
-$(H3 $(LNAME2 static-init-static, Static Initialization of Statically Allocated Arrays))
+$(GNAME ArrayElementInitializers):
+    $(I ArrayElementInitializer)
+    $(I ArrayElementInitializer) $(D ,)
+    $(I ArrayElementInitializer) $(D ,) $(GSELF ArrayElementInitializers)
+
+$(GNAME ArrayElementInitializer):
+    $(GLINK2 declaration, NonVoidInitializer)
+    $(GLINK2 expression, AssignExpression) $(D :) $(GLINK2 declaration, NonVoidInitializer)
+)
+
+$(H4 $(LNAME2 static-init-static, Static Initialization of Statically Allocated Arrays))
 
         $(P Static initalizations are supplied by a list of array
         element values enclosed in `[ ]`. The values can be optionally
@@ -1057,6 +1078,30 @@ assert(a == [42, 42, 42, 42]);
         Otherwise, they need to be marked with $(D const) or $(D static)
         storage classes to make them statically allocated arrays.)
 
+$(H4 $(LNAME2 index-initializers, Index Initializers))
+
+    $(P To initialize an element at a particular index, use the
+        *AssignExpression* `:` *NonVoidInitializer* syntax.
+        The *AssignExpression* must be known at compile-time.
+        Any missing elements will be initialized to the default value
+        of the element type.
+        Note that if the array type is not specified, the array initializer will
+        be parsed as an
+        $(DDSUBLINK spec/expression, associative_array_literals, associative array
+        literal).)
+
+        $(SPEC_RUNNABLE_EXAMPLE_RUN
+        ---
+        int n = 4;
+        auto aa = [0:1, 3:n]; // associative array `int[int]`
+
+        int[] a = [1, 3:n, 5];
+        assert(a == [1, 0, 0, n, 5]);
+
+        //int[] e = [n:2]; // error, n not known at compile-time
+        ---
+        )
+
 
 $(H2 $(LNAME2 special-array, Special Array Types))
 

spec/declaration.dd

@@ -183,26 +183,38 @@ int x, *y;  // x is an int, y is a pointer to int
 int x[], y; // x is an array/pointer, y is an int
 )
 
-$(H2 $(LEGACY_LNAME2 initializers, initialization, Initialization))
+$(H2 $(LNAME2 initialization, Initialization))
+
+        $(P When no *Initializer* is given, a variable is set to the
+        $(DDSUBLINK spec/property, init, default `.init` value) for
+        its type.)
+
+$(H3 $(LNAME2 initializers, Initializers))
 
 $(GRAMMAR
 $(GNAME Initializer):
     $(GLINK VoidInitializer)
     $(GLINK NonVoidInitializer)
 
 $(GNAME NonVoidInitializer):
-    $(GLINK2 expression, AssignExpression)$(LEGACY_LNAME2 ExpInitializer)
-    $(GLINK2 expression, ArrayLiteral)$(LEGACY_LNAME2 ArrayInitializer)
+    $(GLINK2 arrays, ArrayInitializer)$(LEGACY_LNAME2 ArrayInitializer)
     $(GLINK2 struct, StructInitializer)$(LEGACY_LNAME2 StructInitializer)
+    $(GLINK2 expression, AssignExpression)$(LEGACY_LNAME2 ExpInitializer)
 )
 
-        $(P When no *Initializer* is given, a variable is set to the
-        $(DDSUBLINK spec/property, init, default `.init` value) for
-        its type.)
+        $(P A variable can be initialized with a $(I NonVoidInitializer).
+        An *ArrayInitializer* or *StructInitializer* takes precedence over
+        an expression initializer.)
 
-        $(P A variable can be initialized with a $(I NonVoidInitializer).)
+$(SPEC_RUNNABLE_EXAMPLE_COMPILE
+---
+struct S { int i; }
 
-        $(P See also: $(DDSUBLINK spec/arrays, array-initialization, Array Initialization).)
+S s = {}; // struct initializer, not a function literal expression
+S[] a = [{2}]; // array initializer holding a struct initializer
+//a = [{2}]; // invalid array literal expression
+---
+)
 
 $(H3 $(LNAME2 void_init, Void Initialization))
 

spec/expression.dd

@@ -2101,16 +2101,7 @@ $(H3 $(LNAME2 array_literals, Array Literals))
 
 $(GRAMMAR
 $(GNAME ArrayLiteral):
-    $(D [) $(I ArrayMemberInitializations)$(OPT) $(D ])
-
-$(GNAME ArrayMemberInitializations):
-    $(I ArrayMemberInitialization)
-    $(I ArrayMemberInitialization) $(D ,)
-    $(I ArrayMemberInitialization) $(D ,) $(GSELF ArrayMemberInitializations)
-
-$(GNAME ArrayMemberInitialization):
-    $(GLINK2 declaration, NonVoidInitializer)
-    $(GLINK AssignExpression) $(D :) $(GLINK2 declaration, NonVoidInitializer)
+    $(D [) $(GLINK ArgumentList)$(OPT) $(D ])
 )
 
     $(P An array literal is a comma-separated list of expressions
@@ -2162,27 +2153,6 @@ $(GNAME ArrayMemberInitialization):
         }
         ---
 
-    $(P To initialize an element at a particular index, use the
-        *AssignExpression* `:` *NonVoidInitializer* syntax.
-        The *AssignExpression* must be known at compile-time.
-        Any missing elements will be initialized to the default value
-        of the element type.
-        Note that if the array type is not specified, the literal will
-        be parsed as an
-        $(RELATIVE_LINK2 associative_array_literals, associative array).)
-
-        $(SPEC_RUNNABLE_EXAMPLE_RUN
-        ---
-        int n = 4;
-        auto aa = [0:1, 3:n]; // associative array `int[int]`
-
-        int[] a = [1, 3:n, 5];
-        assert(a == [1, 0, 0, n, 5]);
-
-        //int[] e = [n:2]; // error, n not known at compile-time
-        ---
-        )
-
 $(H4 $(LNAME2 cast_array_literal, Casting))
 
     $(P When array literals are cast to another array type, each