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


-- | Execute a set of actions (e.g. parsers) in each possible order
--   
--   Sequence a set of Alternative actions in each possible order, based on
--   "Parsing Permutation Phrases", by Arthur Baars, Andres Loeh and S.
--   Doaitse Swierstra, <i>Haskell Workshop 2001</i>. This is particularly
--   useful for constructing a parser for permutations of elements. This
--   version has a slightly different interface from the paper.
@package action-permutations
@version 0.0.0.1


-- | Constructing an action as a choice between all the permutations of
--   some given actions (e.g. parsers), based on "Parsing Permutation
--   Phrases", by Arthur Baars, Andres Loeh and S. Doaitse Swierstra,
--   <i>Haskell Workshop 2001</i>.
--   
--   This version has a slightly different interface from the paper.
module Control.Applicative.Permutation

-- | A representation of a permutation of actions of an <a>Alternative</a>
--   type <tt>p</tt>. The value type of the composite action is <tt>a</tt>.
--   
--   Permutations are constructed from the primitives <a>atom</a>,
--   <a>optAtom</a> and <a>maybeAtom</a>, and combined using the methods of
--   <a>Functor</a> and <a>Applicative</a>. They are converted back to
--   composite actions using <a>runPerms</a> and <a>runPermsSep</a>.
--   
--   The component actions of a permutation will be executed in each
--   possible order, but the values they produce are always assembled in
--   the order they occur in the program text, as in the following
--   permutations of one, two or three component actions:
--   
--   <ul>
--   <li><pre><a>runPerms</a> (f <a>&lt;$&gt;</a> <a>atom</a> a) = f
--   <a>&lt;$&gt;</a> a</pre></li>
--   <li><pre><a>runPerms</a> (f <a>&lt;$&gt;</a> <a>atom</a> a
--   <a>&lt;*&gt;</a> <a>atom</a> b) = (f <a>&lt;$&gt;</a> a
--   <a>&lt;*&gt;</a> b) <a>&lt;|&gt;</a> (<a>flip</a> f <a>&lt;$&gt;</a> b
--   <a>&lt;*&gt;</a> a)</pre></li>
--   <li><pre><a>runPerms</a> (f <a>&lt;$&gt;</a> <a>atom</a> a
--   <a>&lt;*&gt;</a> <a>atom</a> b <a>&lt;*&gt;</a> <a>atom</a> c) = ((\ x
--   (y,z) -&gt; f x y z) <a>&lt;$&gt;</a> a <a>&lt;*&gt;</a> ((,)
--   <a>&lt;$&gt;</a> b <a>&lt;*&gt;</a> c) <a>&lt;|&gt;</a> (<a>flip</a>
--   (,) <a>&lt;$&gt;</a> c <a>&lt;*&gt;</a> b)) <a>&lt;|&gt;</a> ((\ y
--   (z,x) -&gt; f x y z) <a>&lt;$&gt;</a> b <a>&lt;*&gt;</a> ((,)
--   <a>&lt;$&gt;</a> a <a>&lt;*&gt;</a> c) <a>&lt;|&gt;</a> (<a>flip</a>
--   (,) <a>&lt;$&gt;</a> c <a>&lt;*&gt;</a> a)) <a>&lt;|&gt;</a> ((\ z
--   (x,y) -&gt; f x y z) <a>&lt;$&gt;</a> c <a>&lt;*&gt;</a> ((,)
--   <a>&lt;$&gt;</a> a <a>&lt;*&gt;</a> b) <a>&lt;|&gt;</a> (<a>flip</a>
--   (,) <a>&lt;$&gt;</a> b <a>&lt;*&gt;</a> a))</pre></li>
--   </ul>
--   
--   The permutation is encoded as a tree, with the first action executed
--   before the second selection is made. Thus failing actions, e.g.
--   parsers, prune this tree. The size of the tree is exponential in the
--   number of components, but it is constructed lazily.
data Perms p a

-- | A primitive permutation consisting of a single action.
--   
--   <ul>
--   <li><pre><a>runPerms</a> (<a>atom</a> a) = a</pre></li>
--   </ul>
--   
--   When building permutation parsers, the argument parser should not
--   match the empty string: use <a>optAtom</a> or <a>maybeAtom</a> for
--   optional elements.
atom :: Alternative p => p a -> Perms p a

-- | Like <a>atom</a>, but the action may be omitted from the permutation.
--   
--   <ul>
--   <li><pre><a>runPerms</a> (<a>optAtom</a> d p) = p <a>&lt;|&gt;</a>
--   <a>pure</a> d</pre></li>
--   </ul>
--   
--   When building permutation parsers, the argument parser should not
--   match the empty string.
optAtom :: Alternative p => a -> p a -> Perms p a

-- | Like <a>atom</a>, but the action may be omitted from the permutation.
--   
--   <ul>
--   <li><pre><a>runPerms</a> (<a>maybeAtom</a> p) = <a>Just</a>
--   <a>&lt;$&gt;</a> p <a>&lt;|&gt;</a> <a>pure</a>
--   <a>Nothing</a></pre></li>
--   </ul>
--   
--   When building permutation parsers, the argument parser should not
--   match the empty string.
maybeAtom :: Alternative p => p a -> Perms p (Maybe a)

-- | Construct a permutation action.
--   
--   <ul>
--   <li><pre><a>runPerms</a> (<a>pure</a> x) = <a>pure</a> x</pre></li>
--   <li><pre><a>runPerms</a> (f <a>&lt;$&gt;</a> p) = f <a>&lt;$&gt;</a>
--   <a>runPerms</a> p</pre></li>
--   </ul>
runPerms :: Alternative p => Perms p a -> p a

-- | <tt><a>runPermsSep</a> sep p</tt> is similar to <tt><a>runPerms</a>
--   p</tt>, except that the action <tt>sep</tt> is interleaved between
--   atomic actions in each permutation.
--   
--   <ul>
--   <li><pre><a>runPermsSep</a> sep (f <a>&lt;$&gt;</a> <a>atom</a> a) = f
--   <a>&lt;$&gt;</a> a</pre></li>
--   <li><pre><a>runPermsSep</a> sep (f <a>&lt;$&gt;</a> <a>atom</a> a
--   <a>&lt;*&gt;</a> <a>atom</a> b) = (f <a>&lt;$&gt;</a> a <a>&lt;*</a>
--   sep <a>&lt;*&gt;</a> b) <a>&lt;|&gt;</a> (<a>flip</a> f
--   <a>&lt;$&gt;</a> b <a>&lt;*</a> sep <a>&lt;*&gt;</a> a)</pre></li>
--   </ul>
--   
--   It is particularly useful in constructing permutation parsers, where
--   <tt>sep</tt> might be a parser for a comma or other separator.
runPermsSep :: Alternative p => p b -> Perms p a -> p a
instance GHC.Base.Functor p => GHC.Base.Functor (Control.Applicative.Permutation.Perms p)
instance GHC.Base.Functor p => GHC.Base.Functor (Control.Applicative.Permutation.Branch p)
instance GHC.Base.Alternative p => GHC.Base.Applicative (Control.Applicative.Permutation.Perms p)
instance GHC.Base.Alternative p => GHC.Base.Applicative (Control.Applicative.Permutation.Branch p)
