Coal

This repository is the home of the Coal programming language and compiler.

1. About
2. Documentation
3. Installation and setup
4. How to contribute
5. License

About

Coal is a declarative, statically typed, purely functional programming language with simple and intuitive syntax. It provides algebraic data types and pattern matching, extensible records, structural recursion, codata, and traits (type classes), among other features. Coal’s type system, like Haskell’s and ML’s, supports type inference and parametric polymorphism, drawing on the System-F lambda calculus. The Coal compiler is implemented in Haskell and targets LLVM for code generation. As a total language, Coal takes a different approach to recursion, following the motto that "recursion is the goto of functional programming." To guarantee that programs are provably terminating, recursion is only available in a restricted form, known as structural recursion. The language finds inspiration in ideas from the field of Mathematics of Program Construction, where streams and other infinite data types are described as coalgebras — hence the name Coal.

Documentation

The language documentation is available at: coal-lang.org

Installation and setup

The compiler has been tested on Linux and Mac OS.

Prerequisites

Haskell/GHC

A recent version of GHC is needed. It is recommended to install Haskell, GHC and Stack using the GHCup tool.

LLVM

An LLVM toolchain that provides llvm-as and llc (the LLVM static compiler) is also required.

Linux

• Debian/Ubuntu (or derivatives):

  sudo apt update
  sudo apt install llvm clang 
  

• Fedora, RHEL, or CentOS:

  sudo dnf install llvm clang
  

• Arch Linux:

  sudo pacman -S llvm
  

Mac OS

See Getting Started with the LLVM System, or install using Homebrew:

brew install llvm

Note: If you use Homebrew to install LLVM, you may need to add the binaries to your PATH manually.

Additional dependencies

• GCC (probably not needed on Mac)
• Boehm–Demers–Weiser garbage collector
• The GNU Multiple Precision Arithmetic Library

Linux

• Debian/Ubuntu (or derivatives):

  sudo apt update
  sudo apt install libgc-dev libgmp-dev build-essential
  

• Fedora, RHEL, or CentOS:

  sudo dnf install gc-devel gmp-devel gcc make
  

• Arch Linux:

  sudo pacman -S gc gmp base-devel
  

Mac OS

brew install bdw-gc gmp

Building the compiler

Clone the repository:

git clone ssh://git@codeberg.org/laserpants/coal.git

cd coal && stack install

Restart or refresh your shell, using e.g., exec $SHELL -l. To verify that the executable is installed, run:

coal --version

Hello, world!

module Main {
 import IO(println_string)
 fun main() =
 println_string("Hello, world!")
}

Save this program as "Main.coal". Compile the program with the command:

coal compile -I. Main.coal -o dist

How to contribute

This is an open and evolving project — contributions are welcome.

Bug reports

If you want to report a bug 🐞, open an issue with:

• A description of the problem
• Steps to reproduce it
• What you expected to happen
• What actually happened (including error messages)

If possible, include a small code example that demonstrates the issue — this makes debugging much easier.

Contributing code

If you want to work on a feature or bug fix, fork the repository and create a new branch for your work. Then submit a pull request with a description of:

• What you changed
• Why the change was made
• Relevant issue number (if any)

Contributing coffee

Buy me a coffee

Documentation

The documentation is built with MkDocs and the Material for MkDocs (mkdocs-material) theme. The source code is hosted at: github.com/laserpants/coal-docs.

License

This project is licensed under the terms of the MIT license. See the LICENSE file in this repository for details.