Rewrite the parser

.travis.yml

@@ -2,4 +2,4 @@ language: node_js
 node_js:
   - 8
 
-before_install: npm i -g gulp
+# before_install: npm i -g gulp

.vscode/launch.json

@@ -27,7 +27,7 @@
 			"type": "node",
 			"request": "launch",
 			"name": "Launch Program",
-			"program": "${workspaceFolder}/main.js"
+			"program": "${workspaceFolder}/build/index.js"
 		}
 	]
 }

.vscode/settings.json

@@ -1,12 +0,0 @@
-{
-  "files.exclude": {
-    "**/.git": true,
-    "**/.svn": true,
-    "**/.hg": true,
-    "**/.DS_Store": true,
-    "**/*.js.map": true,
-    "**/*.js": {
-      "when": "$(basename).ts"
-    }
-  }
-}

README.md

@@ -1,27 +1,97 @@
-# Parser
+# mr-doc-parser
 
 [![Build Status](https://travis-ci.org/mr-doc/mr-doc-parser.svg?branch=master)](https://travis-ci.org/mr-doc/mr-doc-parser)
 
-## Specification
+## Introduction
 
-A parser must implement the following interface:
+This is the official parser for Mr. Doc. The parser uses [node-tree-sitter](https://github.com/tree-sitter/node-tree-sitter) to parse different programming languages. It also uses [xdoc-parser](https://github.com/iwatakeshi/xdoc-parser) to parse JSDoc-like syntaxes in a comment. Note that `mr-doc-parser` is in alpha. Thus, the algorithms may change over time. At the moment, there are two languages that are supported by `mr-doc-parser`: JavaScript and TypeScript. More languages can be added as long as [tree-sitter](https://github.com/tree-sitter) can parse them.
+
+## Creating a Language Parser
+
+### Extend the Language Parser
+
+To create a parser, simply extend an abstract class named `Parser` in `src/lang/common/parser.ts`:
 
 ```typescript
-interface IParser {
-  parse: (file: IFile) => IParseResult
+abstract class Parser {
+  constructor(source: Source, options: any) {/* ... */}
+  abstract parse(): ASTNode[]
+  abstract get tree(): Tree
+}
+```
+
+**Note**: See the [JavaScript parser](./src/lang/javascript/index.ts) for an example.
+
+### Extend the Language Visitor
+
+The next step is to walk the tree that parsed by `tree-sitter` and to wrap each node as an `Node` type.
+Bear in mind that `tree-sitter` keeps its tree as a DOM-like structure.
+
+It may seem like an additional step to re-wrap the nodes, but it is a necessary step to make visiting each node a bit easier:
+
+```ts
+// Example for JavaScript
+import * as Parser from 'tree-sitter';
+import * as JavaScript from 'tree-sitter-javascript';
+import walk from 'path to [src/utils/walk]'
+
+// Create the parser
+const parser = new Parser();
+// Set the langauge
+parser.setLangauge(JavaScript);
+// Parse the source code
+const tree = parser.parse('...');
+// Walk the tree
+const nodes = walk(tree);
+
+```
+
+Once the tree is wrapped, we need to extend the abstract `Visitor` visitor:
+
+```ts
+abstract class Visitor {
+  abstract getAST(): ASTNode[]
+  abstract visitNode(node: SyntaxNode, properties?: object): ASTNode
+  abstract visitChildren(nodes: SyntaxNode[], properties?: object): ASTNode[]
 }
 ```
 
-The output should be in the following format:
+**Note**: See the [JavaScript visitor](./src/lang/javascript/visitor.ts) for an example.
+
+### Return the AST
+
+The last step is to return the AST. To do so, simply use the `createNode` function and return an array of `ASTNode` type:
 
 ```typescript
 
-interface IParseResult {
-  comments: IComment[],
+interface ASTNode extends TextRange {
+  /**
+   * @property - The type of node.
+   */
   type: string,
-  file: IFile
+  /**
+   * @property - The context string.
+   */
+  text: string,
+  /**
+   * @property - The node's children.
+   */
+  children: ASTNode[] | undefined[],
+  /**
+   * @property - The context node that a comment node refers to.
+   */
+  context: ASTNode,
+  /**
+   * @property - The properties that a ASTNode may possess.
+   */
+  properties?: object
+  /**
+   * @property - The parsed XDoc comment.
+   */
+  comment?: {
+    markdown: RemarkNode,
+    documentation: Partial<DocumentationNode>
+  }
 }
 
 ```
-
-These interfaces are defined in `parser/interface.ts`.

build/corpus/example.d.ts

@@ -0,0 +1,6 @@
+export declare namespace X {
+    /**
+     *
+     */
+    function name(...args: any[]): void;
+}

build/index.d.ts

@@ -0,0 +1,28 @@
+import Source from './src/interfaces/Source';
+import Parser from './src/lang/common/parser';
+import { Tree } from 'tree-sitter';
+/**
+ * A class that parses a source code and generates an AST.
+ *
+ * @class Parser
+ * @implements IParser
+ *
+ * # Example
+ *
+ * ```js
+ * const parser = new Parser({
+ *  name: '...',
+ *  path: '....',
+ *  text: '...'
+ * }, { language: 'typescript' });
+ *
+ * const result = parser.parse();
+ *
+ * ```
+ */
+export default class DocParser extends Parser {
+    private parser;
+    constructor(source: Source, options?: object);
+    parse: () => import("./src/interfaces/ASTNode").default[];
+    readonly tree: Tree;
+}

build/src/ParserFactory.d.ts

@@ -0,0 +1,8 @@
+import Source from "./interfaces/Source";
+import Parser from "./lang/common/parser";
+export default class ParserFactory {
+    private source;
+    private options;
+    constructor(file: Source, options?: any);
+    getParser: () => Parser;
+}

build/src/interfaces/ASTNode.d.ts

@@ -0,0 +1,32 @@
+import TextRange from "./TextRange";
+import { RemarkNode } from "xdoc-parser/src/XDocParser";
+import { DocumentationNode } from "xdoc-parser/src/XDocASTNode";
+export default interface ASTNode extends TextRange {
+    /**
+     * @property - The type of node.
+     */
+    type: string;
+    /**
+     * @property - The context string.
+     */
+    text: string;
+    /**
+     * @property - The node's children.
+     */
+    children: ASTNode[] | undefined[];
+    /**
+     * @property - The context node that a comment node refers to.
+     */
+    context: ASTNode;
+    /**
+     * @property - The properties that a ASTNode may possess.
+     */
+    properties?: object;
+    /**
+     * @property - The parsed XDoc comment.
+     */
+    comment?: {
+        markdown: RemarkNode;
+        documentation: Partial<DocumentationNode>;
+    };
+}

build/src/interfaces/Source.d.ts

@@ -0,0 +1,5 @@
+export default interface Source {
+    name: string;
+    path: string;
+    text: string;
+}

build/src/interfaces/TextRange.d.ts

@@ -0,0 +1,37 @@
+/**
+ * An interface that represents a range.
+ *
+ * @interface Range
+ */
+export interface Range {
+    start: number;
+    end: number;
+}
+/**
+ * An interface that represents the positional
+ * and locational ranges of a source code.
+ *
+ * @interface TextRange
+ */
+export default interface TextRange {
+    /**
+     * Represents a context's start and end position.
+     * @property position: {
+     *  start: number,
+     *  end: number
+     * }
+     */
+    position: Range;
+    /**
+     * Represents a context's row and column location.
+     *
+     * @location: {
+     *  row: Range,
+     *  column: Range
+     * }
+     */
+    location: {
+        row: Range;
+        column: Range;
+    };
+}

build/src/lang/common/ast.d.ts

@@ -0,0 +1,9 @@
+import { SyntaxNode } from "tree-sitter";
+import Source from "../../interfaces/Source";
+import ASTNode from "../../interfaces/ASTNode";
+export declare function isASTNode(object: object): object is ASTNode;
+export declare function createASTNode(source: Source, node: SyntaxNode): ASTNode;
+export declare function createASTNode(source: Source, node: SyntaxNode, properties: object): any;
+export declare function createASTNode(source: Source, node: SyntaxNode, children: object[]): ASTNode;
+export declare function createASTNode(source: Source, node: SyntaxNode, children: object[], properties: object): any;
+export declare function createASTNode(source: Source, node: SyntaxNode, context: ASTNode, document: boolean): ASTNode;