pfm/ava
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Compare commits

base: pfm:revision2
Branches Tags
pfm:main
pfm:revision2
..
compare: pfm:main
Branches Tags
pfm:revision2
pfm:main

No commits in common. "revision2" and "main" have entirely different histories.
revision2 ... main

4 changed files with 5 additions and 535 deletions
Show stats Expand all files Collapse all files

8
README.md
View file

@ -10,7 +10,9 @@ specification phase. There is no grammar, parser, compiler, or way to use any
Ava code. Ava is a way to get ideas out of my head, challenged, and further Ava code. Ava is a way to get ideas out of my head, challenged, and further
explored. explored.
## Documentation ## Notes
Please start with the [Documentation Contents](./docs), which provides links to These notes are not guaranteed to be up to date and represent a large amount of
different iterations of the language. brainstorming and trying/discarding of ideas.
Please start with the [Table of Contents](./notes/table-of-contents.md)

6
docs/README.md
View file

@ -1,6 +0,0 @@
# Ava Documentation
This documentation is currently organized by revision, where major updates are
made to the specification.
- [R2](./revision2.md)

463
docs/revision2.md
View file

@ -1,463 +0,0 @@
# 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)
- [Constants](#constants)
## 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.
```
internal fn foo: Int32 -> Int32
λ x => x + 1
end fn
```
Unused `internal` definitions are considered errors.
### Private Accessibility
`private` definitions are only accessible _within their file_. Even if another
file shares a namespace, `private` definitions are invisible to that file.
```
private fn foo: Int32 -> Int32
λ x => x + 1
end fn
```
Unused `private` definitions are considered errors.
## 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
```
## Constants
_Constants_ are top-level [definitions](#definitions) in Ava. They are named,
concrete values with a concrete type.
### Rules
- Constants must be defined at the top level of Ava source files.
- Constants must have an explicit type (they may not infer).
- Constants must have a concrete type.
- Constants must have a literal value.
- Constants _may_ reference the value of another constant.
- Constants _may_ be a record, itself defined in terms of literal values or
constant values.
Note that these rules exist to permit constant definitions that are not limited
to literal values.
### Syntax
Constants are defined using the [const](#const) keyword.
```
const <name>: <type> = <value>
```
### Examples
```
const foo: String = "foo"
const bar: Int32 = 12
record Foo
x: String,
y: Int32,
end record
const baz: Foo = Foo(foo, bar)
```
## Functions
_Functions_ are top-level [definitions](#definitions) in Ava, values in Ava, and
are the heart of programming in Ava. In general, functions have type `A -> B`,
where input of type `A` produces a result of type `B`.
### Functions Without Arguments
Technically, there are _no_ functions without arguments in Ava. All functions
are pure, and thus a function without arguments is just a value. The `Unit` type
can be used as a "nothing" argument, as it's a singleton object.
```
given A
record IO
thunk: Unit -> A
end record
given A
fn io_new: (Unit -> A) -> IO A
λ thunk => IO(thunk = thunk)
end fn
fn demonstrate: Unit -> IO Int32
λ () =>
block
let foo: Int32 = 10
let bar: IO Int32 = io_new λ () => foo
bar
end block
end fn
```
### Functions With Multiple Arguments
Arguments should be chained with `->` in Ava:
```
import ava.string
fn example: String -> Int32 -> Int32
λ x y => (string.length x) + y
end fn
```
Technically, this represents a curried function with left associativity:
```
A -> B -> C -> D == ((A -> B) -> C) -> D
```
This means that Ava naturally supports curried functions with partial
application:
```
fn example: Int32 -> Int32 -> Int32 -> Int32
λ x y z => x + y + z
end fn
let add1: Int32 -> Int32 -> Int32 = example 1
-- Result: 6
let result = add1 2 3
```
In this case, `example 1` invokes `example` with an input of literal value `1`,
which results in a partial application of example that looks like:
```
fn partial: Int32 -> Int32 -> Int32
λ y z => 1 + y + z
end fn
```

63
docs/sketch-atomics-mutation.md
View file

@ -1,63 +0,0 @@
# Sketch: Atomics and Mutation
What does it look like to mutate state outside of the scope of a function?
## Problem Statement
I want the ability to _modify_, _in-place_, the value of some reference or some
value on the stack. I want the ability to do this _outside_ of the scope of a
single function.
## Example Functionality
What is a `State`? How is a `state_set` implementation possible?
```
fn example: State String -> String -> IO Unit
λ state newValue => state_set state newValue
end fn
```
## Problem: Thread-Safe Access
- All access to the `State` "thing" must be thread-safe.
## Problem: Representation
- Ava, to this point, has not had any record-mutable state or the notion of such
an object.
- Ava does not and will not have inheritance (precondition).
- Must Ava have a mutable primitive?
- How could Ava support mutability without direct access? This implies that
something like `mut` as a `record` field modifier is not sufficient.
## Idea: Support via Modifiers
The following implementation is incomplete and does not enforce any thread
safety, but illustrates how `private` access could help this work.
Also, it demonstrates that anonymous function syntax needs to be considered.
```
given A
record State
private mut data: A,
end record
given A
fn state_get: State A -> IO A
λ state => defer (λ => state.data)
end fn
given A
fn state_set: State A -> A -> IO State A
λ state newValue => map (defer (λ => state.data = newValue)) (λ => state)
end fn
given A
fn state_modify: State A -> (A -> A) -> IO State A
λ state f =>
map
(defer λ => state.data = f state.data)
λ => state
```