Programming in Lensor Glint

Glint started in 2023 when Lens_r decided he wanted to make a compiler, from scratch, for fun. That compiler needed to compile a language, and so he made one up. At first, it had no name, and was referred to as "the language the FUNCompiler compiles"; as you may have guessed, that grew tedious rather fast, and we needed a name.

That's when Glint got it's name: Intercept. Yes, it was named something else for the first year or so. It was renamed Glint when the language itself was cleaned up and made more opinionated toward important design goals, and the language kind of outgrew it's initial version, looking nothing like it used to (and as such, felt deserving of a new name).

The hope is that, even if this language doesn't change your perceptions entirely, or blow your mind, you'll be able to see a glint of promise in an otherwise dark world :^).

A Glint program consists of:

Header

The first portion of the file designates module status and imported dependencies.

Comments

Non-code portions of the file that are used to describe, annotate, and document the code portions of the file. Comments begin at ;; and go until a newline or EOF.

Expressions

Code portions of the file that are used to tell the computer what to do; they are said to "return" a value of some type upon evaluation/execution.

 1: ;; Declare some variables with initial values.
 2: a : int 42;
 3: b : byte 27;
 4: 
 5: ;; @returns the sum of parameters x and y.
 6: foo : int(x : int, y : int)
 7:   x + y; ;; adds x and y
 8: 
 9: ;; Invocation of function foo with parameters a and b.
10: foo a, b;

The following questions relate to the above example. If you don't know the answer to one, just keep reading and move on, it's okay; you can come back whenever you are ready.

1. On what line does the first expression appear?
2. On what line does the comment with an @ directive appear?
3. Is there an expression on line 7?
4. What would the result of the entire program be?
5. Is there a comment on line 7?

Extra credit:

1. How many parameters does foo take?
2. What kind of type is foo of?

Glint supports decimal, hexadecimal, octal, and binary integer literal formats; all except decimal are accessible through a special prefix that begins with 0. A decimal number literal may not begin with 0.

A hexadecimal number literal is prefixed with 0x. 0xf has the value of f in hexadecimal, or 15 in decimal.

An octal number literal is prefixed with 0o. 0o25 has the value of 25 in octal, or 21 in decimal.

A binary number literal is prefixed with 0b. 0b10 has the value of 10 in binary, or 2 in decimal.

Integer literals are always of int type.

Glint makes no distinction between character and integer data types (unlike Pascal, and like C).

Glint provides a way to get the encoded byte value of a character as an integer value in the program, and that is to wrap the character in ` (back-ticks).

`0` is equivalent to 48.

Often, it can be messy to have control characters appear in the source code, so Glint provides an "escape" syntax, such that other, non-control characters may represent the control characters.

Relevant escape characters include \n for a line feed, \\ for a \ (backslash), and \t for a tab stop.

Byte literals are always of byte type.

Logical values that denote veracity of an expression.

true and false keywords to access these values.

Boolean values are always of s1 (one-bit signed integer) type.

A string allows the Glint programmer to include (textual) data directly from the source code into the final program as an array of byte values.

Inescapable strings are wrapped with ' (U+0027, apostrophe), and escape-able strings with " (U+0022, quotation mark).

An inescapable string will contain the contents between the two ' (apostrophes), verbatim. \ is not special within an inescapable string. An inescapable string may span any amount of newlines.

'foo\n' -> [102, 111, 111, 92, 110, 0]

An escape-able string accepts the "escape" syntax that byte literals also accept.

"foo\n" -> [102, 111, 111, 10, 0]

For historical reasons, and compatibility with other languages and tooling, Glint strings have a NUL byte (value of zero) appended. So, the empty string literal '' contains the bytes [0], and is of type [byte 1].

String literals are always a fixed array of byte, with the length set long enough to store the string and the implicit NUL byte.

A declaration expression may take on several different forms. All of these forms accomplish the same thing (declaring a variable), but in different ways and with different requirements.

The most standard form of declaration expression is an explicitly-typed variable.

x : int;

This sort of expression may be read as, "x is an integer".

This form may be built upon to include an initializing expression, placed directly after the type expression. In this way, it is equivalent in syntax to an explicit cast expression preceded by an identifier.

x : int 69;

This may be read as, "x is an integer with the value sixty-nine".

There is another form of declaration, though, that allows us to shorten a lot of code, and reduce duplicated type names in declarations: the type-inferred declaration expression form.

x :: 69;

This may be read as "x has the value of 69". The type of x will be set to whatever the type of the initializing expression is (in this case, int).

Uninitialized variables are default initialized, which, for the most part, means they have a value of zero (except for dynamic arrays, but, we'll get to that).

One of the more confusing parts of any type system is declaration type decay; as long as you aren't doing anything too weird, you'll never run into problems. But, if you are trying to pass functions as parameters to other functions, it becomes relevant. For now, just understand that some types are quite complex in Glint, but quite simple in the underlying implementation, and that means that sometimes you want the simple underlying implementation rather than all the complexities that come with the Glint type (if that makes any sense).

A scope is a concept of a meaningful collection of declarations. For example, the body of a function is within a new scope, such that any variable declarations are not accessible from outside the function.

A Glint programmer may open a scope manually by using a block expression; the contents of which is within a new scope.

Whenever a new scope is created (or opened), it is given a parent scope; if a name lookup doesn't match in the enclosing scope, the parent will be searched until either the name is found or there are no more parent scopes.

x : int;

{
  y : int;
}

y; ;; Error! Unknown symbol y'

The scope structure of the above program might look something like the following. (NOTE: Simplification for explanation purposes: leaves out global and top level scope).

root
|-- x
`--block
   `-- y

When we "exit" the block expression, the scope is exited as well; further expressions are once again within the parent scope.

If we were to lookup x from the block scope, we would not find it in the enclosing scope, search the parent (root), and find it. This means that x is accessible from the block scope, and it would not be an error to use it there.

On the contrary, if we were to lookup y from the root scope, we would again not find it in the enclosing scope; but, there is no parent of the root scope, so we are done searching. Because we exhausted the search of scopes and did not find a matching declaration, that means this symbol is not valid at this point in the program. That is why the above use of y, outside of the block expression, is invalid.

In Glint, shadowing is not allowed, so you cannot actually declare a variable of the same name as another if both would be valid at that point.

x : int;
{ x : int; } ;; Error! Redeclaration of 'x'

The following is a non-exhaustive list of expressions which have containing expressions that are parsed in a different scope.

• Block Expression
• If Expression
• Else Clause
• For/CFor
• Function Body
• Each Match Expression

Assignment is the operation of setting a variable's value, such that further accesses to the variable result in the set value. Assignment uses the := operator (like Pascal). Assignment destructively modifies the values in memory associated with the given variable. After assignment, any value that was held in the memory before the assignment is destroyed, and can not be accessed.

x : int;

;; This is an assignment!
x := 69;

Often, you want to use the variable itself in the calculation of the new value of the variable; there are short-hands for lots of operations mixed with assignment.

x :: 42;
x += 27; ;; Now, x = 69

Exercise Mission

• Recognize declarations of any form.
• Differentiate variable names, types, and initializing expressions.
• Reason about the values variables have at different points in the control flow of the program.

x : int;
y : int = 420;

;; y := y - x;
y -= x;

x := 351;

z :: y - x;

The following questions relate to the above example.

1. What is the name of the first variable declared?
2. How many variables are declared?
3. What is the value of variable 'y' when the program starts, and when the program finishes?
4. What is the initial value of 'z'?
5. What is the type of 'z'?
6. What is the value of the variable 'x' when the program starts, and when the program finishes?

Glint programs often need to do basic math; for this, there are the arithmetic operators. These include the standard addition (+), subtraction (- ), multiplication (*), division (/), and modulo (%).

On computers, data is represented as bits. Bitwise operations allow you to operate directly on the data bits, rather than on sets of bits with some applied semantics (i.e. an 8-bit signed byte). Bitwise operations include AND, OR, XOR, and NOT.

In Glint, the philosophy is that you should have to write less code when you can. That means that, as long as everything is clear to the compiler, you don't need to mark up your program with meaning that is already implied. This reduces the code the Glint programmer has to write, and, in turn, reduces chances that they may introduce a bug.

An integer is implicitly convertible to a boolean, and vice versa.

For integer to integer casts, it is valid if the bitwidth we are casting from is less than or equal to the bitwidth we are casting to, OR, if the values are known at compile time, if data is preserved through performing the cast.

A struct is implicitly convertible to any supplanted member.

A fixed array is implicitly convertible to an array view.

A dynamic array is implicitly convertible to an array view.

Functions are implicitly convertible to their corresponding function pointers.

Functions with no parameters are implicitly convertible to their return type.

Pointers are convertible to void.ptr.

To treat a variable's memory as if it were of another type, you can explicitly cast a value. To do this, simply invoke the type with a single argument of the type you'd like to cast.

To cast integer 42 to byte:

byte 42;

TODO

TODO

A fixed array has the amount of elements known at compile-time. This means that the compiler is able to check every compile-time known subscript to be in range. You should use this type of array if the amount of elements never changes.

The type of a string literal is a fixed array with an element type of byte. The size of the fixed array is the amount of bytes needed to contain the contents of the string literal, plus one for the implicit terminating NUL byte.

A dynamic array may have any amount of elements; any given instance of a dynamic array type stores a value regarding it's size.

A dynamic array's data pointer is initialized using the return value of malloc (A function provided by the C standard library). Glint is (mainly) intended to write userspace programs, and as such defaults to defining main (such that a C runtime may call it). Therefore, Glint implementations may rely on the presence of any C runtime functions (like malloc) to implement their features.

That's right! Dynamic arrays are always default initialized, and data always points to some memory of size capacity * byte_size_of_element_type.

Therefore, the elements of a dynamic array are available via a subscriptable pointer at the data member. The first element of dynamic array d is accessible via @d.data[0]; there is a short-hand that subscripting a dynamic array directly is equivalent to subscripting it's data member. That means the first element is usually accessed using @d[0].

You can think of a dynamic array type as a shorthand for defining the following struct, where T is the element type of the dynamic array.

[T];
;; equivalent to
struct {
  data : T.ptr;
  size : uint;
  capacity : uint;
};

Where size is the first invalid index at data. capacity refers to the size of memory located at data. If the memory at data is not large enough to store an inserted element, data is reallocated and all of the old elements are copied to the new memory.

An element may be prepended to (added to the front of) a dynamic array using the ~= operator.

d : [byte];
d ~= `9`;
d ~= `6`;

;; Outputs 69, then a newline
print d, `\n`;

An element may be appended to (added to the back of) a dynamic array using the += operator.

d : [byte];
d += `6`;
d += `9`;

;; Outputs 69, then a newline
print d, `\n`;

Finally, when a dynamic array is declared, memory is allocated; that means that, after the dynamic array is done being used, the programmer must free it by using the unary minus operator -.

d : [byte];
d += `6`;
d += `9`;

;; Outputs 69, then a newline
print d, `\n`;

;; Free the memory associated with the dynamic array.
-d;
;; Any further uses of 'd' would be a program error reported by the
;; compiler.

A dynamic array is compatible with a ranged for loop expression (more on that later).

You can think of a view type as a shorthand for defining the following struct, where T is the element type.

[T view];
;; equivalent to
struct {
  data : T.ptr;
  size : uint;
};

A view is meant to act as the minimal representation of a contiguous set of elements of a given type; it contains a pointer to the contiguous memory where all the elements are stored, as well as a value denoting how many elements are stored there.

A view is compatible with a ranged for loop expression (more on that later).

if evaluates a condition expression, and, if the result is truthy, evaluates a body expression. Optionally, when an else clause is present, a different body expression will be evaluated if the result of evaluating the condition expression is falsy.

if condition, body;

if condition,
  then
else otherwise;

while evaluates a condition expression, and, if the result is truthy, evaluates a body expression. After evaluating the body expression, it will jump back to evaluating the condition expression.

while condition, body;

for is a loop structure that will iterate over anything with data and size members (like dynamic arrays or array views). It provides a reference to the corresponding element for each iteration.

for element in container, body;

cfor is a control structure that mimics C's for.

cfor init; condition; increment; body;

match selects a control flow depending on which member of a sum type is held.

match must handle every possible member a sum type may have.

match value_of_sum_type, {
  .member0 expr;
  .member1 expr;
};

The most important declared type there is, the struct. A struct is a way to group other types together in memory, and reference each type's value by a name.

struct {
  x : int;
  y : uint;
};

Given an instance of the above struct, setting the value of x would not alter the value of y, and vice versa. They are unique, named points in memory.

To access these points, you use the member access operator, ., with the object you are trying to access on the left hand side, and the name of the member you are trying to reference on the right hand side. A member access, as it references a unique point in memory, may be assigned to.

A :: struct {
  x : int;
  y : int;
};

foo : A;

foo.x := 70;
foo.y := -1;

foo.x + foo.y;

A union is a way to store multiple types in one place in memory. A union is only as big as it's largest member.

union {
  x : int;
  y : uint;
};

Given an instance of the above struct, setting the value of x would alter the value of y, and vice versa. They are named points in memory, but they are not unique. You could say a union gives multiple names to the same position in memory.

If you can't picture why that'd be useful, then you don't ever need to use unions; they are really just there so that people who want to solve problems a certain way are able to do it that way.

Enumerations, often shortened to just enums, are named constant values.

Let's say you wanted the number 1 to be called Success, and the number 7 to be called Erased, to make your Glint code more readable, or understandable.

Code :: enum(int) {
  Success :: 1;
  Erased :: 7;
};

Code.Success; ;; = 1
Code.Erased; ;; = 7

Enumerators (in Glint) are just named constants. As such, the values of an enumerator must be known at compile time. The underlying value type may be specified within parentheses.

If you come from Rust (you crustacean, you), see sum types for what you may call enums. If you come from C or C++, not too much has changed.

A sum is a way to store one of a group of types in one position.

A sum type is a lot like a union, except that when you access a member of a sum type, it is verified that the member you are accessing is actually currently stored in the memory where that member is stored. You see, each member of a sum type is stored at the same position in memory (like a union), but the sum type also keeps track of what member was last assigned to, and, as such, what kind of value is stored in it's member memory.

sum {
  x : int;
  y : int;
  z : byte;
};

Given an instance of the above struct, setting the value of x would alter the value of y, and vice versa. The catch is that, you would never be able to access y after setting x; doing so would actually cause the program to exit.

A :: sum {
  x : int;
  y : byte;
};

foo : A;
foo.x; ;; program exits here

The only way to get your Glint program to continue execution when accessing a sum's member is to access the right one. The right one is whichever one is currently stored in the sum type. Note that this is NOT calculated at compile-time; each sum type stores a value in the computer's memory at run-time indicating which member is valid (if any). The compiler automatically generates code to update this value accordingly whenever assigning to any sum type's member.

A :: sum {
  x : int;
  y : byte;
};

foo : A;
foo.x := 69;
foo.y; ;; program exits here

A :: sum {
  x : int;
  y : byte;
};

foo : A;
foo.x := 69;
foo.y := foo.x;
foo.y;
foo.x; ;; program exits here

The members of a given instance of a sum type may not co-exist at any one time. However, over the "lifetime" of an instance of a sum type, any amount of members may be valid.

You may query if a given member is valid using the has unary prefix operator.

A :: sum {
  x : int;
  y : byte;
};

foo : A;
foo.x := 69;
foo.y := foo.x;

out : int;

if (has foo.x), out := foo.x;
if (has foo.y), out := foo.y;

out;

To avoid long chains of if expressions used in conjunction with has, as seen above, the match expression may be used in turn. In fact, there are more benefits to using match, such as compile-time guarantee that every possible member has a control flow to handle it.

A :: sum {
  x : int;
  y : byte;
};

foo : A;
foo.x := 69;
foo.y := foo.x;

match foo, {
  .x out := foo.x;
  .y out := foo.y;
};

The match expression will execute exactly one of it's named body expressions: the one matching the name of the value currently stored in the instance of the given sum type.

The program would not compile if there were no body expression named x or if there were no body expression named y; every declared member within the sum type must have an expression associated with it in a match expression on that sum type.

A Glint program is a collection of Glint source code that may be compiled and linked to an executable. A Glint program may import Glint modules.

A Glint module is a collection of Glint source code that does not compile to executable, but rather a library. This library then may be used by a linker to include it's code in a separate executable. This library is also used by the Glint compiler to resolve the Glint module's metadata that produced it when compiling code that imports the module.

Programs and modules may import modules, but neither programs nor modules may import programs.

A Glint module may export any amount of variables, such that those variables are accessible by any Glint program or module that imports the module. This is done via the export keyword, a storage specifier. Storage specifiers come before the name, within a declaration expression.

module Foo;

export foo : int 69;

Within Glint, you may now put import Foo; at the top of a file, and subsequent expressions will execute as if foo : int 69; was at the top of the file (but without having to execute any code for that to happen!).

In practice, this most often makes the symbol associated with the variable "visible" to the linker in the generated object file. This means that other object files may reference the symbol to access, operate on, and interact with the variable.

import Foo;

foo; ;; equals int 69

TODO: Mention Glint compiler not being able to find module metadata.

You can make a pointer to any type by appending .ptr.

This is a pointer to a signed integer type.

int.ptr;

Pointers may be loaded from, which yields the underlying type.

value : int
  69;
pointer : int.ptr
  &value;
loaded_value : int
  @pointer;

Pointers may be stored into, which destrucively modifies the underlying value.

value : int
  69;
pointer : int.ptr
  &value;

@pointer := 420;

value = 69; ;; false!!!

As you can see, a pointer doesn't store an int value, it stores somewhere an int may be found (upon loading from it). This also lets you change the value where that int may be found (upon storing into it).

You can make a reference to almost any type by appending .ref.

This is a reference to a signed integer type.

int.ref;

Like a pointer, a reference doesn't store the underlying value, but a location where that value may be found. The difference is that a reference does not require explicit loading and storing via the @ operator; you can just use it like it's the underlying type.

value : int
  69;

reference : int.ref
  &value;

reference -= 27;

value = 42; ;; true!!!

reference_example : uint()

A struct type is a sequential set of typed values that may be accessed via a given name. These are called the struct's members.

For an instance of the following struct…

struct {
  x : int;
  y : uint;
};

If x was modified, y would be unchanged, and vice versa. A struct may have as many members as you could feasibly want, and their types are not required to be unique. You may have two int typed values in one struct with different names.

A union type is an non-type-safe way of converting between types. A union declaration looks a lot like a struct, but the underlying semantics are very different. For one, a union is only large enough to store it's largest member, and all the members share an address. This means that, if one member is changed, all the others are destructively modified! For most use cases, you should use a sum type instead. But, this is here if you know what you are doing and need to do it your way. You are the Glint programmer, after all, you are in total control.

For a real world use case: use unions to convert between a type and it's binary format easily.

union {
  value : int;
  bytes : [byte (sizeof int)];
};

A sum type is a type-safe way of storing a group of types in one location. A sum type may only have one of it's members valid at a time, and, each time an access is performed, Glint will safely (and forcefully) exit the program before any memory errors may occur iff the access is not to the valid member.

A sum type's members are much like a union type's: only one member is valid at a given point in the program, and all the members share an address. However, the sum type has a hidden tag value that stores which member is currently valid (if any). Whenever an access occurs, this tag may be checked against, and an access to an invalid value will error. This means that sum types do not allow you to convert between types, like a union, but they do allow you to have one variable have "one of a group of" types.

Bit alignment is not something that is supported by any real machine or language. By definition, a byte is the minimum addressable unit in any computer. So, when it comes to alignment of an address, bytes are relevant. However, when it comes to the size of a type in Glint, bits are definitely relevant, since you may have a u27 or a s42.

fib : uint(n : uint) {
  if n <= 1, return n;
  (fib n - 1) + (fib n - 2);
};

;; Calculate 7th number in the Fibonacci sequence, and return that.
fib 7;

Writing this example actually caught a bug in the compiler implementation regarding IR generation; see commit 9d152973, if interested.