.AS File Format – Packages and namespaces

package

package [name.name…] {
    [import directives]
    [one public or internal definition, and any internal ones]
}

• A package block can hold classes, interfaces, functions, variables, constants, namespaces and even statements. Only one definition in a file may be public, and the file is named after it.
• Only public and internal are allowed at package level; internal is the default. The package itself cannot be given an attribute.
• There are no nested or private classes as in Java. Helper classes go after the package block, where only the same file can see them.
• The package name follows the folders under the source path: com.example.ui.Button is com/example/ui/Button.as. The unnamed package is the top level of the source path.
• Nested packages such as flash.display and flash.display3D share nothing but the start of their names: there is no inheritance or special access between them.
• Package names are usually reversed domain names in lower case, as in Java: com.example.project.

import

import package.Name;
import package.*;

A class or function from another package must be imported before it can be used; the compiler does not search for it as ActionScript 2.0 did. Classes in the same package and the top-level classes need no import. An import of one definition is preferred to the wildcard, which can bring in names that clash.

• After the import, the short name (Sprite) and the fully qualified name (flash.display.Sprite) both work.
• When two imported packages define the same name, the short name is ambiguous and must be written fully qualified.
• Declaring a name that an import already brings in is an error.
• An import lasts for the block it is written in: imports inside the package block do not reach helper classes after it.
• import does not copy code in, unlike C’s #include; the include directive does that.

Access attributes

In ActionScript 3.0 private is enforced at run time too: even obj["secret"] cannot reach a private member, and subclasses cannot see it. A constructor may only be public. Interface members carry no attribute; they are always public.

User-defined namespaces

A namespace is a set of names identified by a URI. It is used in three steps: define it, apply it to definitions in place of an access attribute, and open it or qualify names with it to use them.

[public | internal] namespace name [= "uri"];
name function f() { … }          // apply: name replaces public/private/…
use namespace name;              // open it for the rest of the block
obj.name::f();                   // or qualify one reference

// example/myInternal.as
package example {
    public namespace myInternal = "http://www.example.com/internal";
}

// example/alpha/Utility.as
package example.alpha {
    import example.myInternal;

    public class Utility {
        private static var _count:int = 0;
        myInternal static function get count():int { return _count; }
    }
}

// Main.as
package {
    import example.myInternal;
    import example.alpha.Utility;

    public class Main {
        public function Main() {
            use namespace myInternal;
            trace(Utility.count);
            trace(Utility.myInternal::count);   // the same, qualified
        }
    }
}

• A namespace can be applied to methods, getters, setters, variables and constants, but not to classes.
• A definition takes one namespace, and not together with an access attribute.
• Without a URI the compiler makes up a unique one that code cannot name.
• A namespace defined in a package is internal unless declared public; like a class, it is the file’s one public definition and is imported by name.
• use namespace may appear at the top of a package, in a class or in a function, and lasts to the end of that block. An opened namespace cannot be closed again.
• A namespace is also a value of class Namespace; obj.ns::[expr] qualifies a name computed at run time.

use namespace

use namespace name [, name…];

Adds the namespaces to the set the compiler searches for unqualified names. If two open namespaces define the same name, using that name unqualified is ambiguous and must be qualified with ::.

Built-in namespaces

package {
    import flash.utils.Proxy;
    import flash.utils.flash_proxy;

    public dynamic class Logger extends Proxy {
        override flash_proxy function callProperty(name:*, ...args):* {
            trace("called", name, args);
            return null;
        }
    }
}

Namespaces in the compiled code

In the compiled ABC every name carries its namespace: a package namespace for public definitions of a package, a package-internal namespace for internal ones, a private namespace for each class’s private members, a protected namespace per class, and the URI of each user-defined namespace. See Compiled bytecode.