gdritter repos blue-blistering-barnacles / master
Just some early experiments + a NOTES file that explains the rough idea Getty Ritter 8 years ago
6 changed file(s) with 243 addition(s) and 0 deletion(s). Collapse all Expand all
+2
-0
.gitignore less more
1 *~
2 dist-newstyle
+0
-0
LICENSE less more
(New empty file)
+128
-0
NOTES.md less more
1 % Blue Blistering Barnacles!
2 % Getty Ritter
3
4 The basic idea of `blue-blistering-barnacles` is that, when looking
5 at documentation in a language like Haskell, you have two questions
6 about a type:
7
8 - How can I create it?
9 - What can I do with it?
10
11 Therefore, BBB will ignore the traditional Haddock structure and
12 spit out documentation that will have a page _for each type_ `T`. Each
13 page will have two sections: **Creating** and **Using**. The
14 **Creating** section will contain
15 - All constructors for `T`
16 - All defined values of type `T`
17 - All functions whose return value contains `T`
18
19 On the other hand, the **Using** section will contain
20 - All other functions that take a `T`, even if they appeared
21 in the above section
22
23 Both of these include _instances of typeclasses specialized
24 to `T`_, as well, but maybe hidden behind JavaScript. (TBD:
25 whether to _also_ include every function written in terms
26 of that typeclass.) So, given a source file like
27
28 ```{.haskell}
29 module Sample(S(..), T(..), flip, mkT, sumT, zero) where
30
31 newtype S = S { fromS :: Int } deriving (Eq, Show)
32
33 instance Monoid S where
34 mempty = S 0
35 mappend (S x) (S y) = S (x + y)
36
37 zero :: S
38 zero = S 0
39
40 data T = Leaf S | Node T T | Nil deriving (Show)
41
42 mkT :: [Int] -> T
43 mkT [] = Nil
44 mkT [x] = Leaf (S x)
45 mkT (x:xs) = Node (Leaf (S x)) (mkT xs)
46
47 sumT :: T -> Int
48 sumT Nil = 0
49 sumT (Leaf (S x)) = x
50 sumT (Node l r) = sum l + sum r
51
52 flip :: T -> T
53 flip (Leaf s) = Leaf s
54 flip (Node l r) = Node (flip l) (flip r)
55 ```
56
57 will produce two pages:
58
59 ## newtype S :: *
60
61 ### Creating
62 - _constructor_ `S { fromS :: Int }`
63 - _value_ `zero :: S`
64 - _typeclass instance_ `Monoid S` _where_
65 - _value_ `mempty :: S`
66 - _function_ `mappend :: S -> S -> S`
67
68 ### Using
69 - _record field_ `fromS :: S -> Int`
70 - _typeclass instance_ `Monoid S` _where_
71 - _function_ `mappend :: S -> S -> S`
72 - _typeclass instance_ `Eq S` _where_
73 - _function_ `(==) :: S -> S -> Bool`
74 - _function_ `(/=) :: S -> S -> Bool`
75 - _typeclass instance_ `Show S` _where_
76 - _function_ `showsPrec :: Int -> S -> ShowS`
77 - _function_ `show :: S -> String`
78 - _function_ `showList :: [S] -> ShowS`
79
80 ## data T :: *
81
82 ### Creating
83 - _constructor_ `Leaf :: S -> T`
84 - _constructor_ `Node :: T -> T -> T`
85 - _function_ `mkT :: [Int] -> T`
86 - _function_ `flip :: T -> T`
87
88 ### Using
89 - _function_ `flip :: T -> T`
90 - _function_ `sumT :: T -> Int`
91 - _typeclass instance_ `Show T` _where_
92 - _function_ `showsPrec :: Int -> T -> ShowS`
93 - _function_ `show :: T -> String`
94 - _function_ `showList :: [T] -> ShowS`
95
96 We also want to have pages for typeclasses, with typeclass
97 methods in one section, and functions and values that make
98 use of that typeclass in another section, e.g.
99
100 ## class Show a
101
102 ### Methods
103 - _function_ `showsPrec :: Int -> a -> ShowS`
104 - _function_ `show :: a -> String`
105 - _function_ `showList :: [a] -> String`
106
107 ### Functions
108 - _function_ `print :: Show a => a -> IO ()`
109
110 and so forth.
111
112 In generating HTML + JS, we can use fragment identifiers to
113 indicate that a typeclass should also be monomorphized to a
114 particular type, too, e.g. visiting `show.html` might give
115 you the docs you see above, but visiting
116 `show.html#subst_a:Bool` would execute some JavaScript that
117 would change the above to
118
119
120 ## instance Show Bool
121
122 ### Methods
123 - _function_ `showsPrec :: Int -> Bool -> ShowS`
124 - _function_ `show :: Bool -> String`
125 - _function_ `showList :: [Bool] -> String`
126
127 ### Functions
128 - _function_ `print :: Bool -> IO ()`
+21
-0
blue-blistering-barnacles.cabal less more
1 name: blue-blistering-barnacles
2 version: 0.1.0.0
3 -- synopsis:
4 -- description:
5 license: BSD3
6 license-file: LICENSE
7 author: Getty Ritter <gdritter@galois.com>
8 maintainer: Getty Ritter <gdritter@galois.com>
9 copyright: ©2016 Getty Ritter
10 -- category:
11 build-type: Simple
12 cabal-version: >= 1.12
13
14 executable blue-blistering-barnacles
15 hs-source-dirs: src
16 main-is: Main.hs
17 default-extensions: OverloadedStrings,
18 ScopedTypeVariables
19 ghc-options: -Wall
20 build-depends: base >=4.7 && <4.9, ghc, haddock-api, text
21 default-language: Haskell2010
+54
-0
src/Main.hs less more
1 module Main where
2
3 -- import Documentation.Haddock
4
5 import Types
6
7 sample :: [Decl]
8 sample =
9 [ Decl "Sample" "S" (TypeDecl KStar [ Constructor "S" [TNamed "Int"] ])
10 , Decl "Sample" "T" (TypeDecl KStar [ Constructor "Leaf" [TNamed "S"]
11 , Constructor "Node" [TNamed "T", TNamed "T"]
12 , Constructor "Nil" []
13 ])
14 , Decl "Sample" "flip"
15 (ValDecl (TNamed "T" `TArr` TNamed "T"))
16 , Decl "Sample" "mkT"
17 (ValDecl (TListOf (TNamed "Int") `TArr` TNamed "T"))
18 , Decl "Sample" "sumT"
19 (ValDecl (TNamed "T" `TArr` TNamed "Int"))
20 , Decl "Sample" "zero" (ValDecl (TNamed "S"))
21 ]
22
23 data Creator
24 = CreatorVal Decl
25 | CreatorConstr Constructor
26 deriving (Eq, Show)
27
28 findCreators :: Identifier -> [Decl] -> [Creator]
29 findCreators name decls =
30 [ CreatorVal decl
31 | decl@Decl { dKind = ValDecl t } <- decls
32 , produces name t
33 ] ++
34 [ CreatorConstr c
35 | Decl { dName = n
36 , dKind = TypeDecl _ cs
37 } <- decls
38 , n == name
39 , c <- cs
40 ]
41
42 produces :: Identifier -> Type -> Bool
43 produces n' (TNamed n) = n == n'
44 produces n' (TArr _ r) = produces n' r
45 produces n' (TApp t xs) =
46 produces n' t || any (produces n') xs
47 produces n' (TPair xs) = any (produces n') xs
48 produces _ _ = False
49
50 main :: IO ()
51 main = do
52 print (findCreators "S" sample)
53 putStrLn ""
54 print (findCreators "T" sample)
+38
-0
src/Types.hs less more
1 module Types where
2
3 import Data.Text (Text)
4
5 type Identifier = Text
6 type Module = Text
7
8 data Kind
9 = KStar
10 | KArr Kind Kind
11 deriving (Eq, Show)
12
13 data Doc = Doc Text
14
15 data Type
16 = TNamed Identifier
17 | TVar Identifier
18 | TArr Type Type
19 | TPair [Type]
20 | TListOf Type
21 | TApp Type [Type]
22 deriving (Eq, Show)
23
24 data Decl = Decl
25 { dModule :: Module
26 , dName :: Identifier
27 , dKind :: DeclKind
28 } deriving (Eq, Show)
29
30 data DeclKind
31 = TypeDecl Kind [Constructor]
32 | ValDecl Type
33 deriving (Eq, Show)
34
35 data Constructor = Constructor
36 { csName :: Identifier
37 , csArgs :: [Type]
38 } deriving (Eq, Show)