linear-base

# Linear base

[![License MIT](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://github.com/tweag/linear-base/blob/master/LICENSE)
[![Hackage](https://img.shields.io/hackage/v/linear-base.svg?style=flat&color=brightgreen)][hackage-pkg]
[![Stackage](https://stackage.org/package/linear-base/badge/nightly)][stackage-pkg]
[![Discord](https://img.shields.io/badge/Discord-100000?style=flat&logo=Discord&logoColor=C3C3C3&labelColor=4179DA&color=010101)][discord]

Linear base is a standard library for developing applications with linear
types. It is named `linear-base` to be an analog to the original [`base`]
package that ships with GHC.

The purpose of `linear-base` is to provide the minimal facilities you need to
write _practical_ Linear Haskell code, i.e., Haskell code that uses the
`-XLinearTypes` language extension.

## Motivation

_Why do you need `linear-base` to write linear projects?_

1. Data types, functions and classes in `base` are not linear types
  aware. For instance, if `n` is a linearly-bound `Int`, the RHS of
  a definition cannot write `n + 1` — this will not type check. We
  need linear variants of `Num`, `Functor`s, `Monad`s, `($)`, etc.

2. This library exports new abstractions that leverage linear types
  for resource safety or performance. For example, there are new APIs
  for file and socket I/O as well as for safe in-place mutation of
  arrays.

## Getting started

`-XLinearTypes` is released with GHC 9, and `linear-base` is released
on [Hackage][hackage-pkg] and [Stackage][stackage-pkg].

All source files with linear types need a language extension pragma at
the top:

```
{-# LANGUAGE LinearTypes #-}
```

To get in touch, you can join our
[![Discord](https://img.shields.io/badge/Discord-100000?style=flat&logo=Discord&logoColor=C3C3C3&labelColor=4179DA&color=010101)][discord] server


## User Guide

If you already know what `-XLinearTypes` does and what the linear
arrow `a %1-> b` means, then read the [User Guide] and explore the
[`examples/`](https://github.com/tweag/linear-base/blob/master/examples) folder to know how to use `linear-base`.

You can also find a table comparing `base` and `linear-base` typeclasses
[here](https://github.com/tweag/linear-base/blob/master/docs/CLASS_TABLE.md).

## Learning about `-XLinearTypes`

If you're a Haskeller who hasn't written any Linear Haskell code, don't fear!
There are plenty of excellent resources and examples to help you.

### Tutorials and examples

 * See the [`examples/`](https://github.com/tweag/linear-base/blob/master/examples) folder.
 * [Linear examples on watertight 3D models](https://github.com/gelisam/linear-examples)

### Reading material

  * There is a [wiki page](https://gitlab.haskell.org/ghc/ghc/-/wikis/linear-types).
  * Key Blog posts
    * [Predictable performance](https://www.tweag.io/posts/2017-03-13-linear-types.html) (the first blog post from Tweag on this)
    * [IO State Transitions](https://www.tweag.io/posts/2017-08-03-linear-typestates.htm