From 0ba9ac30ea599bb6d0756b2399719d930c334037 Mon Sep 17 00:00:00 2001
From: Pat Garrity <pfm@garrity.co>
Date: Tue, 23 Jul 2024 22:11:36 -0500
Subject: [PATCH] WIP on functions

---
 docs/revision2.md | 112 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 112 insertions(+)

diff --git a/docs/revision2.md b/docs/revision2.md
index 20b4c04..93b88f1 100644
--- a/docs/revision2.md
+++ b/docs/revision2.md
@@ -12,6 +12,7 @@ started 2024-07-18.
 - [Imports](#imports)
 - [Definitions](#definitions)
 - [Comments](#comments)
+- [Constants](#constants)
 
 ## Names
 
@@ -292,11 +293,27 @@ to be either [internal](#internal-accessibility) or
 `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
@@ -330,3 +347,98 @@ fn foo: String -> String
     λ 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)
+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. However, the
+`Unit` type (the empty tuple) may be used to express that case.
+
+```
+fn example: Unit -> Int32
+    λ _ => 10
+end fn
+
+let demonstrate: Int32 = example ()
+```
+
+### 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
+```