> Are you out of the loop? do you want to know more about shard?
*\*slaps sunroof\** well this is the document for _you_!
# Preliminary (shitty) shard doc (PSSH)
permalink: https://hackmd.io/@NMrPsS1ORLq4tTSvRWdR2w/pssh/edit
### Purpouse
- **To serve as a very vague, easily malluable spec**
for shard designed for people
who are "out-of-the-loop" and who dont want to sift through 10 weeks worth of
shitposts on discord to find out what the state of shard looks like.

- **To have a consolidated place for shard synax** outside of discord where you
can edit it to your hearts content so that the once transient vc calls can become
archaivable, and easily accessible for others.

### Anti-goals
- **Providing a specific, concrete spec** which is outside the goals of this document
as everything here is subject to change over time as systems are worked out over time;
as such it is _recommended_ to omit actual details of how itll work

- **Beaurocratic git syncing** is also not what this document is designed for. Just
change the [Last Edited](##Last edited) section with a brief, one sentance description
of what happened and who was present.

- **Democratic voting on changes** is also a huge time waste and we will decide on
things later

---

Now that we got that out of the way, and everyone understands this is just a "what
happened since i last left" type of document instead of a datasheet, we can begin:

## Types
- refer to the type document, which is actually accurate and specific (shocker, i know).

## Operators
~~all other operators are the same as the shardlang docs (as of now) ~~

### Precedence
| Precedence | Operator | Description | Associativity |
| ---------- | ---------------- | ----------------- | ------------- |
| 1 | `$` `!` `[]` `.` | Extern function call, function call, dereferece, array subscripting/member access | Left-to-Right |
| 2 | `++` `--` `+` `-` `~` `->` `*` `&` `@builtin` `=>`| increment, decrement, unary plus, unary, minus, bitwise NOT, cast, dereference, address-of, builtin function, pipe into | Right-to-Left|
| 3 | `*` `/` `%` | Multiplication, division, modulus | Left-to-Right |
| 4 | `+`, `-` | | |

### Semicolon
The semicolon `;` is equivalent to C's `,` operator. The grammar is as such:
`(expr1/statement1) ; (expr2)`. It basically evaluates the first thing, discards it,
then returns whatever the second thing evals to. `1 ; 2` returns 2. not much to it.
Unlike C's comma, we actually allow a statement for the lhs which just gets eval'd:
You can also chain them:

1 ; 2; 3 //returns 3

$printf "Hello, " ; $printf "World!"; 3 // prints "Hello, World!", and returns 3

^ gramatically allowed cause we allow any statement as the lhs.

These get parsed as:

1 ; (2; 3)
     ^ expression

and

                    v rhs inner expression
$printf ; ($printf; 3)
^statement    ^   ^ ; always is an expression
              |lhs inner statement

## Function calls
After a long arduous fiend to find a middleground between
requiring `()` everywhere and putting in the work to see
where they are needed or not (involving checking functions
to be variadic, macros, ect ect) which are both not ideal,
we came up with:

"Required parens unless the function ***only*** accepts 1
or 0 arguments".

Pretty clean and avoids any lambda, heap, and variadic
issues:

!foo (1, 2, 3)
!foo 1
!foo

// vec iter extravaganza
Vec !new 9
   => !map |x: x * 2|
   => !for_each |x: $printf("%d\n", x)|


// the prev example
!( !0x23412( 2, 3, !as ) )(2, 3)

!foo({1, 2}, !bar 3)

// funcs in heaps
%simpler = {!my_fn(1, 3), !nhshdjf 4, !sdg(1, 3)}

This is basically good in all scenarios and still
allows for nice cleaner syntax

## Mutations
`a'+10` // returns a then adds 10 to a
`'a+10` // adds 10 to a then returns a

for straight up assignment use `'a := 2`

## Constants and Heap Literals
func/label/whatchamacallit definitions ending with `:` contain a single following statement/expr as their body.
Constant expressions will be evaluated at comptime and stored as a literal value.
Anything else is interpreted as code.

struct Pos {
    2 x,
    2 y,
}

new -> Pos:
    ret {0, 0}

TWO @ .rodata: 2

GOAL_POS @ .rodata: {
    2 0x2a,
    2 0xe0,
} 

GOAL_POS_REAL @ .rodata: Pos { 1, 2 }

## Generics
rust style `<>`

struct Vec<T> {
    [T:] array,
    #WORD len,
    #WORD cap,
}

new -> Vec<T>:
    ret {0, 0, 0}

destr Vec<T>:
    $free #1
    
push Vec<T> vec, T element {
   (vec->contents == 0) {
      'vec->array := $malloc @size T * 2
      'vec->cap := 2
   }

   (vec->len == vec->cap) {
      'vec->cap * 2
      'vec->array := $realloc(vec->array, @size T * vec->cap)
   }

   'vec->array.(vec->len) := element
   'vec->len + 1
}

entry {
   %vec = Vec<4> !new

   vec => !push 1
   vec => !push 2
   vec => !push 3
   vec => !push 4
   vec => !push 5

   $printf("third num: %d\n", vec.2)
   @destr vec
}

## Polymorphism?! in ze Shard?!
`Formatter <- T` essentially means "any T that can be cast to `Formatter`"

struct Formatter

struct Debug
cast Debug -> Formatter

fmt Debug f, 1:? array -> [1:] {
   /* do formatting */
}

struct Display
cast Display -> Formatter

fmt Display f, 1:? array -> [1:] {
   /* do formatting */
}

print Formatter <- T fmt, V value -> [1:]:
   $puts !fmt(fmt, value)


entry {
   !print(Debug {}, {1, 2, 3, 4})
   !print(Display {}, {1, 2, 3, 4})
}

## Last edited

- **slbsh**: Polymorphism, Generics, collapse mutation options
- **slbsh**: Heap literals, some spelling fixes
- **fami-fish**: update to include new function grammar and also the new mutation syntax frfr. Also moved to hackmd
- **fami-fish**: create this document