Lexically scoped child resources

Fixes: Azure#1363

This change add support for lexical scoping/nesting of child resources.
That it, for a resource type: `My.RP/someType@2020-01-01` there's now a
simplified syntax for including a resource:
`My.RP/someType/childType@2020-01-01` inside the body of the parent.

This syntax also allows simplication of the type name of the child,
limits its scope/visibility and implies an automatic `dependsOn` to the
parent resource. The goal is to be the most idiomatic way to declare
multiple resources to be deployed with a parent/child/grandchild/etc
relationship.

This also includes the new "nested resource access" operator which
allows lookup of a nested resource:

```
output someOutput string = parent:child.properties.size
``

docs/spec/expressions.md

@@ -6,7 +6,7 @@ The operators below are listed in descending order of precedence (the higher the
 
 | Symbol | Type of Operation | Associativity |
 |:-|:-|:-|
-| `(` `)` `[` `]` `.` | Parentheses, property accessors and array indexers | Left to right |
+| `(` `)` `[` `]` `.` `:` | Parentheses, array indexers, property accessors, and nested-resource accessor  | Left to right |
 | `!` `-` | Unary | Right to left |
 | `%` `*` `/` | Multiplicative | Left to right |
 | `+` `-` | Additive | Left to right |
@@ -106,6 +106,27 @@ Given the above declaration, the expression `x.y.z` would evaluate to the litera
 
 Property accessors can be used with any object. This includes parameters and variables of object types and object literals. Using a property accessor on an expression of non-object type is an error.
 
+## Nested resource accessors
+Nested resource accessors are used to access resources that are declared inside another resource. Only top-level resources are considered top-level declarations.  
+
+```
+resource myParent 'My.Rp/parentType@2020-01-01' = {
+  name: 'myParent'
+  location: 'West US'
+
+  // declares a nested resource inside 'myParent'
+  resource myChild 'childType' = {
+    name: 'myChild'
+    properties: {
+      displayName: 'Child Resource'
+    }
+  }
+}
+
+// using nested resource access to access a property of a nested resource
+output displayName string = myParent:myChild.properties.displayName
+```
+
 ## Array indexers
 Array indexers serve two purposes. Most commonly, they are used to access items in an array. However, they can also be used to access properties of objects via expressions or string literals.
 

docs/spec/resources.md

@@ -42,6 +42,29 @@ resource dnsZone 'Microsoft.Network/dnszones@2018-05-01' = {
 }
 ```
 
+## Resource nesting
+
+A resource declaration may appear inside another resource declaration when the inner resource is a child type of the other type.
+
+```
+resource myParent 'My.Rp/parentType@2020-01-01' = {
+  name: 'myParent'
+  location: 'West US'
+
+  // declares a resource of type 'My.Rp/parentType/childType@2020-01-01' 
+  resource myChild 'childType' = {
+    name: 'myChild'
+    properties: {
+      displayName: 'child in ${parent.location}'
+    }
+  }
+}
+```
+
+When used in this form the nested declaration must use a simple `name` with a single segment.
+
+A nested resource declaration must appear at the top level of syntax of the containing resource. Declarations may be nested arbirarily deep, as long as each level is a child type of its containing resource. A nested resource may access properties of its containing resource. A containing resource may not access properties of the resources it contains, this would cause a cyclic-dependency.
+
 ## Resource dependencies
 All declared resources will be deployed concurrently in the compiled template. Order of resource deployment can be influenced in the following ways:
 ### Explicit dependency
@@ -78,6 +101,20 @@ resource otherResource 'Microsoft.Example/examples@2020-06-01' = {
 }
 ```
 
+A nested resource has an implicit dependency on its containing resource.
+
+```
+resource myParent 'My.Rp/parentType@2020-01-01' = {
+  name: 'myParent'
+  location: 'West US'
+
+  // depends on 'myParent' implicitly
+  resource myChild 'childType' = {
+    name: 'myChild'
+  }
+}
+```
+
 ## Conditions
 
 > Requires Bicep CLI v0.2.212 or later