# Namespaces

_Namespaces_ are the primary organizational unit of Ava. Every Ava file _must_
define a namespace. The namespace is ALWAYS the first line of the file.

## Syntax

Each namespace is an ordered, delimited, list of [names](names.md). Each name is
separated by the `.` character.

```
namespace foo.bar.baz
```

```
[export] namespace <name>[.<name>]*
```

- At least one name MUST be specified.
- CANNOT contain more than one `.` character in a row.
- CANNOT begin with `.` character.
- CANNOT end with `.` character.
- CANNOT start with a [Reserved Name](#reserved-names).

### Examples

- `foo`
- `foo.bar.baz`
- `language.v0`
- `collections.v0`

## Reserved Names

Any namespaces provided with a particular Ava distribution are considered
_reserved_. This means that, for example, the following namespaces cannot be
used:

- `ava`
- `collections`

## Ava Namespace

The `Ava` namespace is automatically imported into every Ava file.

## Exports

- Each file MAY _export_ definitions using the `export` keyword.
- If the `export` keyword is used at the beginning of the namespace declaration,
  all definitions in the file are exported.
- Otherwise, definitions may be individually exported by prefixing them with the
  `export` keyword.

### Export Syntax

```
export fn foo: () => Int32
    10
end fn

export enum Color
    object Red
    object Yellow
    object Blue
end enum

export namespace foo.bar.baz

export class Something
    fn foo: () => Int32
end class
```

### Exporting Enumerations

For some enumeration, if the `enum` is exported, that means that all members of
the enumeration are also exported.

### Exporting Type Classes

If some type class is exported, all enclosed functions are also exported.

## Imports

Imports immediately follow the namespace definition in each file. Each file may
have zero or more imports. Imports bring definitions from another namespace into
scope.

### Import Syntax

Each import is a single, fully-qualified name. Imported names MAY be mapped to
some alternative name using the `as` keyword. An import may refer to a specific
namespace or it may refer to some specific definition within a namespace.

```
import <namespace>[.<definition name>|.*] [as <name>]
```

### Importing Enumerations

Importing an enumeration does NOT import each member of the enumeration. Using
some example enumeration:

```
export enum Color
    object Red
    object Yellow
    object Blue
end enum
```

The import and usage might be:

```
import foo.bar.baz.Color

let x: Color := Color.Red
```

Direct imports or `*` imports can bring members into direct scope:

```
import foo.bar.baz.Color
import foo.bar.baz.Color.*

let x: Color := Red
```

### Importing Type Classes

When a type class is imported, its functions (both defined and
instance-delegated) are made available and in scope for all types that satisfy
that type class. _All `instance`s for the imported type class are resolved and
made available_. Type class instances cannot be imported directly.

- Only one `instance` may exist per `class` per type.
- `instance` are globally resolved.

### Splat Imports

Splat imports, aka `*`, pull _everything_ from the given path into scope. This
means that all exported members are imported. Notably, this does NOT lift
enumeration members into scope.

### Examples

```
import collections.NonEmptyList as NEL
import collections.Queue
import collections.*
import collections as colls
```