design/mvp/WORLD.md

@@ -1,26 +1,26 @@
 # The `*.world` format
 
-This is intended to document the `*.world` format as it currently exists. The goal is to provide an overview to understand what features `world` files give you and how they're structured. This isn't intended to be a formal grammar, although it's expected that one day we'll have a formal grammar for `*.world` files.
+This is intended to document the `*.world` format. The goal is to provide an overview to understand what features `world` files give you and how they're structured. This isn't intended to be a formal grammar, although it's expected that one day we'll have a formal grammar for `*.world` files.
 
-Conceptually `world` documents act as a contract between runtimes and components. I.e., hosts implement worlds and components target them.
+The `*.world` format is a way to define the contract between runtimes and components. I.e., hosts implement worlds and components target them. Furthermore, the examples in this document should be read from the perspective of a component targeting a world implemented by a host unless otherwise noted.
 
 ## Lexical structure
 
 > TODO: Mention lexical additions relative to WIT.md
 
 ## Top-level items
 
-A `world` document is a sequence of items specified at the top level. These items come one after another and it's recommended to separate them with newlines for readability but this isn't required.
+A `world` document is a sequence of items specified at the top level. These items come one after another and it's recommended to separate them with newlines for readability but  this isn't required.
 
 Conceretely, the structure of a `world` file is:
 
 ```
-top-level ::= (import | export | extend | use-item | type-item)*
+world ::= (import | export | extend | use-item | type-item)*
 ```
 
 ### Item: `import`
 
-An `import` statement imports an instance, function, or value.
+An `import` statement imports an interface, function, or value.
 
 The structure of an import statment is:
 
@@ -31,13 +31,21 @@ import ::= 'import' id ':' type-use
 Example:
 
 ```world
+// Import an instance called backends that contains zero-or-more 
+// instances that implement the "wasi:http/Handler" interface. 
 import backends: { *: "wasi:http/Handler" }
+
+// Import an instance called console that implements the 
+// "wasi:logging/Logger" interface.
 import console: "wasi:logging/Logger"
+
+// Import a value called "greetings" with type string.
+import greetings: string
 ```
 
 ### Item: `export`
 
-An `export` statement exports an instance, function, or value.
+An `export` statement exports an interface, function, or value.
 
 The structure of an export statment is:
 
@@ -48,48 +56,52 @@ export ::= 'export' id ':' type-use
 Example:
 
 ```world
+// Export instance called backends which contains one-or-more 
+// implementations of the "wasi:http/Handler" interface.
 export backends: { +: "wasi:http/Handler" }
+
+// Export instance handler that implements the 
+// "wasi:http/Handler" interface.
 export handler: "wasi:http/Handler"
+
+// Export an instance of the "wasi:http/Handler" interface directly.
+export "wasi:http/Handler"
 ```
 
-### Item: `extends`
+### Item: `extend`
 
-An `extends` statement defines a subtype relationship with the referenced profile as the super type.
+An `extend` statement defines a subtype relationship with the referenced profile as the super type.
 
 The structure of an extend statement is:
 
 ```
-extends ::= 'extends' pathlit
+extend ::= 'extend' world-file
 ```
 
 Example:
 
 ```world
-// Service.world -- Common service profile
+// Service.world -- Common service
 
-import console: "wasi:logging/Logger"
-import logs: { *: "wasi:logging/Logger" }
-import config: { *: "wasi:config/Value" }
+import logging: { *: "wasi:logging/Logger" }
 import secrets: { *: "wasi:config/Secret" }
 import metrics: { *: "wasi:metrics/Counter" }
 
 ```
 
 ```world
-// http/Service.world -- An HTTP service profile
+// HttpService.world -- An HTTP service
 
-extends "wasi:Service"
+extend "wasi:Service"
 export "wasi:http/Handler"
 ```
 
-### Item: `use-item`
-
-> TODO: Does `use` apply to `wit` files?
-
 ### Item: `type-item`
 
 A `type-item` statement declares a new named type in the `world` document. This name can be later referred to when defining `import` and `export` items. 
 
+The types in a `*.world` file map directly to the [component model specification](https://github.com/WebAssembly/component-model/blob/main/design/mvp/Explainer.md)
+
 The structure of a type-item statement is:
 
 ```
@@ -99,31 +111,34 @@ type-item ::= 'type' id '=' extern-type
 Example:
 
 ```world
-type message = record { x: string }
-type greeter = func(msg: message) -> expected<unit, string>
+type number = u32
+type result = expected<number, string>
+type handler = func(msg: message) -> expected<unit, string>
 ```
 
-> TODO: Discuss semantics of type item
+> TODO: Describe what it means to type-alias an optionally nested interface type
 
 # Grammar
 ```
-    top-level ::= (extend | import | export  | use-item | type-item)*
-      extends ::= 'extends' worldfile
-       import ::= 'import' id ':' type-use
-       export ::= 'export' id ':' type-use
-    type-item ::= 'type' id '=' extern-type
-     type-use ::= id | extern-type
-    func-type ::= 'async'? 'func' '(' func-args? ')' func-ret?
-    func-args ::= func-arg | func-arg ',' func-args?
-     func-arg ::= id ':' val-type
-     func-ret ::= '->' val-type
-     val-type ::= ty | ... | 'any'
-  extern-type ::= instance-type | func-type | val-type
-instance-type ::= '{' export* '}' | '{' ('*' | '+') extern-type '}' | witfile
+         world ::= (extend | import | export  | use-item | type-item)*
+        extend ::= 'extend' world-file
+        import ::= 'import' id ':' type-use
+        export ::= 'export' id ':' type-use
+     type-item ::= 'type' id '=' extern-type
+      type-use ::= id | extern-type
+     func-type ::= 'async'? 'func' '(' func-args? ')' func-ret?
+     func-args ::= func-arg | func-arg ',' func-args?
+      func-arg ::= id ':' val-type
+      func-ret ::= '->' val-type
+      val-type ::= wit-ty | ... | 'anyval'
+   extern-type ::= interface-type | func-type | val-type
+interface-type ::= wit-file
+                 | '{' export* '}' 
+                 | '{' ('*' | '+') ':' extern-type '}' 
 ```
 
 > NOTE: `use-def` as defined in [WIT.md](https://github.com/bytecodealliance/wit-bindgen/blob/main/WIT.md#item-use)
 
 > NOTE: `ty` as defined in [WIT.md](https://github.com/bytecodealliance/wit-bindgen/blob/main/WIT.md#item-ty)
 
-> TODO: Describe `*` & `+` instance types.
+> TODO: Describe `*` & `+` instance types.