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


-- | Data types for named entities
--   
--   The library provides data types which can be used to represent forest
--   structures with labels stored in internal nodes and words kept in
--   leaves. In particular, those types are well suited for representing
--   the layer of named entities (NEs).
--   
--   The IOB method is implemented in the Data.Named.IOB module and can be
--   used to translate between a forest of entities and a sequence of
--   compound IOB labels. This method can be used together with a sequence
--   classifier to indirectly model forest structures.
--   
--   The Data.Named.Graph module can be used to represent more general,
--   graph structures of entities. The module provides also a lossy
--   conversion from a DAG to a disjoint forest of entities.
@package data-named
@version 0.3.0


-- | Parsing text in the Enamex data format. Each node is enclosed between
--   opening and closing tags with tag name representing the label and
--   contents representing children of the node. Both leaf and label values
--   should be escaped by prepending the \ character before special >,
--   <, \ and space characters.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; :m Data.Tree Data.Text Text.Named.Enamex
--   
--   &gt;&gt;&gt; let drawIt = putStr . drawForest . fmap (fmap unpack) . parseForest
--   
--   &gt;&gt;&gt; drawIt $ pack "&lt;x&gt;w1.1\\ w1.2&lt;/x&gt; &lt;y&gt;&lt;z&gt;w2&lt;/z&gt; w3&lt;/y&gt;"
--   x
--   |
--   `- w1.1 w1.2
--   ,
--   y
--   |
--   +- z
--   |  |
--   |  `- w2
--   |
--   `- w3
--   </pre>
module Text.Named.Enamex

-- | Parse the enamex forest.
parseForest :: Text -> Forest

-- | Parse the enamex file.
parseEnamex :: Text -> [Forest]

-- | Map the first function over internal nodes and the second one over
--   leaves.
mapTwo :: (a -> b) -> (a -> c) -> Tree a -> Tree (Either b c)


-- | IOB encoding method extended to forests.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; :m Data.Tree Data.Text Text.Named.Enamex Data.Named.IOB
--   
--   &gt;&gt;&gt; let enamex = pack "&lt;x&gt;w1.1\\ w1.2&lt;/x&gt; w2 &lt;y&gt;&lt;z&gt;w3&lt;/z&gt; w4&lt;/y&gt;"
--   
--   &gt;&gt;&gt; let parseIt = fmap (mapTwo id id . fmap unpack) . parseForest
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; putStr . drawForest . fmap (fmap show) . parseIt $ enamex
--   Left "x"
--   |
--   `- Right "w1.1 w1.2"
--   ,
--   Right "w2"
--   ,
--   Left "y"
--   |
--   +- Left "z"
--   |  |
--   |  `- Right "w3"
--   |
--   `- Right "w4"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; mapM_ print . encodeForest . parseIt $ enamex
--   IOB {word = "w1.1 w1.2", label = [B "x"]}
--   IOB {word = "w2", label = []}
--   IOB {word = "w3", label = [B "y",B "z"]}
--   IOB {word = "w4", label = [I "y"]}
--   </pre>
module Data.Named.IOB

-- | An <a>IOB</a> data structure consists of a word with a corresponding
--   compound label.
data IOB w a
IOB :: w -> Label a -> IOB w a
word :: IOB w a -> w
label :: IOB w a -> Label a

-- | A <a>Label</a> consists of a list of atomic <a>Atom</a> labels.
type Label a = [Atom a]

-- | An <a>Atom</a> is the atomic label with additional marker.
data Atom a

-- | Beginning marker
B :: a -> Atom a

-- | Inside marker
I :: a -> Atom a

-- | Encode the forest with the IOB method.
encodeForest :: Forest (Either a w) -> [IOB w a]

-- | Decode the forest using the IOB method.
decodeForest :: Eq a => [IOB w a] -> Forest (Either a w)
instance Show a => Show (Atom a)
instance Eq a => Eq (Atom a)
instance Ord a => Ord (Atom a)
instance (Show w, Show a) => Show (IOB w a)


-- | Working with NE trees and forests.
module Data.Named.Tree

-- | Spanning of a tree.
data Span w
Span :: w -> w -> Span w
beg :: Span w -> w
end :: Span w -> w

-- | Make span for a leaf node.
leafSpan :: w -> Span w

-- | Minimum span overlapping both input spans.
(<>) :: Ord w => Span w -> Span w -> Span w

-- | Set of positions covered by the span.
spanSet :: Ix w => Span w -> Set w

-- | Get span of the span-annotated tree.
span :: Tree (a, Span w) -> Span w

-- | Annotate tree nodes with spanning info given the function which
--   assignes indices to leaf nodes.
spanTree :: Ord w => Tree (Either n w) -> Tree (Either n w, Span w)

-- | Annotate forest nodes with spanning info.
spanForest :: Ord w => Forest (Either n w) -> Forest (Either n w, Span w)

-- | Remove span annotations from the tree.
unSpanTree :: Tree (k, Span w) -> Tree k

-- | Remove span annotations from the forest.
unSpanForest :: Forest (k, Span w) -> Forest k

-- | Sort the tree with respect to spanning info.
sortTree :: Ord w => Tree (k, Span w) -> Tree (k, Span w)

-- | Sort the forest with respect to spanning info.
sortForest :: Ord w => Forest (k, Span w) -> Forest (k, Span w)

-- | Map function over tree leaves.
mapLeaves :: (a -> b) -> Tree (Either c a) -> Tree (Either c b)

-- | Map function over tree internal nodes.
mapNodes :: (a -> b) -> Tree (Either a c) -> Tree (Either b c)

-- | Map function over each tree from the forest.
mapTrees :: (a -> b) -> Forest a -> Forest b
instance Show w => Show (Span w)
instance Eq w => Eq (Span w)
instance Ord w => Ord (Span w)


-- | Implementation of a graph with each internal node identified by a
--   unique key and each leaf represented by a position in the sentence.
module Data.Named.Graph

-- | A graph over a sentence.
data Graph n w
Graph :: (w, w) -> Map n [Either n w] -> Graph n w
bounds :: Graph n w -> (w, w)
edgeMap :: Graph n w -> Map n [Either n w]

-- | Make a graph given the bounds and list of edges.
mkGraph :: (Ord n, Ix w) => (w, w) -> [(n, [Either n w])] -> Graph n w

-- | Get keys of adjacent nodes for the given node key.
edges :: Ord n => Graph n w -> n -> [Either n w]

-- | Return all graph roots (i.e. nodes with no parents).
roots :: Ord n => Graph n w -> [n]

-- | Transform graph into a disjoint forest, i.e. with no mutually
--   overlapping trees.
toForest :: (Ord n, Ix w) => Graph n w -> Forest (Either n w)
instance Monad (RanM w)