WIP on R2
This commit is contained in:
parent
a4add937c8
commit
07a2011997
GPG key ID:
5CA5D21BAB7F3A76
1 changed files with 282 additions and 57 deletions
|
|
@ -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 <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 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.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue