reference types

1 files changed, 28 insertions, 2 deletions

diff --git a/TYPES.md b/TYPES.md
index 811c7b0..6950f78 100644
--- a/TYPES.md
+++ b/TYPES.md
@@ -111,6 +111,34 @@ Generics are replaced with concrete types at compile time (monomorphization) bas
 
 Constrained generics have two syntaxes: the constraint can be directly on a parameter, leaving off the `[T]` box, or it may be defined within the box as `[T: int | float]` for easy reuse in the parameters.
 
+## Reference types
+
+Types are typically constructed as value on the stack. That is, without any level of indirection: and so type declarations that recursively refer to one another would not be allowed. However, Puck provides two avenues for indirection.
+
+Reference types can be one-of:
+- `ref T`: An automatically-managed reference to type `T`.
+- `ptr T`: A manually-managed pointer to type `T`. (very) unsafe.
+
+In addition, `var T` may somewhat be considered a reference type as it may implicitly create a `ref` for mutability if the type is not already `ref`: but it is only applicable on parameters.
+
+```
+type Node = ref struct
+  left: Node
+  right: Node
+
+type AnotherNode = struct
+  left: ref AnotherNode
+  right: ref AnotherNode
+
+type BinaryTree = ref struct
+  left: BinaryTree
+  right: BinaryTree
+```
+
+The compiler abstracts over `ref` types to provide optimization for reference counts: and so neither a distinction between `Rc`/`Arc`/`Box`, nor a `*` dereference operator is needed.
+Much care has been given to make references efficient and safe, and so `ptr` should be avoided if at all possible. The compiler will yell at you if you use it (or any other unsafe features).
+These types are delved into in further detail in the section on memory management.
+
 ## Advanced Types
 
 The `type` keyword is used to declare custom types.
@@ -119,7 +147,5 @@ Custom types can be one-of:
 - `tuple`: An ordered collection of types. Optionally named.
 - `struct`: An unordered, named collection of types. May have default values.
 - `enum`: Powerful algebraic data types a la Rust.
-  - undecided: ordinal by default, which sacrifice their ordinality when assigned static values? probably a bad idea. could be ordinal by ordering in declaration. i think rust is ordinal by alphabetical order, which is weird?? i wonder why
 - `concept`: typeclasses. they have some unique syntax
 - `distinct`: a type that must be explicitly converted
-  - useful for preventing sql injections, ascii/unicode fuckups, etc