diff --git a/docs/revision2.md b/docs/revision2.md index 3ca64cc..ad886a3 100644 --- a/docs/revision2.md +++ b/docs/revision2.md @@ -3,64 +3,289 @@ This document specifies the second revision of the Ava programming language, started 2024-07-18. -## Example +## Table of Contents -- TODO: Disambiguate `fn` with and without implementation. +- [Names](#names) +- [Reserved Keywords](#reserved-keywords) +- [Reserved Symbols and Operators](#reserved-symbols-and-operators) +- [Namespaces](#namespaces) +- [Imports](#imports) +- [Definitions](#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](#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`. + +### MISSING SOME VALUES + +TODO: Things like `do`/`return` + +## 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](#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 ``` -fn not: Boolean -> Boolean - λ false => true - λ true => false -end fn - -given A -given B -class Eq - fn eq: A -> B -> Boolean - - fn neq: A -> B -> Boolean - λ x y => not (eq x y) - end fn - - infix =: A -> B -> Boolean - λ x y => eq x y - end infix - - infix !=: A -> B -> Boolean - λ x y => neq x y - end infix -end class - -given F * -class Functor - --- Transform some wrapped data from one type to another, preserving the - --- wrapper. - --- - --- @tparam A The type of input data. - --- @tparam B The type of output data. - given A - given B - fn map: F A -> (A -> B) -> F B -end class - -given A -class Semigroup - fn combine: A -> A -> A -end class - -given A :: Semigroup -class Monoid - fn empty: A -end class - -fn silly_string: String -> Int32 - λ "foo" => 1 - λ "bar" => 2 - λ baz => - -- No reason to do this, but demonstrates the syntax. - baz match - case "baz" => 3 - case _ => 4 - end match -end fn +namespace [.]* ``` + +### 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 [.]*[.\* | as ] +``` + +### 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 Aliases](#type-aliases) +- [Opaque Types](#opaque-types) +- [Type Unions](#type-unions) + +### 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.