@@ -1,14 +1,121 @@
1+{-# LANGUAGE PatternGuards #-}
2+
3+-- | Generation of HTML documentation for Idris code
14module Idris.IdrisDoc (generateDocs) where
25
3−import Idris.AbsSyntax (IState)
6+import Idris.Core.TT (Name (..))
7+import Idris.Core.Evaluate (ctxtAlist, Def (..))
8+import Idris.AbsSyntax (IState, tt_ctxt, runIO, imported)
9+
10+import qualified Data.Map as M
11+import qualified Data.Text as T
12+
13+
14+-- | Generates HTML documentation for a series of loaded namespaces and their dependencies.
15+generateDocs :: IState -- ^ IState where all necessary information is extracted from.
16+ -> [Name] -- ^ List of namespaces to generate documentation for.
17+ -> FilePath -- ^ The directory to which documentation will be written.
18+ -> IO (Either String ())
19+generateDocs ist nss out = -- err "IdrisDoc is still in development..."
20+ -- Right `fmap` (print $ createNameTrie ist)
21+ -- Right `fmap` (print $ imported ist)
22+
423
524type Failable = Either String
25+type NsDict = M.Map Name NsInfo
626
7−-- ist: IState
8−-- nss: List of namespaces to generate documentation for
9−-- out: Where to place the directory of documentation
10−generateDocs :: IState -> [String] -> FilePath -> IO (Either String ())
11−generateDocs ist nss out = err "IdrisDoc is still in development..."
27+data NsInfo = NsInfo { ns :: Name, info :: Maybe () }
1228
29+-- | Make an error message
1330err :: String -> IO (Failable ())
14−err s = return $ Left s
31+err s = return $ Left s
32+
33+
34+-- ------------------------------------------------------------- [ Name Trie ]
35+
36+-- | A NameTrie is either:
37+-- a namespace item,
38+-- a namespace node with children,
39+-- both
40+data NameTrie a = NameTrie {
41+ content :: Maybe (Name, a),
42+ children :: M.Map T.Text (NameTrie a)
43+ } deriving Show
44+
45+-- | Empty NameTrie
46+ntEmpty :: NameTrie a
47+ntEmpty = NameTrie { content = Nothing, children = M.empty }
48+
49+-- | Build NameTrie from a Map
50+ntFromMap :: M.Map T.Text (NameTrie a) -- ^ Mapping of namespace contents
51+ -> NameTrie a
52+ntFromMap m = NameTrie { content = Nothing, children = m }
53+
54+-- | Build NameTrie from a (Maybe NameTrie a)
55+ntFromMaybe :: Maybe (NameTrie a) -- ^ Maybe a NameTrie?
56+ -> NameTrie a
57+ntFromMaybe (Just nt) = nt
58+ntFromMaybe Nothing = ntEmpty
59+
60+
61+-- | Lookup a sub-NameTrie based on a NameTrie identifier.
62+-- Identifier example: A.B.c -> [A,B,c] (reverse Idris-style)
63+ntLookup :: [T.Text] -- ^ Identifier to lookup
64+ -> NameTrie a -- ^ The trie to lookup within
65+ -> Maybe (NameTrie a)
66+ntLookup (t:ts) n | Just n' <- M.lookup t (children n) = ntLookup ts n'
67+ntLookup [t] n = M.lookup t (children n)
68+ntLookup _ _ = Nothing
69+
70+
71+-- | Add content to a NameTrie
72+ntInsert :: Name -- ^ The name to add content under
73+ -> a -- ^ The content to add
74+ -> NameTrie a -- ^ The NameTrie (Ns) to add the content to
75+ -> NameTrie a
76+ntInsert n@(UN t) c = ntInsertHelper [t] n c
77+ntInsert n@(NS (UN t) ns) c = ntInsertHelper (reverse $ t:ns) n c
78+ntInsert _ _ = id -- Ignore
79+
80+-- | Add content to a NameTrie using a NameTrie identifier
81+ntInsertHelper :: [T.Text] -- ^ Path of identifiers
82+ -> Name -- ^ Name of final entry
83+ -> a -- ^ The content to add
84+ -> NameTrie a -- ^ The NameTrie (Ns) to add the content to
85+ -> NameTrie a
86+ntInsertHelper (t:ts) n c nt = let cs = children nt
87+ subnt = ntFromMaybe $ M.lookup t cs
88+ nt' = ntInsertHelper ts n c subnt
89+ in nt { children = M.insert t nt' cs }
90+ntInsertHelper [] n c nt = nt { content = Just (n, c) }
91+
92+
93+-- | Creates a trie on which names can be looked up by traveling their namespaces
94+ntCreate :: IState -- ^ IState to fetch info from
95+ -> NameTrie Def
96+ntCreate ist = let defList = ctxtAlist $ tt_ctxt ist
97+ adder t (n, d) = ntInsert n d t
98+ in foldl adder ntEmpty defList
99+
100+
101+-- --------------------------------------------------------- [ Info Fetching ]
102+
103+-- | Fetch info about namespaces and their contents
104+fetchInfo :: IState -- ^ IState to fetch info from
105+ -> [Name] -- ^ List of namespaces to fetch info for
106+ -> NsDict -- ^ Mapping from namespace name to info about its contents
107+fetchInfo ist ns = let nameTrie = ntCreate ist
108+ in undefined
109+
110+-- | Returns all names defined in a namespace, including child namespaces
111+allNamesInNs :: NameTrie a -- ^ NameTrie to fetch info from
112+ -> Name -- ^
113+ -> [Name] -- ^ All names within the namespace
114+allNamesInNs nt n = undefined
115+
116+-- | Returns the namespace within a name is defined
117+nsOfName :: Name -- ^ Name to retrieve the namespace of
118+ -> Name -- ^ The namespace
119+nsOfName n = undefined
120+
121+-- ------------------------------------------------------- [ HTML Generation ]