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


-- | Ferry Table Algebra
--   
--   The Ferry 2.0 Table Algebra library
--   
--   The table algebra [2] is an intermediate language used by Ferry 2.0
--   [3] and DSH [4]. It forms the input for the pathfinder [1] optimiser
--   that can translate it into SQL. The library exposes a monadic
--   interface to construct algebraic plans, it automatically performs
--   common sub-tree elimination so that the resulting plan is as small as
--   possible and the optimiser can do it's work better. XML rendering is
--   present and needed for interfacing with DSH-Pathfinder, and for
--   debugging plans with the standalone Pathfinder.
--   
--   <ol>
--   
--   <li><a>http://www-db.informatik.uni-tuebingen.de/research/pathfinder</a></li>
--   
--   <li><a>http://dbworld.informatik.uni-tuebingen.de/projects/pathfinder/wiki/Logical_Algebra</a></li>
--   
--   <li><a>http://www-db.informatik.uni-tuebingen.de/research/ferry</a></li>
--   
--   <li><a>http://www-db.informatik.uni-tuebingen.de/files/publications/ferryhaskell.pdf</a></li>
--   </ol>
@package TableAlgebra
@version 0.7.1

module Database.Ferry.Algebra.Render.XML
document :: Document i -> Doc
mkXMLDocument :: Element () -> Document ()
mkPlanBundle :: [Element ()] -> Element ()
serializeAlgebra :: [Element ()] -> GraphNode -> XML XMLNode
type ColName = String
type Graph = (AlgNode, [(Algebra, AlgNode)])
type GraphNode = Int
type XMLNode = Int
type Dictionary = Map GraphNode XMLNode
type XML = WriterT [Element ()] (ReaderT (Map AlgNode Algebra, Map AlgNode [String], Bool) (State (Int, Dictionary)))
getTags :: GraphNode -> XML (Maybe [String])
debugEnabled :: XML Bool
isDefined :: GraphNode -> XML (Maybe XMLNode)
freshId :: XML Int
addNodeTrans :: GraphNode -> XMLNode -> XML ()
getNode :: Int -> XML Algebra
runXML :: Bool -> Map AlgNode Algebra -> Map AlgNode [String] -> XML a -> [Element ()]

-- | Childs of takes a list of xml elements, and nests them in the xml
--   element given as a second argument
childsOf :: [Element ()] -> Element () -> Element ()

-- | Data child of takes some data that can be printed and adds that as
--   child to the xml element given as second argument
dataChildOf :: Show a => a -> Element () -> Element ()
stringChildOf :: String -> Element () -> Element ()

-- | Construct a column with name n, and new status v
column :: String -> Bool -> Element ()

-- | XML element representing a type
typeN :: ATy -> Element ()

-- | Construct an xml tag with name n
xmlElem :: String -> Element ()

-- | Construct an algebraic node with id xId and of kind t
node :: XMLNode -> String -> Element ()

-- | Construct a content node
contentNode :: Element ()

-- | Construct an attribute for an xml node, attrname = n and its value is
--   v
attr :: String -> String -> Attribute

-- | Attach list of attributes to an xml element
attrsOf :: [Attribute] -> Element () -> Element ()
iterCol :: Element ()
posCol :: Element ()
mkQueryPlan :: Maybe (Int, Int) -> Element () -> [Element ()] -> XML Int


-- | This package provides a convenient interface to construct Table
--   Algebra plans that can be dealt with by Pathfinder
--   (http:<i></i>www-db.informatik.uni-tuebingen.de<i>research</i>pathfinder).
--   A describtion of the algebra can be found at:
--   http:<i></i>dbworld.informatik.uni-tuebingen.de<i>projects</i>pathfinder<i>wiki</i>Logical_Algebra
--   This module only provides a subset of the complete algebra.
module Database.Ferry.Algebra

-- | An algebraic plan is the result of constructing a graph. | The pair
--   consists of the mapping from nodes to their respective ids | and the
--   algres from the top node.
type AlgPlan res = (Map Algebra AlgNode, res, Tags)

-- | Union between two plans
union :: AlgNode -> AlgNode -> GraphM a AlgNode

-- | Attach a column <a>ResAttrName</a> of type <a>ATy</a> with value
--   <a>AVal</a> in all rows to table <a>AlgNode</a>
attach :: ResAttrName -> ATy -> AVal -> AlgNode -> GraphM a AlgNode

-- | Project/rename certain column out of a plan
proj :: ProjInf -> AlgNode -> GraphM a AlgNode

-- | Get the current loop table
getLoop :: GraphM a AlgNode

-- | Similar to rowrank but this will assign a emph{unique} number to every
--   row (even if two rows are equal)
rownum :: AttrName -> [AttrName] -> Maybe AttrName -> AlgNode -> GraphM a AlgNode

-- | Same as rownum but columns can be assigned an ordering direction
rownum' :: AttrName -> [(AttrName, SortDir)] -> Maybe AttrName -> AlgNode -> GraphM a AlgNode

-- | Join two plans where the columns n1 of table 1 and columns n2 of table
--   2 are equal.
eqJoin :: String -> String -> AlgNode -> AlgNode -> GraphM a AlgNode

-- | Assign a number to each row in column <a>ResAttrName</a> incrementing
--   sorted by <a>SortInf</a>. The numbering is not dense!
rank :: ResAttrName -> SortInf -> AlgNode -> GraphM a AlgNode

-- | The same as eqJoin but with multiple columns.
eqTJoin :: [(String, String)] -> ProjInf -> AlgNode -> AlgNode -> GraphM a AlgNode

-- | Remove duplicate rows
distinct :: AlgNode -> GraphM a AlgNode

-- | Same as rank but provides a dense numbering.
rowrank :: ResAttrName -> SortInf -> AlgNode -> GraphM a AlgNode

-- | Cast column <a>AttrName</a> to type <a>ATy</a> and give it the name
--   <a>ResAttrName</a> afterwards.
cast :: AttrName -> ResAttrName -> ATy -> AlgNode -> GraphM a AlgNode

-- | Compute the difference between two plans.
difference :: AlgNode -> AlgNode -> GraphM a AlgNode

-- | Apply aggregate functions to a plan
aggr :: [(AggrType, ResAttrName, Maybe AttrName)] -> Maybe PartAttrName -> AlgNode -> GraphM a AlgNode

-- | Select rows where the column <a>SelAttrName</a> contains True.
select :: SelAttrName -> AlgNode -> GraphM a AlgNode

-- | Get's the nth element(s) of a (partitioned) table.
posSelect :: Int -> SortInf -> Maybe AttrName -> AlgNode -> GraphM a AlgNode

-- | Construct a database table node The first argument is the
--   emph{qualified} name of the database table. The second describes the
--   columns in alphabetical order. The third argument describes the
--   database keys (one table key can span over multiple columns).
dbTable :: String -> Columns -> KeyInfos -> GraphM a AlgNode

-- | Negate the boolen value in column n and store it in column r
notC :: AttrName -> AttrName -> AlgNode -> GraphM a AlgNode

-- | Make cross product from two plans
cross :: AlgNode -> AlgNode -> GraphM a AlgNode

-- | Apply an operator to the element in <a>LeftAttrName</a> and
--   <a>RightAttrName</a>, store the result in <a>ResAttrName</a>
oper :: String -> ResAttrName -> LeftAttrName -> RightAttrName -> AlgNode -> GraphM a AlgNode

-- | Construct an empty table node with
emptyTable :: SchemaInfos -> GraphM a AlgNode

-- | Tag a subtree with a comment
tag :: String -> AlgNode -> GraphM a AlgNode

-- | Construct a table with one value
litTable :: AVal -> String -> ATy -> GraphM a AlgNode
litTable' :: [[AVal]] -> [(String, ATy)] -> GraphM a AlgNode

-- | Evaluate the graph construction computation with the current
--   environment extended with a binding n to v.
withBinding :: String -> a -> GraphM a r -> GraphM a r

-- | Evaluate the graph construction computation with a differnt gamma, |
--   and loop table. Return within he current computational context.
withContext :: Gam a -> AlgNode -> GraphM a r -> GraphM a r

-- | Get the current variable environment
getGamma :: GraphM a (Gam a)

-- | Lookup a variable in the environment
fromGam :: String -> GraphM a a

-- | Create an algebraic nat value
nat :: Integer -> AVal

-- | Create an algebraic int value
int :: Integer -> AVal

-- | Create an algebraic boolean value
bool :: Bool -> AVal

-- | Create an algebraic double value
double :: Double -> AVal

-- | Create an algebraic string value
string :: String -> AVal

-- | Types of algebraic values
intT, surT, natT, doubleT, boolT, stringT :: ATy

-- | Sorting rows in a direction
data SortDir
Asc :: SortDir
Desc :: SortDir
data AggrType
Avg :: AggrType
Max :: AggrType
Min :: AggrType
Sum :: AggrType
Count :: AggrType
All :: AggrType
Prod :: AggrType
Dist :: AggrType

-- | The column data type is used to represent the table structure while
--   compiling ferry core into an algebraic plan The col column contains
--   the column number and the type of its contents The NCol column is used
--   to group columns that together form an element of a record , its
--   string argument is used to represent the field name.
data Column
Col :: Int -> ATy -> Column
NCol :: String -> Columns -> Column

-- | One table can have multiple columns
type Columns = [Column]

-- | Algebraic types At this level we do not have any structural types
--   anymore those are represented by columns. ASur is used for surrogate
--   values that occur for nested lists.
data ATy
AInt :: ATy
AStr :: ATy
ABool :: ATy
ADec :: ATy
ADouble :: ATy
ANat :: ATy
ASur :: ATy

-- | Wrapper around values that can occur in an algebraic plan
data AVal

-- | Schema information, represents a table structure, the first element of
--   the tuple is the column name the second its type.
type SchemaInfos = [(AttrName, ATy)]

-- | Multiple keys
type KeyInfos = [KeyInfo]
type AlgNode = Int

-- | Graphs are constructed in a monadic environment. | The graph
--   constructed has to be a DAG. | The reader monad provides access to the
--   variable environment Gamma and the loop table | The variable
--   environment is a mapping from variable names to graphnodes that
--   represent | their compiled form. | The state monad gives access to a
--   supply of fresh variables, and maintains a map from | nodes to node
--   ids. When a node is inserted and an equal node (equal means, equal
--   node | and equal child nodes) already exists in the map the node id
--   for that already existing | node is returned. This allows maximal
--   sharing.
type GraphM a = ReaderT (Gam a, AlgNode) (State (Int, Map Algebra AlgNode, Tags))

-- | Variable environemtn mapping from variables to compiled nodes.
type Gam a = [(String, a)]

-- | Shorthand for the initial loop condition used by Ferry.
initLoop :: Algebra

-- | Evaluate the monadic graph into an algebraic plan, given a loop
--   relation.
runGraph :: Algebra -> GraphM res res -> AlgPlan res
type ProjPair = (NewAttrName, OldAttrName)

-- | Projection information, a list of new attribute names, and their old
--   names.
type ProjInf = [ProjPair]

-- | Attach a column <a>ResAttrName</a> of type <a>ATy</a> with value
--   <a>AVal</a> in all rows to table <a>AlgNode</a>
attachM :: ResAttrName -> ATy -> AVal -> GraphM a AlgNode -> GraphM a AlgNode

-- | Cast column <a>AttrName</a> to type <a>ATy</a> and give it the name
--   <a>ResAttrName</a> afterwards.
castM :: AttrName -> ResAttrName -> ATy -> GraphM a AlgNode -> GraphM a AlgNode

-- | Join two plans where the columns n1 of table 1 and columns n2 of table
--   2 are equal.
eqJoinM :: String -> String -> GraphM a AlgNode -> GraphM a AlgNode -> GraphM a AlgNode

-- | The same as eqJoin but with multiple columns.
eqTJoinM :: [(String, String)] -> ProjInf -> GraphM a AlgNode -> GraphM a AlgNode -> GraphM a AlgNode

-- | Assign a number to each row in column <a>ResAttrName</a> incrementing
--   sorted by <a>SortInf</a>. The numbering is not dense!
rankM :: ResAttrName -> SortInf -> GraphM a AlgNode -> GraphM a AlgNode

-- | Compute the difference between two plans.
differenceM :: GraphM a AlgNode -> GraphM a AlgNode -> GraphM a AlgNode

-- | Same as rank but provides a dense numbering.
rowrankM :: ResAttrName -> SortInf -> GraphM a AlgNode -> GraphM a AlgNode

-- | Get's the nth element(s) of a (partitioned) table.
posSelectM :: Int -> SortInf -> Maybe AttrName -> GraphM a AlgNode -> GraphM a AlgNode

-- | Select rows where the column <a>SelAttrName</a> contains True.
selectM :: SelAttrName -> GraphM a AlgNode -> GraphM a AlgNode

-- | Remove duplicate rows
distinctM :: GraphM a AlgNode -> GraphM a AlgNode

-- | Make cross product from two plans
crossM :: GraphM a AlgNode -> GraphM a AlgNode -> GraphM a AlgNode

-- | Negate the boolen value in column n and store it in column r
notM :: AttrName -> AttrName -> GraphM a AlgNode -> GraphM a AlgNode

-- | Union between two plans
unionM :: GraphM a AlgNode -> GraphM a AlgNode -> GraphM a AlgNode

-- | Project/rename certain column out of a plan
projM :: ProjInf -> GraphM a AlgNode -> GraphM a AlgNode

-- | Apply aggregate functions to a plan
aggrM :: [(AggrType, ResAttrName, Maybe AttrName)] -> Maybe PartAttrName -> GraphM a AlgNode -> GraphM a AlgNode

-- | Similar to rowrank but this will assign a emph{unique} number to every
--   row (even if two rows are equal)
rownumM :: AttrName -> [AttrName] -> Maybe AttrName -> GraphM a AlgNode -> GraphM a AlgNode

-- | Same as rownum but columns can be assigned an ordering direction
rownum'M :: AttrName -> [(AttrName, SortDir)] -> Maybe AttrName -> GraphM a AlgNode -> GraphM a AlgNode

-- | Apply an operator to the element in <a>LeftAttrName</a> and
--   <a>RightAttrName</a>, store the result in <a>ResAttrName</a>
operM :: String -> ResAttrName -> LeftAttrName -> RightAttrName -> GraphM a AlgNode -> GraphM a AlgNode

-- | Tag a subtree with a comment
tagM :: String -> GraphM a AlgNode -> GraphM a AlgNode