Doc.icl 16.6 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 25
from Text import <+,
	class Text(join,split,trim,rtrim,replaceSubString,endsWith),
26 27 28 29 30
	instance Text String, instance Text [Char]
import Text.Language
import Text.Parsers.Simple.ParserCombinators

from Clean.Types import :: Type, :: TypeRestriction
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 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 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 89 90 91 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

gDefault{|Maybe|} _ = Nothing

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

instance docDescription       ModuleDoc where docDescription       d = d.ModuleDoc.description
instance docPropertyBootstrap ModuleDoc where docPropertyBootstrap d = fromMultiLine <$> d.property_bootstrap
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
instance docProperties       FunctionDoc where docProperties       d = d.properties
instance docPropertyTestWith FunctionDoc where docPropertyTestWith d = d.FunctionDoc.property_test_with

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 _ = ""

derive gDefault Type, TypeRestriction, ModuleDoc, FunctionDoc, ClassMemberDoc,
	ConstructorDoc, ClassDoc, TypeDoc, Property, PropertyVarInstantiation,
	MultiLineString, PropertyTestGenerator, ParamDoc

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
117
docBlockToDoc{|String|} _         = abort "error in docBlockToDoc{|String|}\n"
118
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
119 120
docBlockToDoc{|[]|} _  _         = abort "error in docBlockToDoc{|[]|}\n"
docBlockToDoc{|Maybe|} fx (Left [])    = Right (Nothing, [])
121
docBlockToDoc{|Maybe|} fx ss=:(Left _) = appFst Just <$> fx ss
Camil Staps's avatar
Camil Staps committed
122
docBlockToDoc{|Maybe|} _  _            = abort "error in docBlockToDoc{|Maybe|}\n"
123 124
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
125 126
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
127
	Right (f, ws)            -> Right (FIELD f, ws)
Camil Staps's avatar
Camil Staps committed
128
	Left InternalNoDataError -> Left (MissingField gfd_name)
129 130 131 132 133 134 135 136 137 138
	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
139
docBlockToDoc{|FIELD of {gfd_name}|} _ _ = abort "error in docBlockToDoc{|FIELD|}\n"
140 141 142 143 144 145 146 147 148 149 150 151 152 153 154
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
docBlockToDoc{|OBJECT|} fx doc = appFst OBJECT <$> fx doc

docBlockToDoc{|MultiLineString|} (Left [s]) = Right (MultiLine $ trimMultiLine $ split "\n" s, [])
Camil Staps's avatar
Camil Staps committed
155
docBlockToDoc{|MultiLineString|} _          = abort "error in docBlockToDoc{|MultiLineString|}\n"
156 157 158 159 160 161 162 163 164 165 166 167 168 169 170

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
171
docBlockToDoc{|ParamDoc|} _ = abort "error in docBlockToDoc{|ParamDoc|}\n"
172 173

docBlockToDoc{|Type|} (Left []) = Left InternalNoDataError
Mart Lubbers's avatar
Mart Lubbers committed
174
docBlockToDoc{|Type|} (Left ss) = case [v \\ Just v <- map (parseType o fromString) ss] of
175 176
	[] -> Left (UnknownError "no parsable type")
	vs -> Right (last vs, [])
Camil Staps's avatar
Camil Staps committed
177
docBlockToDoc{|Type|} _ = abort "error in docBlockToDoc{|Type|}\n"
178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203

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
		parser :: Parser Char (!String, ![(!String, !Type)])
		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
204
			>>= \t -> case parseType t of
205 206 207 208 209
				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
210
docBlockToDoc{|Property|} _ = abort "error in docBlockToDoc{|Property|}\n"
211 212

docBlockToDoc{|PropertyVarInstantiation|} (Left [s]) = case split "=" s of
Mart Lubbers's avatar
Mart Lubbers committed
213
	[var:type:[]] -> case parseType (fromString type) of
214 215 216
		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
217
docBlockToDoc{|PropertyVarInstantiation|} _ = abort "error in docBlockToDoc{|PropertyVarInstantiation|}\n"
218

Mart Lubbers's avatar
Mart Lubbers committed
219
docBlockToDoc{|PropertyTestGenerator|} (Left [s]) = case parseType (fromString sig) of
220 221 222 223
	Just t -> Right (PropertyTestGenerator t (trimMultiLine imp), [])
	Nothing -> Left (UnknownError "type could not be parsed")
where
	[sig:imp] = split "\n" s
Camil Staps's avatar
Camil Staps committed
224
docBlockToDoc{|PropertyTestGenerator|} _ = abort "error in docBlockToDoc{|PropertyTestGenerator|}\n"
225 226 227 228

derive docBlockToDoc ModuleDoc, FunctionDoc, ClassMemberDoc, ConstructorDoc,
	ClassDoc, TypeDoc

229 230 231 232 233 234 235 236 237 238
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
Camil Staps's avatar
Camil Staps committed
239 240 241
	fields` = case docToDocBlock{|*|} False d of
		Right fs -> fs
		_        -> abort "error in printDoc\n"
242 243 244 245 246
	fields = filter ((<>) "description" o fst) fields`
	desc = lookup "description" fields`

generic docToDocBlock a :: Bool a -> Either [String] DocBlock
docToDocBlock{|String|} True s = Left [s]
Camil Staps's avatar
Camil Staps committed
247
docToDocBlock{|String|} _    _ = abort "error in docToDocBlock{|String|}\n"
248
docToDocBlock{|[]|} fx True xs = Left [x \\ Left xs` <- map (fx True) xs, x <- xs`]
Camil Staps's avatar
Camil Staps committed
249
docToDocBlock{|[]|} _  _    _  = abort "error in docToDocBlock{|[]|}\n"
250 251 252
docToDocBlock{|Maybe|} fx True mb = case mb of
	Nothing -> Left []
	Just x  -> fx True x
Camil Staps's avatar
Camil Staps committed
253 254 255 256 257 258 259 260 261 262 263
docToDocBlock{|Maybe|} _  _    _  = abort "error in docToDocBlock{|Maybe|}\n"

docToDocBlock{|PAIR|} fx fy False (PAIR x y) = case fx False x of
	Right xs -> case fy False y of
		Right ys -> Right (xs ++ ys)
		_        -> abort "error in docToDocBlock{|PAIR|}\n"
	_            -> abort "error in docToDocBlock{|PAIR|}\n"
docToDocBlock{|PAIR|} _  _  _      _         = abort "error in docToDocBlock{|PAIR|}\n"
docToDocBlock{|FIELD of d|} fx False (FIELD x) = case fx True x of
	Left xs -> Right [(name,x) \\ x <- xs]
	_       -> abort "error in docToDocBlock{|FIELD|}\n"
264 265 266 267 268 269
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
Camil Staps's avatar
Camil Staps committed
270
docToDocBlock{|FIELD|} _ _ _ = abort "error in docToDocBlock{|FIELD|}\n"
271
docToDocBlock{|RECORD|} fx False (RECORD x) = fx False x
Camil Staps's avatar
Camil Staps committed
272
docToDocBlock{|RECORD|} _  _     _          = abort "error in docToDocBlock{|RECORD|}\n"
273 274 275 276 277 278 279 280

docToDocBlock{|ParamDoc|} True pd = case pd.ParamDoc.name of
	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]
Camil Staps's avatar
Camil Staps committed
281
docToDocBlock{|ParamDoc|} _ _ = abort "error in docToDocBlock{|ParamDoc|}\n"
282
docToDocBlock{|MultiLineString|} True (MultiLine s) = Left [s]
Camil Staps's avatar
Camil Staps committed
283
docToDocBlock{|MultiLineString|} _    _             = abort "error in docToDocBlock{|MultiLineString|}\n"
284
docToDocBlock{|Type|} True t = Left [toString t]
Camil Staps's avatar
Camil Staps committed
285
docToDocBlock{|Type|} _    _ = abort "error in docToDocBlock{|Type|}\n"
286 287
docToDocBlock{|Property|} True (ForAll name args impl) = Left
	[name +++ ": A." +++ join "; " [a +++ " :: " <+ t \\ (a,t) <- args] +++ ":\n" +++ impl]
Camil Staps's avatar
Camil Staps committed
288
docToDocBlock{|Property|} _ _ = abort "error in docToDocBlock{|Property|}\n"
289
docToDocBlock{|PropertyVarInstantiation|} True (PropertyVarInstantiation (a,t)) = Left [a +++ " = " <+ t]
Camil Staps's avatar
Camil Staps committed
290
docToDocBlock{|PropertyVarInstantiation|} _    _                                = abort "error in docToDocBlock{|PropertyVarInstantiation|}\n"
291
docToDocBlock{|PropertyTestGenerator|} True (PropertyTestGenerator t impl) = Left [t <+ "\n" +++ impl]
Camil Staps's avatar
Camil Staps committed
292
docToDocBlock{|PropertyTestGenerator|} _    _                              = abort "error in docToDocBlock{|PropertyTestGenerator|}\n"
293 294 295 296

derive docToDocBlock ModuleDoc, FunctionDoc, ClassMemberDoc, ClassDoc,
	ConstructorDoc, TypeDoc

297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330
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
331 332
	parseFields _
		= abort "error in parseDocBlock\n"
333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370

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
371
	toString InternalNoDataError = "Doc error: internal parsing error"
372 373 374 375 376 377 378 379 380 381 382

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