gleam Documentation

File: README.md Copy Chapter

Gleam is a friendly language for building type-safe systems that scale! For more
information see the website.

Support Gleam! Copy Chapter

Gleam is not owned by a corporation, instead it is kindly supported by its
sponsors. If you like Gleam please consider sponsoring the project or members
of the core team.

Thank you so much! 💖

File: compiler-wasm/README.md Copy Chapter

Compiler WASM

# Install the build tool with cargo or brew etc
cargo install wasm-pack

# Build the wasm library
wasm-pack build --release --target web

# Make a tarball to attach to a release
tar -C pkg/ -czvf gleam-v1.1.0-browser.tar.gz .

File: docs/compiler/README.md Copy Chapter

Compiler documentation

Hello! Welcome to the documentation for the Gleam compiler. I hope you have fun
with the project!

• Project structure
• Compilation flow
• Testing
  • Running the tests
  • Snapshot testing

Project structure Copy Chapter

The project is made up of several Rust crates (projects):

• compiler-core: This project parses, analyses, and compiles Gleam projects.
  It is entirely pure and has no IO so that is provided by the other Rust crates
  that wrap this one.
• language-server: This project contains code for the Gleam language server,
  including autocomplete, code actions, hover and other features.
• compiler-cli: A command line interface that wraps the core compiler and
  language server, providing IO to files and to the console.
• compiler-wasm: A JavaScript interface to the core compiler via web assembly.
  Suitable for running in a web browser.

In addition to the Rust code there are these components:

• Makefile: A makefile that defines shortcut commands for common tasks when
  working in the Gleam codebase. Run make help to view them.
• test: A collection of (mostly) Gleam projects that serve as integration tests for the
  compiler.
• deny.toml: Configuration for the cargo-deny tool which is used to ensure
  that the Rust libraries the compiler depends on adhere to our expectations.
• containers: A collection of docker-files used to produce OCI containers for
  each Gleam release.
• .github/workflows: GitHub Actions workflow definitions, used to build, test,
  and release new versions of the project.
• docs: You're looking at it pal.

Compilation flow Copy Chapter

The process for compiling Gleam modules within the compiler looks roughly like
this:

Gleam source code       .cache binaries
          ▼                         ▼
┌────────────────────┐ ┌───────────────────────┐
│       Parser       │ │ Metadata deserializer │
└────────────────────┘ └───────────────────────┘
          │                         │
      Untyped AST            Module metadata
          └─────────┐   ┌────────┘     │
                    ▼   ▼              │
           ┌─────────────────────┐     │
           │  Dependency sorter  │     │
           └─────────────────────┘     │
                      │                │
                 Untyped AST           │
              (sorted by deps)         │
                      ▼                │
            ┌───────────────────┐      │
            │   Type checker    │◄─────┘
            └───────────────────┘
                      │
          ┌────── Typed AST ──────┐
          ▼                       ▼
┌────────────────────┐ ┌─────────────────────┐
│   Code generator   │ │ Metadata serializer │
└────────────────────┘ └─────────────────────┘
          │                       │
          │                       ▼
 Erlang or JavaScript   .cache binaries
   printing algebra
          ▼
┌────────────────────┐
│   Pretty printer   │
└────────────────────┘
          │
          ▼
 Erlang or JavaScript
     source code

Testing Copy Chapter

We like automated tests! They're a great way to verify that the compiler is
doing what we expect it do as we make changes.

Running the tests Copy Section

• make test: Run all the tests. Worth doing before committing any changes.
• make test-watch: Run the Rust unit tests when files are saved.
• make language-test: Run the cross-platform language integration tests in
  test/language.
• make language-test-watch: Run said tests when files are saved.
• make javascript-prelude-test: Run the unit tests for the JavaScript code
  that implements the Gleam prelude when compiling to JavaScript.
• make javascript-prelude-test-watch: Run said tests when files are saved.

The *-watch commands require the watchexec program to be
installed.

Snapshot testing Copy Section

The compiler makes heavy use of snapshot testing using the
cargo-insta tool.

If you're not familiar with snapshot testing instead of writing an input and an
expected output (as in normal example based tests) you write only the input. The
snapshot testing tool can then be used to mark any new outputs as accepted and
saved into the repository as snap files. If an output for one of the tests
changes then it is considered a failed test and the programmer has the option to
either reject the new version (as it is an incorrect result) or accept it as the
new correct output.

This style of testing saves us huge amounts of time as manually updating all the
expected output when we make changes to the output format of the compiler or
error messaging is time-consuming and very dull. With snapshot testing it takes
seconds.

# Run the tests
make test

# Interactively verify changes to the snapshots
cargo insta review

File: docs/annoyances.md Copy Chapter

Annoyances

This document contains a list of issues and annoyances that we have writing
Gleam code today, so that we can devise solutions to them in future.

There are other annoyances that have known solutions that are yet to be
implemented. These are tracked in the Gleam issue tracker instead.

Bundling compiled JavaScript is non-obvious Copy Chapter

Cannot shift repeated work to compile or initialise time Copy Chapter

For example, regex compilation.

JavaScript custom type representation could be faster Copy Chapter

There's performance improvements to be had. Would would be optimal?

File: docs/runtime-errors.md Copy Chapter

Runtime errors

There are several runtime errors that Gleam code can throw. This documentation
lists them and their runtime properties.

On Erlang runtime errors are Erlang maps thrown with erlang:error/1, having at
least these properties:

On JavaScript runtime errors are instances of the JavaScript Error class,
having at least these properties added to them:

Todo Copy Chapter

A panic that indicates that the code has not yet been completed, intended for
use in development.

todo
todo as "some message"

Panic Copy Chapter

An explicit panic to unconditionally error.

panic
panic as "some message"

Let assert Copy Chapter

An inexhaustive pattern match, erroring if the pattern does not match.

let assert Ok(x) = something()
let assert Error(e) = something() as "This should fail"

Assert Copy Chapter

An assertion of a boolean value.

The error format of assert differs based on the expression that is asserted.
It always has these fields:

But, depending on the expression that was asserted, it contains additional
information which can be used to diagnose the error.

Binary operators Copy Section

assert level >= 30

Function calls Copy Section

assert check_some_property(a, b, c)

Other expressions Copy Section

assert other_expression

The expression maps have this structure:

If the expression is a literal, such as True or 15, it will have the literal
kind. This signals that its value is not runtime dependent, and may not need to
be printed.

If the expression is on the right hand side of a short-circuiting operator, like
|| or &&, it might not be evaluated. If the operator short-circuits, the right
hand side expression will have kind unevaluated.

File: test-community-packages/README.md Copy Chapter

test_community_packages

gleam add test_community_packages

import test_community_packages

pub fn main() {
  // TODO: An example of the project in use
}

Further documentation can be found at https://test-community-packages.hexdocs.pm.

Development Copy Chapter

gleam run   # Run the project
gleam test  # Run the tests
gleam shell # Run an Erlang shell