# 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`: 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.
- `never`: a type that denotes functions that do not return. distinct from returning nothing.
- `empty`: possibly? in place of the empty tuple? the empty tuple has always bothered me

`bool`, `int`/`uint` and siblings, `float` and siblings, `char`, and `rune` are all considered **primitive types** and are _always_ [[copied]], unless specifically passed with `mut/ref` type {undecided}.

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 used by name: instead, the absence of a type typically 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 `->`?

Aside: How should we handle pure functions? fold it into a more powerful Effects system? probably.

## Container types / Sequence types / Iterable types

Iterable types can be one-of:
- `array[T]`: Static arrays. Can only contain one type `T`.
- `list[T]`: Dynamic arrays. Can only contain one type `T`.
- `tuple[T, U, V...]`: n-tuples. May contain multiple types, however, any given position in the tuple must be of a known type.
- `slice[T]`, where `T` is a container type. This represents a "view" into some sequence of elements of type `T`.
  - Tuples are a special case: when iterated, they expose themselves as a sequence of `TupleElement`s wrapping their inner types. This allows us to assert a single type for inner elements (which then must be matched if one is to do anything productive with them).
- `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...

Aside: i really need to be consistent between sequence, collection, iterable, container.

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

Probably better as external data structures:
- `set[T]` / `bitset[T]` / `hashset[T]`
- `dict[T]` / `table[T]` / `hashmap[T]`

### Aside: laziness

Quite a few functions, mostly those related to functional programming of some sort, benefit from _laziness_: not computing the result of a function applied to a value instantly, and instead waiting until this is _collected_ by a special `collect` function (in Haskell, just being used will do: we're not quite that lazy).

Rust does laziness via types: i.e. a map function returns a Map wrapper, which then you can map again on to get a `Map<Map<T>>` and so on and so forth with a variety of types. Particularly for maps, this allows for computing all of the functions applied through a single iteration, rather than the 4-5-6-etc iterations that an eager implementation may need. (is this a monad? i think this is a monad)

Nim _doesn't_ do laziness: to the detriment of its `sequtils` library, whose functions simply chain naively. External libraries overcome this, but have to resort to extensive syntax tree rewriting with macros (which isn't bad in and of itself! the point of macros is to be able to implement language-level features that are lacking, but wouldn't it be nice if we baked in those features beforehand?). I think that Rust's approach is Really Quite Good in comparison.

I think Rust's approach is primarily made possible by traits (map implements the Iterable trait or the Collectable trait or whatever). It should be doable with concepts: and be a good baseline test for if concepts are a usable replacement for traits.

```
type Iterable: concept =
  Iterable.iter() is Iter[T]
# or depending on syntax
type Iterable: concept[T] =
  Iterable.iter() is Iter[T]
type Iterable[T]: concept =
  Iterable[T].iter() is Iter[T]
type Collectable[T]: concept =
  Collectable[T].collect() is T
```

## Generic types / 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.

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.
- Options: `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 occupied with strings).
- Iterable: `func foo(a: iterable)`: the special "iterable" type mentioned above.

## Advanced Types

The `type` keyword is used to declare custom types.

Custom types can be one-of:
- `struct`/`object`: A collection of types, that may have default values
  - potentially: `struct` vs. `object` denote types passed by reference/value?
- `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
- `tuple`: See [[tuples]], earlier.
- `concept`: typeclasses. they have some unique syntax
- `distinct`: a type that must be explicitly converted
  - useful for preventing sql injections, ascii/unicode fuckups, etc