arrows-0.4.4.2: 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

Instances details

ArrowState s a => ArrowState s (Automaton a) Source # |
Instance details Defined in Control.Arrow.Transformer.Automaton Methods fetch :: Automaton a e s Source # store :: Automaton a s () Source #
ArrowState s a => ArrowState s (StreamArrow a) Source # |
Instance details Defined in Control.Arrow.Transformer.Stream Methods fetch :: StreamArrow a e s Source # store :: StreamArrow a s () Source #
(ArrowState s a, ArrowChoice a) => ArrowState s (ErrorArrow ex a) Source # |
Instance details Defined in Control.Arrow.Transformer.Error Methods fetch :: ErrorArrow ex a e s Source # store :: ErrorArrow ex a s () Source #
ArrowState s a => ArrowState s (ReaderArrow r a) Source # |
Instance details Defined in Control.Arrow.Transformer.Reader Methods fetch :: ReaderArrow r a e s Source # store :: ReaderArrow r a s () Source #
Arrow a => ArrowState s (StateArrow s a) Source # |
Instance details Defined in Control.Arrow.Transformer.State Methods fetch :: StateArrow s a e s Source # store :: StateArrow s a s () Source #
(ArrowState s a, Applicative f) => ArrowState s (StaticArrow f a) Source # |
Instance details Defined in Control.Arrow.Transformer.Static Methods fetch :: StaticArrow f a e s Source # store :: StaticArrow f a s () Source #
(ArrowState s a, Monoid w) => ArrowState s (WriterArrow w a) Source # |
Instance details Defined in Control.Arrow.Transformer.Writer Methods fetch :: WriterArrow w a e s Source # store :: WriterArrow w a s () 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

Instances details

ArrowReader r a => ArrowReader r (Automaton a) Source # |
Instance details Defined in Control.Arrow.Transformer.Automaton Methods readState :: Automaton a b r Source # newReader :: Automaton a e b -> Automaton a (e, r) b Source #
(ArrowReader r a, ArrowChoice a) => ArrowReader r (ErrorArrow ex a) Source # |
Instance details Defined in Control.Arrow.Transformer.Error Methods readState :: ErrorArrow ex a b r Source # newReader :: ErrorArrow ex a e b -> ErrorArrow ex a (e, r) b Source #
Arrow a => ArrowReader r (ReaderArrow r a) Source # |
Instance details Defined in Control.Arrow.Transformer.Reader Methods readState :: ReaderArrow r a b r Source # newReader :: ReaderArrow r a e b -> ReaderArrow r a (e, r) b Source #
ArrowReader r a => ArrowReader r (StateArrow s a) Source # |
Instance details Defined in Control.Arrow.Transformer.State Methods readState :: StateArrow s a b r Source # newReader :: StateArrow s a e b -> StateArrow s a (e, r) b Source #
(ArrowReader r a, Applicative f) => ArrowReader r (StaticArrow f a) Source # |
Instance details Defined in Control.Arrow.Transformer.Static Methods readState :: StaticArrow f a b r Source # newReader :: StaticArrow f a e b -> StaticArrow f a (e, r) b Source #
(ArrowReader r a, Monoid w) => ArrowReader r (WriterArrow w a) Source # |
Instance details Defined in Control.Arrow.Transformer.Writer Methods readState :: WriterArrow w a b r Source # newReader :: WriterArrow w a e b -> WriterArrow w a (e, r) b 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

Instances details

ArrowWriter w a => ArrowWriter w (Automaton a) Source # |
Instance details Defined in Control.Arrow.Transformer.Automaton Methods write :: Automaton a w () Source # newWriter :: Automaton a e b -> Automaton a e (b, w) Source #
ArrowWriter w a => ArrowWriter w (StreamArrow a) Source # |
Instance details Defined in Control.Arrow.Transformer.Stream Methods write :: StreamArrow a w () Source # newWriter :: StreamArrow a e b -> StreamArrow a e (b, w) Source #
(ArrowWriter w a, ArrowChoice a) => ArrowWriter w (ErrorArrow ex a) Source # |
Instance details Defined in Control.Arrow.Transformer.Error Methods write :: ErrorArrow ex a w () Source # newWriter :: ErrorArrow ex a e b -> ErrorArrow ex a e (b, w) Source #
ArrowWriter s a => ArrowWriter s (ReaderArrow r a) Source # |
Instance details Defined in Control.Arrow.Transformer.Reader Methods write :: ReaderArrow r a s () Source # newWriter :: ReaderArrow r a e b -> ReaderArrow r a e (b, s) Source #
ArrowWriter w a => ArrowWriter w (StateArrow s a) Source # |
Instance details Defined in Control.Arrow.Transformer.State Methods write :: StateArrow s a w () Source # newWriter :: StateArrow s a e b -> StateArrow s a e (b, w) Source #
(ArrowWriter w a, Applicative f) => ArrowWriter w (StaticArrow f a) Source # |
Instance details Defined in Control.Arrow.Transformer.Static Methods write :: StaticArrow f a w () Source # newWriter :: StaticArrow f a e b -> StaticArrow f a e (b, w) Source #
(Arrow a, Monoid w) => ArrowWriter w (WriterArrow w a) Source # |
Instance details Defined in Control.Arrow.Transformer.Writer Methods write :: WriterArrow w a w () Source # newWriter :: WriterArrow w a e b -> WriterArrow w a e (b, w) 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

Instances details

ArrowError r a => ArrowError r (Automaton a) Source # |
Instance details Defined in Control.Arrow.Transformer.Automaton Methods raise :: Automaton a r b Source # handle :: Automaton a e b -> Automaton a (e, r) b -> Automaton a e b Source # tryInUnless :: Automaton a e b -> Automaton a (e, b) c -> Automaton a (e, r) c -> Automaton a e c Source # newError :: Automaton a e b -> Automaton a e (Either r b) Source #
ArrowChoice a => ArrowError ex (ErrorArrow ex a) Source # |
Instance details Defined in Control.Arrow.Transformer.Error Methods raise :: ErrorArrow ex a ex b Source # handle :: ErrorArrow ex a e b -> ErrorArrow ex a (e, ex) b -> ErrorArrow ex a e b Source # tryInUnless :: ErrorArrow ex a e b -> ErrorArrow ex a (e, b) c -> ErrorArrow ex a (e, ex) c -> ErrorArrow ex a e c Source # newError :: ErrorArrow ex a e b -> ErrorArrow ex a e (Either ex b) Source #
ArrowError ex a => ArrowError ex (ReaderArrow r a) Source # |
Instance details Defined in Control.Arrow.Transformer.Reader Methods raise :: ReaderArrow r a ex b Source # handle :: ReaderArrow r a e b -> ReaderArrow r a (e, ex) b -> ReaderArrow r a e b Source # tryInUnless :: ReaderArrow r a e b -> ReaderArrow r a (e, b) c -> ReaderArrow r a (e, ex) c -> ReaderArrow r a e c Source # newError :: ReaderArrow r a e b -> ReaderArrow r a e (Either ex b) Source #
ArrowError ex a => ArrowError ex (StateArrow s a) Source # |
Instance details Defined in Control.Arrow.Transformer.State Methods raise :: StateArrow s a ex b Source # handle :: StateArrow s a e b -> StateArrow s a (e, ex) b -> StateArrow s a e b Source # tryInUnless :: StateArrow s a e b -> StateArrow s a (e, b) c -> StateArrow s a (e, ex) c -> StateArrow s a e c Source # newError :: StateArrow s a e b -> StateArrow s a e (Either ex b) Source #
(ArrowError ex a, Applicative f) => ArrowError ex (StaticArrow f a) Source # |
Instance details Defined in Control.Arrow.Transformer.Static Methods raise :: StaticArrow f a ex b Source # handle :: StaticArrow f a e b -> StaticArrow f a (e, ex) b -> StaticArrow f a e b Source # tryInUnless :: StaticArrow f a e b -> StaticArrow f a (e, b) c -> StaticArrow f a (e, ex) c -> StaticArrow f a e c Source # newError :: StaticArrow f a e b -> StaticArrow f a e (Either ex b) Source #
(ArrowError ex a, Monoid w) => ArrowError ex (WriterArrow w a) Source # |
Instance details Defined in Control.Arrow.Transformer.Writer Methods raise :: WriterArrow w a ex b Source # handle :: WriterArrow w a e b -> WriterArrow w a (e, ex) b -> WriterArrow w a e b Source # tryInUnless :: WriterArrow w a e b -> WriterArrow w a (e, b) c -> WriterArrow w a (e, ex) c -> WriterArrow w a e c Source # newError :: WriterArrow w a e b -> WriterArrow w a e (Either ex b) 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

Instances details

ArrowLoop a => ArrowCircuit (Automaton a) Source # |
Instance details Defined in Control.Arrow.Transformer.Automaton Methods delay :: b -> Automaton a b b Source #
ArrowLoop a => ArrowCircuit (StreamArrow a) Source # |
Instance details Defined in Control.Arrow.Transformer.Stream Methods delay :: b -> StreamArrow a b b Source #
ArrowCircuit a => ArrowCircuit (ReaderArrow r a) Source # |
Instance details Defined in Control.Arrow.Transformer.Reader Methods delay :: b -> ReaderArrow r a b b Source #
ArrowCircuit a => ArrowCircuit (StateArrow s a) Source # |
Instance details Defined in Control.Arrow.Transformer.State Methods delay :: b -> StateArrow s a b b Source #
(ArrowCircuit a, Applicative f) => ArrowCircuit (StaticArrow f a) Source # |
Instance details Defined in Control.Arrow.Transformer.Static Methods delay :: b -> StaticArrow f a b b Source #
(ArrowCircuit a, Monoid w) => ArrowCircuit (WriterArrow w a) Source # |
Instance details Defined in Control.Arrow.Transformer.Writer Methods delay :: b -> WriterArrow w a b b Source #