# Typing in Puck

Puck has a comprehensive static type system.

## Basic types

Basic types can be one-of:
- `bool`: internally an enum.
- `int`: integer number. x bits of precision by default.
  - `uint`: unsigned integer for more precision.
  - `i8`, `i16`, `i32`, `i64`, `i28`: specified integer size
  - `u8`, `u16`, `u32`, `u64`, `u128`: specified integer size
- `float`: floating-point number.
  - `f32`, `f64`: specified float sizes
- `char`: a distinct 0-127 character. For working with ascii.
- `rune`: a Unicode character.
- `str`: a string type. mutable. internally a char-array? must also support unicode.
- `void`: an internal type designating the absence of a value.
  - possibly, the empty tuple. then would `empty` be better?
- `never`: a type that denotes functions that do not return. distinct from returning nothing.
  - the bottom type.

`bool`, `int`/`uint` and siblings, `float` and siblings, `char`, and `rune` are all considered **primitive types** and are _always_ [[copied]] (unless passed as `var`).

Basic types as a whole include the primitive types, as well as `str`, `void`, and `never`. Basic types can further be broken down into the following categories:
- boolean types: `bool`
- numeric types: `int`, `float`, and siblings
- textual types: `char`, `rune`, `str`
- funky types: `void`, `never`

Funky types will rarely be referenced by name: instead, the absence of a type typically implicitly denotes one or the other. Still, having a name is helpful in some situations: like with [[concepts]].

## Function types

Functions can also be types.
- `func(T, U): V`: denotes a type that is a function taking arguments of type T and U and returning a value of type V.
  - The syntactical sugar `(T, U) -> (V)` is available, to consolidate type declarations and disambiguate when dealing with many `:`s. Is this a good idea? should i universally use `:` or `->`?

## Container types

Container types, broadly speaking, are types that contain other types. These exclude the types in [[advanced types]].

### Iterable types

Iterable types can be one-of:
- `array[S, T]`: Static arrays. Can only contain one type `T`. Of size `S` and cannot grow/shrink.
  - Initialize in-place with `array(a, b, c)`. Should we do this? otherwise `[a, b, c]`.
- `list[T]`: Dynamic arrays. Can only contain one type `T`. May grow/shrink dynamically.
  - Initialize in-place with `list(a, b, c)`. Should we do this? otherwise `@[a, b, c]`.
- `slice[T]`: Slices. Used to represent a "view" into some sequence of elements of type `T`.
  - Cannot be directly constructed. May be initialized from an array, list, or string, or may be used as a generic parameter on functions (more on that later).
  - Slices cannot grow/shrink. Their elements may be accessed and mutated. As they are underlyingly a reference to an array or list, they **must not** outlive the data they reference.
- `str`: Strings. Contain the `rune` type or alternatively `char`s or `bytes`?? {undecided}

All of these above types are some sort of sequence: and so have a length, and so can be _iterated_.
For convenience, a special `iterable` generic type is defined for use in parameters: that abstracts over all of the container types. This `iterable` type is also extended to any collection with a length of a single type (and also tuples). It is functionally equivalent to the `openarray` type in Nim: but hopefully a bit more powerful?
- Aside: how do we implement this? rust-style (impl `iter()`), or monomorphize the hell out of it? i think compiler magic is the way to go for specifically this...
- Aside: `iterable` may need a better name. it implies iterators right now which it is distinctly Unrelated to. unless i don't have iterators? that may be the way to go...

Elements of container types can be accessed by the `container[index]` syntax. Slices of container types can be accessed by the `container[lowerbound..upperbound]` syntax. Slices of non-consecutive elements can be accessed by the `container[a,b,c..d]` syntax, and indeed, the previous example expands to these. They can also be combined: `container[a,b,c..d]`.
- Aside: take inspiration from Rust here? they make it really safe if a _little_ inconvenient

### Abstract data types

There are an additional suite of related types: abstract data types. While falling under container types, these do not have a necessarily straightforward or best implementation, and so multiple implementations are provided.

Abstract data types can be one-of:
- `set[T]`: high-performance sets implemented as a bit array.
  - These have a maximum data size, at which point the compiler will suggest using a `HashSet[T]` instead.
- `table[T, U]`: simple symbol tables implemented as an association list.
  - These do not have a maximum size. However, at some point the compiler will suggest using a `HashTable[T, U]` instead.
- `HashSet[T]`: standard hash sets.
- `HashTable[T, U]`: standard hash tables.

Unlike iterable types, abstract data types are not iterable by default: as they are not ordered, and thus, it is not clear how they should be iterated. Despite this: for utility purposes, an `elems()` iterator based on a normalization of the elements is provided for `set` and `HashSet`, and `keys()`, `values()`, and `pairs()` iterators are provided for `table` and `HashTable` based on a normalization of the keys. This is deterministic to prevent user reliance on shoddy randomization, see Golang.

## Parameter types

Some types are only valid when being passed to a function, or in similar contexts.
No variables may be assigned these types, nor may any function return them.
These are monomorphized into more specific functions at compile-time if needed.

Parameter types can be one-of:
- generic: `func foo[T](a: list[T], b: T)`: The standard implementation of generics, where a parameter's exact type is not listed, and instead statically dispatched based on usage.
- constrained: `func foo(a: str | int | float)`: A basic implementation of generics, where a parameter can be one-of several listed types. Makes for particularly straightforward monomorphization.
  - Separated with the bitwise or operator `|` rather than the symbolic or `||` or a raw `or` to give the impression that there isn't a corresponding "and" operation (the `&` operator is preoccupied with strings).
- mutable: `func foo(a: var str)`: Denotes the mutability of a parameter. Parameters are immutable by default.
  - Passed as a `ref` if not one already, and marked mutable.
- a built-in typeclass: `func foo[T](a: slice[T])`: Included, special typeclasses for being generic over [[advanced types]].
  - Of note is how `slice[T]` functions: it is generic over `lists` and `arrays` of any length.

### Generic types

Functions can take a _generic_ type, that is, be defined for a number of types at once:

```
func add[T](a: list[T], b: T) =
  return a.add(b)

func length[T](a: T) =
  return a.len # monomorphizes based on usage.
  # lots of things use .len, but only a few called by this do.
  # throws a warning if exported for lack of specitivity.

func length[T: str | list](a: T) =
  return a.len
```

The syntax for generics is `func`, `ident`, followed by the names of the generic parameters in brackets `[T, U, V]`, followed by the function's parameters (which may refer to the generic types).
Generics are replaced with concrete types at compile time (monomorphization) based on their usage in functions within the main function body.

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.

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.
- `concept`: typeclasses. they have some unique syntax
- `distinct`: a type that must be explicitly converted