Specs: Module overview

sky/specs/modules.md

Index: sky/specs/modules.md
diff --git a/sky/specs/modules.md b/sky/specs/modules.md
new file mode 100644
index 0000000000000000000000000000000000000000..42bb484e5858842594a91d0438b3ce44bcdbf2b6
--- /dev/null
+++ b/sky/specs/modules.md
@@ -0,0 +1,77 @@
+Sky module system
+=================
+
+This document describes the Sky module system.
+
+Overview
+--------
+
+The Sky module system is based on the ```import``` element. In its
+most basic form, you import a module as follows:
+
+```html
+<import src="path/to/module.sky" />
+```
+
+As these ```import``` elements are inserted into a document, the
+document's list of outstanding dependencies grows. When an imported
+module completes, it is removed from the document's list of
+outstanding dependencies.
+
+Before executing any ```script``` elements, the parser waits until the
+list of outstanding dependencies is empty. After the parser has
+finished parsing, the document waits until its list of outstanding
+dependencies is empty before the module it represents is marked
+complete.
+
+Module API
+----------
+
+Within a script in a module, the ```module``` identifier is bound to
+the ```Module``` object that represents the module:
+
+```
+interface Module : EventTarget {
+  constructor (Application application, Document document); // O(1)
+  attribute any exports; // O(1) // defaults to the module's document
+  readonly attribute Document document; // O(1) // the module's document
+  readonly attribute Application application; // O(1)
+}
+```
+
+### Exporting values ###
+
+A module can export a value by assigning the ```exports``` property of
+its ```Module``` object. By default, the ```exports``` property of a
+```Module``` is its ```Document``` object, so that a script-less
+import is still useful (it exposes its contents, e.g. templates that
+the import might have been written to provide).
+
+Naming modules
+--------------
+
+The ```as``` attribute on the ```import``` element binds a name to the
+imported module:
+
+```html
+<import src="path/to/chocolate.sky" as="chocolate" />
+```
+
+The parser executes the contents of script elements inside a module as
+if they were executed as follow:
+
+```javascript
+(new Function(module, name_1, ..., name_n, source_code)).call(
+  source_module, value_1, ..., value_n);
+```
+
+Where ```name_1``` through ```name_n``` are the names bound to the
+various named imports in the script element's document,
+```source_code``` is the text content of the script element,
+```source_module`` is the ```Module``` object of the script element's
+module, and ```value_1``` through ```value_n``` are the values
+exported by the various named imports in the script element's
+document.
+
+When an import fails to load, the ```as``` name for the import gets
+bound to ```undefined```.