Overview of Namespaces

Namespaces group related declarations and keep their short names from colliding with declarations in other parts of a program.

Namespace declarations

A namespace declaration places the namespace name before NAMESPACE and the owned declarations in the declaration body:

::geometry NAMESPACE
{
  ::origin STATIC I32 := 0;

  ::distance FUNCTION(@left I32, @right I32): I32
  {
    RETURN right - left;
  }
}

The :: before geometry, origin, and distance marks each as a named declaration in its current owner. It is not punctuation that can be omitted.

Qualified names

The namespace::name form selects a declaration owned by a namespace:

::measure FUNCTION(): I32
{
  RETURN geometry::distance(
    @left geometry::origin,
    @right 12
  );
}

Inside the namespace, sibling declarations can usually use one another by their short names. Outside it, qualification makes the owner explicit.

Nested namespaces

Namespaces can be nested to describe a larger hierarchy:

::network NAMESPACE
{
  ::http NAMESPACE
  {
    ::default_port STATIC U16 := 80;
  }
}

::configured_port FUNCTION(): U16
{
  RETURN network::http::default_port;
}

Namespace nesting expresses ownership relationships between declarations. A namespace has no runtime value and cannot be constructed like a structure.

Extending a namespace

The same namespace can be reopened:

::geometry NAMESPACE
{
  ::minimum STATIC I32 := 0;
}

::geometry NAMESPACE
{
  ::maximum STATIC I32 := 100;
}

Both declarations belong to geometry. Reopening lets several source files contribute related declarations without placing them in one large file.

Namespaces, modules, and structures

An imported module uses the same :: qualification separator:

IMPORT std;

VAR message std::string := "ready";

Here std is a module, not a namespace. Modules are selected by source headers and the build; namespaces are declared within a module.

Structures use . for instance members and :: for declarations owned by the type:

VAR value counter;
value.increment();
VAR initial I32 := counter::initial;

Reference

For reopening, identifier, qualification, privacy, and lookup rules, see the Namespaces Reference.