CompilerUtils

CompilerUtils

const { CompilerUtils } = require('biblo').Compilers;

CompilerUtils is a collection of misc utility functions used by the AST compilers. The AST compilers take the parsed AST to find the comments and attach them to their respective artifacts.

An "Artifact" is any given chunk of code, such as a "ClassDeclaration", a "FunctionDeclaration", etc... "Comment Artifacts" are also internally generated from the comments found in the source code.

function collectCommentsIntoArtifacts(artifacts: Array<Artifact>): Array<Artifact>

Collect all comments and assign them to their respective artifact. This will iterate all artifacts, find comments associated with each, and put the associated comments into each "artifact.comment" key inside the artifact.

This method will also sort the artifacts by source code position, and will also remove any duplicate artifacts.

Arguments:

• artifacts: Array<Artifact>

  A list of artifacts and comment artifacts to mutate.

Return value: Array<Artifact>

Return a new array of artifacts, where the comment artifacts have been removed, and inserted into their respective "artifact.comment".

function getGlobalComment(artifacts: Array<Artifact>): Artifact | undefined

Search all provided artifacts and find the first global comment. If no global comment is found, then return undefined.

Arguments:

• artifacts: Array<Artifact>

  A list of artifacts to search.

Return value: Artifact | undefined

Return the global comment artifact specified in the source file if one exists, undefined otherwise.

See also: isGlobalComment

function isGlobalComment(artifacts: Artifact): boolean

Check if the specified artifact is a global comment.

Global comments take the form:

///! This is a global comment.
///! There can only be one global comment per-file.
///! A global comment is designated by putting an
///! exclamation point after the triple forward
///! slashes. A global comment will appear at the
///! top of the page it specifies via the "DocScope"
///! property. All other comments in the same file
///! will also inherit any other properties defined
///! in a global comment automatically. For example,
///! all remaining comments in this file will also
///! inherit my "DocScope" property that I specify.
///!
///! DocScope: MyCustomPageName

Arguments:

• artifacts: Artifact

  An artifact to check.

Return value: boolean

Return true if the specified artifact is a global comment, or false otherwise.

See also: getGlobalComment

function parseDocComment(comment: string, artifact: Artifact): Array<Artifact>

Parse a document comment into its parts. This right here is a document comment. They are the comments in the code that begin with triple forward slash.

Example return "ParsedComment" object:

{
"description": {
"type": "Description",
"body": "Parse a document comment into its parts. This right here is a document comment..."
},
"arguments": [
{
"type":         "FunctionArgument",
"name":         "comment",
"description":  "The document comment to parse.",
"types":        [ "string" ]
},
...
],
"docScope": "CompilerUtils",
"return": {
"type":         "ReturnType",
"name":         "return",
"description":  "A parsed document comment object.",
"types":        [ "ParsedComment" ]
},
"properties": [
{
"type":         "PropertyDeclaration",
"name":         "ThePropertyOfAClass",
"description":  "Some description for this property.",
"types":        [ "boolean" ]
}
],
"see": [
{
"type":         "SeeAlso",
"name":         "CompilerUtils.parseDocComments",
}
],
"types": [ "string", "Array<number>" ],
...,
}

Arguments:

• comment: string

  The document comment to parse.

• artifact: Artifact

  The artifact that is related to this comment.

Return value: Array<Artifact>

A parsed document comment object.

See also: parseDocComments

function parseDocComments(artifacts: Array<Artifact>): Array<Artifact>

Iterate all artifacts, finding the comment artifacts. When a comment artifact is found parse it using parseDocComment. Parsed comments are injected into the related artifact under the "comment" key. After all comment artifacts have been parsed and stored on "comment" keys inside the artifacts, then this function returns an array of the original artifacts.

Arguments:

• artifacts: Array<Artifact>

  All artifacts to process.

Return value: Array<Artifact>

All artifacts, with their related comments parsed and stored inside them via the "comment" key.

Notes:

• This will mutate the incoming "artifacts" by adding a "comment" key to some.

See also: parseDocComment

function removeDuplicateArtifacts(artifacts: Array<Artifact>): Array<Artifact>

Remove duplicate artifacts from the list of artifacts.

An artifact is considered a duplicate if its "type", "start" position, and "end" position properties are the same.

Arguments:

• artifacts: Array<Artifact>

  A list of artifacts and comment artifacts to process.

Return value: Array<Artifact>

Return a new array of artifacts, where duplicate artifacts have been removed.

function sortArtifacts(artifacts: Array<Artifact>, startPositionKey?: string): Array<Artifact>

Sort all artifacts by source code position.

Arguments:

• artifacts: Array<Artifact>

  A list of artifacts and comment artifacts to sort.

• startPositionKey?: string (Default: 'start')

  An optional key to pull from each artifact to specify its start position in the code.

Return value: Array<Artifact>

Return a new array of artifacts, where the artifacts have been sorted based on their position in the source code.