readme_examples.tri

// -------------------------------------------
// |                EXAMPLE 1                |
// -------------------------------------------

// During compilation, the compiler analyses the program and tries to figure out what
// potential values expressions might evaluate to at runtime. It puts these potential
// values into or-patterns for each expression.
// 
// Some expressions do however never return; instead they crash or loop forever.
// If the compiler cannot exclude the possibility of this happening for an expression,
// it will add the special `N/A` value to its or-pattern.
// 
// (`N/A` = never-returned value = "Never Available" / "Not Available" / "No Answer")
// 
// Below is an example of this.

let ($a as nat) - ($b as nat) = $a $b => a - b unless b > a then panic "below 0!";

let n = nat;

// - n == n is True
// - The remaining terms of LHS & RHS are known
// => Compiler can determine if True or False
(n - 1)     * 2 + 2 == n * 2
N/A|0|1|... * 2 + 2 == 0|2|4...
// Potential N/A(s) found!
// Add N/A to or-pattern, then
// start over with values not leading to N/A:
    0|1|... * 2 + 2 ==   2|4|...
    0|2|...     + 2 ==   2|4|...
    2|4|...         ==   2|4|...
// LHS == RHS since:
// - Compiler can determine if True or False
// - LHS & RHS or-patterns consist of the same values in the same order
=> N/A|True

// - n == n2 is True|False
// => Compiler *cannot* determine if True or False
(n - 1)     * 2 + 2 == n2 * 2
N/A|0|1|... * 2 + 2 == 0|2|4...
// Potential N/A(s) found!
// Since the compiler cannot determine anything more,
// and it's irrelevant if there are more potential N/As,
// it stops here and returns:
=> N/A|True|False

// Basically, `N/A` is propagating just like `???`.
// It can be given to any function and will make it return `N/A`.
   N/A * 2 + 2 == n * 2
=> N/A     + 2 == n * 2
=> N/A         == n * 2
=> N/A
// Note that this means that you can't directly check if something equals `N/A`,
// since `x == N/A` just returns `N/A`. However, it is still possible to do
// it indirectly by doing `!(x is ~N/A)`. This is because `~N/A` is built-in
// to mean an or-pattern excluding `N/A`. This is necessary because all other
// or-patterns implicitly include `N/A`:
nat :== 0|1|... :== 0|1|...|N/A;
// To override this default behaviour, one can add `& ~N/A` to the or-pattern:
nat & ~N/A :== 0|1|... & ~N/A;

// Really, typing `N/A` has no good use outside of `~N/A`. It could be used
// as an alternative to `???`, but doing so will just cause confusion and problems.
// For that reason, `N/A` on its own will probably give a warning on compilation.

// (Also, `~~N/A` <=> `N/A` if it wasn't obvious, so `x is ~~N/A`
//  will still become `x is N/A` and then `N/A`)

// -------------------------------------------
// |                EXAMPLE 2                |
// -------------------------------------------

// OUTDATED. Will be either replaced or removed soon.

// 'closed' prevents the compiler from looking at the function body
// before the function is in its final scope.
// 'impure' allows the function to be non-pure.
$x => (
	($y $z => (
		// Final scope
		// 'z' is defined here, so all is fine

		(() => y x) () // just to show final scope isn't necessarily call scope
	)) (closed impure $a => x++ * z a) 123 // 'impure' allows change of 'x', so all is fine
)

$x => (
	($y => (
		// Final scope
		// ERROR: 'z' is undefined
		
		($z => y x) 123 // just to show final scope isn't necessarily call scope
	)) (closed impure $a => x++ * z a) // 'impure' allows change of 'x', so all is fine
)

$x => (
	($y $z => (
		// Final scope
		
		(() => y x) () // just to show final scope isn't necessarily call scope
	)) ($a => x++ * z a) 123 // ERROR: 'z' is undefined, and 'x' is an outside/free pattern being changed
)

// -------------------------------------------
// |                EXAMPLE 3                |
// -------------------------------------------

// Declarations to allow use of patterns before they have been defined
decl $x $y $z;

println x;
let x = 123;

// -------------------------------------------
// |                EXAMPLE 4                |
// -------------------------------------------

// Example of a cool thing using #-defs
// '#($y)%' defines 'y' inside function body as '5' in this case
// You could also do '#($y as 5)%' if you only want to allow that input
object (num)%;

func ($x as num) * (#($y)%) {
    x * y / 100
}

120 * 5% == 6

// This special function catches matching
// terms in the scope its defined for.
// It only catches the terms if they are
// used in a place where all pattern
// matching has failed.
//
// Here we are making it possible to do
// <x>% <op> <y>% for every existing operator
// that works with numbers. This works because
// i.e. '120% * 5%' fails all pattern matching
// but still matches the below catcher pattern.
func __catch__ ($(_ op _) as #(#($x)%) #(#($y)%)) {
    (((x / 100) op (y / 100)) * 100)%
}

// The 2 lines below work thanks to
// the above __catch__ overload
120% * 5% == 6%
120% + 5% == 125%

// Running '__catch__' as if it was a normal
// function is allowed only for testing.
// Doing this will get you a warning on
// debug-mode and an error on release-mode.
__catch__ (5% * 120%) == 6%

// Below we instead catch all matching terms
// *before* any other pattern matching is
// done by using an implicit closure.
//
// This results in every single function
// being catched before evaluation.
impure func __catch__ ($f as implicitly _ => __explicit__) {
	println "nope!";
}

println "Hello world!"; // prints "nope!"
9 + 10 == 21;           // prints "nope!"
9 + 10 == 19;           // prints "nope!"

// NOTE: We could ofc just define '%' as '/ 100'
// if we don't care about having an object:
func ($x as any Number)% {x / 100}
// But I chose to use an object for this example
// to better showcase features of the language.

// -------------------------------------------
// |                EXAMPLE 5                |
// -------------------------------------------

// Examples of referring to the same function or not
impure func f ($x as any String) $y {println 123};
impure func f ($x as any Int)    $y {println 123};

f      != f      // ERROR! Unable to determine function being referred to
f "hi" != f 789

impure func    g ($x as any Int) $y {println 123};
impure func $y g ($x as any Int)    {println 123};

g 789 == g 789
g 789 != $y g 789

// Here the second function shadows the first
impure func h ($x as any Int) $y {println 123};
impure func h ($x as any Int) $y {println 456};

h 1 == h 1
h 1 != h 2

// Note! Full application this time
h 1 2 == 456

// Other comparison examples
let    id    = $x => x;
let    plus1 = $x => id x + 1
let    f     = plus1;
let $x g     = f;

f <=> f $x

// g <=> f <=> plus1 is just shorthand for g == f && f == plus1
g <=> f <=> plus1 // because 'g' is just a synonym for 'f' which is a synonym for 'plus1'

g != id

// All 4 lines below error! Anonymous functions are not comparable
f $x      != ($x => f x)
plus1     != ($x => id x + 1)
id        != ($x => x)
($x => x) != ($x => x)

123 g <=> f 123 <=> plus1 123 <=> id 123 + 1 <=> 123 + 1 <=> 124 // since all evaluate to 124

// -------------------------------------------
// |                EXAMPLE 6                |
// -------------------------------------------

func Potato () {};

let potato  = Potato;
let potato2 = Potato;
let potato3 = {
	func Potato () {};

	Potato
};

potato == potato2
potato != potato3 // the Potato:es were created using different constructors, so they are different

// -------------------------------------------
// |                EXAMPLE 7                |
// -------------------------------------------

// Pattern matching order:
// - Most specific patterns are checked first.
// - More general patterns are checked second.
// - If order can't be decided based on this,
//   follow the order in which the patterns
//   are defined.
// 
// The most specific pattern is the one with
// the smallest or-patterns.
// - '_' is an or-pattern of everything,
//   and therefore the biggest or-pattern
// 
// Pattern matching stops when a match is found.
// If no match is found, there's an error.

object Player [
	$name   as any String,
	$health as any Number
];

impure func f ($x as _) {
	println "last";
};

impure func f ($x as Player "Steve" 25..75) {
	println "fourth";
};

impure func f ($x as any Player) {
	println "fifth"
};

impure func f ($x as Player "Steve" 55..75) {
	println "first";
};

impure func f ($x as Player "Steve"|"Alex" 50..70) {
	println "third";
};

impure func f ($x as Player "Steve" 50..70) {
	println "second";
};

f (Player "Steve" 80) // prints "fifth"
f (Player "Steve" 60) // prints "first"
f (Player "Steve" 50) // prints "second"
f (Player "Alex"  40) // prints "fifth"
f (Player "Alex"  60) // prints "third"
f Potato              // prints "last"

// -------------------------------------------
// |                EXAMPLE 8                |
// -------------------------------------------

// Dictionaries/HashMaps + Error Handling example

func test() --> () implic made Wrapped EXPLIC {
  // Only allowing optional Int values for demonstration purposes.
  // 'optionally any Int' <=> 'any Int | ()' (read as "any Int or nothing")
  func lookup $key in $dict --> optionally any Int implic made Wrapped EXPLIC {
    for each [$hash, $val] in dict {
      if hash of key == hash {
        return val; // all returns implicitly wrapped by default, making this become 'return (Wrapped val)'
      };
    };
    
    // '`$expr`' can however be used to bypass the implicit wrapping
    // '`$expr`' is read as "precisely $expr"
    
    return `()`; // "return precisely nothing"; returns unwrapped '()', here meaning no entry was found
  };
  
  // Idk if dictionaries actually will have this syntax,
  // but let's assume they do for this example.
  let dict = [["abc", 123], ["def", ()], ["ghi", 456]];
  
  println(lookup "abc"     in dict); // prints "Wrapped 123"; entry with value '123' found
  println(lookup "invalid" in dict); // prints "()"; no entry found
  println(lookup "def"     in dict); // prints "Wrapped ()"; entry found, but the entry is nothing
  
  // '?' can be used to automatically unwrap.
  // If unwrapping fails, it returns to an error handler.
  println(lookup "def"     in dict)?; // prints "()"; entry found, but the entry is nothing
  println(lookup "invalid" in dict)?; // no entry found; returns '`()`' to error handler without printing anything
  
  (lookup "ghi" in dict)? // returning something fallible requires '?'; else 'Wrapped $val' could be returned which doesn't match '()'
};

func handle error () {
	// Handle the error somehow...
};

func init() {
  // If test() succeeds, it returns 'Wrapped ()'.
  // If it however fails, it returns '()':
  if test() == () then handle error;
  
  // (We could ofc also have chosen to return 'Err $err_info' or similar instead to know better how to handle the error)
};