From 1746f21bc3720585d2fe877db8d69aae301ff02c Mon Sep 17 00:00:00 2001 From: Rowan Goemans Date: Sun, 31 Dec 2017 02:03:08 +0100 Subject: -- Added many unit tests for the C parser. Almost complete now -- Refactored project structure to allow for more overview once we add more languages. -- Renamed a lot of types in the CParser to be more explicit. -- Made configuration injectable into the classes that need them. This allows to unit test configuration variables. -- Added 2 new config params that allows to customize what gets returned for a bool return type. -- Small changes to the logic to make it more concise. --- package.json | 10 + src/CodeParser/CParser/Argument.ts | 6 - src/CodeParser/CParser/CParser.ts | 643 -------------------------------- src/CodeParser/CParser/CppParser.ts | 16 - src/CodeParser/CParser/ParseTree.ts | 121 ------ src/CodeParser/CParser/Token.ts | 27 -- src/CodeParser/CodeParser.ts | 9 - src/CodeParser/CodeParserController.ts | 119 ------ src/CodeParserController.ts | 108 ++++++ src/Common/ICodeParser.ts | 9 + src/Common/IDocGen.ts | 9 + src/Config.ts | 57 ++- src/DocGen/CGen.ts | 185 --------- src/DocGen/CppGen.ts | 6 - src/DocGen/DocGen.ts | 9 - src/Lang/C/CArgument.ts | 6 + src/Lang/C/CDocGen.ts | 183 +++++++++ src/Lang/C/CParseTree.ts | 121 ++++++ src/Lang/C/CParser.ts | 608 ++++++++++++++++++++++++++++++ src/Lang/C/CToken.ts | 26 ++ src/extension.ts | 2 +- src/test/Attributes.test.ts | 49 --- src/test/CTests/Attributes.test.ts | 62 +++ src/test/CTests/FunctionPointer.test.ts | 42 +++ src/test/CTests/Operators.test.ts | 256 +++++++++++++ src/test/CTests/ReturnTypes.test.ts | 99 +++++ src/test/CTests/Templates.test.ts | 51 +++ src/test/CTests/TestSetup.ts | 52 +++ src/test/CTests/TrailingReturns.test.ts | 39 ++ src/test/FunctionPointer.test.ts | 42 --- src/test/Operators.test.ts | 38 -- src/test/ReturnTypes.test.ts | 99 ----- src/test/Templates.test.ts | 44 --- src/test/TrailingReturns.test.ts | 39 -- src/test/Variadic.test.ts | 38 -- src/test/tools/TestSetup.ts | 46 --- 36 files changed, 1723 insertions(+), 1553 deletions(-) delete mode 100644 src/CodeParser/CParser/Argument.ts delete mode 100644 src/CodeParser/CParser/CParser.ts delete mode 100644 src/CodeParser/CParser/CppParser.ts delete mode 100644 src/CodeParser/CParser/ParseTree.ts delete mode 100644 src/CodeParser/CParser/Token.ts delete mode 100644 src/CodeParser/CodeParser.ts delete mode 100644 src/CodeParser/CodeParserController.ts create mode 100644 src/CodeParserController.ts create mode 100644 src/Common/ICodeParser.ts create mode 100644 src/Common/IDocGen.ts delete mode 100644 src/DocGen/CGen.ts delete mode 100644 src/DocGen/CppGen.ts delete mode 100644 src/DocGen/DocGen.ts create mode 100644 src/Lang/C/CArgument.ts create mode 100644 src/Lang/C/CDocGen.ts create mode 100644 src/Lang/C/CParseTree.ts create mode 100644 src/Lang/C/CParser.ts create mode 100644 src/Lang/C/CToken.ts delete mode 100644 src/test/Attributes.test.ts create mode 100644 src/test/CTests/Attributes.test.ts create mode 100644 src/test/CTests/FunctionPointer.test.ts create mode 100644 src/test/CTests/Operators.test.ts create mode 100644 src/test/CTests/ReturnTypes.test.ts create mode 100644 src/test/CTests/Templates.test.ts create mode 100644 src/test/CTests/TestSetup.ts create mode 100644 src/test/CTests/TrailingReturns.test.ts delete mode 100644 src/test/FunctionPointer.test.ts delete mode 100644 src/test/Operators.test.ts delete mode 100644 src/test/ReturnTypes.test.ts delete mode 100644 src/test/Templates.test.ts delete mode 100644 src/test/TrailingReturns.test.ts delete mode 100644 src/test/Variadic.test.ts delete mode 100644 src/test/tools/TestSetup.ts diff --git a/package.json b/package.json index 041abf3..67b83b8 100644 --- a/package.json +++ b/package.json @@ -59,6 +59,16 @@ "type": "boolean", "default": true }, + "doxdocgen.generic.boolReturnsTrueFalse": { + "description": "If this is enabled a bool return value will be split into true and false return param.", + "type": "boolean", + "default": true + }, + "doxdocgen.generic.boolPointerReturnsNull": { + "description": "If this is enabled a pointer to a bool return value will include a null return param.", + "type": "boolean", + "default": true + }, "doxdocgen.generic.briefTemplate": { "description": "The template of the brief DoxyGen line that is generated. If empty it won't get generated at all.", "type": "string", diff --git a/src/CodeParser/CParser/Argument.ts b/src/CodeParser/CParser/Argument.ts deleted file mode 100644 index 4cd793d..0000000 --- a/src/CodeParser/CParser/Argument.ts +++ /dev/null @@ -1,6 +0,0 @@ -import { ParseTree } from "./ParseTree"; - -export class Argument { - public Name: string = undefined; - public Type: ParseTree = new ParseTree(); -} diff --git a/src/CodeParser/CParser/CParser.ts b/src/CodeParser/CParser/CParser.ts deleted file mode 100644 index 34ffba4..0000000 --- a/src/CodeParser/CParser/CParser.ts +++ /dev/null @@ -1,643 +0,0 @@ -import { Position, TextDocumentContentChangeEvent, TextEditor, TextLine, workspace } from "vscode"; -import { Config, ConfigType } from "../../Config"; -import Generator from "../../DocGen/CGen"; -import { IDocGen } from "../../DocGen/DocGen"; -import ICodeParser from "../CodeParser"; -import { Argument } from "./Argument"; -import { ParseTree } from "./ParseTree"; -import { Token, TokenType } from "./Token"; - -/** - * - * Parses C code for methods and signatures - * - * @export - * @class CParser - * @implements {ICodeParser} - */ -export default class CParser implements ICodeParser { - protected activeEditor: TextEditor; - protected activeSelection: Position; - - private typeKeywords: string[]; - private stripKeywords: string[]; - private keywords: string[]; - private specifiers: string[]; - private lexerVocabulary; - - constructor() { - this.typeKeywords = [ - "constexpr", - "const", - "struct", - ]; - - this.stripKeywords = [ - "final", - "static", - "inline", - "friend", - "virtual", - "extern", - "explicit", - "class", - "override", - "typename", - ]; - - this.specifiers = [ - "noexcept", - "throw", - "alignas", - ]; - - // Non type keywords will be stripped from the final return type. - this.keywords = this.typeKeywords.concat(this.stripKeywords); - - this.lexerVocabulary = { - ArraySubscript: (x: string): string => (x.match("^\\[[^\\[]*?\\]") || [])[0], - Arrow: (x: string): string => (x.match("^->") || [])[0], - Assignment: (x: string): string => (x.match("^=") || [])[0], - Attribute: (x: string): string => (x.match("^\\[\\[[^\\[]*?\\]\\]") || [])[0], - CloseParenthesis: (x: string): string => (x.match("^\\)") || [])[0], - Comma: (x: string): string => (x.match("^,") || [])[0], - CommentBlock: (x: string): string => { - if (x.startsWith("/*") === false) { - return undefined; - } - - let closeOffset: number = x.indexOf("*/"); - closeOffset = closeOffset === -1 ? x.length : closeOffset + 2; - return x.slice(0, closeOffset); - }, - CommentLine: (x: string): string => { - if (x.startsWith("//") === false) { - return undefined; - } - - let closeOffset: number = x.indexOf("\n"); - closeOffset = closeOffset === -1 ? x.length : closeOffset + 1; - return x.slice(0, closeOffset); - }, - CurlyBlock: (x: string): string => { - if (x.startsWith("{") === false) { - return undefined; - } - const startEndOffset: number[] = this.GetSubExprStartEnd(x, 0, "{", "}"); - return startEndOffset[1] === 0 ? undefined : x.slice(0, startEndOffset[1]); - }, - Ellipsis: (x: string): string => (x.match("^\\.\\.\\.") || [])[0], - OpenParenthesis: (x: string): string => (x.match("^\\(") || [])[0], - Pointer: (x: string): string => (x.match("^\\*") || [])[0], - Reference: (x: string): string => (x.match("^&") || [])[0], - Specifier: (x: string): string => { - const foundIndex: number = this.specifiers - .findIndex((n: string) => x.startsWith(n) === true); - - if (foundIndex === -1) { - return undefined; - } - - if (x.slice(this.specifiers[foundIndex].length).trim().startsWith("(") === false) { - return x.slice(0, this.specifiers[foundIndex].length); - } - - const startEndOffset: number[] = this.GetSubExprStartEnd(x, 0, "(", ")"); - return startEndOffset[1] === 0 ? undefined : x.slice(0, startEndOffset[1]); - - }, - Symbol: (x: string): string => { - // Handle access specifiers since they aren't really symbols. - if (x.startsWith("public:") || x.startsWith("protected:") || x.startsWith("private:")) { - return undefined; - } - - // Handle specifiers - const specifierFound: number = this.specifiers - .findIndex((n: string) => x.startsWith(n) === true); - - if (specifierFound !== -1) { - return undefined; - } - - // Handle decltype special cases. - if (x.startsWith("decltype") === true) { - const startEndOffset: number[] = this.GetSubExprStartEnd(x, 0, "(", ")"); - return startEndOffset[1] === 0 ? undefined : x.slice(0, startEndOffset[1]); - } - - // Special case group up the fundamental types with the modifiers. - // tslint:disable-next-line:max-line-length - let reMatch: string = (x.match("^(unsigned|signed|short|long|int|char|double)(\\s+(unsigned|signed|short|long|int|char|double))+") || [])[0]; - if (reMatch !== undefined) { - return reMatch.trim(); - } - - // Regex to handle a part of all symbols and includes all symbol special cases. - // This is run in a loop because template parts of a symbol can't be parsed using regex. - // tslint:disable-next-line:max-line-length - const symbolRegex: string = "^([a-z|A-Z|:|_|~|\\d]*operator\\s*(\"\"_[a-z|A-Z]+|>>=|<<=|->\\*|\\+=|-=|\\*=|\\/=|%=|ˆ=|&=|\\|=|<<|>>|==|!=|<=|->|>=|&&|\\|\\||\\+\\+|--|\\+|-|\\*|\\/|%|\\^|&|\||~|!|=|<|>|,|\\[\\s*\\]|\\(\\s*\\)|(new|delete)\\s*(\\[\\s*\\]){0,1}){0,1}|[a-z|A-Z|:|_|~|\\d]+)"; - - reMatch = (x.match(symbolRegex) || [])[0]; - if (reMatch === undefined) { - return undefined; - } - - let symbol: string = reMatch; - while (true) { - if (x.slice(symbol.length).trim().startsWith("<") === true) { - const offsets: number[] = this.GetSubExprStartEnd(x, symbol.length, "<", ">"); - if (offsets[1] === 0) { - return undefined; - } - symbol = x.slice(0, offsets[1]); - } - - reMatch = (x.slice(symbol.length).match(symbolRegex) || [])[0]; - if (reMatch === undefined) { - break; - } - - symbol += reMatch; - } - - return symbol.replace(/\s+$/, ""); - }, - }; - } - - /** - * @inheritdoc - */ - public Parse(activeEdit: TextEditor): IDocGen { - this.activeEditor = activeEdit; - this.activeSelection = this.activeEditor.selection.active; - - let line: string = ""; - try { - line = this.getLogicalLine(); - } catch (err) { - // console.dir(err); - } - - // template parsing is simpler by using heuristics rather then tokenizing first. - const templateArgs: string[] = []; - while (line.startsWith("template")) { - const template: string = this.GetTemplate(line); - - templateArgs.push.apply(templateArgs, this.GetArgsFromTemplate(template)); - - line = line.slice(template.length, line.length + 1).trim(); - } - - let retAndArgs: string[][] = [[], []]; - try { - retAndArgs = this.GetReturnAndArgs(line); - } catch (err) { - // console.dir(err); - } - - const retVals = retAndArgs[0]; - const args = retAndArgs[1]; - - const cppGenerator: IDocGen = new Generator( - this.activeEditor, - this.activeSelection, - args, - templateArgs, - retVals, - ); - - return cppGenerator; - } - - /*************************************************************************** - Implementation - ***************************************************************************/ - private getLogicalLine(): string { - let logicalLine: string = ""; - - let nextLine: Position = new Position(this.activeSelection.line + 1, this.activeSelection.character); - - let nextLineTxt: string = this.activeEditor.document.lineAt(nextLine.line).text.trim(); - - // VSCode may enter a * on itself, we don"t want that in our method - if (nextLineTxt === "*") { - nextLineTxt = ""; - } - - let currentNest: number = 0; - logicalLine = nextLineTxt; - - // Get method end line - let linesToGet: number = 20; - while (linesToGet-- > 0) { // Check for end of expression. - nextLine = new Position(nextLine.line + 1, nextLine.character); - nextLineTxt = this.activeEditor.document.lineAt(nextLine.line).text.trim(); - - // Check if method has finished if curly brace is opened while - // nesting is occuring. - for (let i: number = 0; i < nextLineTxt.length; i++) { - if (nextLineTxt[i] === "(") { - currentNest++; - } else if (nextLineTxt[i] === ")") { - currentNest--; - } else if (nextLineTxt[i] === "{" && currentNest === 0) { - logicalLine += "\n" + nextLineTxt.slice(0, i); - return logicalLine.replace(/^\s+|\s+$/g, ""); - } else if ((nextLineTxt[i] === ";" - || (nextLineTxt[i] === ":" && nextLineTxt[i - 1] !== ":" && nextLineTxt[i + 1] !== ":")) - && currentNest === 0) { - - logicalLine += "\n" + nextLineTxt.slice(0, i); - return logicalLine.replace(/^\s+|\s+$/g, ""); - } - } - - logicalLine += "\n" + nextLineTxt; - } - - throw new Error("More then 20 lines were gotten from editor and no end of expression was found."); - } - - private Tokenize(expression: string): Token[] { - const tokens: Token[] = []; - expression = expression.replace(/^\s+|\s+$/g, ""); - - while (expression.length !== 0) { - const matches: Token[] = Object.keys(this.lexerVocabulary) - .map((k): Token => new Token(TokenType[k], this.lexerVocabulary[k](expression))) - .filter((t) => t.Value !== undefined); - - if (matches.length === 0) { - throw new Error("Next token couldn\'t be determined: " + expression); - } else if (matches.length > 1) { - throw new Error("Multiple matches for next token: " + expression); - } - - tokens.push(matches[0]); - expression = expression.slice(matches[0].Value.length, expression.length).replace(/^\s+|\s+$/g, ""); - } - - return tokens; - } - - private GetReturnAndArgs(line: string): string[][] { - const retVals: string[] = []; - let args: string[] = []; - - // Tokenize rest of expression and remove comment tokens; - const tokens: Token[] = this.Tokenize(line) - .filter((t) => t.Type !== TokenType.CommentBlock) - .filter((t) => t.Type !== TokenType.CommentLine); - - // Create hierarchical tree based on the parenthesis. - const tree: ParseTree = ParseTree.CreateTree(tokens).Compact(); - - // return argument. - const returnArg = this.GetArgument(tree); - // check if it is a constructor or descructor since these have no name.. - // and reverse the assignment of type and name. - if (returnArg.Name === undefined) { - if (returnArg.Type.nodes.length !== 1) { - throw new Error("Too many symbols found for constructor/descructor."); - } else if (returnArg.Type.nodes[0] instanceof ParseTree) { - throw new Error("One node found with just a parsetree. Malformed input."); - } - - returnArg.Name = (returnArg.Type.nodes[0] as Token).Value; - returnArg.Type.nodes = []; - } - - // Check if return type is a pointer - const ptrReturnIndex = returnArg.Type.nodes - .findIndex((n) => n instanceof Token && n.Type === TokenType.Pointer); - - // Special case for void functions. - const voidReturnIndex = returnArg.Type.nodes - .findIndex((n) => n instanceof Token && n.Type === TokenType.Symbol && n.Value === "void"); - - // Special case for bool return type. - const boolReturnIndex: number = returnArg.Type.nodes - .findIndex((n) => n instanceof Token && n.Type === TokenType.Symbol && n.Value === "bool"); - - if (boolReturnIndex !== -1) { - retVals.push("true"); - retVals.push("false"); - if (ptrReturnIndex !== -1) { - retVals.push("null"); - } - } else if (voidReturnIndex !== -1 && ptrReturnIndex !== -1) { - retVals.push(returnArg.Type.Yield()); - } else if (voidReturnIndex === -1 && returnArg.Type.nodes.length > 0) { - retVals.push(returnArg.Type.Yield()); - } - - // Get arguments list as a parsetree and create arguments from them. - args = this.GetArgumentList(tree) - .map((a) => this.GetArgument(a)) - .map((a) => a.Name === undefined ? "" : a.Name); - - return [retVals, args]; - } - - private RemoveUnusedTokens(tree: ParseTree): ParseTree { - tree = tree.Copy(); - - // First slice of everything after assignment since that will not be used. - const assignmentIndex = tree.nodes.findIndex((n) => n instanceof Token && n.Type === TokenType.Assignment); - if (assignmentIndex !== -1) { - tree.nodes = tree.nodes.slice(0, assignmentIndex); - } - - // Specifiers aren't needed so remove them. - while (true) { - const specifierIndex = tree.nodes - .findIndex((n) => n instanceof Token && n.Type === TokenType.Specifier); - if (specifierIndex !== -1) { - tree.nodes.splice(specifierIndex, 1); - } else { - break; - } - } - - return tree; - } - - private GetArgumentList(tree: ParseTree): ParseTree[] { - const args: ParseTree[] = []; - - tree = this.RemoveUnusedTokens(tree); - - let cursor: ParseTree = tree; - while (this.IsFuncPtr(cursor.nodes) === true) { - cursor = cursor.nodes.find((n) => n instanceof ParseTree) as ParseTree; - } - - const argTree: ParseTree = cursor.nodes.find((n) => n instanceof ParseTree) as ParseTree; - if (argTree === undefined) { - throw new Error("Function arguments not found."); - } - - // Split the argument tree on commas - let arg: ParseTree = new ParseTree(); - for (const node of argTree.nodes) { - if (node instanceof Token && node.Type === TokenType.Comma) { - args.push(arg); - arg = new ParseTree(); - } else { - arg.nodes.push(node); - } - } - - if (arg.nodes.length > 0) { - args.push(arg); - } - - return args; - } - - private IsFuncPtr(nodes: Array) { - return nodes.filter((n) => n instanceof ParseTree).length === 2; - } - - private StripNonTypeNodes(tree: ParseTree) { - tree.nodes = tree.nodes - // All strippable keywords. - .filter((n) => { - return !(n instanceof Token - && n.Type === TokenType.Symbol - && this.stripKeywords.find((k) => k === n.Value) !== undefined); - }) - // Attributes aren't part of the type. - .filter((n) => !(n instanceof Token && n.Type === TokenType.Attribute)); - } - - private GetArgumentFromTrailingReturn(tree: ParseTree, startTrailingReturn: number): Argument { - const argument: Argument = new Argument(); - - // Find index of auto prior to the first parseTree. - // If auto is not found something is going wrong since trailing return - // requires auto. - let autoIndex: number = -1; - for (let i: number = 0; i < tree.nodes.length; i++) { - const node = tree.nodes[i]; - if (node instanceof ParseTree) { - break; - } - if (node.Type === TokenType.Symbol && node.Value === "auto") { - autoIndex = i; - break; - } - } - - if (autoIndex === -1) { - throw new Error("Function declaration has trailing return but type is not auto."); - } - - // Get symbol between auto and parseTree which is the argument name. It also may not be a keyword. - for (let i: number = autoIndex + 1; i < tree.nodes.length; i++) { - const node = tree.nodes[i]; - if (node instanceof ParseTree) { - break; - } - if (node.Type === TokenType.Symbol && this.keywords.find((k) => k === node.Value) === undefined) { - argument.Name = node.Value; - break; - } - } - - argument.Type.nodes = tree.nodes.slice(startTrailingReturn + 1, tree.nodes.length); - this.StripNonTypeNodes(argument.Type); - - return argument; - } - - private GetArgumentFromFuncPtr(tree: ParseTree): Argument { - const argument: Argument = new Argument(); - - argument.Type = tree; - - let cursor: ParseTree = tree; - - while (this.IsFuncPtr(cursor.nodes) === true) { - cursor = cursor.nodes.find((n) => n instanceof ParseTree) as ParseTree; - } - - // Remove parseTree. This can be if it is a function declaration. - const argumentsIndex = cursor.nodes.findIndex((n) => n instanceof ParseTree); - if (argumentsIndex !== -1) { - cursor.nodes.splice(argumentsIndex, 1); - } - - // Find first symbol that is the argument name. - // Remove it from the tree and set the name to the argument name - for (let i: number = 0; i < cursor.nodes.length; i++) { - const node = cursor.nodes[i]; - if (node instanceof ParseTree) { - continue; - } - - if (node.Type === TokenType.Symbol && this.keywords.find((k) => k === node.Value) === undefined) { - argument.Name = node.Value; - cursor.nodes.splice(i, 1); - } - } - - this.StripNonTypeNodes(argument.Type); - return argument; - } - - private GetDefaultArgument(tree: ParseTree): Argument { - const argument: Argument = new Argument(); - - for (const node of tree.nodes) { - if (node instanceof ParseTree) { - break; - } - const symbolCount = argument.Type.nodes - .filter((n) => n instanceof Token) - .map((n) => n as Token) - .filter((n) => n.Type === TokenType.Symbol) - .filter((n) => this.keywords.find((k) => k === n.Value) === undefined) - .length; - - if (node.Type === TokenType.Symbol - && this.keywords.find((k) => k === node.Value) === undefined - ) { - if (symbolCount === 1 && argument.Name === undefined) { - argument.Name = node.Value; - continue; - } else if (symbolCount > 1) { - throw new Error("Too many non keyword symbols."); - } - } - - argument.Type.nodes.push(node); - } - - this.StripNonTypeNodes(argument.Type); - return argument; - } - - private GetArgument(tree: ParseTree): Argument { - // Copy tree structure leave original untouched. - const copy = this.RemoveUnusedTokens(tree); - - // Special case with only ellipsis. C style variadic arguments - if (copy.nodes.length === 1) { - const node = copy.nodes[0]; - if (node instanceof Token && node.Type === TokenType.Ellipsis) { - const argument: Argument = new Argument(); - argument.Name = node.Value; - return argument; - } - } - - // Check if it is has a trailing return. - const startTrailingReturn: number = copy.nodes - .findIndex((t) => t instanceof Token ? t.Type === TokenType.Arrow : false); - - // Special case trailing return. - if (startTrailingReturn !== -1) { - return this.GetArgumentFromTrailingReturn(copy, startTrailingReturn); - } - - // Handle function pointers - if (this.IsFuncPtr(copy.nodes) === true) { - return this.GetArgumentFromFuncPtr(copy); - } - - return this.GetDefaultArgument(copy); - } - - private GetSubExprStartEnd(expression: string, startSearch: number, openExpr: string, closeExpr: string): number[] { - let openExprOffset: number = -1; - let nestedCount: number = 0; - for (let i: number = startSearch; i < expression.length; i++) { - if (expression[i] === openExpr && openExprOffset === -1) { - openExprOffset = i; - } - - if (expression[i] === openExpr) { - nestedCount++; - } else if (expression[i] === closeExpr && nestedCount > 0) { - nestedCount--; - } - - if (expression[i] === closeExpr && nestedCount === 0 && openExprOffset !== -1) { - return [openExprOffset, i + 1]; - } - } - - return [0, 0]; - } - - private GetTemplate(expression: string): string { - if (expression.startsWith("template") === false) { - return ""; - } - - let startTemplateOffset: number = -1; - for (let i: number = "template".length; i < expression.length; i++) { - if (expression[i] === "<") { - startTemplateOffset = i; - break; - } else if (expression[i] !== " ") { - return ""; - } - } - - if (startTemplateOffset === -1) { - return ""; - } - - const [start, end] = this.GetSubExprStartEnd(expression, startTemplateOffset, "<", ">"); - return expression.slice(0, end); - } - - private GetArgsFromTemplate(template: string): string[] { - const args: string[] = []; - if (template === "") { - return args; - } - - // Remove <> and add a comma to the end to remove edge case. - template = template.slice(template.indexOf("<") + 1, template.lastIndexOf(">")).replace(/^\s+|\s+$/g, "") + ","; - - const nestedCounts: { [key: string]: number; } = { - "(": 0, - "<": 0, - "{": 0, - }; - - let lastSeparator: number = 0; - for (let i: number = 0; i < template.length; i++) { - const notInSubExpr: boolean = nestedCounts["<"] === 0 - && nestedCounts["("] === 0 - && nestedCounts["{"] === 0; - - if (notInSubExpr === true && template[i] === ",") { - args.push(template.slice(lastSeparator + 1, i).replace(/^\s+|\s+$/g, "")); - } else if (notInSubExpr === true && (template[i] === " " || template[i] === ".")) { - lastSeparator = i; - } - - if (template[i] === "(") { - nestedCounts["("]++; - } else if (template[i] === ")" && nestedCounts["("] > 0) { - nestedCounts["("]--; - } else if (template[i] === "<") { - nestedCounts["<"]++; - } else if (template[i] === ">" && nestedCounts["<"] > 0) { - nestedCounts["<"]--; - } else if (template[i] === "{") { - nestedCounts["{"]++; - } else if (template[i] === "}" && nestedCounts["{"] > 0) { - nestedCounts["{"]--; - } - } - - return args; - } -} diff --git a/src/CodeParser/CParser/CppParser.ts b/src/CodeParser/CParser/CppParser.ts deleted file mode 100644 index b3279c6..0000000 --- a/src/CodeParser/CParser/CppParser.ts +++ /dev/null @@ -1,16 +0,0 @@ -import { Position, TextDocumentContentChangeEvent, TextEditor, TextLine } from "vscode"; -import Generator from "../../DocGen/CGen"; -import { IDocGen } from "../../DocGen/DocGen"; -import CParser from "./CParser"; - -/** - * - * Parses C++ code for methods and signatures - * - * @export - * @class CppParser - * @implements {ICodeParser} - */ -export default class CppParser extends CParser { - // For now C++ is the same as C -} diff --git a/src/CodeParser/CParser/ParseTree.ts b/src/CodeParser/CParser/ParseTree.ts deleted file mode 100644 index bec5b91..0000000 --- a/src/CodeParser/CParser/ParseTree.ts +++ /dev/null @@ -1,121 +0,0 @@ -import { Token, TokenType } from "./Token"; - -export class ParseTree { - - /** - * Create a tree from tokens. This consumes the tokens. - * @param tokens The tokens to create a tree for. - * @param inNested If currently allready nesting. - */ - public static CreateTree(tokens: Token[], inNested: boolean = false): ParseTree { - const tree: ParseTree = new ParseTree(); - - while (tokens.length > 0) { - const token: Token = tokens.shift(); - switch (token.Type) { - case TokenType.OpenParenthesis: - tree.nodes.push(this.CreateTree(tokens, true)); - break; - case TokenType.CloseParenthesis: - if (inNested === false) { - throw new Error("Unmatched closing parenthesis."); - } - return tree; - default: - tree.nodes.push(token); - break; - } - } - - if (inNested === true) { - throw new Error("No match found for an opening parenthesis."); - } - - return tree; - } - - public nodes: Array = []; - - /** - * Compact empty branches. Example ((foo))(((bar))) will become (foo)(bar) - * @param tree The ParseTree to compact. Defaults to the current tree. - */ - public Compact(tree: ParseTree = this): ParseTree { - const newTree: ParseTree = new ParseTree(); - newTree.nodes = tree.nodes.map((n) => n); - const isNotCompact = (n) => n instanceof ParseTree && n.nodes.length === 1 && n.nodes[0] instanceof ParseTree; - - // Compact current level of nodes to the maximum amount. - while (newTree.nodes.some((n) => isNotCompact(n))) { - newTree.nodes = newTree.nodes - .map((n) => n instanceof ParseTree && isNotCompact(n) ? n.nodes[0] : n); - } - - // Compact all nested parsetrees. - newTree.nodes = newTree.nodes - .map((n) => n instanceof ParseTree ? this.Compact(n) : n); - - return newTree; - } - - /** - * Copy parsetree. - * @param tree The ParseTree to compact. Defaults to the current tree. - */ - public Copy(tree: ParseTree = this): ParseTree { - const newTree: ParseTree = new ParseTree(); - newTree.nodes = tree.nodes - .map((n) => n instanceof Token ? n : this.Copy(n)); - return newTree; - } - - /** - * Create string from the parsetree which is a representation of the original code. - * @param tree The ParseTree to compact. Defaults to the current tree. - */ - public Yield(tree: ParseTree = this): string { - let code: string = ""; - - for (const node of tree.nodes) { - if (node instanceof ParseTree) { - code += "(" + this.Yield(node) + ")"; - continue; - } - - switch (node.Type) { - case TokenType.Symbol: - code += code === "" ? node.Value : " " + node.Value; - break; - case TokenType.Pointer: - code += node.Value; - break; - case TokenType.Reference: - code += node.Value; - break; - case TokenType.ArraySubscript: - code += node.Value; - break; - case TokenType.CurlyBlock: - code += node.Value; - break; - case TokenType.Assignment: - code += " " + node.Value; - break; - case TokenType.Comma: - code += node.Value; - break; - case TokenType.Arrow: - code += " " + node.Value; - break; - case TokenType.Ellipsis: - code += node.Value; - break; - case TokenType.Attribute: - code += code === "" ? node.Value : " " + node.Value; - break; - } - } - - return code; - } -} diff --git a/src/CodeParser/CParser/Token.ts b/src/CodeParser/CParser/Token.ts deleted file mode 100644 index 0cbd412..0000000 --- a/src/CodeParser/CParser/Token.ts +++ /dev/null @@ -1,27 +0,0 @@ -export enum TokenType { - Symbol, - Pointer, - Reference, - ArraySubscript, - OpenParenthesis, - CloseParenthesis, - CurlyBlock, - Assignment, - Comma, - Arrow, - CommentBlock, - CommentLine, - Ellipsis, - Attribute, - Specifier, -} - -export class Token { - public Type: TokenType; - public Value: string; - - constructor(type: TokenType, value: string) { - this.Type = type; - this.Value = value; - } -} diff --git a/src/CodeParser/CodeParser.ts b/src/CodeParser/CodeParser.ts deleted file mode 100644 index cc2c709..0000000 --- a/src/CodeParser/CodeParser.ts +++ /dev/null @@ -1,9 +0,0 @@ -import { Position, TextDocumentContentChangeEvent, TextEditor } from "vscode"; - -export default interface ICodeParser { - - /** - * @param {TextEditor} activeEditor The open active Editor where the event came from - */ - Parse(activeEditor: TextEditor); -} diff --git a/src/CodeParser/CodeParserController.ts b/src/CodeParser/CodeParserController.ts deleted file mode 100644 index 7eae9c0..0000000 --- a/src/CodeParser/CodeParserController.ts +++ /dev/null @@ -1,119 +0,0 @@ -import { - Disposable, - Position, - Range, - TextDocumentContentChangeEvent, - TextEditor, - TextLine, - window, - workspace, -} from "vscode"; -import { Config, ConfigType } from "../Config"; -import CodeParser from "./CodeParser"; -import CParser from "./CParser/CParser"; -import CppParser from "./CParser/CppParser"; - -/** - * - * Checks if the event matches the specified guidelines and if a parser exists for this language - * - * @export - * @class CodeParserController - */ -export default class CodeParserController { - private disposable: Disposable; - private triggerSequence: string; - - /** - * Creates an instance of CodeParserController - * - * @memberOf CodeParserController - */ - public constructor() { - const subscriptions: Disposable[] = []; - - // Hand off the event to the parser if a valid parser is found - workspace.onDidChangeTextDocument((event) => { - const activeEditor: TextEditor = window.activeTextEditor; - if (activeEditor && event.document === activeEditor.document) { - this.readConfig(); - - this.onEvent(activeEditor, event.contentChanges[0]); - } - }, this, subscriptions); - - this.disposable = Disposable.from(...subscriptions); - } - - /** - * - * Disposes of the subscriptions - * - * @memberOf CodeParserController - */ - public dispose() { - this.disposable.dispose(); - } - - /*************************************************************************** - Implementation - ***************************************************************************/ - - private readConfig() { - this.triggerSequence = workspace - .getConfiguration(ConfigType.generic) - .get(Config.triggerSequence, "/**"); - } - - private check(activeEditor: TextEditor, event: TextDocumentContentChangeEvent): boolean { - if (activeEditor == null || event.text == null) { - return false; - } - const activeSelection: Position = activeEditor.selection.active; - const activeLine: TextLine = activeEditor.document.lineAt(activeSelection.line); - const activeChar: string = activeLine.text.charAt(activeSelection.character); - const startsWith: boolean = event.text.startsWith("\n") || event.text.startsWith("\r\n"); - - // Check if enter was pressed. Note the ! - if (!((activeChar === "") && startsWith)) { - return false; - } - - const cont: string = activeLine.text.trim(); - - return this.triggerSequence === cont; - } - - private onEvent(activeEditor: TextEditor, event: TextDocumentContentChangeEvent) { - if (!this.check(activeEditor, event)) { - return null; - } - - const lang: string = activeEditor.document.languageId; - let parser: CodeParser; - - switch (lang) { - case "c": - parser = new CParser(); - break; - case "cpp": - parser = new CppParser(); - break; - default: - // tslint:disable-next-line:no-console - console.log("No comments can be generated for language: " + lang); - return null; - } - - const currentPos: Position = window.activeTextEditor.selection.active; - const startReplace: Position = new Position( - currentPos.line, - currentPos.character - this.triggerSequence.length, - ); - - const nextLineText: string = window.activeTextEditor.document.lineAt(startReplace.line + 1).text; - const endReplace = new Position(currentPos.line + 1, nextLineText.length); - - parser.Parse(activeEditor).GenerateDoc(new Range(startReplace, endReplace)); - } -} diff --git a/src/CodeParserController.ts b/src/CodeParserController.ts new file mode 100644 index 0000000..32d1d75 --- /dev/null +++ b/src/CodeParserController.ts @@ -0,0 +1,108 @@ +import { + Disposable, + Position, + Range, + TextDocumentContentChangeEvent, + TextEditor, + TextLine, + window, + workspace, +} from "vscode"; +import CodeParser from "./Common/ICodeParser"; +import { Config } from "./Config"; +import CParser from "./Lang/C/CParser"; +/** + * + * Checks if the event matches the specified guidelines and if a parser exists for this language + * + * @export + * @class CodeParserController + */ +export default class CodeParserController { + private disposable: Disposable; + private cfg: Config; + + /** + * Creates an instance of CodeParserController + * + * @memberOf CodeParserController + */ + public constructor() { + const subscriptions: Disposable[] = []; + + // Hand off the event to the parser if a valid parser is found + workspace.onDidChangeTextDocument((event) => { + const activeEditor: TextEditor = window.activeTextEditor; + if (activeEditor && event.document === activeEditor.document) { + this.cfg = Config.ImportFromSettings(); + this.onEvent(activeEditor, event.contentChanges[0]); + } + }, this, subscriptions); + + this.disposable = Disposable.from(...subscriptions); + } + + /** + * + * Disposes of the subscriptions + * + * @memberOf CodeParserController + */ + public dispose() { + this.disposable.dispose(); + } + + /*************************************************************************** + Implementation + ***************************************************************************/ + + private check(activeEditor: TextEditor, event: TextDocumentContentChangeEvent): boolean { + if (activeEditor == null || event.text == null) { + return false; + } + const activeSelection: Position = activeEditor.selection.active; + const activeLine: TextLine = activeEditor.document.lineAt(activeSelection.line); + const activeChar: string = activeLine.text.charAt(activeSelection.character); + const startsWith: boolean = event.text.startsWith("\n") || event.text.startsWith("\r\n"); + + // Check if enter was pressed. Note the ! + if (!((activeChar === "") && startsWith)) { + return false; + } + + const cont: string = activeLine.text.trim(); + + return this.cfg.triggerSequence === cont; + } + + private onEvent(activeEditor: TextEditor, event: TextDocumentContentChangeEvent) { + if (!this.check(activeEditor, event)) { + return null; + } + + const lang: string = activeEditor.document.languageId; + let parser: CodeParser; + + switch (lang) { + case "c": + case "cpp": + parser = new CParser(this.cfg); + break; + default: + // tslint:disable-next-line:no-console + console.log("No comments can be generated for language: " + lang); + return null; + } + + const currentPos: Position = window.activeTextEditor.selection.active; + const startReplace: Position = new Position( + currentPos.line, + currentPos.character - this.cfg.triggerSequence.length, + ); + + const nextLineText: string = window.activeTextEditor.document.lineAt(startReplace.line + 1).text; + const endReplace = new Position(currentPos.line + 1, nextLineText.length); + + parser.Parse(activeEditor).GenerateDoc(new Range(startReplace, endReplace)); + } +} diff --git a/src/Common/ICodeParser.ts b/src/Common/ICodeParser.ts new file mode 100644 index 0000000..afe2967 --- /dev/null +++ b/src/Common/ICodeParser.ts @@ -0,0 +1,9 @@ +import { TextEditor } from "vscode"; +import { IDocGen } from "./IDocGen"; + +export default interface ICodeParser { + /** + * @param {TextEditor} activeEditor The open active Editor where the event came from + */ + Parse(activeEditor: TextEditor): IDocGen; +} diff --git a/src/Common/IDocGen.ts b/src/Common/IDocGen.ts new file mode 100644 index 0000000..1b5b1e1 --- /dev/null +++ b/src/Common/IDocGen.ts @@ -0,0 +1,9 @@ +import { Range } from "vscode"; + +export interface IDocGen { + /** + * @brief Generate documentation string and write it to the active editor + * @param {Range} rangeToReplace Range to replace with the generated comment. + */ + GenerateDoc(rangeToReplace: Range); +} diff --git a/src/Config.ts b/src/Config.ts index 3cc78fb..6297a66 100644 --- a/src/Config.ts +++ b/src/Config.ts @@ -1,18 +1,43 @@ -export enum ConfigType { - generic = "doxdocgen.generic", -} +import { workspace } from "vscode"; + +export class Config { + public static ImportFromSettings(): Config { + const values: Config = new Config(); + + const cfg = workspace.getConfiguration("doxdocgen.generic"); + + values.firstLine = cfg.get("firstLine", values.firstLine); + values.commentPrefix = cfg.get("commentPrefix", values.commentPrefix); + values.lastLine = cfg.get("lastLine", values.lastLine); + values.newLineAfterBrief = cfg.get("newLineAfterBrief", values.newLineAfterBrief); + values.newLineAfterParams = cfg.get("newLineAfterParams", values.newLineAfterParams); + values.newLineAfterTParams = cfg.get("newLineAfterTParams", values.newLineAfterTParams); + values.includeTypeAtReturn = cfg.get("includeTypeAtReturn", values.includeTypeAtReturn); + values.boolReturnsTrueFalse = cfg.get("boolReturnsTrueFalse", values.boolReturnsTrueFalse); + values.boolPointerReturnsNull = cfg.get("boolPointerReturnsNull", values.boolPointerReturnsNull); + values.briefTemplate = cfg.get("briefTemplate", values.briefTemplate); + values.paramTemplate = cfg.get("paramTemplate", values.paramTemplate); + values.tparamTemplate = cfg.get("tparamTemplate", values.tparamTemplate); + values.returnTemplate = cfg.get("returnTemplate", values.returnTemplate); + + return values; + } + + public readonly paramTemplateReplace: string = "{param}"; + public readonly typeTemplateReplace: string = "{type}"; -export enum Config { - triggerSequence = "triggerSequence", - firstLine = "firstLine", - commentPrefix = "commentPrefix", - lastLine = "lastLine", - newLineAfterBrief = "newLineAfterBrief", - newLineAfterParams = "newLineAfterParams", - newLineAfterTParams = "newLineAfterTParams", - includeTypeAtReturn = "includeTypeAtReturn", - briefTemplate = "briefTemplate", - paramTemplate = "paramTemplate", - tparamTemplate = "tparamTemplate", - returnTemplate = "returnTemplate", + public triggerSequence: string = "/**"; + public firstLine: string = "/**"; + public commentPrefix: string = " * "; + public lastLine: string = " */"; + public newLineAfterBrief: boolean = true; + public newLineAfterParams: boolean = false; + public newLineAfterTParams: boolean = false; + public includeTypeAtReturn: boolean = true; + public boolReturnsTrueFalse: boolean = true; + public boolPointerReturnsNull: boolean = true; + public briefTemplate: string = "@brief "; + public paramTemplate: string = "@param {param} "; + public tparamTemplate: string = "@tparam {param} "; + public returnTemplate: string = "@return {type} "; } diff --git a/src/DocGen/CGen.ts b/src/DocGen/CGen.ts deleted file mode 100644 index 13ecbf1..0000000 --- a/src/DocGen/CGen.ts +++ /dev/null @@ -1,185 +0,0 @@ -import { Position, Range, Selection, TextEditor, TextLine, workspace, WorkspaceEdit } from "vscode"; -import { Config, ConfigType } from "../Config"; -import { IDocGen } from "./DocGen"; - -export default class CGen implements IDocGen { - protected firstLine: string; - protected commentPrefix: string; - protected lastLine: string; - protected newLineAfterBrief: boolean; - protected newLineAfterParams: boolean; - protected newLineAfterTParams: boolean; - protected includeTypeAtReturn: boolean; - protected briefTemplate: string; - protected paramTemplate: string; - protected tparamTemplate: string; - protected returnTemplate: string; - - protected templateParamReplace: string; - protected templateTypeReplace: string; - - protected activeEditor: TextEditor; - - protected retVals: string[]; - protected params: string[]; - protected tparams: string[]; - - /** - * @param {TextEditor} actEdit Active editor window - * @param {Position} cursorPosition Where the cursor of the user currently is - * @param {string[]} params The parameter names of the method extracted by the parser - * @param {string[]} tparam The template parameter names of the method extracted by the parser. - * @param {string[]} returnVals The return values extracted by the parser - */ - public constructor( - actEdit: TextEditor, - cursorPosition: Position, - params: string[], - tparam: string[], - returnVals: string[], - ) { - this.activeEditor = actEdit; - this.templateParamReplace = "{param}"; - this.templateTypeReplace = "{type}"; - this.params = params; - this.tparams = tparam; - this.retVals = returnVals; - } - - /** - * @inheritdoc - */ - public GenerateDoc(rangeToReplace: Range) { - this.readConfig(); - const comment: string = this.generateComment(); - - this.activeEditor.edit((editBuilder) => { - editBuilder.replace(rangeToReplace, comment); // Insert the comment - }); - - // Set cursor to first DoxyGen command. - this.moveCursurToFirstDoxyCommand(comment, rangeToReplace.start.line, rangeToReplace.start.character); - } - - /*************************************************************************** - Implementation - ***************************************************************************/ - - protected readConfig() { - const getCfg = workspace.getConfiguration; - - this.firstLine = getCfg(ConfigType.generic).get(Config.firstLine, "/**"); - this.commentPrefix = getCfg(ConfigType.generic).get(Config.commentPrefix, " * "); - this.lastLine = getCfg(ConfigType.generic).get(Config.lastLine, " */"); - this.newLineAfterBrief = getCfg(ConfigType.generic).get(Config.newLineAfterBrief, true); - this.newLineAfterParams = getCfg(ConfigType.generic).get(Config.newLineAfterParams, false); - this.newLineAfterTParams = getCfg(ConfigType.generic).get(Config.newLineAfterTParams, false); - this.includeTypeAtReturn = getCfg(ConfigType.generic).get(Config.includeTypeAtReturn, false); - this.briefTemplate = getCfg(ConfigType.generic).get(Config.briefTemplate, "@brief "); - this.paramTemplate = getCfg(ConfigType.generic).get(Config.paramTemplate, "@param {param} "); - this.tparamTemplate = getCfg(ConfigType.generic).get(Config.tparamTemplate, "@tparam {param} "); - this.returnTemplate = getCfg(ConfigType.generic).get(Config.returnTemplate, "@return {type} "); - } - - protected getIndentation(): string { - const line: TextLine = this.activeEditor.document.lineAt(this.activeEditor.selection.start.line); - const lineTxt: string = line.text; - let stringToIndent: string = ""; - // Find indentation from previous line - for (let i = 0; i < line.firstNonWhitespaceCharacterIndex; i++) { - if (lineTxt.charAt(i) === "\t") { - stringToIndent = stringToIndent + "\t"; - } else if (lineTxt.charAt(i) === " ") { - stringToIndent = stringToIndent + " "; - } - } - return stringToIndent; - } - - protected getTemplatedString(replace: string, template: string, param: string): string { - return template.replace(replace, param); - } - - protected generateBrief(lines: string[]) { - lines.push(this.commentPrefix + this.briefTemplate); - } - - protected generateFromTemplate(lines: string[], replace: string, template: string, templateWith: string[]) { - let line: string = ""; - - templateWith.forEach((element: string) => { - // Ignore null values - if (element !== null) { - line = this.commentPrefix; - line += this.getTemplatedString(replace, template, element); - lines.push(line); - } - }); - } - - protected generateComment(): string { - const lines: string[] = []; - - if (this.firstLine.trim().length !== 0) { - lines.push(this.firstLine); - } - - if (this.briefTemplate.trim().length !== 0) { - this.generateBrief(lines); - if (this.newLineAfterBrief === true) { - lines.push(this.commentPrefix); - } - } - - if (this.tparamTemplate.trim().length !== 0 && this.tparams.length > 0) { - this.generateFromTemplate(lines, this.templateParamReplace, this.tparamTemplate, this.tparams); - if (this.newLineAfterTParams === true) { - lines.push(this.commentPrefix); - } - } - - if (this.paramTemplate.trim().length !== 0 && this.params.length > 0) { - this.generateFromTemplate(lines, this.templateParamReplace, this.paramTemplate, this.params); - if (this.newLineAfterParams === true) { - lines.push(this.commentPrefix); - } - } - - if (this.returnTemplate.trim().length !== 0 && this.retVals.length > 0) { - if (this.includeTypeAtReturn === false) { - this.retVals = this.retVals.map((t) => t === "true" || t === "false" || t === "null" ? t : ""); - } - - this.generateFromTemplate(lines, this.templateTypeReplace, this.returnTemplate, this.retVals); - } - - if (this.lastLine.trim().length !== 0) { - lines.push(this.lastLine); - } - - const comment: string = lines.join("\n" + this.getIndentation()); - return comment; - } - - protected moveCursurToFirstDoxyCommand(comment: string, baseLine: number, baseCharacter) { - // Find first offset of a new line in the comment. Since that's when the line where the first param starts. - let line: number = baseLine; - let character: number = comment.indexOf("\n"); - - // If a first line is included find the 2nd line with a newline. - if (this.firstLine.trim().length !== 0) { - line++; - const oldCharacter: number = character; - character = comment.indexOf("\n", oldCharacter + 1) - oldCharacter; - } - - // If newline is not found means no first param was found so Set to base line before the newline. - if (character < 0) { - line = baseLine; - character = baseCharacter; - } - - const moveTo: Position = new Position(line, character); - this.activeEditor.selection = new Selection(moveTo, moveTo); - } -} diff --git a/src/DocGen/CppGen.ts b/src/DocGen/CppGen.ts deleted file mode 100644 index c13d194..0000000 --- a/src/DocGen/CppGen.ts +++ /dev/null @@ -1,6 +0,0 @@ -import { Position, Range, Selection, TextEditor, TextLine, WorkspaceEdit } from "vscode"; -import CGen from "./CGen"; - -export default class CppGen extends CGen { - // For now C++ is the same as C -} diff --git a/src/DocGen/DocGen.ts b/src/DocGen/DocGen.ts deleted file mode 100644 index 1b5b1e1..0000000 --- a/src/DocGen/DocGen.ts +++ /dev/null @@ -1,9 +0,0 @@ -import { Range } from "vscode"; - -export interface IDocGen { - /** - * @brief Generate documentation string and write it to the active editor - * @param {Range} rangeToReplace Range to replace with the generated comment. - */ - GenerateDoc(rangeToReplace: Range); -} diff --git a/src/Lang/C/CArgument.ts b/src/Lang/C/CArgument.ts new file mode 100644 index 0000000..46f180c --- /dev/null +++ b/src/Lang/C/CArgument.ts @@ -0,0 +1,6 @@ +import { CParseTree } from "./CParseTree"; + +export class CArgument { + public name: string = null; + public type: CParseTree = new CParseTree(); +} diff --git a/src/Lang/C/CDocGen.ts b/src/Lang/C/CDocGen.ts new file mode 100644 index 0000000..87d59fb --- /dev/null +++ b/src/Lang/C/CDocGen.ts @@ -0,0 +1,183 @@ +import { Position, Range, Selection, TextEditor, TextLine, WorkspaceEdit } from "vscode"; +import { IDocGen } from "../../Common/IDocGen"; +import { Config } from "../../Config"; +import { CArgument } from "./CArgument"; +import { CParseTree } from "./CParseTree"; +import { CToken, CTokenType } from "./CToken"; + +export default class CDocGen implements IDocGen { + protected activeEditor: TextEditor; + + protected readonly cfg: Config; + + protected func: CArgument; + protected templateParams: string[]; + protected params: CArgument[]; + + /** + * @param {TextEditor} actEdit Active editor window + * @param {Position} cursorPosition Where the cursor of the user currently is + * @param {string[]} templateParams The template parameters of the declaration. + * @param {CArgument} func The type and name of the function to generate doxygen. + * Doesn't contain anything if it is not a function. + * @param {CArgument[]} params The parameters of the function. Doesn't contain anything if it is not a function. + */ + public constructor( + actEdit: TextEditor, + cursorPosition: Position, + cfg: Config, + templateParams: string[], + func: CArgument, + params: CArgument[], + ) { + this.activeEditor = actEdit; + this.cfg = cfg; + this.func = func; + this.templateParams = templateParams; + this.params = params; + } + + /** + * @inheritdoc + */ + public GenerateDoc(rangeToReplace: Range) { + const comment: string = this.generateComment(); + + this.activeEditor.edit((editBuilder) => { + editBuilder.replace(rangeToReplace, comment); // Insert the comment + }); + + // Set cursor to first DoxyGen command. + this.moveCursurToFirstDoxyCommand(comment, rangeToReplace.start.line, rangeToReplace.start.character); + } + + /*************************************************************************** + Implementation + ***************************************************************************/ + protected getIndentation(): string { + const line: TextLine = this.activeEditor.document.lineAt(this.activeEditor.selection.start.line); + return line.text.slice(0, line.firstNonWhitespaceCharacterIndex); + } + + protected getTemplatedString(replace: string, template: string, param: string): string { + return template.replace(replace, param); + } + + protected generateBrief(lines: string[]) { + lines.push(this.cfg.commentPrefix + this.cfg.briefTemplate); + } + + protected generateFromTemplate(lines: string[], replace: string, template: string, templateWith: string[]) { + let line: string = ""; + + templateWith.forEach((element: string) => { + // Ignore null values + if (element !== null && element !== undefined && element !== "") { + line = this.cfg.commentPrefix; + line += this.getTemplatedString(replace, template, element); + lines.push(line); + } + }); + } + + protected generateReturnParams(): string[] { + const params: string[] = []; + + // Check if return type is a pointer + const ptrReturnIndex = this.func.type.nodes + .findIndex((n) => n instanceof CToken && n.type === CTokenType.Pointer); + + // Special case for void functions. + const voidReturnIndex = this.func.type.nodes + .findIndex((n) => n instanceof CToken && n.type === CTokenType.Symbol && n.value === "void"); + + // Special case for bool return type. + const boolReturnIndex: number = this.func.type.nodes + .findIndex((n) => n instanceof CToken && n.type === CTokenType.Symbol && n.value === "bool"); + + if (boolReturnIndex !== -1) { + if (this.cfg.boolReturnsTrueFalse === true) { + params.push("true"); + params.push("false"); + } + if (ptrReturnIndex !== -1 && this.cfg.boolPointerReturnsNull === true) { + params.push("null"); + } + } else if (voidReturnIndex !== -1 && ptrReturnIndex !== -1) { + params.push(this.cfg.includeTypeAtReturn === true ? this.func.type.Yield() : ""); + } else if (voidReturnIndex === -1 && this.func.type.nodes.length > 0) { + params.push(this.cfg.includeTypeAtReturn === true ? this.func.type.Yield() : ""); + } + + return params; + } + + protected generateComment(): string { + const lines: string[] = []; + + if (this.cfg.firstLine.trim().length !== 0) { + lines.push(this.cfg.firstLine); + } + + if (this.cfg.briefTemplate.trim().length !== 0) { + this.generateBrief(lines); + if (this.cfg.newLineAfterBrief === true) { + lines.push(this.cfg.commentPrefix); + } + } + + if (this.cfg.tparamTemplate.trim().length !== 0 && this.templateParams.length > 0) { + this.generateFromTemplate( + lines, + this.cfg.paramTemplateReplace, + this.cfg.paramTemplate, + this.templateParams, + ); + if (this.cfg.newLineAfterTParams === true) { + lines.push(this.cfg.commentPrefix); + } + } + + if (this.cfg.paramTemplate.trim().length !== 0 && this.params.length > 0) { + const paramNames: string[] = this.params.map((p) => p.name); + this.generateFromTemplate(lines, this.cfg.paramTemplateReplace, this.cfg.paramTemplate, paramNames); + if (this.cfg.newLineAfterParams === true) { + lines.push(this.cfg.commentPrefix); + } + } + + if (this.cfg.returnTemplate.trim().length !== 0 && this.func.type !== null) { + const returnParams = this.generateReturnParams(); + this.generateFromTemplate(lines, this.cfg.typeTemplateReplace, this.cfg.returnTemplate, returnParams); + } + + if (this.cfg.lastLine.trim().length !== 0) { + lines.push(this.cfg.lastLine); + } + + const comment: string = lines.join("\n" + this.getIndentation()); + return comment; + } + + protected moveCursurToFirstDoxyCommand(comment: string, baseLine: number, baseCharacter) { + // Find first offset of a new line in the comment. Since that's when the line where the first param starts. + let line: number = baseLine; + let character: number = comment.indexOf("\n"); + + // If a first line is included find the 2nd line with a newline. + if (this.cfg.firstLine.trim().length !== 0) { + line++; + const oldCharacter: number = character; + character = comment.indexOf("\n", oldCharacter + 1) - oldCharacter; + } + + // If newline is not found means no first param was found so Set to base line before the newline. + if (character < 0) { + line = baseLine; + character = baseCharacter; + } + + const