# Cuttlefish Docs

# Data

### Basics types:
- `Int` - 32 bit integer number
- `Float` - 32 bit floating point number
- `Int16`, `Int32`, `Int64` - 16/32/64 bit integer numbers
- `Float16`, `Float32`, `Float64` - 16/32/64 bit floating point numbers
---
- `Empty` - Empty primitive (think null or void)
- `Container` - Container primative, stores data in an indexable interface
- `Bool` - Boolean primitive, `True` and `False`
- `Char` - Character primative, `'A'`, `'B'`, ...
---
- `Maybe a` - `Just a` or `Nothing`, potential usage of value - used as a `Monad`
- `Either a b` - `Left a` or `Right b`, extended usage of value
- `Error a b c` - `Pass a` or `Error b c`, simple error handling - used as a `Monad`
- `Map a b` - `Map a b`, wrapper around `List` for expressive multidimensional mapping of functions, value `a` and rank `b`

### Composite types:
- `List` - Fixed-length container of a single type, `Container<...A>`
- Constructed with `[]`
- `Tuple` - Fixed-length container of a single type, `Container<A, B, C...>`
- Constructed with `()`
- `String` - List of characters, `List<Char>`
- Constructed with `""`

### Functions:
- Typed are `a ->> b`, given input, receive output
- Comes in multiple kinds: `normal`, `lambda`, `pipeline`, `partial operator`

### Typeclasses:
- `Number` - Numeric operations
- `Equal` - Test for equality
- `Show` - Converts data into a `String`
---
- `Functor` - Mapping between one type and another
- `Monad` - Context for additional computation
- `Maybe`, `Either`, `Error`, `Map`
---
- `Semigroup` - associative binary operator
- `Number` with `min`, `max`
- `Tuple` with `first`, `last`
- `Monoid` - semigroup with identity element
- `List` with `concat`
- `Number` with `%`
- `Group` - monoid with inverse element
- `Bool` with `||`, `&&`
- `Number` with `+-*/^`

### *Special typeclasses:
- These typeclasses contain native, non-FP processes for functionality and ease of use
- `IO` - `Monad` for IO processes
- `Var` - `Monad a ` - `Mut a` - `Static a` or `Const a`, wrapper for mutable variables

# Misc
### Comments:
There are two types of comments in Cuttlefish. Comments are ignored by the compiler entirely. They are removed by the preprocessor.
- Single-line comments use `#`
- The preprocessor removes the comment symbol and all characters until the end of the line (`\n` or `\r\n`, inclusive).

# This is a single line comment

- Multi-line comments use `/*` and `*/`
- The preprocessor removes the comment brackets and all characters inbetween, newlines included. Hence, an example like `1 + /* interrupt */ 2` is perfecty valid

/*
    This is
    a multiline
    comment!
*/

# Functions
Functions transform data, `a ->> b`, and are first-order objects. Functions, transformation of data, are also considered data. Functions come in multiple types:

## Normal
The standard function syntax. These are considered statements, so you can only use the variable a normal function is bound to if required in an expression. Supports both pattern matching which can extend to overloading. Addtionally pattern guards are also supported.

# Basic 
functionName :: functionType
functionName =
     arg1 <arg2> <arg3> ...    => functionStatement        # Arg pattern 1
     arg1' <arg2'> <arg3'> ... => functionStatement     # Optional Arg pattern 2

**Pattern matching** comes in two variants: type matching and data matching.

**Type matching:**
An argument can fit a match by matching a type (using `=:`). The expression to use is `argument : Type`.

# Type matching
addFlair :: (Num | String) ->> String
addFlair =
    input : Num    => (String.parseNum input) + "!"
    input : String => input + "!"

Type matching can also match typeclasses.

**Data matching:**
An argument can also fit a match by equaling some data (using `==`). If you are to match with data equality, the data must implement `Equal`. You simply replace the argument variable with the matching data.

# Data matching
fibanocci :: Num ->> Num
fibanocci =
    0 => 1
    1 => 1
    n => (fibanocci <- n - 1) + (fibanocci <- n - 2) 

The type and data matching patterns can also be mix and matched.

# Data matching
fibanocci :: (Num | String) ->> Num
fibanocci =
    0          => 1
    1          => 1
    s : String => -1
    n : Num    => (fibanocci <- n - 1) + (fibanocci <- n - 2) 

**Destructuring:**
Most notably, Cuttlefish's pattern matching also supports *extensive* destructuring.

**Pattern guards:**

### Lambda

arg1 <arg2> ... => expression

arg1 <arg2> ... +> expression
arg1 <arg2> ... *> expression
arg1 <arg2> ... ~> expression

arg1 <arg2> ... N> expression    # Where N is an operator

### Pipeline

{
    function1
    <function2>
    <function3>
    ...
}

### Partial Operator

(1+)
(/3)

# Closures

## Types of closures
A closure is a block of code with either sequential action (ie. chaining functions, statements, etc) or acts as a collection (namespace, class)

### Closure (Sequential action)
**Do blocks:**
- Chains statements together sequentially.
- Impure statements can only be used here.
- Pure statements are also allowed.
- Must use the `return` keyword to return a value. Otherwise, the block is of type `Void` (or `()`) and does not return anything

doScope :: () ->> () -- or Empty ->> Empty
doScope _ = do
    imperativeStatement1
    pureStatement1
    ...

**Pure blocks:**
- Chains statements together sequentially
- Pure statements only
- Must bind value to the "equals variable"

pureScope :: Num -> Num 
pureScope n = value where
    pureStatement1
    pureStatement2
    ...
    value

### Closure (Collection)
**Namespaces:**
- Create a scope of variables in a collection
- Use with `with` in functions to add to a scope

namespace namespaceBlock
    value1 :: Num
    value1 = 1
    
namespace.value1    # 1

# Expressions