ava/docs/revision2.md

# Ava R2

This document specifies the second revision of the Ava programming language,
started 2024-07-18.

## Table of Contents

- [Names](#names)
- [Reserved Keywords](#reserved-keywords)
- [Reserved Symbols and Operators](#reserved-symbols-and-operators)
- [Namespaces](#namespaces)
- [Imports](#imports)
- [Definitions](#definitions)
- [Comments](#comments)

## Names

_Names_ in Ava source code are user-defined strings that provide some form of
identifier to some component that may be named. All names in Ava follow the same
rules.

### Name Rules

- Names are UTF-8 strings.
- Names may **not** be a reserved keyword.
- Names may **not** be a reserved symbol/operator.
- Names may **not** include whitespace characters.
- Names may **not** include `.`
- Names may **not** include `"`
- Names may **not** include `'`
- Names may **not** include `,`
- Names may **not** include `:`
- Names may **not** include `\`
- Names may **not** include `(`
- Names may **not** include `)`
- Names may **not** begin with a number.
- Two definitions may **not** share the same name in scope.
    - This implies that names may **not** reuse the name of any standard type
      that is always considered in scope, such as `Int32` or `Boolean`.

### Name Targets

The following items may be named in Ava:

- [Namespaces](#namespaces)
- [Definitions](#definitions)
- [Variables](#variables)
- [Function Arguments](#function-arguments)
- [Record Fields](#record-fields)
- [Destructured Fields](#destructured-fields)

### Name Examples

- `foo`
- `foo-bar`
- `foo_bar`
- `<=`
- `>`
- `==`
- `%`
- `f1`
- `_foo`
- `&&`
- `||`

## Reserved Keywords

### `namespace`

Used to specify the [Namespace](#namespaces) of a file.

### `import`

Used to declare an [Import](#imports) within a file.

### `private`

Used to mark a [Definition](#definitions) as [Private](#private-accessibility).

### `internal`

Used to mark a [Definition](#definitions) as
[Internal](#internal-accessibility).

### `let`

Declares an immutable [Variable](#variables) binding.

### `mut`

Declares a mutable [Variable](#variables) binding.

### `const`

Declares a [Constant](#constants) definition.

### `given`

Used to define [type constructors](#type-constructors) within the scope of some
definition.

### `fn`

Indicates a [function](#functions) definition. Each function may or may not be
implemented.

### `class`

Indicates a [type class](#type-classes) definition.

### `instance`

Indicates the definition of a specific
[type class instance](#type-class-instances).

### `match`

Keyword that identifies a [match expression](#match-expressions).

### `λ`

Alias for the [case](#case) keyword.

### `case`

Defines a [pattern matching](#pattern-matching) case within some pattern
matching context (either a function implementation or a match expression).

### `end`

Used to indicate the end of some block.

### `type`

Declare a [type definition](#type-definitions).

### `opaque`

Declare an [opaque type](#opaque-types).

### `record`

Define a [record](#records) (immutable data structure).

### `enum`

Define a new [enumeration](#enumerations) (sum type).

### `as`

Used to rename a specific [import](#imports).

### `if`

Denotes an [if/then/else expression](#if-then-else-expressions).

### `then`

Required after the predicate of an
[if/then/else expression](#if-then-else-expressions).

### `else`

Required after the first block of an
[if/then/else expression](#if-then-else-expressions).

### `true`

The Boolean value `true`.

### `false`

The Boolean value `false`.

### `object`

Define a [singleton object](#singleton-objects).

### MISSING SOME VALUES

TODO: Things like `do`/`return`, `infix`, `const`

TODO: Consider `abstract` to be used for abstract type class functions.

## Reserved Symbols and Operators

### `.` (Access Operator)
### `=` (Assignment Operator)
### `:` (Type Assignment Operator)
### `::` (Type Class Membership Operator)
### `(` (Open Parenthesis)
### `)` (Close Parenthesis)
### `,` (Comma)
### `=>` (Case Implementation Operator)
### `->` (Type Function Operator)
### `_` (Anonymous Value Binding)
### `|` (Type Union Operator)
### `--` (Comment Prefix)

## Namespaces

The primary organizational concept in Ava is the _namespace_. Namespaces must be
explicitly declared in _every_ Ava file.

### Rules

- Every Ava source file _must_ begin with a `namespace` declaration.
- The first non-comment code in any Ava source file _must_ be a `namespace`
  declaration.
- Namespaces must contain at least one [name](#names).
- Namespaces may concatenate names using the `.` character.
- Multiple files may share the same namespace.
- Namespaces are **public** by default. This means that if any
  [definition](#definition) is not marked [private](#definition-accessibility)
  or [internal](#definition-accessibility), all definitions will be exported.

### Syntax Specification

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

### Syntax Examples

```
namespace foo
namespace foo.bar
namespace foo.bar.baz_buzz
namespace foo.bar.v0
```

## Imports

An `import` can be used to pull other namespaces, or [definitions](#definitions)
from other namespaces, into the current scope.

### Rules

- Imports **must** follow the [namespace](#namespaces) declaration.
- Imports may **not** be placed after any definition.
- Glob imports may **not** use `as` to rename (since they have no specific
  target to rename).

### Syntax Specification

```
import <name>[.<name>]*[.\* | as <name>]
```

### Syntax Examples

```
-- import a namespace, which can be referenced by name
import foo.bar

-- import everything within some namespace
import foo.bar.baz.*

-- import a specific definition from within a namespace
import foo.bar.SomeDef

-- import and rename a namespace
import baz.buzz as bb

-- import and rename a specific definition from within a namespace
import baz.buzz.FooBar as Foo
```

## Definitions

A "definition" is something that might be _defined_ at the top level of any Ava
source file. These include:

- [Constants](#constants)
- [Functions](#functions)
- [Infix Functions](#infix-functions)
- [Type Classes](#type-classes)
- [Type Class Instances](#type-class-instances)
- [Enumerations](#enumerations)
- [Records](#records)
- [Type Definitions](#type-definitions)
- [Opaque Types](#opaque-types)

### Definition Accessibility

All definitions are **public** by default. All definitions **may** be modified
to be either [internal](#internal-accessibility) or
[private](#private-accessibility).

### Internal Accessibility

`internal` definitions are only accessible _within their namespace_. This means
that they are shared across files that share a namespace.

### Private Accessibility

`private` definitions are only accessible _within their file_. Even if another
file shares a namespace, `private` definitions are invisible to that file.

## Comments

_Comments_ are sections of code that are not parsed as code. They are used to
add in-code documentation.

### Rules

- All comments begin with `--`. This is a _prefix_, `--` tells the parser to
  ignore any following content on sight.
- Multi-line comments are **not** supported.
- Names may _not_ include the comment designator.

### Standard Comment Syntax

Comments start with `--`. If that string is detected, the comment initializer to
the end of the line will be completely ignored.

### Docstring Comment Syntax

Docstrings start with `---` and must precede a _definition_ at the top level of
some source file. Docstrings _may_ be parsed in a separate process to produce a
documentation artifact.

### Examples

```
--- This is a docstring for the function definition.
fn foo: String -> String
    -- This is a regular comment.
    --- This is a regular comment, because it is not at the definition level.
    λ x => x + x
end fn
```