-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Write more understandable Haskell.
--   
--   Flow provides operators for writing more understandable Haskell.
@package flow
@version 1.0.13


-- | Flow provides operators for writing more understandable Haskell. It is
--   an alternative to some common idioms like (<a>$</a>) for function
--   application and (<a>.</a>) for function composition.
--   
--   Flow is designed to be imported unqualified. It does not export
--   anything that conflicts with the base package.
--   
--   <pre>
--   &gt;&gt;&gt; import Flow
--   </pre>
--   
--   <h2>Rationale</h2>
--   
--   I think that Haskell can be hard to read. It has two operators for
--   applying functions. Both are not really necessary and only serve to
--   reduce parentheses. But they make code hard to read. People who do not
--   already know Haskell have no chance of guessing what <tt>foo $
--   bar</tt> or <tt>baz &amp; qux</tt> mean.
--   
--   Those that do know Haskell are forced to read lines forwards and
--   backwards at the same time, thanks to function composition. Even
--   something simple, like finding the minimum element, bounces around:
--   <tt>f = head . sort</tt>.
--   
--   I think we can do better. By using directional operators, we can allow
--   readers to move their eye in only one direction, be that left-to-right
--   or right-to-left. And by using idioms common in other programming
--   languages, we can allow people who aren't familiar with Haskell to
--   guess at the meaning.
--   
--   So instead of (<a>$</a>), I propose (<a>&lt;|</a>). It is a pipe,
--   which anyone who has touched a Unix system should be familiar with.
--   And it points in the direction it sends arguments along. Similarly,
--   replace (<a>&amp;</a>) with (<a>|&gt;</a>). And for composition,
--   (<a>&lt;.</a>) replaces (<a>.</a>). I would have preferred
--   <tt>&lt;&lt;</tt>, but its counterpart <tt>&gt;&gt;</tt> is taken by
--   Haskell's syntax. So-called "backwards" composition is normally
--   expressed with (<a>&gt;&gt;&gt;</a>), which Flow provides as
--   (<a>.&gt;</a>).
module Flow

-- | Left-associative <a>apply</a> operator. Read as "apply forward" or
--   "pipe into". Use this to create long chains of computation that
--   suggest which direction things move in.
--   
--   <pre>
--   &gt;&gt;&gt; 3 |&gt; succ |&gt; recip |&gt; negate
--   -0.25
--   </pre>
--   
--   Or use it anywhere you would use (<a>&amp;</a>).
--   
--   <pre>
--   \ x -&gt; (x |&gt; f) == f x
--   </pre>
--   
--   <pre>
--   \ x -&gt; (x |&gt; f |&gt; g) == g (f x)
--   </pre>
(|>) :: a -> (a -> b) -> b
infixl 0 |>

-- | Right-associative <a>apply</a> operator. Read as "apply backward" or
--   "pipe from". Use this to create long chains of computation that
--   suggest which direction things move in. You may prefer this operator
--   over (<a>|&gt;</a>) for <a>IO</a> actions since it puts the last
--   function first.
--   
--   <pre>
--   &gt;&gt;&gt; print &lt;| negate &lt;| recip &lt;| succ &lt;| 3
--   -0.25
--   </pre>
--   
--   Or use it anywhere you would use (<a>$</a>).
--   
--   Note that (<a>&lt;|</a>) and (<a>|&gt;</a>) have the same precedence,
--   so they cannot be used together.
--   
--   <pre>
--   &gt;&gt;&gt; -- This doesn't work!
--   
--   &gt;&gt;&gt; -- print &lt;| 3 |&gt; succ |&gt; recip |&gt; negate
--   </pre>
--   
--   <pre>
--   \ x -&gt; (f &lt;| x) == f x
--   </pre>
--   
--   <pre>
--   \ x -&gt; (g &lt;| f &lt;| x) == g (f x)
--   </pre>
(<|) :: (a -> b) -> a -> b
infixr 0 <|

-- | Function application. This function usually isn't necessary, but it
--   can be more readable than some alternatives when used with
--   higher-order functions like <a>map</a>.
--   
--   <pre>
--   &gt;&gt;&gt; map (apply 2) [succ, recip, negate]
--   [3.0,0.5,-2.0]
--   </pre>
--   
--   In general you should prefer using an explicit lambda or operator
--   section.
--   
--   <pre>
--   &gt;&gt;&gt; map (\ f -&gt; 2 |&gt; f) [succ, recip, negate]
--   [3.0,0.5,-2.0]
--   
--   &gt;&gt;&gt; map (2 |&gt;) [succ, recip, negate]
--   [3.0,0.5,-2.0]
--   
--   &gt;&gt;&gt; map (&lt;| 2) [succ, recip, negate]
--   [3.0,0.5,-2.0]
--   </pre>
--   
--   <pre>
--   \ x -&gt; apply x f == f x
--   </pre>
apply :: a -> (a -> b) -> b

-- | Left-associative <a>compose</a> operator. Read as "compose forward" or
--   "and then". Use this to create long chains of computation that suggest
--   which direction things move in.
--   
--   <pre>
--   &gt;&gt;&gt; let f = succ .&gt; recip .&gt; negate
--   
--   &gt;&gt;&gt; f 3
--   -0.25
--   </pre>
--   
--   Or use it anywhere you would use (<a>&gt;&gt;&gt;</a>).
--   
--   <pre>
--   \ x -&gt; (f .&gt; g) x == g (f x)
--   </pre>
--   
--   <pre>
--   \ x -&gt; (f .&gt; g .&gt; h) x == h (g (f x))
--   </pre>
(.>) :: (a -> b) -> (b -> c) -> (a -> c)
infixl 9 .>

-- | Right-associative <a>compose</a> operator. Read as "compose backward"
--   or "but first". Use this to create long chains of computation that
--   suggest which direction things move in. You may prefer this operator
--   over (<a>.&gt;</a>) for <a>IO</a> actions since it puts the last
--   function first.
--   
--   <pre>
--   &gt;&gt;&gt; let f = print &lt;. negate &lt;. recip &lt;. succ
--   
--   &gt;&gt;&gt; f 3
--   -0.25
--   </pre>
--   
--   Or use it anywhere you would use (<a>.</a>).
--   
--   Note that (<a>&lt;.</a>) and (<a>.&gt;</a>) have the same precedence,
--   so they cannot be used together.
--   
--   <pre>
--   &gt;&gt;&gt; -- This doesn't work!
--   
--   &gt;&gt;&gt; -- print &lt;. succ .&gt; recip .&gt; negate
--   </pre>
--   
--   <pre>
--   \ x -&gt; (g &lt;. f) x == g (f x)
--   </pre>
--   
--   <pre>
--   \ x -&gt; (h &lt;. g &lt;. f) x == h (g (f x))
--   </pre>
(<.) :: (b -> c) -> (a -> b) -> (a -> c)
infixr 9 <.

-- | Function composition. This function usually isn't necessary, but it
--   can be more readable than some alternatives when used with
--   higher-order functions like <a>map</a>.
--   
--   <pre>
--   &gt;&gt;&gt; let fs = map (compose succ) [recip, negate]
--   
--   &gt;&gt;&gt; map (apply 3) fs
--   [0.25,-4.0]
--   </pre>
--   
--   In general you should prefer using an explicit lambda or operator
--   section.
--   
--   <pre>
--   &gt;&gt;&gt; map (\ f -&gt; f 3) (map (\ f -&gt; succ .&gt; f) [recip, negate])
--   [0.25,-4.0]
--   
--   &gt;&gt;&gt; map (\ f -&gt; f 3) (map (succ .&gt;) [recip, negate])
--   [0.25,-4.0]
--   
--   &gt;&gt;&gt; map (\ f -&gt; f 3) (map (&lt;. succ) [recip, negate])
--   [0.25,-4.0]
--   </pre>
--   
--   <pre>
--   \ x -&gt; compose f g x == g (f x)
--   </pre>
compose :: (a -> b) -> (b -> c) -> (a -> c)

-- | Left-associative <a>apply'</a> operator. Read as "strict apply
--   forward" or "strict pipe info". Use this to create long chains of
--   computation that suggest which direction things move in.
--   
--   <pre>
--   &gt;&gt;&gt; 3 !&gt; succ !&gt; recip !&gt; negate
--   -0.25
--   </pre>
--   
--   The difference between this and (<a>|&gt;</a>) is that this evaluates
--   its argument before passing it to the function.
--   
--   <pre>
--   &gt;&gt;&gt; undefined |&gt; const True
--   True
--   
--   &gt;&gt;&gt; undefined !&gt; const True
--   *** Exception: Prelude.undefined
--   ...
--   </pre>
--   
--   <pre>
--   \ x -&gt; (x !&gt; f) == seq x (f x)
--   </pre>
--   
--   <pre>
--   \ x -&gt; (x !&gt; f !&gt; g) == let y = seq x (f x) in seq y (g y)
--   </pre>
(!>) :: a -> (a -> b) -> b
infixl 0 !>

-- | Right-associative <a>apply'</a> operator. Read as "strict apply
--   backward" or "strict pipe from". Use this to create long chains of
--   computation that suggest which direction things move in. You may
--   prefer this operator over (<a>!&gt;</a>) for <a>IO</a> actions since
--   it puts the last function first.
--   
--   <pre>
--   &gt;&gt;&gt; print &lt;! negate &lt;! recip &lt;! succ &lt;! 3
--   -0.25
--   </pre>
--   
--   The difference between this and (<a>&lt;|</a>) is that this evaluates
--   its argument before passing it to the function.
--   
--   <pre>
--   &gt;&gt;&gt; const True &lt;| undefined
--   True
--   
--   &gt;&gt;&gt; const True &lt;! undefined
--   *** Exception: Prelude.undefined
--   ...
--   </pre>
--   
--   Note that (<a>&lt;!</a>) and (<a>!&gt;</a>) have the same precedence,
--   so they cannot be used together.
--   
--   <pre>
--   &gt;&gt;&gt; -- This doesn't work!
--   
--   &gt;&gt;&gt; -- print &lt;! 3 !&gt; succ !&gt; recip !&gt; negate
--   </pre>
--   
--   <pre>
--   \ x -&gt; (f &lt;! x) == seq x (f x)
--   </pre>
--   
--   <pre>
--   \ x -&gt; (g &lt;! f &lt;! x) == let y = seq x (f x) in seq y (g y)
--   </pre>
(<!) :: (a -> b) -> a -> b
infixr 0 <!

-- | Strict function application. This function usually isn't necessary,
--   but it can be more readable than some alternatives when used with
--   higher-order functions like <a>map</a>.
--   
--   <pre>
--   &gt;&gt;&gt; map (apply' 2) [succ, recip, negate]
--   [3.0,0.5,-2.0]
--   </pre>
--   
--   The different between this and <a>apply</a> is that this evaluates its
--   argument before passing it to the function.
--   
--   <pre>
--   &gt;&gt;&gt; apply undefined (const True)
--   True
--   
--   &gt;&gt;&gt; apply' undefined (const True)
--   *** Exception: Prelude.undefined
--   ...
--   </pre>
--   
--   In general you should prefer using an explicit lambda or operator
--   section.
--   
--   <pre>
--   &gt;&gt;&gt; map (\ f -&gt; 2 !&gt; f) [succ, recip, negate]
--   [3.0,0.5,-2.0]
--   
--   &gt;&gt;&gt; map (2 !&gt;) [succ, recip, negate]
--   [3.0,0.5,-2.0]
--   
--   &gt;&gt;&gt; map (&lt;! 2) [succ, recip, negate]
--   [3.0,0.5,-2.0]
--   </pre>
--   
--   <pre>
--   \ x -&gt; apply' x f == seq x (f x)
--   </pre>
apply' :: a -> (a -> b) -> b
