Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
https://github.com/ivanperez-keera/Yampa

Functional Reactive Programming domain-specific language for efficient hybrid systems
https://github.com/ivanperez-keera/Yampa
android frp functional-reactive-programming game haskell ios ipad iphone mobile multimedia opengl sdl yampa
Last synced: about 2 months ago
JSON representation
Functional Reactive Programming domain-specific language for efficient hybrid systems
Host: GitHub
URL: https://github.com/ivanperez-keera/Yampa
Owner: ivanperez-keera
Created: 2014-02-10T08:36:41.000Z (over 10 years ago)
Default Branch: develop
Last Pushed: 2024-04-08T09:21:17.000Z (about 2 months ago)
Last Synced: 2024-04-09T09:34:56.176Z (about 2 months ago)
Topics: android, frp, functional-reactive-programming, game, haskell, ios, ipad, iphone, mobile, multimedia, opengl, sdl, yampa
Language: Haskell
Homepage:
Size: 5.27 MB
Stars: 415
Watchers: 19
Forks: 49
Open Issues: 1
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
Lists

awesome-readme - ivanperez-keera/Yampa - Clear description. Feature list. TOC for easy navigation. Simple install instructions. Usage code samples. Project samples with GIFs and links to app stores. Documentation and publications. Clear development / contribution rules. (Examples)
fucking-awesome-readme - ivanperez-keera/Yampa - Clear description. Feature list. TOC for easy navigation. Simple install instructions. Usage code samples. Project samples with GIFs and links to app stores. Documentation and publications. Clear development / contribution rules. (Examples)
my-awesome - ivanperez-keera/Yampa - reactive-programming,game,haskell,ios,ipad,iphone,mobile,multimedia,opengl,sdl,yampa pushed_at:2024-04 star:0.4k fork:0.0k Functional Reactive Programming domain-specific language for efficient hybrid systems (Haskell)
README

        


# Yampa

[![Build Status](https://api.travis-ci.com/ivanperez-keera/Yampa.svg?branch=master)](https://app.travis-ci.com/github/ivanperez-keera/Yampa)

[![Version on Hackage](https://img.shields.io/hackage/v/Yampa.svg)](https://hackage.haskell.org/package/Yampa)

Domain-specific language embedded in Haskell for programming hybrid (mixed

discrete-time and continuous-time) systems. Yampa is based on the concepts of

Functional Reactive Programming (FRP).

[Installation](#installation) •

[Examples](#examples) •

[Related projects](#related-projects) •

[Documentation](#documentation) •

[Contributions](#contributions) •

[History](#history)



## Features

- Implements Functional Reactive Programming.

- Allows for dynamic programs whose structure changes over time.

- Isolates of effect-free signal functions from effectful actions.

- Runs fast and is memory efficient.

- Has been industry tested.

- Provides a robust, elegant, stable interface.

- Has well-defined semantics.

- Supports applicative, functional and arrowized styles.

- Supports all platforms and enjoys multiple backends.

- Programs can be tested with QuickCheck and debugged using Haskell Titan.

## Table of Contents

- [Installation](#installation)

  - [Pre-requisites](#pre-requisites)

  - [Compilation](#compilation)

- [Examples](#examples)

- [Related projects](#related-projects)

  - [Games and applications](#games-and-applications)

  - [Use in industry](#use-in-industry)

  - [Backends](#backends)

  - [Testing](#testing)

  - [Other projects](#other-projects)

- [Documentation](#documentation)

  - [API documentation and tutorials](#api-documentation-and-tutorials)

  - [Publications](#publications)

- [Contributions](#contributions)

  - [Discussions, issues and pull requests](#discussions-issues-and-pull-requests)

  - [Structure and internals](#structure-and-internals)

  - [Style](#style)

  - [Version control](#version-control)

  - [Versioning model](#versioning-model)

- [History](#history)

# Installation

^{[(Back to top)](#table-of-contents)}

## Pre-requisites

^{[(Back to top)](#table-of-contents)}

To use Yampa, you must have a Haskell compiler installed (GHC). We currently

support all versions of GHC from 7.6.3 to modern versions (9.X series as of

this writing).

On Debian/Ubuntu, the Haskell toolchain can be installed with:

```sh

$ apt-get install ghc cabal-install

```

On Mac, they can be installed with:

```sh

$ brew install ghc cabal-install

```

## Compilation

^{[(Back to top)](#table-of-contents)}

Once you have a working set of Haskell tools installed, install Yampa from

[hackage](http://hackage.haskell.org/package/Yampa) by executing:

```sh

$ cabal update

$ cabal install --lib Yampa

```

Running the following will print the word `Success` if installation has gone

well, or show an error message otherwise:

```

$ runhaskell <<< 'import FRP.Yampa; main = putStrLn "Success"'

```

# Examples

^{[(Back to top)](#table-of-contents)}

Getting Yampa to run is trivial. FRP is about values that change over time. In

Yampa, a system is defined by a signal function (SF), which determines how the

varying input and the varying output relate.

Code can be written in multiple styles: _applicative style_, _arrowized style_,

and just plain _arrow combinators_. All three are compatible and

interchangeable.

For example, the following signal function takes a value, integrates it, and

then divides that value by the current time:

```haskell

{-# LANGUAGE Arrows #-}

import FRP.Yampa

signalFunction :: SF Double Double

signalFunction = proc x -> do

  y <- integral -< x

  t <- time     -< ()

  returnA -< y / t

```

This signal function says that the output signal is the integral `y` of the

input signal `x`, divided by the time `t`. The elements between `<-` and `-<`

are always signal functions (in this case, `integral` and `time` are signal

functions used to define another signal function).

The example above is written in arrow syntax and uses a Haskell extension

called Arrows. If you are unhappy using arrow syntax, you can implement the

same behavior using applicative style and/or arrow combinators:

```haskell

-- Applicative style

signalFunction1 :: SF Double Double

signalFunction1 = (/) <$> integral <*> time

-- Functional style with arrow combinators

signalFunction2 :: SF Double Double

signalFunction2 = (integral &&& time) >>^ (/)

```

All three are equivalent, and it's a matter of which one you like best.

To run this example, we need to provide the inputs, the times, and consume the

output:

```haskell

firstSample :: IO Double   -- sample at time zero

firstSample =

  return 1.0  -- time == 0, input == 1.0

nextSamples :: Bool -> IO (Double, Maybe Double)

nextSamples _ =

  return (0.1, Just 1.0) -- time delta == 0.1s, input == 1.0

output :: Bool -> Double -> IO Bool

output _ x = do

  print x     -- print the output

  return False -- just continue forever

```

This is a trivial example, since the integral of the constant function 1.0 over

time, divided by the time, is always 1.0! Nevertheless, we are now ready to

run!

```

ghci> reactimate firstSample nextSamples output signalFunction

1.0

1.0

1.0

1.0

1.0

1.0

...

```

There is a directory with examples, which includes two basic SDL examples and

one with using a Nintendo Wii Remote. You can install them with:

```

$ cabal update

$ cabal install Yampa -fexamples

```

# Related projects

^{[(Back to top)](#table-of-contents)}

## Games and applications

^{[(Back to top)](#table-of-contents)}

* [cuboid](http://hackage.haskell.org/package/cuboid): 3D puzzle game with GLUT.

* [Frag](https://hackage.haskell.org/package/frag): a 3D first person shooting game.

* [hamball](https://github.com/harley/hamball): 3D, LAN FPS game of hamster balls flying around and shooting lasers written in Haskell.

* [Haskanoid](https://github.com/ivanperez-keera/haskanoid): a game that uses SDL multimedia, wiimote and kinect. It's cross platform and works in desktop, mobile, and [web](http://ivanperez-keera.github.io/haskanoid/haskanoid.jsexe/index.html) (compiled with [GHCJS](https://github.com/ghcjs/ghcjs)).

* [Haskelloids](https://github.com/keera-studios/Haskelloids): a reproduction of the Atari 1979 classic "Asteroids"

* [LaneWars](https://github.com/Mattiemus/LaneWars): Top-down MOBA game with online multiplayer.

* [MandelbrotYampa](https://github.com/madjestic/Haskell-OpenGL-Tutorial/tree/master/MandelbrotYampa): a "hello world" using SDL2, Yampa and OpenGL.

* [Pang-a-lambda](https://hackage.haskell.org/package/pang-a-lambda): 2D arcade game inspired by the classic super-pang.

* [Peoplemon](https://linearity.itch.io/peoplemon): a role playing game.

* [Spaceinvaders](https://github.com/ivanperez-keera/SpaceInvaders): Re-write of the classic space invaders.

* [The Bearriver Arcade](https://github.com/walseb/The_Bearriver_Arcade): A couple of arcade games made using bearriver, a library that

implements the Yampa API.

* [Yampa-2048](https://github.com/ksaveljev/yampa-2048): an implementation of the game 2048 using Yampa and Gloss.

* [Yampa - Game of Life](https://github.com/Poselsky/Yampa-Game-Of-Life): an implementation of Game of Life using SDL2 and OpenGL.

* [YampaShooter](https://github.com/werk/YampaShooter): Top-down team based networked tank game.

* [YampaSynth](http://hackage.haskell.org/package/YampaSynth): Software synthesizer.

* [YFrob](hackage.haskell.org/package/YFrob): Yampa-based library for programming robots.

A more comprehensive list can be obtained using the reverse dependency finder

(http://packdeps.haskellers.com/reverse/Yampa), but only programs uploaded to

hackage are listed.

|  |  |  |

|-------------------------------------------|---------------|-------------------------|

| Haskanoid, SDL cross-platform arkanoid. | Peoplemon, a role playing game | Yampa2048, a gloss board game |

## Use in industry

^{[(Back to top)](#table-of-contents)}

[Keera Studios](https://keera.co.uk) uses Yampa to create Haskell games available on [Google Play for Android](https://play.google.com/store/apps/developer?id=Keera+Studios&hl=en_US&gl=US) and [iTunes for iOS](https://apps.apple.com/us/developer/keera-studios-ltd/id1244709870):

  

    

    


      Magic Cookies!

      



      

        

      

      


      ^{Copyright © 2015 - 2020 Keera Studios Ltd. All Rights Reserved.}

      


      

        

        

      

        

    

    

    

    

      Magic Cookies 2!

      



      

        

      

      


      ^{Copyright © 2015 - 2022 Keera Studios Ltd. All Rights Reserved.}

      


      

        

        

      

        

    

    

    

    

      Enpuzzled

      


      


      

        

      

      


      ^{Copyright © - 2017 - Keera Studios Ltd - All Rights Reserved.}

      


      

        

        

      

        

    

    

    

    

    

      _{^{Keera, Keera Studios, Magic Cookies, Magic Cookies 2, the Magic

          Cookies logo, the Magic Cookies 2 logo, the Magic Cookies splash

          screen, the Magic Cookies 2 splash screen, Enpuzzled, the Enpuzzled

          splash screen, and the Enpuzzled logo are trademarks of Keera Studios

          Ltd. Google Play and the Google Play logo are trademarks of Google

          LLC. Apple, the Apple logo, iPhone, and iPad are trademarks of Apple

          Inc., registered in the U.S. and other countries and regions. App

          Store is a service mark of Apple Inc.}}

    

  

## Backends

^{[(Back to top)](#table-of-contents)}

Yampa is backend agnostic, you can ultimately connect it to any backend you

want. Existing backends include:

* SDL (see [Haskanoid](https://github.com/ivanperez-keera/haskanoid) for an example)

* SDL2 (see [yampa-sdl2](https://github.com/Simre1/yampa-sdl2))

* OpenGL / GLUT (see [Haskell-OpenGL-Tutorial](https://github.com/madjestic/Haskell-OpenGL-Tutorial/tree/master/MandelbrotYampa)).

* GLFW (see [yampa-glfw](https://github.com/deepfire/yampa-glfw))

* WX (see wxHaskell)

* HTML Canvas via JS Dom (for an example, see [haskanoid's GHCJS branch](https://github.com/ivanperez-keera/haskanoid/blob/ghcjs/src/Display.hs))

* HTML5 Canvas via blank-canvas (see [yampa-canvas](https://github.com/ku-fpg/yampa-canvas))

* HTML5 with Web Assembly (Wasm) (for an example, see [yampa-wasm-example](https://github.com/AntanasKal/yampa-wasm-example))

* Gloss (see [yampa-gloss](https://github.com/ivanperez-keera/yampa-gloss))

* Diagrams (see [diagrams example](https://github.com/ivanperez-keera/Yampa/blob/develop/yampa/examples/Diagrams.hs))

* [Keera Hails](https://github.com/keera-studios/keera-hails/tree/master/keera-hails-reactive-yampa) (reactive programming framework with GTK, WX, Qt, Android, iOS and HTML support).

## Testing

^{[(Back to top)](#table-of-contents)}

Yampa comes with a sophisticated testing library that allows you to use

QuickCheck to test your games, and use a time-travel debugger. These features

are described in the paper [Testing and Debugging Functional Reactive

Programming](http://dl.acm.org/authorize?N46564).

You can find the additional projects at:

* [yampa-test](https://github.com/ivanperez-keera/Yampa/tree/develop/yampa-test)

* [Haskell Titan](https://github.com/keera-studios/haskell-titan)

## Other projects

^{[(Back to top)](#table-of-contents)}

* [Bearriver](https://github.com/ivanperez-keera/dunai/tree/develop/dunai-frp-bearriver): API-compatible Yampa replacement built on top of dunai using Monadic Stream Functions.

* [Dunai](https://github.com/ivanperez-keera/dunai): An FRP implementation inspired by Yampa that extends SFs with a monad.

* [Functional Reactive Virtual Reality](https://imve.informatik.uni-hamburg.de/projects/FRVR): a fork of Yampa with extensions for VR.

* [graphui](https://github.com/sinelaw/graphui): Attempt to implement Graphui.

* [Haskell-OpenGL-Tutorial](https://github.com/madjestic/Haskell-OpenGL-Tutorial/tree/master/MandelbrotYampa) same as [here](https://github.com/ubuntunux/LambdaEngine3D/tree/master/MandelbrotYampa): Visually attractive mandelbrot implementation.

* [Keera Hails](https://github.com/keera-studios/keera-hails/tree/master/keera-hails-reactive-yampa): Backend for reactive framework with GTK, WX, Qt, Android, iOS and HTML support, with a library to connect Yampa signal functions.

# Documentation

^{[(Back to top)](#table-of-contents)}

## API documentation and tutorials

^{[(Back to top)](#table-of-contents)}

The API of Yampa is thoroughly documented

[on hackage](https://hackage.haskell.org/package/Yampa).

Documentation is also available in the

[Haskell wiki page for Yampa](https://wiki.haskell.org/Yampa).

## Publications

^{[(Back to top)](#table-of-contents)}

* [The Beauty and Elegance of Functional Reactive Animation](https://dl.acm.org/doi/10.1145/3609023.3609806?cid=99658741366) (Ivan Perez; 2023)

* [Extensible and Robust Functional Reactive Programming](http://www.cs.nott.ac.uk/~psxip1/papers/2017-Perez-thesis-latest.pdf) (Ivan Perez; 2017)

* [Testing and Debugging Functional Reactive Programming](http://dl.acm.org/authorize?N46564) (Ivan Perez and Henrik Nilsson; 2017)

* [Functional Reactive Programming, Refactored](http://dl.acm.org/authorize?N34896) (Ivan Perez, Manuel Bärenz, and Henrik Nilsson; 2016)

* [Safe Functional Reactive Programming through Dependent Types](http://dl.acm.org/authorize?N08595) (Neil Sculthorpe and Henrik Nilsson; 2009)

* [Push-Pull Functional Reactive Programming](http://conal.net/papers/push-pull-frp/push-pull-frp.pdf) (Conal Elliott; 2009)

* [Switched-on Yampa: Declarative Programming of Modular Synthesizers](http://www.cs.nott.ac.uk/~psznhn/Publications/padl2008.pdf) (George Giorgidze and Henrik Nilsson; 2008)

* [Demo-outline: Switched-on Yampa: Programming Modular Synthesizers in Haskell](http://dl.acm.org/authorize?N08596) (George Giorgidze and Henrik Nilsson; 2007)

* [Dynamic Optimization for Functional Reactive Programming using Generalized Algebraic Data Types](http://dl.acm.org/authorize?N08598) (Henrik Nilsson; 2005)

* [The Yampa Arcade](http://dl.acm.org/authorize?N08599) (Antony Courtney, Henrik Nilsson, and John Peterson; 2003)

* [Arrows, Robots, and Functional Reactive Programming](http://www.cs.nott.ac.uk/~psznhn/Publications/afp2002.pdf) (Paul Hudak, Antony Courtney, Henrik Nilsson, and John Peterson; 2002)

* [Functional Reactive Programming, Continued](http://dl.acm.org/authorize?N08592) (Henrik Nilsson, Antony Courtney, and John Peterson; 2002)

* [Genuinely Functional User Interfaces](http://conal.net/papers/genuinely-functional-guis.pdf) (Antony Courtney and Conal Elliott; 2001)

* See also:

  * [Collection of Yampa diagrams](https://github.com/ivanperez-keera/Yampa/tree/develop/doc/diagrams/Diagrams.md)

  * [Henrik Nilsson's publications](http://www.cs.nott.ac.uk/~psznhn/papers.html)

  * [Ivan Perez's publications](https://ivanperez.io)

  * [First Year PhD Report](http://www.cs.nott.ac.uk/~psxip1/papers/2014-Perez-1st-year-report.pdf) (Ivan Perez, 2014), chapter 3 includes a review of FRP and outlines some existing issues.

# Contributions

^{[(Back to top)](#table-of-contents)}

If this library helps you, you may want to consider

[buying the maintainer a cup of coffee](https://flattr.com/submit/auto?user_id=ivanperez-keera&url=https://github.com/ivanperez-keera/Yampa&title=Yampa&language=&tags=github&category=software).

## Discussions, issues and pull requests

^{[(Back to top)](#table-of-contents)}

**Discussions**

If you have any comments, questions, ideas, or other topics that you think will

be of interest to the Yampa community, start a new discussion

[here](https://github.com/ivanperez-keera/Yampa/discussions). Examples include:

- You've created a new game or application that uses Yampa.

- You've written or found a library that helps use Yampa in a particular

  domain, or apply it to a specific platform.

- You've written or found a paper that mentions Yampa.

- You have an idea for an extension that will enable writing programs that are

  not currently possible or convenient to capture.

- You think you've found a bug.

- You want to propose an improvement (e.g., make the code faster or smaller).

- You have a question.

- Something in the documentation, a tutorial or a Yampa / FRP paper is unclear.

- You like the project and want to introduce yourself.

**Issues**

If a specific change is being proposed (either a new feature or a bug fix), you

can *open an issue* documenting the proposed change

[here](https://github.com/ivanperez-keera/Yampa/issues).

If you are unsure about whether your submission should be filed as an issue or

as a discussion, file it as a discussion. We can always move it later.

**Pull requests**

Once we determine that an issue will be addressed, we'll decide who does it and

when the change will be added to Yampa. Even if you implement the solution,

someone will walk you through the steps to ensure that your submission conforms

with our version control process, style guide, etc. More information on our

process is included below.

Please, do not just send a PR unless there is an issue for it and someone from

the Yampa team has confirmed that you should address it. The PR is *very*

likely to be rejected, and we really want to accept your contributions, so it

will make us very sad. Open a discussion / issue first and let us guide you

through the process.

## Structure and internals

^{[(Back to top)](#table-of-contents)}

This project is split in two:

- _Yampa_: FRP library.

- _Yampa-test_: a testing layer for Yampa.

Yampa's unit tests are mostly implemented as tests inside the yampa-test

library. The module hierarchy of `yampa-test/tests/Test` mirrors that of Yampa.

Yampa also includes some benchmarks as part of the main library. You are

encouraged to use them to evaluate your pull requests, and to improve the

benchmarks themselves.

A directory `yampa/examples` contains a number of examples of Yampa programs,

some of which can be installed with the flag `-fexamples`.

## Style

^{[(Back to top)](#table-of-contents)}

We follow [this style

guide](https://keera.co.uk/wp-content/uploads/2021/11/haskellguide-v1.3.0.pdf)

for the Haskell code and [this style

guide](https://keera.co.uk/wp-content/uploads/2021/11/cabalguide-v1.3.0.pdf)

for Cabal files.

## Version control

^{[(Back to top)](#table-of-contents)}

We follow [git flow](http://nvie.com/posts/a-successful-git-branching-model/).

In addition:

- Please document your commits clearly and separately.

- Always refer to the issue you are fixing in the commit summary line with the

  text `Refs #` at the end.

- If there is no issue for your change, then open an issue first and document

  what you are trying to achieve/improve/fix.

- Do not address more than one issue per commit or per PR. If two changes are

  not directly related to one another, they belong in different PRs, issues and

  commits.

- Document what you did in the respective CHANGELOGs in a separate commit

  before you send a PR. This commit should be the last one in the PR.

- If your commit pertains to one package only, name the package at the

  beginning of the summary line with the syntax `:

  <...rest_of_summary...>`.

- Make sure your changes conform to the [coding

  style](https://keera.co.uk/wp-content/uploads/2021/11/haskellguide-v1.3.0.pdf).

See the recent repo history for examples of this process. Using a visual repo

inspection tool like `gitk` may help.

## Versioning model

^{[(Back to top)](#table-of-contents)}

The versioning model we use is the standard in Haskell packages. Versions have

the format `..(.)?` where:

- `` is just a way to signal important milestones or used for promotional

  reasons (to indicate a major advancement). A zero on this position has no

  special meaning.

- `` increases on incompatible API changes.

- `` increases on backwards-compatible changes.

- `` (optional) increases on small changes that do not affect behavior

  (e.g., documentation).

# History

^{[(Back to top)](#table-of-contents)}

This library was created by Henrik Nilsson and Antony Courtney in 2002, while

working at Yale's Haskell group, led by Paul Hudak. The design and

implementation benefited from frequent discussions with other members of the

group, including also John Peterson. From 2008 to 2012, it was maintained by

George Giorgidze. In 2014, maintenance was passed to Ivan Perez.

Yampa is the longest standing FRP implementation in Haskell still in use. It

has seen and continues to see abundant use in industry, research, and academia.

We invite you to be part of this incredible community project as a user, a

contributor, and overall supporter.

Yampa is named after the Yampa river in Colorado, USA.