docs/Import.rst

:orphan:

.. warning:: This document represents an early proposal for ``import`` syntax and
  has not been kept up to date.

IMPORT SYNTAX
=============
::

  import-decl ::= 'import' import-item-list
  import-item-list ::= import-item (',' import-item)*

  import-item ::= import-kind? identifier-path
  import-item ::= identifier-path '.' '(' import-item-list ')'

  import-kind ::= 'module'

  import-kind ::= 'class'
  import-kind ::= 'enum'
  import-kind ::= 'func'
  import-kind ::= 'protocol'
  import-kind ::= 'struct'
  import-kind ::= 'typealias'
  import-kind ::= 'var'
  // ...

``import`` makes declarations exported from another module available inside
the current module. Imports are not reexported by default.

Importing Modules
-----------------

In its simplest form, ``import`` gives the qualified name of a module and
imports all exported symbols from the module, as well as the module name itself
for qualified lookup::

  import Cocoa

  // Reference the NSArray type from Cocoa
  var a1 : NSArray
  // Same, but qualified
  var a2 : Cocoa.NSArray

In this form, the qualified name *must* refer to a module::

  // Import the Cocoa.NSWindow module, *not* the NSWindow class from inside
  // Cocoa
  import Cocoa.NSWindow

  // Reference the NSWindow type from Cocoa.NSWindow
  var w1 : NSWindow
  // Same, but qualified
  var w2 : Cocoa.NSWindow.NSWindow

Multiple modules may appear in a comma-separated list::

  import Foundation, iAd, CoreGraphics

As a shorthand, multiple submodules with a common parent module may be listed
in parens under the parent module::

  import OpenGL.(GL3, GL3.Ext)

Importing Individual Declarations
---------------------------------

Instead of importing the entire contents of a module, individual declarations
may be imported. This is done by naming the kind of declaration being imported
before the qualified name, such as ``func``, ``var``, or ``class``. The module
name is still imported for qualified lookup of other symbols::

  // Import only the Cocoa.NSWindow class
  import class Cocoa.NSWindow

  var w1 : NSWindow
  var title : Cocoa.NSString

As with modules, multiple declarations may be imported in a comma-separated
list, or imported out of a common parent module with a parenthesized list::

  import func OpenGL.GL3.glDrawArrays, func OpenGL.GL3.Ext.glTextureRangeAPPLE
  // Equivalent
  import OpenGL.GL3.(func glDrawArrays, func Ext.glTextureRangeAPPLE)

RESOLVING NAME CLASHES
======================

Module imports
--------------

Because the local names introduced by a whole-module import are implicit,
a name clash between imported modules is not an error unless a clashing name is
actually used without qualification::

  import abcde // abcde exports A, B, C, D, E
  import aeiou // aeiou exports A, E, I, O, U

  var b : B // OK, references abcde.B
  var i : I // OK, references aeiou.I
  var e : E // Error, ambiguous
  var e : abcde.E // OK, qualified reference to abcde.E

Conflicts are resolved in favor of individually imported or
locally defined declarations when available::

  import abcde         // abcde exports A, B, C, D, E
  import aeiou         // aeiou exports A, E, I, O, U
  import class asdf.A  // explicitly import A from some other module
  import class abcde.E // explicitly import E from abcde

  class U { } // Local class shadows whole-module import

  var a : A // OK, references asdf.A
  var e : E // OK, references abcde.E
  var u : U // OK, references local U

Declaration imports
-------------------

Individual declaration imports shadow whole-module imports, as described above.
If two declarations with the same name are individually imported from different
modules, references to either import must be qualified::

  import class abcde.E
  import class aeiou.E

  var e : E        // Error, ambiguous
  var e1 : abcde.E // OK

A local definition with the same name as an explicitly imported symbol
shadows the unqualified import::

  import class abcde.E

  class E { }

  var e : E       // Refers to local E
  var e : abcde.E // Refers to abcde.E

Module names
------------

FIXME: What is a good rule here? This sucks.

If a module name clashes with a local definition or imported declaration, the
declaration is favored in name lookup. If a member lookup into the declaration
fails, we fall back to qualified lookup into the module::

  import Foo // exports bas

  class Foo {
    class func bar()
  }

  Foo.bar() // bar method from Foo class
  Foo.bas() // bas method from Foo module

FUTURE EXTENSIONS
=================

In the future, we should allow the import declaration to provide an alias
for the imported module or declaration::

  import C = Cocoa
  import NSW = class Cocoa.NSWindow
  import Cocoa.(NSW = class NSWindow, NSV = class NSView)