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


-- | A set of parsers for graph languages and conversions to
--   graph libaries.
--   
--   A package allowing parsing of graph files into graph library
--   datatypes. With aim the cope with large networks and provide
--   translations between graph libraries. Like a pandoc but for graphs.
--   This is my first library so any feedback and help is appreicated. For
--   example use please see the homepage.
@package pangraph
@version 0.2.1


-- | See <a>Pangraph</a> for the type which provides a guaranteed
--   well-formed graph once constructed. The rest of the modules provides
--   constructors and getters on this type.
module Pangraph

-- | The <a>Pangraph</a> type is the core intermediate type between
--   abstract representations of graphs.
data Pangraph

-- | Edges also reqiure [<a>Attribute</a>] and a tuple of <a>Vertex</a>
--   passed as connections to be constructed with <a>makeEdge</a>
data Edge

-- | A Vertex holds [<a>Attribute</a>] and must have a unique
--   <a>VertexID</a> to be constructed with <a>makeVertex</a>.
data Vertex

-- | The type alias for storage of fields.
type Attribute = (Key, Value)

-- | The <a>Key</a> in the tuple that makes up <a>Attribute</a>.
type Key = ByteString

-- | The <a>Value</a> in the tuple that makes up <a>Attribute</a>.
type Value = ByteString

-- | A field that is Maybe internally is exposed for lookup.
type VertexID = ByteString

-- | A type exposed for lookup in the resulting lists.
type EdgeID = Int
type MalformedEdge = (Edge, (Maybe VertexID, Maybe VertexID))

-- | Takes lists of <a>Vertex</a> and <a>Edge</a> to produce 'Just
--   Pangraph' if the graph is correctly formed.
makePangraph :: [Vertex] -> [Edge] -> Maybe Pangraph

-- | Edge constructor
makeEdge :: (VertexID, VertexID) -> [Attribute] -> Edge

-- | Vertex constructor
makeVertex :: VertexID -> [Attribute] -> Vertex

-- | Returns the [<a>Edge</a>] from a <a>Pangraph</a> instance
edgeList :: Pangraph -> [Edge]

-- | Returns the [<a>Vertex</a>] from a <a>Pangraph</a> instance
vertexList :: Pangraph -> [Vertex]

-- | Lookup of the <a>VertexID</a> in a <a>Pangraph</a>. Complexity:
--   <i>O(log n)</i>
lookupVertex :: VertexID -> Pangraph -> Maybe Vertex

-- | Lookup of the <a>EdgeID</a> in a <a>Pangraph</a>. Complexity: <i>O(log
--   n)</i>
lookupEdge :: EdgeID -> Pangraph -> Maybe Edge

-- | Returns the [<a>Attribute</a>] of an <a>Edge</a>
edgeAttributes :: Edge -> [Attribute]

-- | Returns the [<a>Attribute</a>] list of an <a>Edge</a>
vertexAttributes :: Vertex -> [Attribute]

-- | Returns the endpoint of tupled <a>Vertex</a> of an <a>Edge</a>
edgeEndpoints :: Edge -> (VertexID, VertexID)

-- | Returns the EdgeID if it has one. <a>Edge</a>s are given a new
--   <a>EdgeID</a> when they are passed and retrived from a <a>Pangraph</a>
edgeID :: Edge -> Maybe EdgeID

-- | Returns a <a>VertexID</a>
vertexID :: Vertex -> VertexID
instance GHC.Classes.Eq Pangraph.Pangraph
instance GHC.Classes.Eq Pangraph.Vertex
instance GHC.Classes.Eq Pangraph.Edge
instance GHC.Show.Show Pangraph.Pangraph
instance Algebra.Graph.ToGraph.ToGraph Pangraph.Pangraph
instance GHC.Show.Show Pangraph.Vertex
instance GHC.Show.Show Pangraph.Edge


module Pangraph.Containers

-- | Transforms a <a>Pangraph</a> into a <a>Graph</a>.
convert :: Pangraph -> (Graph, Vertex -> (Vertex, VertexID, [VertexID]), VertexID -> Maybe Vertex)

module Pangraph.Examples.SampleGraph
smallGraph :: Pangraph


-- | AST for gml (Graph Modelling Language) files. The specification of the
--   gml format can be found at:
--   <a>http://www.fim.uni-passau.de/fileadmin/files/lehrstuhl/brandenburg/projekte/gml/gml-technical-report.pdf</a>.
module Pangraph.Gml.Ast

-- | Type of a AST node. <tt>k</tt> is the type that is used to represent
--   strings.
data Gml k

-- | Integer value
Integer :: Integer -> Gml k

-- | Floating point value
Float :: Double -> Gml k

-- | String value
String :: k -> Gml k

-- | Object value. A gml object is a list of named values. The names of the
--   values are not necessarily unique!
Object :: [(k, Gml k)] -> Gml k

-- | Looks up a value in the given gml object. Produces <a>Nothing</a> when
--   the given value is not a gml object or the object doesn't contain the
--   a value with the given name. If a object contains multiple values with
--   the same name one the values is returned.
lookupValue :: Eq k => Gml k -> k -> Maybe (Gml k)

-- | If the given gml value is a integer produces the integer value.
integerValue :: Gml k -> Maybe Integer

-- | If the given gml value is a double value produces the float value.
floatValue :: Gml k -> Maybe Double

-- | If the given gml value is a string produces the string value.
stringValue :: Gml k -> Maybe k

-- | If the given gml value is an object produces the list of values that
--   the object contains.
objectValues :: Gml k -> Maybe [(k, Gml k)]

-- | Maps all strings in the gml ast.
mapStrings :: (a -> b) -> Gml a -> Gml b
instance GHC.Classes.Ord k => GHC.Classes.Ord (Pangraph.Gml.Ast.Gml k)
instance GHC.Classes.Eq k => GHC.Classes.Eq (Pangraph.Gml.Ast.Gml k)
instance GHC.Show.Show k => GHC.Show.Show (Pangraph.Gml.Ast.Gml k)


-- | Functions for parseing gml (Graphical Modelling Language) files. A gml
--   specification can be found at:
--   <a>http://www.fim.uni-passau.de/fileadmin/files/lehrstuhl/brandenburg/projekte/gml/gml-technical-report.pdf</a>.
--   
--   This follows the specification except for two cases:
--   
--   <ol>
--   <li>All files are assumed to be encoded in UTF8</li>
--   <li>The line length limit is ignored.</li>
--   </ol>
module Pangraph.Gml.Parser

-- | Parses the <tt>ByteString</tt> into a <a>Pangraph</a>.
parse :: ByteString -> Maybe Pangraph

-- | Parses the <tt>ByteString</tt> into a <a>Gml</a> ast. The function
--   doesn't decode special characters inside strings. To decode special
--   characters inside strings use the <a>decode</a> function.
parseGml :: ByteString -> Maybe (Gml Text)

-- | Decodes special characters inside gml strings.
decode :: Gml Text -> Gml Text

-- | Converts a gml ast into a <a>Pangraph</a>. If a node/edge contains a
--   gml object these object are not contained in the resulting
--   <a>Pangraph</a>.
gmlToPangraph :: Gml Text -> Maybe Pangraph


-- | Functions for writing gml files. Follows the gml specification at
--   <a>http://www.fim.uni-passau.de/fileadmin/files/lehrstuhl/brandenburg/projekte/gml/gml-technical-report.pdf</a>
--   execpt for two cases:
--   
--   <ol>
--   <li>all produced <a>ByteString</a>s are encoded in UTF8 instead of
--   ASCII,</li>
--   <li>the line length limit is ignored.</li>
--   </ol>
module Pangraph.Gml.Writer

-- | Serializes a <a>Gml</a> syntax tree into a bytestring. Produces
--   <a>Nothing</a> for all values except <a>Object</a> since a gml file
--   must contain at least one top level object to hold all values.
writeGml :: Gml ByteString -> Maybe ByteString

-- | Converts a <a>Pangraph</a> into a <a>Gml</a> syntax tree.
--   Automatically encodes special characters in strings.
pangraphToGml :: Pangraph -> Gml ByteString

-- | Serializes a Pangraph into a GML file.
write :: Pangraph -> ByteString

-- | Encodes the string values in a <a>Gml</a> syntax tree.
encodeStrings :: Gml ByteString -> Gml ByteString


module Pangraph.GraphML.Writer

-- | Serialise a <a>Pangraph</a> into a GraphML file producing a
--   <a>ByteString</a>.
write :: Pangraph -> ByteString

module Pangraph.Internal.HexmlExtra

-- | Find the [<a>Node</a>] with the final in the [<a>ByteString</a>] after
--   following the <a>Node</a> names recursively.
followChildren :: Node -> [ByteString] -> [Node]
hexmlParse :: ByteString -> Node

-- | Converts a between the two libaries Attribute types.
convertAtt :: Attribute -> Attribute


-- | This module provides common boilerplate code which implements
--   constructing a Pangraph from either ASTs or Graph types.
--   
--   It is exported as internal for now as it is intended use by modules
--   which will not re-export it.
module Pangraph.Internal.ProtoGraph
data ProtoVertex
data ProtoEdge

-- | ProtoVertex constructor
makeProtoVertex :: [Attribute] -> ProtoVertex

-- | ProtoEdge constructor
makeProtoEdge :: [Attribute] -> ProtoEdge

-- | Returns [<a>Attribute</a>] of a <a>ProtoVertex</a>
protoVertexAttributes :: ProtoVertex -> [Attribute]

-- | Returns [<a>Attribute</a>] of a <a>ProtoEdge</a>
protoEdgeAttributes :: ProtoEdge -> [Attribute]
class BuildPangraph t

-- | Given an Instance t of the BuildGraph will attempt to construct a
--   Pangraph. This can be used to avoid boilerplate code which is common
--   many implementations.
buildPangraph :: BuildPangraph t => t -> (ProtoVertex -> VertexID) -> (ProtoEdge -> (VertexID, VertexID)) -> Maybe Pangraph
getProtoEdge :: BuildPangraph t => t -> [ProtoEdge]
getProtoVertex :: BuildPangraph t => t -> [ProtoVertex]
instance GHC.Classes.Eq Pangraph.Internal.ProtoGraph.ProtoVertex
instance GHC.Classes.Eq Pangraph.Internal.ProtoGraph.ProtoEdge
instance GHC.Classes.Eq Pangraph.Internal.ProtoGraph.ProtoGraphStage2
instance GHC.Classes.Eq Pangraph.Internal.ProtoGraph.ProtoGraphStage1
instance GHC.Show.Show Pangraph.Internal.ProtoGraph.ProtoVertex
instance GHC.Show.Show Pangraph.Internal.ProtoGraph.ProtoEdge

module Pangraph.FGL

-- | Convert a Pangraph to Fgl types.
convert :: Pangraph -> ([LNode ByteString], [LEdge Int])

-- | Revert FGL types into Pangraph.
revert :: ([LNode ByteString], [LEdge Int]) -> Maybe Pangraph
instance Pangraph.Internal.ProtoGraph.BuildPangraph Pangraph.FGL.FGL

module Pangraph.Internal.XMLTemplate
data Template
graphMLTemplate :: Template
hexmlToPangraph :: Template -> HexmlVertex -> Maybe Pangraph


-- | Provides two functions for constructing a <a>Pangraph</a> from a
--   GraphML file.
module Pangraph.GraphML.Parser

-- | Throws on on failed XML parsing. Otherwise returns 'Right Pangraph' if
--   the graph is well formed, listing 'Left [MalformedEdge]' otherwise.
parse :: ByteString -> Maybe Pangraph

-- | Like <a>parse</a> except it throws an error on Nothing, which is when
--   parsing fails OR the graph is malformed.
unsafeParse :: ByteString -> Pangraph

module Pangraph.Example
main :: IO ()