Introduction
The Lumina Programming Language
Lumina is an eager-by-default natively compiled functional programming language with the core goals of readibility, practicality, compiler-driven development and simplicity.
It aims to be a high-level general-purpose language, but also support systems-level functionality such as raw pointer arithmetics to allow for high-level abstractions to be built on top of low-level high performance Lumina code.
Installation
Compiling from scratch
Clone the repository
$ git clone https://github.com/luminalang/lumina.git
Compile and install the compiler
$ cd lumina/
$ cargo build --release
$ sudo mv target/release/lumina /usr/bin/
Copy the luminapath directory containing the Lumina libraries to a suitable runtime folder and point the $LUMINAPATH environment variable to it.
$ cp -r luminapath/ $HOME/.local/share/lumina
# If you're using bash
$ echo "export LUMINAPATH=$HOME/.local/share/lumina/" >> $HOME/.bashrc
Compiling & Running Programs
The Lumina repository contains an example folder.
To run one of the examples
$ lumina run examples/hello-world
Hello World!
Or to compile to a binary
$ lumina build -o hello-world examples/hello-world
$ ./hello-world
Hello World!
Creating a Lumina Project
To create a new Lumina project, use
$ lumina init my-awesome-project/
$ cd my-awesome-project/
$ lumina run
Hello World!
Functions
Declaring Functions
Functions are defined using the fn keyword.
fn add x y as int, int -> int =
x + y
A function which takes two parameters, x and y of type int, then adds them together to return a single int
The type annotation is optional.
fn add x y = x + y
Although remember that type annotations often help as a form of documentation.
Calling Functions
White-space is used to separate the arguments to a function
fn main =
add 1 2
Parenthesis can also be used to 'group' expressions.
fn main =
std:io:println (add (add 1 2) (add 3 4))
A function adding numbers then printing them to the terminal
Pattern Parameters
The parameters in a function declaration may be any infallible pattern, not just plain identifiers.
fn add_pairs xy ab as (int, int), (int, int) -> (int, int) =
...
// can instead be written as
fn add_pairs (x, y) (a, b) as (int, int), (int, int) -> (int, int) =
(x + a, y + b)
fn main =
std:io:println (add_pairs (1, 2) (3, 4))
A function with two tuple parameters being pattern matched in the function declaration
Read more about patterns in the Pattern Matching & Conditionals chapter
Where-Bindings
A function may also be defined inside another function, of which it'll have access to its parent function's parameters.
fn main =
std:io:println (add 5 6)
where
fn add x y = x + y
A function declared inside another function as a where-binding
Operators
New operators can also be defined similarly to functions.
fn +++ left right as int, int -> int =
left + right + right + right
Types
Integer Types
| Size | Unsigned | Signed |
|---|---|---|
| 8 bits | u8 | i8 |
| 16 bits | u16 | i16 |
| 32 bits | u32 | i32 |
| 64 bits | u64 | i64 |
| Arch | uint | int |
Arch refers to that the size depends on the CPU architecture
Decimal Types
float is supported as a double-precision 64-bit floating point.
Bools
The bool type has either the value true or false
Arrays
Arrays are planned but currently not exposed to the user.
Prelude
The following types aren't builtins but are available in prelude by default.
type string // utf-8 encoded bytes
type List a // (or [a]) an efficient dynamic list
type Maybe a
type Result a err
type nothing
trait Num
trait Compare
trait ToString
string is incomplete and not yet validated as utf-8
Record types
Record types are types that contain other types as named fields.
Sometimes also called struct or product types.
type User {
name string
age int
}
// Construct a new record of type `User`
fn main =
{ User | name = "Jonas", age = 25 }
// Construct a new record of type `User`
//
// this time the type is inferred from the field names in scope
// instead of explicitly annotated.
fn main =
{ name = "Jonas", age = 25 }
Defining and constructing a record
Modifying Records
Records can also be constructed by changing some fields of an existing record.
But remember! Lumina is an immutable language, so this creates a new record while keeping the previous record the same.
fn rename user new as User, string -> User =
{ user ~ name = new }
// Is equivalent to:
fn rename user new as User, string -> User =
{ User | name = new, age = user.age }
Function returning a copy of a user with its name substituted
Sum Types
Sum types are types whose value is one out of a set of possible variants.
Sometimes called enum types.
// Define a sum-type whose value can be one of `Admin`, `Client` or `Guest`
type UserKind = Admin | Client | Guest
// Construct a new sum-type of type `UserKind`
fn main =
Admin
Variants of sum types can also have parameters of other types.
type UserKind
= Admin Department
| Client Company
| Guest
type Department = Accounting | Support
type Company {
name string
}
fn main =
Admin Accounting
// or perhaps ...
fn main =
Client { Company | name = "luminalang" }
Trait Types
TODO: explain traits, and pretend dynamically dispatched objects are normal, we can explain trait constraints later.
Generic Type Parameters
TODO: figure out how best to explain the practical use-cases and importance of generic type parameters.
Declared types can take generic type parameters.
type User item {
name string
age int
held item
}
fn main =
// Here we supple the type `string` as type parameter for `User`
// which replaces the `item` generic.
//
// Meaning that the value assigned to the field `held` should be of type `string`.
{ User string | name = "Jonas", age = 25, held = "Laptop" }
// A type which is either "just" a value or "nothing".
type Maybe value
= Nothing
| Just value
// Here we supply the type `int` as type parameter for `Maybe`
// which replaces the `value` generic.
//
// Meaning that the parameter to `Just` should be of type `int`.
fn just_five as Maybe int = Just 5
Two examples of defining a type with type parameters and then instantiating it.
*Since Maybe is known to be very useful, it's already defined in the Lumina standard library.
Evaluating Multiple Expressions
Let bindings
As a function grows larger, complex, or more and more nested. It can become difficult to read.
fn main =
add (add 1 2) (add 3 4)
A useful way to mitigate this is to seperate out the expressions into a sequence of steps.
let allows you to bind the result of an expression to a pattern (often an identifier).
fn main =
let x = add 1 2 in
let y = add 3 4 in
add x y
This also comes with the benefit of allowing you to name the result of an expression, which is important for readability.
The left side of a let binding can be any pattern, and not just an identifier.
fn main =
let (x, y) = (add 1 2, add 3 4)
in add x y
A let-binding with a tuple pattern binding to a tuple expression
Do expressions
Sometimes it's useful to run an expression for its side effects without using its return type.
In those cases, do...then notation works similarly to let except it always discards the value instead of binding it to a pattern.
fn main =
// Run an expression
do io:println "Starting Program..." then
0 // Then do something else to generate a value
// ... Is a clearer way of writing
fn main =
// Run an expression
let _ = io:println "Starting Program..." in
0 // Then do something else to generate a value
Pattern Matching & Conditionals
TODO: Explain the purpose of patterns, their distinction from expressions, and how pattern matching is a core tool of functional programming.
Pattern Matching with match
// Matching integers
fn check_integer n as int -> string =
match n
| 0 -> "zero"
| 1 -> "one"
| 2..9 -> "digit"
| _ -> "large number"
// Matching sum types
fn or default m as int, Maybe int -> int =
match m
| Nothing -> default
| Just n -> n
// Matching records
fn encode_user user as User -> string =
match user
| { kind = Admin, name, .. } -> "admin_" <++> name
| { kind = Guest, name, .. } -> "guest_" <++> name
// Type annotation is optional
| { User | kind = Guest, name, .. } -> "guest_" <++> name
// Matching strings
fn parse_user str as string -> (int, string) =
match str
| "id:" id " username:" username ->
(to_digit id, username)
| _ ->
crash ("parsing error: " <++> str)
// Matching lists
fn first_three list as [int] -> Maybe (int, int, int) =
match list
| [x, y, z : _rest] -> Just (x, y, z)
| _ -> Nothing
// Matching tuples
fn far_away position as (int, int) -> bool =
match position
| (100.., _) -> true
| (_, 100..) -> true
| (_, _) -> false
TODO: Should we show and explain string extractors here or under advanced features? Should probably be after partial application
If Expressions
fn can_drive age =
if age > 18
then "This person can own a drivers license"
else "This person can not own a drivers license"
Partial Application
A large part of why functional programming is so powerful is being able to conveniently pass around functions as if they're values.
This lets you create functions whose behavior is more generalised as a portion of the behavior can be passed down as a parameter.
The Closure Type
Among types such as int or (float, float), functions-as-values also have types in the form of closures.
fn(int, int -> int)
The type of a closure which expects two int parameters and returns an int
So for example;
fn change_if_just f m as fn(int -> int), Maybe int -> Maybe int =
match m
| Nothing -> Nothing
| Just n -> Just (f n)
A function which runs a function to change a value if it exists
The Magic # Unary Operator
To treat a function as if it's a value, the # symbol is used.
fn add_five_if_just m as Maybe int -> Maybe int =
change_if_just #add_five m
fn add_five x as int -> int =
x + 5
A function which adds 5 to an integer if it exists
The # symbol is a general-purpose way to pass various expressions as closures and can be used in a couple of different ways.
fn add x y as int, int -> int = x + y
// ... //
// turns the function into a closure of type
// fn(int, int -> int)
#add
// partially applys the function to create a closure with one less parameter
// fn(int -> int)
#(add 5)
// partially applys an operator to create a closure with a single parameter
// fn(int -> int)
#(+ 5)
// turn a literal value into a closure
// fn( -> int), can also be written as fn(int)
#5
With this in mind, we can rewrite the previous example as:
fn add_five_if_just m as Maybe int -> Maybe int =
change_if_just #(+ 5) m
A function which adds 5 to an integer if it exists
Anonymous Functions with Lambdas
If a function doesn't seem important enough to give it a name, we can inline it with a lambda.
fn main =
(\n -> n + 1) 5
Runs the inline function with the parameter 5 to create 6
Lambdas can also be passed as closures the same way as named functions.
fn add_five_if_just m as Maybe int -> Maybe int =
change_if_just #(\n -> n + 5) m
Partially Applicating Where-Bindings
TODO: Is it overly complicated and confusing to explain this here? Maybe we should have a separate design patterns chapter
A common design pattern is to partially apply where-bindings
fn add_five_if_just m as Maybe int -> Maybe int =
change_if_just #(add 5)
where
fn add x y = x + y
fn change_if_just f as fn(int -> int) -> Maybe int =
match m
| Nothing -> Nothing
| Just n -> Just (f n)