ECMAScript 4 Netscape Proposal Core Language Packages

Wednesday, June 4, 2003

Packages were originally part of the ECMAScript Edition 4 proposal but have been removed due to time constraints. If implemented, packages and import directives might be defined as described below.

Defining Packages

Packages are an abstraction mechanism for grouping and distributing related code. Packages are designed to be linked at run time to allow a program to take advantage of packages written elsewhere or provided by the embedding environment. ECMAScript 4 offers a number of facilities to make packages robust for dynamic linking:

• Selected package contents can be protected from outside reference.
• Classes can maintain invariants that cannot be violated by code outside the class and/or package.
• Function arguments and data structure references can be type-checked to limit the kinds of unexpected inputs the package’s code can experience.
• Packages can export multiple namespaces, allowing graceful upgrades to packages without changing the code that uses them.

A package is defined using the following syntax:

When a package is defined, it may, but is not required to, be given a PackageName, which is either a string or a series of dot-separated identifiers. It is implementation-defined what the restrictions, if any, are on naming packages to avoid clashes with other packages that may be present.

The Block contains the body of a package P. The Block is evaluated at the time package P is loaded. Any public top-level definitions are available to other packages that import package P. Any public class member definitions are available to all other packages, regardless of whether they import package P. Top-level and class definitions defined by P in another namespace N are available to other packages only if they use namespace N or qualify the access with namespace N.

A package is loaded (its body is evaluated) when the package is first imported or invoked directly (if, for example, the package is on an HTML web page). Some standard packages are loaded when the ECMAScript engine first starts up. When a package is loaded, its statements are evaluated in order, which may cause other packages to be loaded along the way when import directives are encountered. Circularities are not allowed in the graph of package imports.

Two attempts to load the same package in the same environment result in sharing of that package. What constitutes an environment is necessarily application-dependent. However, if package P1 loads packages P2 and P3, both of which load package P4, then P4 is loaded only once and thereafter its code and data is shared by P2 and P3.

Javascript does not support package definition circularities (two packages A and B that each import the other), although an implementation may provide such a facility as an extension.

Importing Packages

A package P can reference another package Q via an import directive:

An import directive may be preceded by attributes; however, all such attributes must evaluate to either true or false.

There are two ways an import directive can name a package to be imported:

• The PackageName may be PackageIdentifiers. In this case, the system looks for a package with that exact PackageIdentifiers on its implementation-defined search path.
• The PackageName may be a literal string. In this case, the system interprets the contents of the string in an implementation-defined manner in order to locate the package. Specific ECMAScript 4 embeddings should define the manner in which the contents of the string are interpreted. For example, a browser embedding may be defined to interpret the string as a URI and look for a package at the location given by that URI.

An import directive does the following:

• Locate the target package specified by PackageName. If the package has not yet been loaded, then load it and wait until the target package’s Block is done evaluating. If loading the target package causes an import of the current package then throw a package circularity exception.
• Let P be the target package object.
• If Identifier is given, const-bind it to P in the current scope.
• For each non-explicit top-level definition N::n (n in namespace N) in P, bind an alias N::n to P’s N::n in the global scope unless N::n is already defined in the global scope.

If package P has a top-level definition n and package Q imports P using import PkgP = P, then package Q can refer to n as either n or PkgP.n. The shorter form n is not available if it conflicts with some other n. If package P has an explicit top-level definition n and package Q imports P, then package Q can refer to that n only as PkgP.n.

Waldemar Horwat Last modified Wednesday, June 4, 2003