tour.mar

| Martinaise Tour  
| This is a tour of the Martinaise language.
| This is easier to follow if you have some experience in other programming
| languages.

import stdlib.mar

| Comments  
| Use the pipe character to start comments. They go to the end of the line. If
| a comment line ends with two spaces, it's highlighted as a heading in the IDE.

| Functions  
| The fun keyword is used to create functions. For a function call, the correct
| function is chosen based on the name and the types of arguments. Writing
| a.foo(b) is an alternative way of writing foo(a, b).

fun print_title(header: String) {
  println()
  println("# {header}")
}

fun size(integer: Int): Int { integer }
fun size(string: String): Int { string.len }

fun functions() {
  print_title("Functions")

  println(size(3))
  println(size("Hi"))
  42.size().println()
}

| Variables  
| You can declare variables using the var keyword. Variables can be shadowed by
| other variables (by declaring a new variable using the same name, the old one
| becomes inaccessible).

fun variables() {
  print_title("Variables")

  var a = 3
  a = 4
  | a = true  | This won't work – you can't assign a Bool to a Int.
  println(a)

  var a = true  | This works. It's a completely new variable with the same name.
  {
    var a = 4 | Declares a in the local scope.
  }
  println(a)
}

| Structs and Enums  
| Structs contain each of their fields. Enums only contain one variant.

struct Fruit { name: String, color: Color }
enum Color { red, green, other: String }

| Constants
var banana = Fruit { name = "banana", color = Color.other("yellow") }
var watermelon = Fruit { name = "watermelon", color = Color.green }

fun structs_and_enums() {
  print_title("Structs and enums")

  println(watermelon.name)
}

| If, Switch, And, Or, For, Loop, Break, Continue  
| There are several control flow structures you can use. None of them require
| curly braces. You can start "bodies" with curly braces, grouping multiple
| expressions together. Bodies evaluate to their last inner expression.

fun control_flow() {
  print_title("Control flow")

  if true then println("This will be printed.")

  | An if is an expression:
  println(if 3 < 1 then "This won't." else "But this will.")

  | You can switch over enums:
  var color_string =
    switch banana.color
    case red "red"
    case green "green"
    case other(color) color
  println("The {banana.name} is {color_string}.")

  | The standard library uses the Maybe[T] enum for optional types.
  switch list(1, 2, 3).get_maybe(2)
  case some(item) println(item)
  case none println("index out of bounds")

  var number = list(1, 2, 3).get_maybe(2) or 0

  println(true or panic("not evaluated"))
  println(false and panic("not evaluated"))
  println(false or true and true)

  for i in 0..5 do println("i = {i}")

  var a = 5
  loop if a == 0 then break else {
    println(a)
    a = a.dec()
  }
}

| Generics  
| Functions, structs and enums can be generic by using brackets. Generics are
| only checked when they are used with concrete types, aka they use duck-typing.

enum Package[T] { filled: T, empty }

fun write[W](writer: W, fruit: Fruit) {
  writer.write(fruit.name)
}
fun write[W, T](writer: W, package: Package[T]) {
  switch package
  case filled(content) writer."[{content}]"
  case empty writer."[   ]"
}

fun generics() {
  print_title("Generics")

  println(Package.filled(100))
}

| Custom Logic  
| You can make your own types compatible with the "and" and "or" keywords. Just
| implement "and" and "or" functions.

fun or[T](package: Package[T]): ControlFlow[T, Nothing] {
  switch package
  case filled(content) ControlFlow[T, Nothing].short_circuit(content)
  case empty           ControlFlow[T, Nothing].evaluate_alternative
}

fun custom_logic() {
  print_title("Custom logic")

  var banana = Package.filled(banana) or panic("empty")
  var melon = Package[Fruit].empty or watermelon
}

| References  
| Arguments to functions are copied. Use .& to get a reference.

fun call_by_value(a: Int) { a   = a   + 5 }
fun call_by_ref(a: &Int)  { a.* = a.* + 5 }

fun references() {
  print_title("References")

  var a = 0
  call_by_value(a)
  println(a)
  call_by_ref(a.&)
  println(a)
}

| Operators  
| You already saw operators such as in 2 < 3 or 0..5.
| Operators are functions that accept two arguments and where the name matches
| the following criteria:
| - it only contains these characters: %!~@^\`/&*+$-<>=.
| - it's not =
| - it's not .
| - it doesn't start with .*
| - it doesn't start with .&

fun --->[T](a: &Package[T], b: &Package[T]) {
  b.* = a.*
  a.* = Package[T].empty
}

fun operators() {
  print_title("Operators")

  var a = Package.filled(banana)
  var b = Package[Fruit].empty

  println("a = {a}, b = {b}")
  a.& ---> b.&
  println("a = {a}, b = {b}")

  println(4 %!~@^\`/&*+$-<>=. 3)
}

fun %!~@^\`/&*+$-<>=.(a: Int, b: Int): Int { 42 }

| Assembly  
| You can define functions in Soil assembly. You can also define opaque types,
| which can only be inspected from asm functions. For information about the
| Martinaise calling convention and on how to allocate memory, read the Assembly
| section in the stdlib.

opaque MyInt = 8 bytes big, 8 bytes aligned

fun create_one(): MyInt asm {
  move a sp load a a | return value address
  moveib b 1 store a b ret
}

fun +(left: MyInt, right: MyInt): MyInt asm {
  moveib a 8  add a sp load a a | left
  moveib b 16 add b sp load b b | right
  move c sp load c c | return value address
  add a b store c a ret
}

fun custom_asm_fun() {
  print_title("Custom asm fun")
  var two = create_one() + create_one()
}

| Run everything  

fun main(): Never {
  functions()
  variables()
  structs_and_enums()
  generics()
  control_flow()
  custom_logic()
  references()
  operators()
  custom_asm_fun()

  exit(0)
}