Repository files navigation

• 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.

• Installation
  • Pre-requisites
  • Compilation
• Examples
• Related projects
  • Games and applications
  • Use in industry
  • Backends
  • Testing
  • Other projects
• Documentation
  • API documentation and tutorials
  • Publications
• Contributions
  • Discussions, issues and pull requests
  • Structure and internals
  • Style
  • Version control
  • Versioning model
• History

^{(Back to top)}

^{(Back to top)}

To use Yampa, you must have a Haskell compiler installed (GHC). We currentlysupport all versions of GHC from 7.6.3 to modern versions (9.X series as ofthis writing).

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

$ apt-get install ghc cabal-install

On Mac, they can be installed with:

$ brew install ghc cabal-install

^{(Back to top)}

Once you have a working set of Haskell tools installed, install Yampa fromhackage by executing:

$ cabal update$ cabal install --lib Yampa

Running the following will print the wordSuccess if installation has gonewell, or show an error message otherwise:

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

^{(Back to top)}

Getting Yampa to run is trivial. FRP is about values that change over time. InYampa, a system is defined by a signal function (SF), which determines how thevarying input and the varying output relate.

Code can be written in multiple styles:applicative style,arrowized style,and just plainarrow combinators. All three are compatible andinterchangeable.

For example, the following signal function takes a value, integrates it, andthen divides that value by the current time:

{-#LANGUAGE Arrows #-}importFRP.YampasignalFunction::SFDoubleDoublesignalFunction=proc x->do  y<- integral-< x  t<- time-<()  returnA-< y/ t

This signal function says that the output signal is the integraly of theinput signalx, divided by the timet. The elements between<- and-<are always signal functions (in this case,integral andtime are signalfunctions used to define another signal function).

The example above is written in arrow syntax and uses a Haskell extensioncalled Arrows. If you are unhappy using arrow syntax, you can implement thesame behavior using applicative style and/or arrow combinators:

-- Applicative stylesignalFunction1::SFDoubleDoublesignalFunction1=(/)<$> integral<*> time-- Functional style with arrow combinatorssignalFunction2::SFDoubleDoublesignalFunction2= (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 theoutput:

firstSample::IODouble-- sample at time zerofirstSample=return1.0-- time == 0, input == 1.0nextSamples::Bool->IO (Double,MaybeDouble)nextSamples _=return (0.1,Just1.0)-- time delta == 0.1s, input == 1.0output::Bool->Double->IOBooloutput _ x=doprint x-- print the outputreturnFalse-- just continue forever

This is a trivial example, since the integral of the constant function 1.0 overtime, divided by the time, is always 1.0! Nevertheless, we are now ready torun!

ghci> reactimate firstSample nextSamples output signalFunction1.01.01.01.01.01.0...

There is a directory with examples, which includes two basic SDL examples andone with using a Nintendo Wii Remote. You can install them with:

$ cabal update$ cabal install Yampa -fexamples

^{(Back to top)}

^{(Back to top)}

• cuboid: 3D puzzle game with GLUT.
• Frag: a 3D first person shooting game.
• hamball: 3D, LAN FPS game of hamster balls flying around and shooting lasers written in Haskell.
• Haskanoid: a game that uses SDL multimedia, wiimote and kinect. It's cross platform and works in desktop, mobile, andweb (compiled withGHCJS).
• Haskelloids: a reproduction of the Atari 1979 classic "Asteroids"
• LaneWars: Top-down MOBA game with online multiplayer.
• MandelbrotYampa: a "hello world" using SDL2, Yampa and OpenGL.
• Pang-a-lambda: 2D arcade game inspired by the classic super-pang.
• Peoplemon: a role playing game.
• Spaceinvaders: Re-write of the classic space invaders.
• The Bearriver Arcade: A couple of arcade games made using bearriver, a library thatimplements the Yampa API.
• Yampa-2048: an implementation of the game 2048 using Yampa and Gloss.
• Yampa - Game of Life: an implementation of Game of Life using SDL2 and OpenGL.
• YampaShooter: Top-down team based networked tank game.
• YampaSynth: Software synthesizer.
• 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 tohackage are listed.

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

^{(Back to top)}

Keera Studios uses Yampa to create Haskell games available onGoogle Play for Android andiTunes for iOS:

^{(Back to top)}

Yampa is backend agnostic, you can ultimately connect it to any backend youwant. Existing backends include:

• SDL (seeHaskanoid for an example)
• SDL2 (seeyampa-sdl2)
• OpenGL / GLUT (seeHaskell-OpenGL-Tutorial).
• GLFW (seeyampa-glfw)
• WX (see wxHaskell)
• HTML Canvas via JS Dom (for an example, seehaskanoid's GHCJS branch)
• HTML5 Canvas via blank-canvas (seeyampa-canvas)
• HTML5 with Web Assembly (Wasm) (for an example, seeyampa-wasm-example)
• Gloss (seeyampa-gloss)
• Diagrams (seediagrams example)
• Keera Hails (reactive programming framework with GTK, WX, Qt, Android, iOS and HTML support).

^{(Back to top)}

Yampa comes with a sophisticated testing library that allows you to useQuickCheck to test your games, and use a time-travel debugger. These featuresare described in the paperTesting and Debugging Functional ReactiveProgramming.

You can find the additional projects at:

• yampa-test
• Haskell Titan

^{(Back to top)}

• Bearriver: API-compatible Yampa replacement built on top of dunai using Monadic Stream Functions.
• Dunai: An FRP implementation inspired by Yampa that extends SFs with a monad.
• Functional Reactive Virtual Reality: a fork of Yampa with extensions for VR.
• graphui: Attempt to implement Graphui.
• Haskell-OpenGL-Tutorial same ashere: Visually attractive mandelbrot implementation.
• Keera Hails: Backend for reactive framework with GTK, WX, Qt, Android, iOS and HTML support, with a library to connect Yampa signal functions.

^{(Back to top)}

^{(Back to top)}

The API of Yampa is thoroughly documentedon hackage.Documentation is also available in theHaskell wiki page for Yampa.

^{(Back to top)}

• Using Functional Reactive Programming for Robotic Art: An Experience Report (Eliane I. Schmidli and Farhad Mehta; 2024)

• Demo: The Fun of Robotic Artwork (Eliane I. Schmidli and Farhad Mehta; 2024)

• Reactamole: functional reactive molecular programming (Titus Klinge, James Lathrop, Peter-Michael Osera, Allison Rogers; 2024)

• The Beauty and Elegance of Functional Reactive Animation (Ivan Perez; 2023)

• Extensible and Robust Functional Reactive Programming (Ivan Perez; 2017)

• Testing and Debugging Functional Reactive Programming (Ivan Perez and Henrik Nilsson; 2017)

• Functional Reactive Programming, Refactored (Ivan Perez, Manuel Bärenz, and Henrik Nilsson; 2016)

• Safe Functional Reactive Programming through Dependent Types (Neil Sculthorpe and Henrik Nilsson; 2009)

• Push-Pull Functional Reactive Programming (Conal Elliott; 2009)

• Switched-on Yampa: Declarative Programming of Modular Synthesizers (George Giorgidze and Henrik Nilsson; 2008)

• Demo-outline: Switched-on Yampa: Programming Modular Synthesizers in Haskell (George Giorgidze and Henrik Nilsson; 2007)

• Dynamic Optimization for Functional Reactive Programming using Generalized Algebraic Data Types (Henrik Nilsson; 2005)

• The Yampa Arcade (Antony Courtney, Henrik Nilsson, and John Peterson; 2003)

• Arrows, Robots, and Functional Reactive Programming (Paul Hudak, Antony Courtney, Henrik Nilsson, and John Peterson; 2002)

• Functional Reactive Programming, Continued (Henrik Nilsson, Antony Courtney, and John Peterson; 2002)

• Genuinely Functional User Interfaces (Antony Courtney and Conal Elliott; 2001)

• See also:

  • Collection of Yampa diagrams
  • Henrik Nilsson's publications
  • Ivan Perez's publications
  • First Year PhD Report (Ivan Perez, 2014), chapter 3 includes a review of FRP and outlines some existing issues.

^{(Back to top)}

If this library helps you, you may want to considerbuying the maintainer a cup of coffee.

^{(Back to top)}

Discussions

If you have any comments, questions, ideas, or other topics that you think willbe of interest to the Yampa community, start a new discussionhere. 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 particulardomain, 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 arenot 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), youcanopen an issue documenting the proposed changehere.

If you are unsure about whether your submission should be filed as an issue oras 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 andwhen 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 conformswith our version control process, style guide, etc. More information on ourprocess is included below.

Please, do not just send a PR unless there is an issue for it and someone fromthe Yampa team has confirmed that you should address it. The PR isverylikely to be rejected, and we really want to accept your contributions, so itwill make us very sad. Open a discussion / issue first and let us guide youthrough the process.

^{(Back to top)}

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-testlibrary. The module hierarchy ofyampa-test/tests/Test mirrors that of Yampa.

Yampa also includes some benchmarks as part of the main library. You areencouraged to use them to evaluate your pull requests, and to improve thebenchmarks themselves.

A directoryyampa/examples contains a number of examples of Yampa programs,some of which can be installed with the flag-fexamples.

^{(Back to top)}

We followthis styleguidefor the Haskell code andthis styleguidefor Cabal files.

^{(Back to top)}

We followgit flow.In addition:

• Please document your commits clearly and separately.
• Always refer to the issue you are fixing in the commit summary line with thetextRefs #<issue_number> at the end.
• If there is no issue for your change, then open an issue first and documentwhat you are trying to achieve/improve/fix.
• Do not address more than one issue per commit or per PR. If two changes arenot directly related to one another, they belong in different PRs, issues andcommits.
• Document what you did in the respective CHANGELOGs in a separate commitbefore 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 thebeginning of the summary line with the syntax<package_name>: <...rest_of_summary...>.
• Make sure your changes conform to thecodingstyle.

See the recent repo history for examples of this process. Using a visual repoinspection tool likegitk may help.

^{(Back to top)}

The versioning model we use is the standard in Haskell packages. Versions havethe format<PUB>.<MAJOR>.<MINOR>(.<PATCH>)? where:

• <PUB> is just a way to signal important milestones or used for promotionalreasons (to indicate a major advancement). A zero on this position has nospecial meaning.

• <MAJOR> increases on incompatible API changes.

• <MINOR> increases on backwards-compatible changes.

• <PATCH> (optional) increases on small changes that do not affect behavior(e.g., documentation).

^{(Back to top)}

This library was created by Henrik Nilsson and Antony Courtney in 2002, whileworking at Yale's Haskell group, led by Paul Hudak. The design andimplementation benefited from frequent discussions with other members of thegroup, including also John Peterson. From 2008 to 2012, it was maintained byGeorge Giorgidze. In 2014, maintenance was passed to Ivan Perez.

Yampa is the longest standing FRP implementation in Haskell still in use. Ithas 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, acontributor, and overall supporter.

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