@@ -0,0 +1,205 @@
1+-- | This module provides documentation for the builtin Prim module.
2+module Language.PureScript.Docs.Prim (primDocsModule) where
3+
4+import Prelude.Compat hiding (fail)
5+import Control.Arrow (first)
6+import qualified Data.Text as T
7+import qualified Data.Map as Map
8+import Language.PureScript.Docs.Types
9+import qualified Language.PureScript as P
10+
11+primDocsModule :: Module
12+primDocsModule = Module
13+ { modName = P.moduleNameFromString "Prim"
14+ , modComments = Just "The Prim module is embedded in the PureScript compiler in order to provide compiler support for certain types — for example, value literals, or syntax sugar."
15+ , modDeclarations =
16+ [ function
17+ , array
18+ , record
19+ , number
20+ , int
21+ , string
22+ , char
23+ , boolean
24+ , partial
25+ , fail
26+ , typeConcat
27+ , typeString
28+ ]
29+ , modReExports = []
30+ }
31+
32+unsafeLookup :: forall v (a :: P.ProperNameType).
33+ Map.Map (P.Qualified (P.ProperName a)) v -> String -> String -> v
34+unsafeLookup m errorMsg ty = go ty
35+ where
36+ go = fromJust' . flip Map.lookup m . P.primName . T.pack
37+
38+ fromJust' (Just x) = x
39+ fromJust' _ = P.internalError $ errorMsg ++ ty
40+
41+lookupPrimKind :: String -> P.Kind
42+lookupPrimKind = fst . unsafeLookup P.primTypes "Docs.Prim: No such Prim type: "
43+
44+primType :: String -> String -> Declaration
45+primType title comments = Declaration
46+ { declTitle = title
47+ , declComments = Just comments
48+ , declSourceSpan = Nothing
49+ , declChildren = []
50+ , declInfo = ExternDataDeclaration (lookupPrimKind title)
51+ }
52+
53+-- | Lookup the TypeClassData of a Prim class. This function is specifically
54+-- not exported because it is partial.
55+lookupPrimClass :: String -> P.TypeClassData
56+lookupPrimClass = unsafeLookup P.primClasses "Docs.Prim: No such Prim class: "
57+
58+primClass :: String -> String -> Declaration
59+primClass title comments = Declaration
60+ { declTitle = title
61+ , declComments = Just comments
62+ , declSourceSpan = Nothing
63+ , declChildren = []
64+ , declInfo =
65+ let
66+ tcd = lookupPrimClass title
67+ args = P.typeClassArguments tcd
68+ superclasses = P.typeClassSuperclasses tcd
69+ fundeps = convertFundepsToStrings args (P.typeClassDependencies tcd)
70+ in
71+ TypeClassDeclaration (map (first T.unpack) args) superclasses fundeps
72+ }
73+
74+function :: Declaration
75+function = primType "Function" $ unlines
76+ [ "A function, which takes values of the type specified by the first type"
77+ , "parameter, and returns values of the type specified by the second."
78+ , "In the JavaScript backend, this is a standard JavaScript Function."
79+ , ""
80+ , "The type constructor `(->)` is syntactic sugar for this type constructor."
81+ , "It is recommended to use `(->)` rather than `Function`, where possible."
82+ , ""
83+ , "That is, prefer this:"
84+ , ""
85+ , " f :: Number -> Number"
86+ , ""
87+ , "to either of these:"
88+ , ""
89+ , " f :: Function Number Number"
90+ , " f :: (->) Number Number"
91+ ]
92+
93+array :: Declaration
94+array = primType "Array" $ unlines
95+ [ "An Array: a data structure supporting efficient random access. In"
96+ , "the JavaScript backend, values of this type are represented as JavaScript"
97+ , "Arrays at runtime."
98+ , ""
99+ , "Construct values using literals:"
100+ , ""
101+ , " x = [1,2,3,4,5] :: Array Int"
102+ ]
103+
104+record :: Declaration
105+record = primType "Record" $ unlines
106+ [ "The type of records whose fields are known at compile time. In the"
107+ , "JavaScript backend, values of this type are represented as JavaScript"
108+ , "Objects at runtime."
109+ , ""
110+ , "The type signature here means that the `Record` type constructor takes"
111+ , "a row of concrete types. For example:"
112+ , ""
113+ , " type Person = Record (name :: String, age :: Number)"
114+ , ""
115+ , "The syntactic sugar with curly braces `{ }` is generally preferred, though:"
116+ , ""
117+ , " type Person = { name :: String, age :: Number }"
118+ ]
119+
120+number :: Declaration
121+number = primType "Number" $ unlines
122+ [ "A double precision floating point number (IEEE 754)."
123+ , ""
124+ , "Construct values of this type with literals:"
125+ , ""
126+ , " y = 35.23 :: Number"
127+ , " z = 1.224e6 :: Number"
128+ ]
129+
130+int :: Declaration
131+int = primType "Int" $ unlines
132+ [ "A 32-bit signed integer. See the purescript-integers package for details"
133+ , "of how this is accomplished when compiling to JavaScript."
134+ , ""
135+ , "Construct values of this type with literals:"
136+ , ""
137+ , " x = 23 :: Int"
138+ ]
139+
140+string :: Declaration
141+string = primType "String" $ unlines
142+ [ "A String. As in JavaScript, String values represent sequences of UTF-16"
143+ , "code units, which are not required to form a valid encoding of Unicode"
144+ , "text (for example, lone surrogates are permitted)."
145+ , ""
146+ , "Construct values of this type with literals, using double quotes `\"`:"
147+ , ""
148+ , " x = \"hello, world\" :: String"
149+ , ""
150+ , "Multi-line string literals are also supported with triple quotes (`\"\"\"`)."
151+ ]
152+
153+char :: Declaration
154+char = primType "Char" $ unlines
155+ [ "A single character (UTF-16 code unit). The JavaScript representation is a"
156+ , "normal String, which is guaranteed to contain one code unit. This means"
157+ , "that astral plane characters (i.e. those with code point values greater"
158+ , "than 0xFFFF) cannot be represented as Char values."
159+ , ""
160+ , "Construct values of this type with literals, using single quotes `'`:"
161+ , ""
162+ , " x = 'a' :: Char"
163+ ]
164+
165+boolean :: Declaration
166+boolean = primType "Boolean" $ unlines
167+ [ "A JavaScript Boolean value."
168+ , ""
169+ , "Construct values of this type with the literals `true` and `false`."
170+ ]
171+
172+partial :: Declaration
173+partial = primClass "Partial" $ unlines
174+ [ "The Partial type class is used to indicate that a function is *partial,*"
175+ , "that is, it will throw an error for some inputs. For more information,"
176+ , "see [the Partial type class guide](https://github.com/purescript/documentation/blob/master/guides/The-Partial-type-class.md)."
177+ ]
178+
179+fail :: Declaration
180+fail = primClass "Fail" $ unlines
181+ [ "The Fail type class is part of the custom type errors feature. To provide"
182+ , "a custom type error when someone tries to use a particular instance,"
183+ , "write that instance out with a Fail constraint."
184+ , ""
185+ , "For more information, see"
186+ , "[the Custom Type Errors guide](https://github.com/purescript/documentation/blob/master/guides/Custom-Type-Errors.md)."
187+ ]
188+
189+typeConcat :: Declaration
190+typeConcat = primType "TypeConcat" $ unlines
191+ [ "The TypeConcat type constructor concatenates two Symbols in a custom type"
192+ , "error."
193+ , ""
194+ , "For more information, see"
195+ , "[the Custom Type Errors guide](https://github.com/purescript/documentation/blob/master/guides/Custom-Type-Errors.md)."
196+ ]
197+
198+typeString :: Declaration
199+typeString = primType "TypeString" $ unlines
200+ [ "The TypeString type constructor renders any concrete type into a Symbol"
201+ , "in a custom type error."
202+ , ""
203+ , "For more information, see"
204+ , "[the Custom Type Errors guide](https://github.com/purescript/documentation/blob/master/guides/Custom-Type-Errors.md)."
205+ ]