BSD-3-Clause licensed by Patrick Bahr
Maintained by Patrick Bahr
This version can be pinned in stack with:Rattus-0.5.1@sha256:f86f332d0add2209d40ddc4feabe49c22e5e3a0cb9e4470011c5999dc0579d33,6956

This library implements the Rattus programming language as an embedded DSL. To this end the library provides a GHC plugin that performs the additional checks that are necessary for Rattus. What follows is a brief introduction to the language and its usage. A more detailed introduction can be found in this paper.

Rattus is a functional reactive programming (FRP) language that uses modal types to ensure operational properties that are crucial for reactive programs: productivity (in each computation step, the program makes progress), causality (output depends only on current and earlier input), and no implicit space leaks (programs do not implicitly retain memory over time).

To ensure these properties, Rattus uses the type modality O to express the concept of time at the type level. Intuitively speaking, a value of type O a represents a computation that will produce a value of type a in the next time step. Additionally, the language also features the Box type modality. A value of type Box a is a time-independent computation that can be executed at any time to produce a value of type a.

For example, the type of streams is defined as

data Str a = a ::: (O (Str a))

So the head of the stream is available now, but its tail is only available in the next time step. Writing a map function for this type of streams, requires us to use the Box modality:

map :: Box (a -> b) -> Str a -> Str b
map f (x ::: xs) = unbox f x ::: delay (map f (adv xs))

This makes sure that the function f that we give to map is available at any time in the future.

The core of the language is defined in the module Rattus.Primitives. Note that the operations on O and Box have non-standard typing rules. Therefore, this library provides a compiler plugin that checks these non-standard typing rules. To write Rattus programs, one must enable this plugin via the GHC option -fplugin=Rattus.Plugin, e.g. by including the following line in the source file:

{-# OPTIONS -fplugin=Rattus.Plugin #-}

In addition, one must annotate the functions that are written in Rattus:

{-# ANN myFunction Rattus #-}

Or annotate the whole module as a Rattus module:

{-# ANN module Rattus #-}

Below is a minimal Rattus program using the Rattus.Stream module for programming with streams:

{-# OPTIONS -fplugin=Rattus.Plugin #-}

import Rattus
import Rattus.Stream

{-# ANN sums Rattus #-}
sums :: Str Int -> Str Int
sums = scan (box (+)) 0

The source code of the Rattus.Stream module provides more examples on how to program in Rattus.

Changes

0.5.0.1

Compatibility with GHC 9.2.1

0.5

The typing rules for delay, functions, and guarded recursion have been simplified and generalised. Instead of just one tick, Rattus now allows an arbitrary number of ticks as well as function definitions in the scope of ticks. In practical terms, this means the following:

  • As before, delays can be nested arbitrarily and function definitions may occur under arbitrarily many delays.
  • But now the scope of a delay is no longer interrupted by a nested delay or function definition.

0.4

More general typing rules for delay, functions, and guarded recursion:

  • delay and function definitions may now occur under a delay.
  • Guarded recursive calls may occur at any time in the future – not only exactly one time step into the future.
  • As before, adv and recursive calls may only occur directly in the scope of delay. The scope of a delay is interrupted by adv, box, guarded recursive definitions, and function definitions.

Changes in the library:

  • Rename applicative-style operators to avoid clash with Haskell’s <*> operator.
  • Rename types: Event -> Future; Events -> Event

0.3.1

Guarded recursive types Str and Event are now fully strict (i.e. in particular, they are strict in the component that is of a later type) as they should be.

0.3

Rattus code is now checked just after GHC’s type checking phase (instead of after desugaring to Core). As a consequence, error messages for some corner cases are much improved and we don’t need to use the -g2 compiler option anymore to get good error messages.

0.2

  • the use of lazy data structures will now cause a warning (can be disabled by ‘AllowLazyData’ annotation); this check for lazy data is rather ad hoc and needs to be refined
  • allow functions under ticks (but with limitations, see paper)
  • strictness transformation is now similar to the ‘Strict’ language extension
  • optimisations using custom rewrite rules

0.1.1.0

  • allow mutual guarded recursion
  • improve type error messages

0.1.0.0

initial release