arrows-0.4.4.1: Arrow classes and transformers

Copyright | (c) Ross Paterson 2003
License | BSD-style (see the LICENSE file in the distribution)
Maintainer | ross@soi.city.ac.uk
Stability | experimental
Portability | non-portable (multi-parameter type classes)
Safe Haskell | Safe
Language | Haskell98

Control.Arrow.Operations

Contents

- Conventions
- State transformers
- State readers
- Monoid writers
- Errors
- Synchronous circuits

Description

Subclasses of `Arrow` providing additional operations.

The signatures are designed to be compatible with the proposed notation for arrows, cf. http://www.haskell.org/arrows/.

Synopsis

- class Arrow a => ArrowState s a | a -> s where
  - fetch :: a e s
  - store :: a s ()
- class Arrow a => ArrowReader r a | a -> r where
  - readState :: a b r
  - newReader :: a e b -> a (e, r) b
- class (Monoid w, Arrow a) => ArrowWriter w a | a -> w where
  - write :: a w ()
  - newWriter :: a e b -> a e (b, w)
- class Arrow a => ArrowError ex a | a -> ex where
  - raise :: a ex b
  - handle :: a e b -> a (e, ex) b -> a e b
  - tryInUnless :: a e b -> a (e, b) c -> a (e, ex) c -> a e c
  - newError :: a e b -> a e (Either ex b)
- tryInUnlessDefault :: (ArrowError ex a, ArrowChoice a) => a e b -> a (e, b) c -> a (e, ex) c -> a e c
- class ArrowLoop a => ArrowCircuit a where
  - delay :: b -> a b b

# Conventions

The arrow classes defined in this module have names like `Arrow` Foo, and contain operations specific to such arrows. Some of these include a method `new` Foo, which maps computations to computations of the same arrow type, but exposing some of the internals of the arrow.

Arrow transformers have names like Bar `Arrow`, and are instances of appropriate arrow classes. For each arrow transformer, there is typically an encapsulation operator `run` Bar that removes that transformer from the outside of an arrow type. The `lift` method of the `ArrowTransformer` class adds an arrow transformer to the outside of an arrow type.

Typically a composite arrow type is built by applying a series of arrow transformers to a base arrow (usually either a function arrow or a `Kleisli` arrow. The `lift` method and the `run` Bar function operate only on the arrow transformer at the top of this stack. For more sophisticated manipulation of this stack of arrow transformers, many arrow transformers provide an `ArrowAdd` Bar class, with methods methods `lift` Bar and `elim` Bar to add and remove the transformer anywhere in the stack.

# State transformers

class Arrow a => ArrowState s a | a -> s where Source

An arrow type that provides a modifiable state, based of section 9 of Generalising Monads to Arrows, by John Hughes, Science of Computer Programming 37:67-111, May 2000.

Methods

fetch :: a e s Source

Obtain the current value of the state.

store :: a s () Source

Assign a new value to the state.

Instances

ArrowState s a => ArrowState s (Automaton a) Source |
ArrowState s a => ArrowState s (StreamArrow a) Source |
(ArrowState s a, ArrowChoice a) => ArrowState s (ErrorArrow ex a) Source |
Arrow a => ArrowState s (StateArrow s a) Source |
(ArrowState s a, Applicative f) => ArrowState s (StaticArrow f a) Source |
(ArrowState s a, Monoid w) => ArrowState s (WriterArrow w a) Source |
ArrowState s a => ArrowState s (ReaderArrow r a) Source |

# State readers

class Arrow a => ArrowReader r a | a -> r where Source

An arrow type that provides a read-only state (an environment). If you also need to modify the state, use `ArrowState`.

Methods

readState :: a b r Source

Obtain the current value of the state.

newReader :: a e b -> a (e, r) b Source

Run a subcomputation in the same arrow, but with a different environment. The environment of the outer computation is unaffected.

Typical usage in arrow notation:

    	proc p -> ...
    		(|newReader cmd|) env

Instances

ArrowReader r a => ArrowReader r (Automaton a) Source |
(ArrowReader r a, ArrowChoice a) => ArrowReader r (ErrorArrow ex a) Source |
ArrowReader r a => ArrowReader r (StateArrow s a) Source |
(ArrowReader r a, Applicative f) => ArrowReader r (StaticArrow f a) Source |
(ArrowReader r a, Monoid w) => ArrowReader r (WriterArrow w a) Source |
Arrow a => ArrowReader r (ReaderArrow r a) Source |

# Monoid writers

class (Monoid w, Arrow a) => ArrowWriter w a | a -> w where Source

An arrow type that collects additional output (of some `Monoid` type).

Methods

write :: a w () Source

Add a piece of additional output.

newWriter :: a e b -> a e (b, w) Source

Run a subcomputation in the same arrow, making its additional output accessible.

Typical usage in arrow notation:

    	proc p -> do
    		...
    		(value, output) <- (|newWriter cmd|)

Instances

ArrowWriter w a => ArrowWriter w (Automaton a) Source |
ArrowWriter w a => ArrowWriter w (StreamArrow a) Source |
(ArrowWriter w a, ArrowChoice a) => ArrowWriter w (ErrorArrow ex a) Source |
ArrowWriter w a => ArrowWriter w (StateArrow s a) Source |
(ArrowWriter w a, Applicative f) => ArrowWriter w (StaticArrow f a) Source |
(Arrow a, Monoid w) => ArrowWriter w (WriterArrow w a) Source |
ArrowWriter s a => ArrowWriter s (ReaderArrow r a) Source |

# Errors

class Arrow a => ArrowError ex a | a -> ex where Source

An arrow type that includes errors (or exceptions).

Minimal definition: `raise` and `tryInUnless`.

TODO: the operations here are inconsistent with other arrow transformers.

Minimal complete definition

raise, tryInUnless

Methods

raise :: a ex b Source

Raise an error.

handle Source

Arguments

:: a e b | computation that may raise errors
-> a (e, ex) b | computation to handle errors
-> a e b |

Traditional exception construct.

Typical usage in arrow notation:

    	proc p -> ...
    		body `handle` \ex -> handler

tryInUnless Source

Arguments

:: a e b | computation that may raise errors
-> a (e, b) c | computation to receive successful results
-> a (e, ex) c | computation to handle errors
-> a e c |

Exception construct in the style of Exceptional Syntax, by Nick Benton and Andrew Kennedy, JFP 11(4):395-410, July 2001.

Typical usage in arrow notation:

    	proc p -> ...
    		(|tryInUnless
    			body
    			(\res -> success)
    			(\ex -> handler)
    		|)

newError :: a e b -> a e (Either ex b) Source

Handler that returns the error as a value.

Instances

ArrowError r a => ArrowError r (Automaton a) Source |
ArrowChoice a => ArrowError ex (ErrorArrow ex a) Source |
ArrowError ex a => ArrowError ex (StateArrow s a) Source |
(ArrowError ex a, Applicative f) => ArrowError ex (StaticArrow f a) Source |
(ArrowError ex a, Monoid w) => ArrowError ex (WriterArrow w a) Source |
ArrowError ex a => ArrowError ex (ReaderArrow r a) Source |

tryInUnlessDefault Source

Arguments

:: (ArrowError ex a, ArrowChoice a) |
=> a e b | computation that may raise errors
-> a (e, b) c | computation to receive successful results
-> a (e, ex) c | computation to handle errors
-> a e c |

A suitable value for `tryInUnless` when the arrow type belongs to `ArrowChoice`. To use it, you must define either `handle` or `newError`.

# Synchronous circuits

class ArrowLoop a => ArrowCircuit a where Source

An arrow type that can be used to interpret synchronous circuits.

Methods

delay Source

Arguments

:: b | the value to return initially.
-> a b b | an arrow that propagates its input with a one-tick delay.

A delay component.

Instances

ArrowLoop a => ArrowCircuit (Automaton a) Source |
ArrowLoop a => ArrowCircuit (StreamArrow a) Source |
ArrowCircuit a => ArrowCircuit (StateArrow s a) Source |
(ArrowCircuit a, Applicative f) => ArrowCircuit (StaticArrow f a) Source |
(ArrowCircuit a, Monoid w) => ArrowCircuit (WriterArrow w a) Source |
ArrowCircuit a => ArrowCircuit (ReaderArrow r a) Source |