sky/specs/modules.md

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 script or inserting an element that is not already
registered, 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](apis.md) that represents the module.

### 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 an empty Object. Properties can be added to the object,
or, it can be set to an entirely different object; for example, it
could be set to the module's Document itself, in case the point of the
module is to expose some ``template`` elements.

### Exporting element definitions ###

When importing a module into another, Sky looks at the properties on
the imported module's ``exports`` value, and for each property that is
an element constructor (generated by ``registerElement()``), it adds
an element to the importee's element registry.

 
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(name_1, ..., name_n, module, source_code)).call(
  value_1, ..., value_n, source_module);
```

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``.