-- 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.5.2


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

-- | A tree with a values in internal nodes and b values in leaves.
type NeTree a b = Tree (Either a b)

-- | A forest with a values in internal nodes and b values in leaves.
type NeForest a b = Forest (Either a b)

-- | 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 each tree from the forest.
mapForest :: (a -> b) -> Forest a -> Forest b

-- | Map function over the tree.
mapTree :: (a -> b) -> Tree a -> Tree b

-- | Map function over the leaf value.
onLeaf :: (a -> b) -> Either c a -> Either c b

-- | Map function over the internal node value.
onNode :: (a -> b) -> Either a c -> Either b c

-- | Map the first function over internal node value and the second one
--   over leaf value.
onEither :: (a -> c) -> (b -> d) -> Either a b -> Either c d

-- | Map one function over both node and leaf values.
onBoth :: (a -> b) -> Either a a -> Either b b

-- | Group leaves with respect to the given equality function.
groupForestLeaves :: (b -> b -> Bool) -> NeForest a b -> NeForest a [b]

-- | Group leaves with respect to the given equality function.
groupTreeLeaves :: (b -> b -> Bool) -> NeTree a b -> NeTree a [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 a graph into a disjoint forest, i.e. a forest with no
--   mutually overlapping trees. The process is lossy, discontinuity and
--   overlapping cannot be represented with the <a>NeForest</a> data type.
toForest :: (Ord n, Ix w) => Graph n w -> NeForest n w
instance Monad (RanM w)


-- | IOB encoding method extended to forests.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; :m Data.Named.IOB Data.Named.Tree Text.Named.Enamex Data.Text.Lazy
--   
--   &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;"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; putStr . drawForest . mapForest show . parseForest $ 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 . parseForest $ 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 :: NeForest a w -> [IOB w a]

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


-- | 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 &gt;,
--   &lt;, \ and space characters.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; :m Text.Named.Enamex Data.Named.Tree Data.Text.Lazy
--   
--   &gt;&gt;&gt; let drawIt = putStr . drawForest . mapForest show . 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;"
--   Left "x"
--   |
--   `- Right "w1.1 w1.2"
--   ,
--   Left "y"
--   |
--   +- Left "z"
--   |  |
--   |  `- Right "w2"
--   |
--   `- Right "w3"
--   </pre>
module Text.Named.Enamex

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

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

-- | Show the forest.
showForest :: NeForest Text Text -> Text

-- | Show the enamex file.
showEnamex :: [NeForest Text Text] -> Text