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
• Reserved Keywords
• Reserved Symbols and Operators
• Namespaces
• Imports
• Definitions

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
• Definitions
• Variables
• Function Arguments
• Record Fields
• Destructured Fields

Name Examples

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

Reserved Keywords

namespace

Used to specify the Namespace of a file.

import

Used to declare an Import within a file.

private

Used to mark a Definition as Private.

internal

Used to mark a Definition as Internal.

let

Declares an immutable Variable binding.

mut

Declares a mutable Variable binding.

const

Declares a Constant definition.

given

Used to define type constructors within the scope of some definition.

fn

Indicates a function definition. Each function may or may not be implemented.

class

Indicates a type class definition.

instance

Indicates the definition of a specific type class instance.

match

Keyword that identifies a match expression.

λ

Alias for the case keyword.

case

Defines a 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.

opaque

Declare an opaque type.

record

Define a record (immutable data structure).

enum

Define a new enumeration (sum type).

as

Used to rename a specific import.

if

Denotes an if/then/else expression.

then

Required after the predicate of an if/then/else expression.

else

Required after the first block of an if/then/else expression.

true

The Boolean value true.

false

The Boolean value false.

object

Define a singleton object.

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)

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.
• 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 is not marked private or internal, 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 from other namespaces, into the current scope.

Rules

• Imports must follow the namespace 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
• Functions
• Infix Functions
• Type Classes
• Type Class Instances
• Enumerations
• Records
• Type Definitions
• Opaque Types

Definition Accessibility

All definitions are public by default. All definitions may be modified to be either internal or private.

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.