Doc.icl 17 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14
implementation module Clean.Doc

import _SystemArray
import StdBool
import StdChar
import StdDebug
from StdFunc import flip, o, twice
import StdList
import StdMisc
import StdOrdList
import StdString
import StdTuple

import Control.Applicative
15
from Control.Monad import mapM, class Monad(..), >>=
16 17 18 19 20 21 22 23
import Data.Either
import Data.Error
from Data.Func import $
import Data.Functor
import Data.GenDefault
import Data.List
import Data.Maybe
import Data.Tuple
24
from Text import <+,
25
	class Text(join,split,trim,rtrim,replaceSubString,endsWith,startsWith),
26 27 28 29
	instance Text String, instance Text [Char]
import Text.Language
import Text.Parsers.Simple.ParserCombinators

30
from Clean.Types import :: Type, :: TypeRestriction, :: TypeContext
Mart Lubbers's avatar
Mart Lubbers committed
31
from Clean.Types.Parse import parseType
32
from Clean.Types.Util import instance toString Type
33 34 35 36 37 38 39

gDefault{|Maybe|} _ = Nothing

fromMultiLine :: !MultiLineString -> String
fromMultiLine (MultiLine s) = s

instance docDescription       ModuleDoc where docDescription       d = d.ModuleDoc.description
40
instance docPropertyBootstrap ModuleDoc where docPropertyBootstrap d = d.property_bootstrap
41 42 43 44 45 46 47 48 49 50
instance docPropertyTestWith  ModuleDoc where docPropertyTestWith  d = d.ModuleDoc.property_test_with
instance docPropertyTestGenerators ModuleDoc where docPropertyTestGenerators d = d.property_test_generators

instance docDescription      FunctionDoc where docDescription      d = d.FunctionDoc.description
instance docComplexity       FunctionDoc where docComplexity       d = d.FunctionDoc.complexity
instance docParams           FunctionDoc where docParams           d = d.FunctionDoc.params
instance docVars             FunctionDoc where docVars             d = d.FunctionDoc.vars
instance docResults          FunctionDoc where docResults          d = d.FunctionDoc.results
instance docType             FunctionDoc where docType             d = d.FunctionDoc.type
instance docThrows           FunctionDoc where docThrows           d = d.FunctionDoc.throws
51
instance docProperties       FunctionDoc where docProperties       d = d.FunctionDoc.properties
52
instance docPropertyTestWith FunctionDoc where docPropertyTestWith d = d.FunctionDoc.property_test_with
53 54 55 56 57 58 59
instance docPreconditions    FunctionDoc where docPreconditions    d = d.FunctionDoc.preconditions

instance docDescription      InstanceDoc where docDescription      d = d.InstanceDoc.description
instance docComplexity       InstanceDoc where docComplexity       d = d.InstanceDoc.complexity
instance docProperties       InstanceDoc where docProperties       d = d.InstanceDoc.properties
instance docPropertyTestWith InstanceDoc where docPropertyTestWith d = d.InstanceDoc.property_test_with
instance docPreconditions    InstanceDoc where docPreconditions    d = d.InstanceDoc.preconditions
60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88

instance docDescription ParamDoc where docDescription d = d.ParamDoc.description

instance docDescription ClassMemberDoc where docDescription d = d.ClassMemberDoc.description
instance docComplexity  ClassMemberDoc where docComplexity  d = d.ClassMemberDoc.complexity
instance docParams      ClassMemberDoc where docParams      d = d.ClassMemberDoc.params
instance docResults     ClassMemberDoc where docResults     d = d.ClassMemberDoc.results
instance docType        ClassMemberDoc where docType        d = d.ClassMemberDoc.type
instance docThrows      ClassMemberDoc where docThrows      d = d.ClassMemberDoc.throws

instance docDescription ConstructorDoc where docDescription d = d.ConstructorDoc.description
instance docParams      ConstructorDoc where docParams      d = d.ConstructorDoc.params

instance docDescription ClassDoc where docDescription d = d.ClassDoc.description
instance docVars        ClassDoc where docVars        d = d.ClassDoc.vars
instance docMembers     ClassDoc where docMembers     d = d.ClassDoc.members

instance docDescription    TypeDoc where docDescription    d = d.TypeDoc.description
instance docVars           TypeDoc where docVars           d = d.TypeDoc.vars
instance docFields         TypeDoc where docFields         d = d.TypeDoc.fields
instance docConstructors   TypeDoc where docConstructors   d = d.TypeDoc.constructors
instance docRepresentation TypeDoc where docRepresentation d = d.TypeDoc.representation

instance toString ParamDoc
where
	toString pd=:{name=Just n,description=Just d} = n +++ ": " +++ d
	toString {ParamDoc | description=Just d} = d
	toString _ = ""

89
derive gDefault Type, TypeRestriction, ModuleDoc, FunctionDoc, InstanceDoc, TypeContext,
90
	ClassMemberDoc, ConstructorDoc, ClassDoc, TypeDoc, Property, PropertyBootstrapDoc,
91
	PropertyVarInstantiation, MultiLineString, PropertyTestGenerator, ParamDoc
92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123

constructorToFunctionDoc :: !ConstructorDoc -> FunctionDoc
constructorToFunctionDoc d =
	{ FunctionDoc
	| gDefault{|*|}
	& description = d.ConstructorDoc.description
	, params      = d.ConstructorDoc.params
	}

functionToClassMemberDoc :: !FunctionDoc -> ClassMemberDoc
functionToClassMemberDoc d =
	{ ClassMemberDoc
	| description = d.FunctionDoc.description
	, complexity  = d.FunctionDoc.complexity
	, params      = d.FunctionDoc.params
	, results     = d.FunctionDoc.results
	, type        = d.FunctionDoc.type
	, throws      = d.FunctionDoc.throws
	}

addClassMemberDoc :: !ClassDoc !(Maybe ClassMemberDoc) -> ClassDoc
addClassMemberDoc d m = {d & members=d.members ++ [m]}

parseSingleLineDoc :: (String -> String)
parseSingleLineDoc = toString o trim o dropWhile ((==) '*') o fromString

parseDoc :: !String -> Either ParseError (!d, ![ParseWarning]) | docBlockToDoc{|*|} d
parseDoc s = docBlockToDoc{|*|} (Left [s])

generic docBlockToDoc d :: !(Either [String] DocBlock) -> Either ParseError (!d, ![ParseWarning])
docBlockToDoc{|String|} (Left []) = Left InternalNoDataError
docBlockToDoc{|String|} (Left ss) = Right (trim $ last ss, [])
Camil Staps's avatar
Camil Staps committed
124
docBlockToDoc{|String|} _         = abort "error in docBlockToDoc{|String|}\n"
125
docBlockToDoc{|[]|} fx (Left ss) = (\vws -> (map fst vws, flatten (map snd vws)) ) <$> mapM fx (map (Left o pure) ss)
Camil Staps's avatar
Camil Staps committed
126 127
docBlockToDoc{|[]|} _  _         = abort "error in docBlockToDoc{|[]|}\n"
docBlockToDoc{|Maybe|} fx (Left [])    = Right (Nothing, [])
128
docBlockToDoc{|Maybe|} fx ss=:(Left _) = appFst Just <$> fx ss
Camil Staps's avatar
Camil Staps committed
129
docBlockToDoc{|Maybe|} _  _            = abort "error in docBlockToDoc{|Maybe|}\n"
130 131
docBlockToDoc{|UNIT|} _ = Right (UNIT, [])
docBlockToDoc{|PAIR|} fx fy db=:(Right _) = liftA2 (\(x,ws) (y,ws`) -> (PAIR x y, ws ++ ws`)) (fx db) (fy db)
Camil Staps's avatar
Camil Staps committed
132 133
docBlockToDoc{|PAIR|} _  _  _             = abort "error in docBlockToDoc{|PAIR|}\n"
docBlockToDoc{|FIELD of {gfd_name}|} fx (Right db) = case fx (Left [v \\ (k,v) <- db | k matches gfd_name]) of
134
	Right (f, ws)            -> Right (FIELD f, ws)
Camil Staps's avatar
Camil Staps committed
135
	Left InternalNoDataError -> Left (MissingField gfd_name)
136 137 138 139 140 141 142 143 144 145
	Left e                   -> Left e
where
	(matches) infix 4 :: !String !String -> Bool
	(matches) k name =
		k` == name ||
		pluralise English k` == name ||
		k` == "return" && name == "result" ||
		k` == "return" && name == "results"
	where
		k` = {if (c == '-') '_' c \\ c <-: k}
Camil Staps's avatar
Camil Staps committed
146
docBlockToDoc{|FIELD of {gfd_name}|} _ _ = abort "error in docBlockToDoc{|FIELD|}\n"
147 148 149 150 151 152 153 154 155 156 157 158
docBlockToDoc{|RECORD|} fx (Left [s]) = case parseDocBlock s of
	Right (db, ws) -> case fx (Right db) of
		Right (v, ws`) -> Right (RECORD v, ws ++ ws`)
		Left e -> Left e
	Left e -> Left e
docBlockToDoc{|RECORD|} fx doc = appFst RECORD <$> fx doc
docBlockToDoc{|CONS|} fx doc = appFst CONS <$> fx doc
docBlockToDoc{|EITHER|} fl fr doc = case fl doc of
	Right (v, ws) -> Right (LEFT v, ws)
	Left e -> case fr doc of
		Right (v, ws) -> Right (RIGHT v, ws)
		Left _ -> Left e
159
docBlockToDoc{|OBJECT|} fx doc = appFst (\x -> OBJECT x) <$> fx doc
160

161
docBlockToDoc{|MultiLineString|} (Left [s]) = Right (MultiLine (trimMultiLine $ split "\n" s), [])
Camil Staps's avatar
Camil Staps committed
162
docBlockToDoc{|MultiLineString|} _          = abort "error in docBlockToDoc{|MultiLineString|}\n"
163 164 165 166 167 168 169 170 171 172 173 174 175 176 177

docBlockToDoc{|ParamDoc|} (Left [s]) = case findName (fromString s) of
	Just (name,rest) -> Right (
		{ name        = Just $ toString name
		, description = case rest of
			[] -> Nothing
			_  -> Just $ toString rest
		}, [])
	_                -> Right ({name=Nothing, description=Just s}, [])
where
	findName cs
	# (name,cs) = span (\c -> isAlphanum c || c == '`') cs
	| not (isEmpty name) && not (isEmpty cs) && hd cs == ':'
		= Just (toString name, dropWhile isSpace (tl cs))
		= Nothing
Camil Staps's avatar
Camil Staps committed
178
docBlockToDoc{|ParamDoc|} _ = abort "error in docBlockToDoc{|ParamDoc|}\n"
179 180

docBlockToDoc{|Type|} (Left []) = Left InternalNoDataError
Mart Lubbers's avatar
Mart Lubbers committed
181
docBlockToDoc{|Type|} (Left ss) = case [v \\ Just v <- map (parseType o fromString) ss] of
182 183
	[] -> Left (UnknownError "no parsable type")
	vs -> Right (last vs, [])
Camil Staps's avatar
Camil Staps committed
184
docBlockToDoc{|Type|} _ = abort "error in docBlockToDoc{|Type|}\n"
185

186 187 188 189 190 191 192
docBlockToDoc{|PropertyBootstrapDoc|} (Left [s]) = Right
	(
		{ bootstrap_content                 = MultiLine (trimMultiLine content)
		, bootstrap_without_default_imports = without_imports
		}
	, []
	)
193
where
194 195 196
	lines = split "\n" s
	without_imports = hd lines == "without default imports"
	content = if without_imports (tl lines) lines
197 198
docBlockToDoc{|PropertyBootstrapDoc|} _ = abort "error in docBlockToDoc{|PropertyBootstrapDoc|}\n"

199 200 201 202 203 204 205 206 207 208
docBlockToDoc{|Property|} (Left [s]) = let [signature:property] = split "\n" s in
		parseSignature signature >>= \(sig,ws1) ->
		parseProperty property >>= \(prop,ws2) ->
		Right (sig prop, ws1 ++ ws2)
where
	parseSignature :: !String -> Either ParseError (!String -> Property, ![ParseWarning])
	parseSignature s = case parse parser (fromString s) of
		Left es           -> Left (UnknownError "failed to parse property signature")
		Right (name,args) -> Right (ForAll name args, [])
	where
209
		parser :: Parser Char (!String, ![(String, Type)])
210 211 212 213 214 215 216 217 218 219 220 221 222 223
		parser = skipSpaces *>
			pMany (pSatisfy ((<>) ':')) >>= \name ->
			skipSpaces *> pToken ':' *>
			((skipSpaces *> pToken 'A' *> pToken '.' *>
			pMany
				(skipSpaces *>
				(liftA2 tuple
					(toString <$> pMany (pSatisfy (not o isSpace)))
					(pList [skipSpaces,pToken ':',pToken ':',skipSpaces] *> pTypeWithColonOrSemicolon)
				) <* skipSpaces)) <|> skipSpaces *> pure []) >>= \args ->
			pure (toString name, args)

		skipSpaces = pMany (pSatisfy isSpace) *> pYield undef
		pTypeWithColonOrSemicolon = (pMany (pSatisfy \c -> c <> ':' && c <> ';') <* pOneOf [':;'])
Mart Lubbers's avatar
Mart Lubbers committed
224
			>>= \t -> case parseType t of
225 226 227 228 229
				Nothing -> pError "type could not be parsed"
				Just t  -> pure t

	parseProperty :: ![String] -> Either ParseError (!String, ![ParseWarning])
	parseProperty ss = Right (trimMultiLine ss, [])
Camil Staps's avatar
Camil Staps committed
230
docBlockToDoc{|Property|} _ = abort "error in docBlockToDoc{|Property|}\n"
231 232

docBlockToDoc{|PropertyVarInstantiation|} (Left [s]) = case split "=" s of
Mart Lubbers's avatar
Mart Lubbers committed
233
	[var:type:[]] -> case parseType (fromString type) of
234 235 236
		Just t -> Right (PropertyVarInstantiation (trim var, t), [])
		Nothing -> Left (UnknownError "type could not be parsed")
	_ -> Left (UnknownError "property var instantiation could not be parsed")
Camil Staps's avatar
Camil Staps committed
237
docBlockToDoc{|PropertyVarInstantiation|} _ = abort "error in docBlockToDoc{|PropertyVarInstantiation|}\n"
238

239 240 241 242 243 244 245
docBlockToDoc{|PropertyTestGenerator|} (Left [s])
| startsWith "list: " sig = case parseType [c \\ c <-: sig & i <- [0..] | i > 4] of
	Just t  -> Right (PTG_List t imp, [])
	Nothing -> error
| otherwise = case parseType (fromString sig) of
	Just t  -> Right (PTG_Function t imp, [])
	Nothing -> error
246
where
247 248 249 250
	sig = trim sig`
	imp = trimMultiLine imp`
	[sig`:imp`] = split "\n" s
	error = Left (UnknownError "test generator could not be parsed")
Camil Staps's avatar
Camil Staps committed
251
docBlockToDoc{|PropertyTestGenerator|} _ = abort "error in docBlockToDoc{|PropertyTestGenerator|}\n"
252

253 254
derive docBlockToDoc ModuleDoc, FunctionDoc, InstanceDoc, ClassMemberDoc,
	ConstructorDoc, ClassDoc, TypeDoc
255

256 257 258 259 260 261 262 263 264 265
printDoc :: !d -> String | docToDocBlock{|*|} d
printDoc d = join "\n * "
	[ "/**"
	: (case desc of
		Nothing -> []
		Just d  -> [replaceSubString "\n" "\n * " d] ++ (if (isEmpty fields) [] [""])) ++
	  ["@" +++ f +++ " " +++ replaceSubString "\n" "\n *   " v \\ (f,v) <- fields]
	] +++
	"\n */"
where
266
	fields` = case docToDocBlock{|*|} d of
Camil Staps's avatar
Camil Staps committed
267 268
		Right fs -> fs
		_        -> abort "error in printDoc\n"
269 270 271
	fields = filter ((<>) "description" o fst) fields`
	desc = lookup "description" fields`

272 273 274 275
generic docToDocBlock a :: !a -> Either [String] DocBlock
docToDocBlock{|String|} s = Left [s]
docToDocBlock{|[]|} fx xs = Left [x \\ Left xs` <- map fx xs, x <- xs`]
docToDocBlock{|Maybe|} fx mb = case mb of
276
	Nothing -> Left []
277
	Just x  -> fx x
Camil Staps's avatar
Camil Staps committed
278

279 280
docToDocBlock{|PAIR|} fx fy (PAIR x y) = case fx x of
	Right xs -> case fy y of
Camil Staps's avatar
Camil Staps committed
281 282 283
		Right ys -> Right (xs ++ ys)
		_        -> abort "error in docToDocBlock{|PAIR|}\n"
	_            -> abort "error in docToDocBlock{|PAIR|}\n"
284
docToDocBlock{|FIELD of d|} fx (FIELD x) = case fx x of
Camil Staps's avatar
Camil Staps committed
285 286
	Left xs -> Right [(name,x) \\ x <- xs]
	_       -> abort "error in docToDocBlock{|FIELD|}\n"
287 288 289 290 291 292
where
	name = {if (c=='_') '-' c \\ c <-: name`}
	name`
	| endsWith "ies" d.gfd_name = d.gfd_name % (0,size d.gfd_name-4) +++ "y"
	| endsWith "s" d.gfd_name   = d.gfd_name % (0,size d.gfd_name-2)
	| otherwise                 = d.gfd_name
293
docToDocBlock{|RECORD|} fx (RECORD x) = fx x
294

295
docToDocBlock{|ParamDoc|} pd = case pd.ParamDoc.name of
296 297 298 299 300 301
	Nothing -> case pd.ParamDoc.description of
		Nothing -> Left []
		Just d -> Left [d]
	Just n -> case pd.ParamDoc.description of
		Nothing -> Left [n]
		Just d -> Left [n +++ ": " +++ d]
302 303 304
docToDocBlock{|MultiLineString|} (MultiLine s) = Left [s]
docToDocBlock{|Type|} t = Left [toString t]
docToDocBlock{|PropertyBootstrapDoc|} bs_doc = Left $ [ if bs_doc.bootstrap_without_default_imports " without default imports" ""
305 306
	: map ((+++) "    ") $ split "\n" $ fromMultiLine bs_doc.bootstrap_content
	]
307
docToDocBlock{|Property|} (ForAll name args impl) = Left
308
	[name +++ ": A." +++ join "; " [a +++ " :: " <+ t \\ (a,t) <- args] +++ ":\n" +++ impl]
309 310
docToDocBlock{|PropertyVarInstantiation|} (PropertyVarInstantiation (a,t)) = Left [a +++ " = " <+ t]
docToDocBlock{|PropertyTestGenerator|} ptg = Left [t <+ "\n" +++ imp]
311 312 313 314
where
	(t,imp) = case ptg of
		PTG_Function t imp -> (t,imp)
		PTG_List t imp     -> (t,imp)
315

316 317
derive docToDocBlock ModuleDoc, FunctionDoc, InstanceDoc, ClassMemberDoc,
	ClassDoc, ConstructorDoc, TypeDoc
318

319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352
trimMultiLine :: ![String] -> String
trimMultiLine ss = join "\n" [s % (trimn, size s - 1) \\ s <- ss]
where
	trimn = minList [i \\ Just i <- map (firstNonSpace 0) ss]

	firstNonSpace :: !Int !String -> Maybe Int
	firstNonSpace i s
	| i >= size s   = Nothing
	| isSpace s.[i] = firstNonSpace (i+1) s
	| otherwise     = Just i

parseDocBlock :: !String -> Either ParseError (!DocBlock, ![ParseWarning])
parseDocBlock b = prepareString b >>= parsef
where
	parsef :: ![[Char]] -> Either ParseError (!DocBlock, ![ParseWarning])
	parsef [] = Right ([], [])
	parsef lines = case span (\l -> isEmpty l || hd l <> '@') lines of
		([],   [ln]) = parseFields [ln]
		([],   rest) = appSnd (\ws -> [NoDescription:ws]) <$> parseFields rest
		(desc, rest) = appFst (\d -> [("description", linesToString desc):d]) <$> parseFields rest

	parseFields :: ![[Char]] -> Either ParseError (!DocBlock, ![ParseWarning])
	parseFields []
		= Right ([], [])
	parseFields [['@':line]:rest]
		= parseFields rest` >>=
			\(d,ws) -> appSnd ((++) ws) <$> parseFs field desc d
	where
		(field, descline) = span (not o isSpace) line
		(restdesc, rest`) = span (\l -> isEmpty l || hd l <> '@') rest
		desc = flatten $ intersperse ['\n'] $ if (isEmpty descline) restdesc [tl descline:restdesc]

		parseFs :: ![Char] ![Char] !DocBlock -> Either ParseError (!DocBlock, ![ParseWarning])
		parseFs field val d = Right ([(toString field,toString (rtrim val)):d], [])
Camil Staps's avatar
Camil Staps committed
353 354
	parseFields _
		= abort "error in parseDocBlock\n"
355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392

prepareString :: (String -> Either ParseError [[Char]])
prepareString = checkAsterisks o map trim o break '\n' o fromString
where
	checkAsterisks :: ![[Char]] -> Either ParseError [[Char]]
	checkAsterisks [['*':line]] = Right [safetl line]
	checkAsterisks [line] = Right [line]
	checkAsterisks lines
	| all (\l -> isEmpty l || hd l == '*') lines
		= Right $ map (safetl o dropWhile ((==) '*')) lines
		= Left $ MissingAsterisk $ toString $ hd $ filter (\l -> not (isEmpty l) && hd l <> '*') lines

	safetl :: ![a] -> [a]
	safetl []     = []
	safetl [_:xs] = xs

	break :: !a -> [a] -> [[a]] | == a
	break e = foldr f []
	where
		f x []     = if (x == e) []        [[x]]
		f x [y:ys] = if (x == e) [[]:y:ys] [[x:y]:ys]

linesToString :: ([[Char]] -> String)
linesToString = toString o flatten o intersperse ['\n']

instance toString ParseWarning
where
	toString (UnknownField f)   = "Doc warning: unknown field '" +++ f +++ "'"
	toString (IllegalField f)   = "Doc warning: illegal field '" +++ f +++ "'"
	toString NoDescription      = "Doc warning: missing description"
	toString UsedReturn         = "Doc warning: @return is deprecated, use @result"
	toString (UnparsableType t) = "Doc warning: could not parse type '" +++ t +++ "'"

instance toString ParseError
where
	toString (MissingAsterisk l) = "Doc error: missing leading asterisk in '" +++ l +++ "'"
	toString (MissingField f)    = "Doc error: required field '" +++ f +++ "' was missing"
	toString (UnknownError e)    = "Doc error: " +++ e
Camil Staps's avatar
Camil Staps committed
393
	toString InternalNoDataError = "Doc error: internal parsing error"
394 395 396 397 398 399 400 401 402 403 404

traceParseWarnings :: ![ParseWarning] !a -> a
traceParseWarnings []     x = x
traceParseWarnings [w:ws] x
| trace_tn w = traceParseWarnings ws x
| otherwise  = undef

traceParseError :: !ParseError !a -> a
traceParseError e x
| trace_tn e = x
| otherwise  = undef