syntax.si

# syntax.si
#   The example/test of Simon's syntax design.
#   Every element of the language's syntax should be shown in this file.

### Comments:
#   Comments start with the '#' character and continue until the end of the line.
#   There are no block/multi-line comments.

### Declarations:
#   Declarations take one the following three forms:
#     1. identifier : type_expression;
#     2. identifier : type_expression = value_expression;
#     3. identifier := value_expression;
#
#   *Note that statements are required to be terminated with semicolons.

decl1  : u32;      # default-initialized, unsigned, 32-bit integer variable
decl2  : s64 = -1; # initialized, signed, 64-bit integer variable
decl3  := *decl2;  # type inferred, initialized, s64 pointer variable (the address of decl2)
print  := _builtin_prints;
printi := _builtin_printi;

#   Kinds of declarations:
#     1. Variables (see above).
#     2. Modules
#     3. Structs
#     4. Procedures
#     5. Macros (@todo)

Decl_Module := module  { }
Decl_Proc   := proc()  { }
Decl_Struct := struct  { }
# Decl_Macro  := macro() { }

#   *Note: Declarations of modules, procedures, structs, and macros are
#   not required to end with a semicolon since they have containing curly braces.
#   Though, they are allowed.

#   Declaration tags:
#     Declarations may be "tagged" with any number of specific instructions or hints
#     for the compiler:

[[ program_entry ]]
Entry := proc() { }

[[ struct_union ]]
Union := struct { a: u32, b: u64 }

### Expressions:
expr1 : [2]u32; # The type expression for expr1 uses the prefix `[]` operator and produces an array type.
expr2 := 1 + 2; # `1 + 2` is a binary expression with the `+` operator.

#   There are many more operators, but they are mostly self-explanatory.

### Modules:
#   Modules are namespaced containers for declarations.
_M : module = module { } # Can be declared with explicit type of `module`, but that's redundant.

Example_Module := module {
    _M := 6; # Can declare `_M` here since it is in a module.

    P := proc() { }
    S : type = struct { }
}

#   Access declarations in a module via the `.` operator:
P_from_Example_Module := Example_Module.P;

### Procedures
Procs := module {
    # Procedures may have arguments, which look like variable declarations.
    # If the procedure returns a value, the return type will be specified
    # after a `:` following the argument list.
    square := proc(x: f64): f64 {
        return x * x;
    }

    #   Procedures are called with the standard `()` operator:
    four := Procs.square(2.0);

    #   (Typed) variadic arguments may be used in procedures, but must
    #   be the last argument in the list.

    takes_u32s := proc(args: ...u32) { } # Takes any number of u32 args.
    # takes_u32s := proc(args: ...u32, another: u32) { } # Not allowed.

    #   Procedure arguments may be assigned default values:
    increment := proc(foo: *u32, inc_by: u32 = 1) {
        @foo += inc_by; # `@` is the dereference operator.
    }
    #   increment(*my_val); # Can leave out `inc_by`. (`*` is the "address of" operator.)
}

### Structs
Structs := module {
    # Structs define an aggregate type with fields.
    # Within a struct definition, fields are declared with a name,
    # and a type following a `:`.
    # Fields are separated by commas.
    Point := struct {
        x: f32,
        y: f32, # A trailing comma is allowed, but not required.
    }

    Node := struct {
        data: *u8,
        next: *Node
    }

    List := struct {
        head: *Node,
        len:   u32
    }
}

### Control flow:
##  Loops:
loop_example := proc() {
    n := 0;
    loop i := 0; i < 10; i += 1 {
        n += i;
    }

    loop ; n > 0; n -= 1 { continue; }

    # These are equivalent.
    loop ; 1 ; { break; }
    loop ;;    { break; }
}

##  If statements:
if_example := proc() {
    x := 1;

    if x {
        # do something
    }

    if not x {
        # x is 0
    } else if x + 1 > 0 {
        # true
    } else {
        # unreached
    }
}

##  Defer:
#   Executes the statements at the end of the enclosing scope.
defer_example := proc() {
    defer { print("leaving defer_example(): 1\n"); }
    defer { print("leaving defer_example(): 2\n"); }

    print("A\n");
    loop i := 0; i < 3; i += 1 {
        defer { print("loop iteration\n"); }
        printi(i);
    }
    print("B\n");
}
# Output of defer_example():
#   A
#   0
#   loop iteration
#   1
#   loop iteration
#   2
#   loop iteration
#   B
#   leaving defer_example(): 2
#   leaving defer_example(): 1


[[ extern ]]
mem_alloc := proc (n: u64) : *u8;

### Polymorphism
#   Parametric polymorphism is done through the use of values known
#   at compile time, which includes type values.
#   Parameters that are used to polymorph a procedure or struct are declared
#   with a preceeding `%` character:

allocate := proc(%T: type, n: u32): *T {
    return cast(*T, mem_alloc(sizeof(T) * n));
}
call_allocate := proc() {
    ints   := allocate(s32, 10);
    floats := allocate(f32, 30);
}
#   a new version of `allocate()` is compiled for every value of `T` that gets passed to it.
#   The `allocate()` example is polymorphed on the _value_ of its first argument, which has type `type`.
#   However, polymorphism can also use the _type_ of the argument instead:

sum := proc(a: %T, b: T): T {
    return a + b;
}
call_sum := proc() {
    x := sum(1, 2);
    y := sum(4.56, 7.89);
}
#   Here, like `allocate`, one version of sum is compiled for integers,
#   and one for floats.
#   However in this case, `T` is derived from the _type_ of the first argument.

#   Structs can also be polymorphed:
Pair := struct(%T: type) {
    first:  T,
    second: T
}

uses_pair := proc() {
    int_pair:   Pair(s32);
    float_pair: Pair(f32);
}