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


-- | QuickCheck support for fgl
--   
--   Provides Arbitrary instances for fgl graphs (to avoid adding a
--   QuickCheck dependency for fgl whilst still making the instances
--   available to others).
--   
--   Also available are non-fgl-specific functions for generating
--   graph-like data structures.
@package fgl-arbitrary
@version 0.2.0.2


-- | This module provides default definitions for use with QuickCheck's
--   <a>Arbitrary</a> class.
--   
--   Both <a>Data.Graph.Inductive.Tree</a>- and
--   <a>Data.Graph.Inductive.PatriciaTree</a>-based graph implementations
--   have <a>Arbitrary</a> instances. In most cases, this is all you will
--   need.
--   
--   If, however, you want to create arbitrary custom graph-like data
--   structures, then you will probably want to do some custom processing
--   from an arbitrary <a>GraphNodesEdges</a> value, either directly or
--   with a custom <a>ArbGraph</a> instance.
module Data.Graph.Inductive.Arbitrary

-- | Generate an arbitrary graph. Multiple edges are allowed.
arbitraryGraph :: (Graph gr, Arbitrary a, Arbitrary b) => Gen (gr a b)

-- | Generate an arbitrary graph, using the specified function to
--   manipulate the generated list of edges (e.g. remove multiple edges).
arbitraryGraphWith :: (Graph gr, Arbitrary a, Arbitrary b) => ([LEdge b] -> [LEdge b]) -> Gen (gr a b)

-- | For a graph with at least two nodes, return every possible way of
--   deleting a single node (i.e. will never shrink to an empty graph).
shrinkGraph :: (Graph gr) => gr a b -> [gr a b]

-- | As with <a>shrinkGraph</a>, but also return the node that was deleted.
shrinkGraphWith :: (Graph gr) => gr a b -> [(Node, gr a b)]

-- | Representation of generating arbitrary graph structures.
--   
--   Typically, you would only use this for the <a>toBaseGraph</a> function
--   or if you wanted to make a custom graph wrapper.
--   
--   The intent of this class is to simplify defining and using different
--   wrappers on top of graphs (e.g. you may wish to have an
--   <a>Undirected</a> graph, or one with <a>NoLoops</a>, or possibly
--   both!).
class (DynGraph (BaseGraph ag)) => ArbGraph ag where type BaseGraph ag :: * -> * -> * where {
    type family BaseGraph ag :: * -> * -> *;
}
toBaseGraph :: ArbGraph ag => ag a b -> BaseGraph ag a b
fromBaseGraph :: ArbGraph ag => BaseGraph ag a b -> ag a b

-- | Any manipulation of edges that should be done to satisfy the
--   requirements of the specified wrapper.
edgeF :: ArbGraph ag => GrProxy ag -> [LEdge b] -> [LEdge b]

-- | Shrinking function (assuming only one node is removed at a time) which
--   also returns the node that is removed.
shrinkFWith :: ArbGraph ag => ag a b -> [(Node, ag a b)]

-- | A simple graph-specific proxy type.
data GrProxy (gr :: * -> * -> *)
GrProxy :: GrProxy

-- | In most cases, for an instance of <a>ArbGraph</a> the <a>Arbitrary</a>
--   instance definition will/can have <tt>shrink = shrinkF</tt>.
shrinkF :: (ArbGraph ag) => ag a b -> [ag a b]

-- | Generate an instance of <a>ArbGraph</a> using the class methods.
arbitraryGraphBy :: forall ag a b. (ArbGraph ag, Arbitrary a, Arbitrary b) => Gen (ag a b)

-- | A newtype wrapper to generate a graph without multiple edges (loops
--   allowed).
newtype NoMultipleEdges gr a b
NME :: gr a b -> NoMultipleEdges gr a b
[nmeGraph] :: NoMultipleEdges gr a b -> gr a b

-- | A newtype wrapper to generate a graph without loops (multiple edges
--   allowed).
newtype NoLoops gr a b
NL :: gr a b -> NoLoops gr a b
[looplessGraph] :: NoLoops gr a b -> gr a b

-- | A wrapper to generate a graph without multiple edges and no loops.
type SimpleGraph gr = NoLoops (NoMultipleEdges gr)

-- | A newtype wrapper such that each (non-loop) edge also has its reverse
--   in the graph.
--   
--   Note that there is no way to guarantee this after any additional edges
--   are added or removed.
--   
--   You should also apply this wrapper <i>after</i> <a>NoMultipleEdges</a>
--   or else the wrong reverse edge might be removed.
newtype Undirected gr a b
UG :: gr a b -> Undirected gr a b
[undirGraph] :: Undirected gr a b -> gr a b

-- | A brute-force approach to generating connected graphs.
--   
--   The resultant graph (obtained with <a>connGraph</a>) will <i>never</i>
--   be empty: it will, at the very least, contain an additional connected
--   node (obtained with <a>connNode</a>).
--   
--   Note that this is <i>not</i> an instance of <a>ArbGraph</a> as it is
--   not possible to arbitrarily layer a transformer on top of this.
data Connected ag a b
CG :: Node -> ag a b -> Connected ag a b
[connNode] :: Connected ag a b -> Node
[connArbGraph] :: Connected ag a b -> ag a b

-- | The underlying graph represented by this <a>Connected</a> value.
connGraph :: (ArbGraph ag) => Connected ag a b -> BaseGraph ag a b

-- | Generally a list of labelled nodes.
arbitraryNodes :: (Arbitrary a) => Gen [LNode a]

-- | Given a specified list of nodes, generate a list of edges.
arbitraryEdges :: (Arbitrary b) => [LNode a] -> Gen [LEdge b]

-- | Defined so as to be able to generate valid <a>arbitrary</a> node and
--   edge lists.
--   
--   If any specific structure (no multiple edges, no loops, etc.) is
--   required then you will need to post-process this after generating it,
--   or else create a new instance of <a>ArbGraph</a>.
data GraphNodesEdges a b
GNEs :: [LNode a] -> [LEdge b] -> GraphNodesEdges a b
[graphNodes] :: GraphNodesEdges a b -> [LNode a]
[graphEdges] :: GraphNodesEdges a b -> [LEdge b]
instance GHC.Read.Read (ag a b) => GHC.Read.Read (Data.Graph.Inductive.Arbitrary.Connected ag a b)
instance GHC.Show.Show (ag a b) => GHC.Show.Show (Data.Graph.Inductive.Arbitrary.Connected ag a b)
instance GHC.Classes.Eq (ag a b) => GHC.Classes.Eq (Data.Graph.Inductive.Arbitrary.Connected ag a b)
instance GHC.Read.Read (gr a b) => GHC.Read.Read (Data.Graph.Inductive.Arbitrary.Undirected gr a b)
instance GHC.Show.Show (gr a b) => GHC.Show.Show (Data.Graph.Inductive.Arbitrary.Undirected gr a b)
instance GHC.Classes.Eq (gr a b) => GHC.Classes.Eq (Data.Graph.Inductive.Arbitrary.Undirected gr a b)
instance GHC.Read.Read (gr a b) => GHC.Read.Read (Data.Graph.Inductive.Arbitrary.NoLoops gr a b)
instance GHC.Show.Show (gr a b) => GHC.Show.Show (Data.Graph.Inductive.Arbitrary.NoLoops gr a b)
instance GHC.Classes.Eq (gr a b) => GHC.Classes.Eq (Data.Graph.Inductive.Arbitrary.NoLoops gr a b)
instance GHC.Read.Read (gr a b) => GHC.Read.Read (Data.Graph.Inductive.Arbitrary.NoMultipleEdges gr a b)
instance GHC.Show.Show (gr a b) => GHC.Show.Show (Data.Graph.Inductive.Arbitrary.NoMultipleEdges gr a b)
instance GHC.Classes.Eq (gr a b) => GHC.Classes.Eq (Data.Graph.Inductive.Arbitrary.NoMultipleEdges gr a b)
instance GHC.Read.Read (Data.Graph.Inductive.Arbitrary.GrProxy gr)
instance GHC.Show.Show (Data.Graph.Inductive.Arbitrary.GrProxy gr)
instance GHC.Classes.Ord (Data.Graph.Inductive.Arbitrary.GrProxy gr)
instance GHC.Classes.Eq (Data.Graph.Inductive.Arbitrary.GrProxy gr)
instance (GHC.Read.Read a, GHC.Read.Read b) => GHC.Read.Read (Data.Graph.Inductive.Arbitrary.GraphNodesEdges a b)
instance (GHC.Show.Show a, GHC.Show.Show b) => GHC.Show.Show (Data.Graph.Inductive.Arbitrary.GraphNodesEdges a b)
instance (GHC.Classes.Ord a, GHC.Classes.Ord b) => GHC.Classes.Ord (Data.Graph.Inductive.Arbitrary.GraphNodesEdges a b)
instance (GHC.Classes.Eq a, GHC.Classes.Eq b) => GHC.Classes.Eq (Data.Graph.Inductive.Arbitrary.GraphNodesEdges a b)
instance (Test.QuickCheck.Arbitrary.Arbitrary a, Test.QuickCheck.Arbitrary.Arbitrary b) => Test.QuickCheck.Arbitrary.Arbitrary (Data.Graph.Inductive.Arbitrary.GraphNodesEdges a b)
instance Data.Graph.Inductive.Arbitrary.ArbGraph Data.Graph.Inductive.Tree.Gr
instance Data.Graph.Inductive.Arbitrary.ArbGraph Data.Graph.Inductive.PatriciaTree.Gr
instance (Test.QuickCheck.Arbitrary.Arbitrary a, Test.QuickCheck.Arbitrary.Arbitrary b) => Test.QuickCheck.Arbitrary.Arbitrary (Data.Graph.Inductive.Tree.Gr a b)
instance (Test.QuickCheck.Arbitrary.Arbitrary a, Test.QuickCheck.Arbitrary.Arbitrary b) => Test.QuickCheck.Arbitrary.Arbitrary (Data.Graph.Inductive.PatriciaTree.Gr a b)
instance Data.Graph.Inductive.Arbitrary.ArbGraph gr => Data.Graph.Inductive.Arbitrary.ArbGraph (Data.Graph.Inductive.Arbitrary.NoMultipleEdges gr)
instance (Data.Graph.Inductive.Arbitrary.ArbGraph gr, Test.QuickCheck.Arbitrary.Arbitrary a, Test.QuickCheck.Arbitrary.Arbitrary b) => Test.QuickCheck.Arbitrary.Arbitrary (Data.Graph.Inductive.Arbitrary.NoMultipleEdges gr a b)
instance Data.Graph.Inductive.Arbitrary.ArbGraph gr => Data.Graph.Inductive.Arbitrary.ArbGraph (Data.Graph.Inductive.Arbitrary.NoLoops gr)
instance (Data.Graph.Inductive.Arbitrary.ArbGraph gr, Test.QuickCheck.Arbitrary.Arbitrary a, Test.QuickCheck.Arbitrary.Arbitrary b) => Test.QuickCheck.Arbitrary.Arbitrary (Data.Graph.Inductive.Arbitrary.NoLoops gr a b)
instance Data.Graph.Inductive.Arbitrary.ArbGraph gr => Data.Graph.Inductive.Arbitrary.ArbGraph (Data.Graph.Inductive.Arbitrary.Undirected gr)
instance (Data.Graph.Inductive.Arbitrary.ArbGraph gr, Test.QuickCheck.Arbitrary.Arbitrary a, Test.QuickCheck.Arbitrary.Arbitrary b) => Test.QuickCheck.Arbitrary.Arbitrary (Data.Graph.Inductive.Arbitrary.Undirected gr a b)
instance (Data.Graph.Inductive.Arbitrary.ArbGraph ag, Test.QuickCheck.Arbitrary.Arbitrary a, Test.QuickCheck.Arbitrary.Arbitrary b) => Test.QuickCheck.Arbitrary.Arbitrary (Data.Graph.Inductive.Arbitrary.Connected ag a b)