Skip to content

Commit cb57250

Browse files
paf31paf31
committed
Starting work on code comments
1 parent 71ebb7b commit cb57250

File tree

23 files changed

+777
-21
lines changed

23 files changed

+777
-21
lines changed

‎src/Data/Generics/Extras.hs‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
-- Portability :
1010
--
1111
-- |
12+
-- Additional SYB combinators
1213
--
1314
-----------------------------------------------------------------------------
1415

@@ -18,6 +19,9 @@ module Data.Generics.Extras where
1819

1920
import Data.Data
2021

22+
-- |
23+
-- Apply a top-down monadic transformation everywhere
24+
--
2125
everywhereM' :: (Monad m, Data d) => (forall d1. (Data d1) => d1 -> m d1) -> d -> m d
2226
everywhereM' f x = do
2327
y <- f x

‎src/Language/PureScript.hs‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
-- Portability :
1010
--
1111
-- |
12+
-- The main compiler module
1213
--
1314
-----------------------------------------------------------------------------
1415

@@ -32,6 +33,23 @@ import Control.Monad (when, forM)
3233
import Control.Applicative ((<$>))
3334
import qualified Data.Map as M
3435

36+
-- |
37+
-- Compile a collection of modules
38+
--
39+
-- The compilation pipeline proceeds as follows:
40+
--
41+
-- * Sort the modules based on module dependencies, checking for cyclic dependencies.
42+
--
43+
-- * Perform a set of desugaring passes.
44+
--
45+
-- * Type check, and elaborate values to include type annotations and type class dictionaries.
46+
--
47+
-- * Regroup values to take into account new value dependencies introduced by elaboration
48+
--
49+
-- * Generate Javascript, and perform optimization passes.
50+
--
51+
-- * Pretty-print the generated Javascript
52+
--
3553
compile :: Options -> [Module] -> Either String (String, String, Environment)
3654
compile opts ms = do
3755
sorted <- sortModules ms

‎src/Language/PureScript/CodeGen.hs‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,13 @@
99
-- Portability :
1010
--
1111
-- |
12+
-- A collection of modules related to code generation:
13+
--
14+
-- [@Language.PureScript.CodeGen.JS@] Code generator for Javascript
15+
--
16+
-- [@Language.PureScript.CodeGen.Externs@] Code generator for extern (foreign import) files
17+
--
18+
-- [@Language.PureScript.CodeGen.Optimize@] Optimization passes for generated Javascript
1219
--
1320
-----------------------------------------------------------------------------
1421

‎src/Language/PureScript/Declarations.hs‎

Lines changed: 85 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
-- Stability : experimental
99
-- Portability :
1010
--
11-
-- |
11+
-- | Data types for modules and declarations
1212
--
1313
-----------------------------------------------------------------------------
1414

@@ -24,59 +24,143 @@ import Language.PureScript.CodeGen.JS.AST
2424

2525
import qualified Data.Data as D
2626

27+
-- |
28+
-- A precedence level for an infix operator
29+
--
2730
type Precedence = Integer
2831

32+
-- |
33+
-- Associativity for infix operators
34+
--
2935
data Associativity = Infixl | Infixr deriving (Show, D.Data, D.Typeable)
3036

37+
-- |
38+
-- Fixity data for infix operators
39+
--
3140
data Fixity = Fixity Associativity Precedence deriving (Show, D.Data, D.Typeable)
3241

42+
-- |
43+
-- A module declaration, consisting of a module name and a list of declarations
44+
--
3345
data Module = Module ProperName [Declaration] deriving (Show, D.Data, D.Typeable)
3446

47+
-- |
48+
-- The type of a foreign import
49+
--
3550
data ForeignImportType
51+
-- |
52+
-- A regular foreign import
53+
--
3654
= ForeignImport
55+
-- |
56+
-- A type class dictionary import, generated during desugaring of type class declarations
57+
--
3758
| TypeClassDictionaryImport
59+
-- |
60+
-- A type class dictionary member accessor import, generated during desugaring of type class declarations
61+
--
3862
| TypeClassAccessorImport deriving (Show, Eq, D.Data, D.Typeable)
3963

64+
-- |
65+
-- The data type of declarations
66+
--
4067
data Declaration
68+
-- |
69+
-- A data type declaration (name, arguments, data constructors)
70+
--
4171
= DataDeclaration ProperName [String] [(ProperName, Maybe Type)]
72+
-- |
73+
-- A minimal mutually recursive set of data type declarations
74+
--
4275
| DataBindingGroupDeclaration [Declaration]
76+
-- |
77+
-- A type synonym declaration (name, arguments, type)
78+
--
4379
| TypeSynonymDeclaration ProperName [String] Type
80+
-- |
81+
-- A type declaration for a value (name, ty)
82+
--
4483
| TypeDeclaration Ident Type
84+
-- |
85+
-- A value declaration (name, top-level binders, optional guard, value)
86+
--
4587
| ValueDeclaration Ident [[Binder]] (Maybe Guard) Value
88+
-- |
89+
-- A minimal mutually recursive set of value declarations
90+
--
4691
| BindingGroupDeclaration [(Ident, Value)]
92+
-- |
93+
-- A foreign import declaration (type, name, optional inline Javascript, type)
94+
--
4795
| ExternDeclaration ForeignImportType Ident (Maybe JS) Type
96+
-- |
97+
-- A data type foreign import (name, kind)
98+
--
4899
| ExternDataDeclaration ProperName Kind
100+
-- |
101+
-- A fixity declaration (fixity data, operator name)
102+
--
49103
| FixityDeclaration Fixity String
104+
-- |
105+
-- A module import (module name, optional set of identifiers to import)
106+
--
50107
| ImportDeclaration ModuleName (Maybe [Either Ident ProperName])
108+
-- |
109+
-- A type class declaration (name, argument, member declarations)
110+
--
51111
| TypeClassDeclaration ProperName String [Declaration]
112+
-- |
113+
-- A type instance declaration (dependencies, class name, instance type, member declarations)
114+
--
52115
| TypeInstanceDeclaration [(Qualified ProperName, Type)] (Qualified ProperName) Type [Declaration]
53116
deriving (Show, D.Data, D.Typeable)
54117

118+
-- |
119+
-- Test if a declaration is a value declaration
120+
--
55121
isValueDecl :: Declaration -> Bool
56122
isValueDecl (ValueDeclaration _ _ _ _) = True
57123
isValueDecl _ = False
58124

125+
-- |
126+
-- Test if a declaration is a data type or type synonym declaration
127+
--
59128
isDataDecl :: Declaration -> Bool
60129
isDataDecl (DataDeclaration _ _ _) = True
61130
isDataDecl (TypeSynonymDeclaration _ _ _) = True
62131
isDataDecl _ = False
63132

133+
-- |
134+
-- Test if a declaration is a module import
135+
--
64136
isImportDecl :: Declaration -> Bool
65137
isImportDecl (ImportDeclaration _ _) = True
66138
isImportDecl _ = False
67139

140+
-- |
141+
-- Test if a declaration is a data type foreign import
142+
--
68143
isExternDataDecl :: Declaration -> Bool
69144
isExternDataDecl (ExternDataDeclaration _ _) = True
70145
isExternDataDecl _ = False
71146

147+
-- |
148+
-- Test if a declaration is a fixity declaration
149+
--
72150
isFixityDecl :: Declaration -> Bool
73151
isFixityDecl (FixityDeclaration _ _) = True
74152
isFixityDecl _ = False
75153

154+
-- |
155+
-- Test if a declaration is a foreign import
156+
--
76157
isExternDecl :: Declaration -> Bool
77158
isExternDecl (ExternDeclaration _ _ _ _) = True
78159
isExternDecl _ = False
79160

161+
-- |
162+
-- Test if a declaration is a type class or instance declaration
163+
--
80164
isTypeClassDeclaration :: Declaration -> Bool
81165
isTypeClassDeclaration (TypeClassDeclaration _ _ _) = True
82166
isTypeClassDeclaration (TypeInstanceDeclaration _ _ _ _) = True

‎src/Language/PureScript/Kinds.hs‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,27 @@ module Language.PureScript.Kinds where
1919
import Data.Data
2020
import Language.PureScript.Unknown
2121

22+
-- |
23+
-- The data type of kinds
24+
--
2225
data Kind
26+
-- |
27+
-- Unification variable of type Kind
28+
--
2329
= KUnknown (Unknown Kind)
30+
-- |
31+
-- The kind of types
32+
--
2433
| Star
34+
-- |
35+
-- The kind of effects
36+
--
2537
| Bang
38+
-- |
39+
-- Kinds for labelled, unordered rows without duplicates
40+
--
2641
| Row Kind
42+
-- |
43+
-- Function kinds
44+
--
2745
| FunKind Kind Kind deriving (Show, Eq, Data, Typeable)

‎src/Language/PureScript/ModuleDependencies.hs‎

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
-- Stability : experimental
99
-- Portability :
1010
--
11-
-- |
11+
-- | Provides the ability to sort modules based on module dependencies
1212
--
1313
-----------------------------------------------------------------------------
1414

@@ -27,18 +27,19 @@ import Language.PureScript.Names
2727
import Language.PureScript.Values
2828
import Language.PureScript.Types
2929

30+
-- |
31+
-- Sort a collection of modules based on module dependencies.
32+
--
33+
-- Reports an error if the module graph contains a cycle.
34+
--
3035
sortModules :: [Module] -> Either String [Module]
3136
sortModules ms = do
3237
let verts = map (\m -> (m, getModuleName m, usedModules m)) ms
3338
mapM toModule $ stronglyConnComp verts
3439

35-
collapseBindingGroups :: [Declaration] -> [Declaration]
36-
collapseBindingGroups ds = concatMap go ds
37-
where
38-
go (DataBindingGroupDeclaration ds) = ds
39-
go (BindingGroupDeclaration ds) = map (\(ident, val) -> ValueDeclaration ident [] Nothing val) ds
40-
go other = [other]
41-
40+
-- |
41+
-- Calculate a list of used modules based on explicit imports and qualified names
42+
--
4243
usedModules :: (Data d) => d -> [ProperName]
4344
usedModules = nub . everything (++) (mkQ [] qualifiedIdents `extQ` qualifiedProperNames `extQ` imports)
4445
where
@@ -55,6 +56,9 @@ usedModules = nub . everything (++) (mkQ [] qualifiedIdents `extQ` qualifiedProp
5556
getModuleName :: Module -> ProperName
5657
getModuleName (Module pn _) = pn
5758

59+
-- |
60+
-- Convert a strongly connected component of the module graph to a module
61+
--
5862
toModule :: SCC Module -> Either String Module
5963
toModule (AcyclicSCC m) = return m
6064
toModule (CyclicSCC [m]) = return m

‎src/Language/PureScript/Names.hs‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
-- Portability :
1010
--
1111
-- |
12+
-- Data types for names
1213
--
1314
-----------------------------------------------------------------------------
1415

@@ -18,28 +19,51 @@ module Language.PureScript.Names where
1819

1920
import Data.Data
2021

21-
data Ident = Ident String | Op String deriving (Eq, Ord, Data, Typeable)
22+
-- |
23+
-- Names for value identifiers
24+
--
25+
data Ident
26+
-- |
27+
-- An alphanumeric identifier
28+
--
29+
= Ident String
30+
-- |
31+
-- A symbolic name for an infix operator
32+
--
33+
| Op String deriving (Eq, Ord, Data, Typeable)
2234

2335
instance Show Ident where
2436
show (Ident s) = s
2537
show (Op op) = '(':op ++ ")"
2638

39+
-- |
40+
-- Proper names, i.e. capitalized names for e.g. module names, type//data constructors.
41+
--
2742
newtype ProperName = ProperName { runProperName :: String } deriving (Eq, Ord, Data, Typeable)
2843

2944
instance Show ProperName where
3045
show = runProperName
3146

47+
-- |
48+
-- Module names
49+
--
3250
data ModuleName = ModuleName ProperName deriving (Eq, Ord, Data, Typeable)
3351

3452
instance Show ModuleName where
3553
show (ModuleName name) = show name
3654

55+
-- |
56+
-- A qualified name, i.e. a name with an optional module name
57+
--
3758
data Qualified a = Qualified (Maybe ModuleName) a deriving (Eq, Ord, Data, Typeable)
3859

3960
instance (Show a) => Show (Qualified a) where
4061
show (Qualified Nothing a) = show a
4162
show (Qualified (Just (ModuleName name)) a) = show name ++ "." ++ show a
4263

64+
-- |
65+
-- Provide a default module name, if a name is unqualified
66+
--
4367
qualify :: ModuleName -> Qualified a -> (ModuleName, a)
4468
qualify m (Qualified Nothing a) = (m, a)
4569
qualify _ (Qualified (Just m) a) = (m, a)

‎src/Language/PureScript/Options.hs‎

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,17 +9,36 @@
99
-- Portability :
1010
--
1111
-- |
12+
-- The data type of compiler options
1213
--
1314
-----------------------------------------------------------------------------
1415

1516
module Language.PureScript.Options where
1617

17-
data Options = Options
18-
{ optionsTco :: Bool
18+
-- |
19+
-- The data type of compiler options
20+
--
21+
data Options = Options {
22+
-- |
23+
-- Perform tail-call elimination
24+
--
25+
optionsTco :: Bool
26+
-- |
27+
-- Perform type checks at runtime
28+
--
1929
, optionsPerformRuntimeTypeChecks :: Bool
30+
-- |
31+
-- Inline calls to ret and bind for the Eff monad
32+
--
2033
, optionsMagicDo :: Bool
34+
-- |
35+
-- Check the type of Main.main and generate its code
36+
--
2137
, optionsRunMain :: Bool
2238
} deriving Show
2339

40+
-- |
41+
-- Default compiler options
42+
--
2443
defaultOptions :: Options
2544
defaultOptions = Options False False False False

0 commit comments

Comments
 (0)