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


-- | A library for patching functions and data structures
--   
--   A library for patching functions and data structures
@package patch-combinators
@version 0.1


-- | Patch combinators: A library for patching functions and data
--   structures
--   
--   A patch can be, for example
--   
--   <ul>
--   <li>a type constraint (an identity function with a specific type)</li>
--   <li>a surjective function extending the domain of a function (e.g.
--   turning a function on natural numbers into a function defined for any
--   integer)</li>
--   </ul>
--   
--   A typical use-case is to constrain the types of a QuickCheck property.
--   Let's say we have a property to check associativity of addition:
--   
--   <pre>
--   prop_addAssoc :: (Num a, Ord a) =&gt; a -&gt; a -&gt; a -&gt; Bool
--   prop_addAssoc a b c = (a + b) + c == a + (b + c)
--   </pre>
--   
--   In order to check that this property holds for <a>Int8</a>, we just
--   say:
--   
--   <pre>
--   *Data.Patch&gt; quickCheck (prop_addAssoc -:: tI8 &gt;-&gt; id)
--   </pre>
--   
--   Note that we only had to give a <i>partial</i> type annotation since
--   all arguments are required to have the same type.
--   
--   Sometimes properties are only defined for a sub-set of the possible
--   arguments. Consider the following property of <a>enumFromTo</a>:
--   
--   <pre>
--   prop_enum m n = enumFromTo 0 m !! n == n
--   </pre>
--   
--   This property is only valid when <tt>m</tt> and <tt>n</tt> are natural
--   numbers and <tt>n&lt;=m</tt>. Instead of rewriting the property to
--   account for arbitrary integers, we can simply apply a patch:
--   
--   <pre>
--   quickCheck (prop_enum -:: name (\m -&gt; abs &gt;-&gt; (min (abs m) . abs) &gt;-&gt; id))
--   </pre>
--   
--   Here <a>name</a> allows us to bind the first argument generated by
--   QuickCheck. The patch uses <a>abs</a> to make sure that the values
--   passed to the property are natural numbers, and <tt><a>min</a>
--   (<a>abs</a> m)</tt> to ensure that the second argument does not exceed
--   the first.
--   
--   The library has some similarities with Semantic editor combinators:
--   
--   <a>http://conal.net/blog/posts/semantic-editor-combinators</a>
--   
--   The main difference is that semantic editors are about locating and
--   changing a small part of a data structure, while patches are about
--   changing all parts of the structure. (For partial updates, use the
--   <a>id</a> patch to leave sub-structures untouched.)
module Data.Patch
type Patch a b = a -> b

-- | Patch application
(-::) :: a -> Patch a b -> b

-- | Function patch
--   
--   The first patch is applied to the argument and the second patch to the
--   result.
(>->) :: Patch c a -> Patch b d -> Patch (a -> b) (c -> d)

-- | A patch that depends on the first argument of the resuting function
name :: (c -> Patch (a -> b) (c -> d)) -> Patch (a -> b) (c -> d)

-- | Pair patch (a specialized version of <a>***</a>)
tup2 :: Patch a1 b1 -> Patch a2 b2 -> Patch (a1, a2) (b1, b2)

-- | Analogous to <a>tup2</a>
tup3 :: Patch a1 b1 -> Patch a2 b2 -> Patch a3 b3 -> Patch (a1, a2, a3) (b1, b2, b3)

-- | Analogous to <a>tup2</a>
tup4 :: Patch a1 b1 -> Patch a2 b2 -> Patch a3 b3 -> Patch a4 b4 -> Patch (a1, a2, a3, a4) (b1, b2, b3, b4)

-- | Analogous to <a>tup2</a>
tup5 :: Patch a1 b1 -> Patch a2 b2 -> Patch a3 b3 -> Patch a4 b4 -> Patch a5 b5 -> Patch (a1, a2, a3, a4, a5) (b1, b2, b3, b4, b5)

-- | Analogous to <a>tup2</a>
tup6 :: Patch a1 b1 -> Patch a2 b2 -> Patch a3 b3 -> Patch a4 b4 -> Patch a5 b5 -> Patch a6 b6 -> Patch (a1, a2, a3, a4, a5, a6) (b1, b2, b3, b4, b5, b6)

-- | Analogous to <a>tup2</a>
tup7 :: Patch a1 b1 -> Patch a2 b2 -> Patch a3 b3 -> Patch a4 b4 -> Patch a5 b5 -> Patch a6 b6 -> Patch a7 b7 -> Patch (a1, a2, a3, a4, a5, a6, a7) (b1, b2, b3, b4, b5, b6, b7)
tBool :: Patch Bool Bool
tWord :: Patch Word Word
tInt :: Patch Int Int
tW8 :: Patch Word8 Word8
tI8 :: Patch Int8 Int8
tW16 :: Patch Word16 Word16
tI16 :: Patch Int16 Int16
tW32 :: Patch Word32 Word32
tI32 :: Patch Int32 Int32
tInteger :: Patch Integer Integer
tFloat :: Patch Float Float
tComplex :: Patch a a -> Patch (Complex a) (Complex a)

-- | Type constructor
tCon :: Patch a a -> Patch (c a) (c a)