Home Reference Source 
import AFormatter from 'auto-format/src/core/formatter.js'
public class | source

AFormatter

Direct Subclass:

JavaFormatter

This is the core formatter. It contains most of the logic behind the formatting, and it is written in such a way that it is easily extendable to other programming languages. To create a formatter for a new programming language, extend this class and follow the JavaFormatter as an example.

Constructor Summary

Public Constructor
public

constructor(formatUnit: *)

Create a new AFormatter (abstract formatter).

Member Summary

Public Members
public
Private Members
private
private
private
private
private
private
private
private
private
private
private
private

Method Summary

Public Methods
public

format(code: *, expressionIdentifier: *, scopeEnterFunc: *, scopeExitFunc: *, formatCommentsFunc: *): Array

Format a string of code.
public

formatSnippet(code: *, startRow: *, endRow: *, offset: *, expressionIdentifier: *, scopeEnterFunc: *, scopeExitFunc: *, formatCommentsFunc: *, identifyMethodSigFunc: *, identifySpecialStatement: *, bodyCommentToken: *, simpleCommentToken: *): Array

A slight variation of format(codeString).
Private Methods
private

_fillBucketRange(array: *, start: *, end: *)

Adds indentations to the array from the start to the end index, inclusive.
private

_formatPrefix(scopeTree: *, array: *, oldStart: *): Array

Format the prefix of a snippet.
private

_formatSuffix(codeArray: *, oldEnd: *): Array

Format the suffix of a snippet.
private

_handleOpenComments(codeArray: *, startLine: *): Array

If an open comment is met, take all lines necessary to close it from the original file and append them to the snippet.
private

_preFormatArray(array: *, node: *)

Pre-formats an empty array by adding the indentations (the specified format unit).
private

_preFormatSnippet(snippet: *, selection: *): Array

Performs the following preliminary tasks:

  • Fills open comments
  • Removes extra method signatures (===> scope break so it will be removed later)
private

Remove method signatures in the prefix that do not belong to the selection.
private

Remove method signatures in the suffix that do not belong to the selection.
private

_splitSelection(codeArray: *, selection: *): Array

Splits the code array into three parts: prefix, selection, suffix.
private

_trimBeginning(codeArray: *): Array

Removes empty lines at beginning of snippet.
private

_trimEnd(codeArray: *): Array

Removes empty lines at end of snippet.

Public Constructors

public constructor(formatUnit: *) source

Create a new AFormatter (abstract formatter).

Params:

NameTypeAttributeDescription
formatUnit *

The token to be used for line indentations.

Public Members

public formatCommentFunc: * source

Private Members

private bodyCommentToken: string source

private endSelection: number source

private expressionIdentifier: * source

private formatUnit: * source

private fullCodeArray: string source

private identifyMethodSigFunc: * source

private identifySpecialStatement: * source

private scopeEnterFunc: * source

private scopeExitFunc: * source

private simpleCommentToken: string source

private snippetOffset: number source

private startSelection: number source

Public Methods

public format(code: *, expressionIdentifier: *, scopeEnterFunc: *, scopeExitFunc: *, formatCommentsFunc: *): Array source

Format a string of code. The string will be cut into lines and lines will be indented accordingly to their scope.

As a reference, look at the format function in the JavaFormatter.

Params:

NameTypeAttributeDescription
code *

String of code to format.
expressionIdentifier *

Function that identifies if a line qualifies as an expression:

  • A line that ends with a termination token (e.g. ';')
  • A line that defines a scope start (e.g. '{')
  • A line that defines a scope end (e.g. '}')
  • A line that starts with a special character (e.g. '@')
  • A line that starts with a comment (e.g. '//')
  • An empty line (e.g. '')
scopeEnterFunc *

Function that identifies if a new scope is entered in a line.
scopeExitFunc *

Function that identifies if a scope is exited in a line.
formatCommentsFunc *

Function that formats comments (e.g. add space before body and end comment in Javadoc)

Return:

Array

An array of formatted lines.

public formatSnippet(code: *, startRow: *, endRow: *, offset: *, expressionIdentifier: *, scopeEnterFunc: *, scopeExitFunc: *, formatCommentsFunc: *, identifyMethodSigFunc: *, identifySpecialStatement: *, bodyCommentToken: *, simpleCommentToken: *): Array source

A slight variation of format(codeString). Useful if you want to display a code snippet around a selection of lines.

As a reference, look at the formatSnippet function in the JavaFormatter.

In addition to indenting lines, formatSnippet takes a selection as a start and end row in a large slab of code and cuts out a snippet of code around this selection. The start and end of the snippet is based on an offset that is provided as a parameter. The offset with the start and end of the selection create a sort of range from which the snippet is taken.

In the example below, the selection is identified to belong to test2() and thus only test2() is returned. If the method is longer than the offset, than only the part within the offset will be returned. No code is added to the range with the exception of comment lines above the selection, to close unfinished comments.

Params:

NameTypeAttributeDescription
code *

The original code base in which the selection is.
startRow *

The start row of the selection in the code base.
endRow *

The end row of the selection in the code base.
offset *

The offset the defines the range on which to base the snippet.
expressionIdentifier *

Function that identifies if a line qualifies as an expression: An expression is defined as:

  • A line that ends with a termination token (e.g. ';')
  • A line that defines a scope start (e.g. '{')
  • A line that defines a scope end (e.g. '}')
  • A line that starts with a special character (e.g. '@')
  • A line that starts with a comment (e.g. '//')
  • An empty line (e.g. '')
scopeEnterFunc *

Function that identifies if a new scope is entered in a line.
scopeExitFunc *

Function that identifies if a scope is exited in a line.
formatCommentsFunc *

Function that formats comments (e.g. add space before body and end comment in Javadoc)
identifyMethodSigFunc *

Function that identifies if a line is a method signature.
identifySpecialStatement *

Function that identifies if a line contains a special statement (e.g. comment or '@' in Java)
bodyCommentToken *

The token for 'body comments' (e.g. '*' in Java)
simpleCommentToken *

Simple comment token (e.g. '//')

Return:

Array

An array of formatted lines that form the snippet, separated into prefix selection and suffix, as well as the start and end lines of the snippet in the original code base.

Example:

Selection start row: 11 ---- Selection end row: 11 ---- Offset: 6 ----> Snippet range: [11 - 6, 11 + 6] = [5, 17]

START:
1.  @Test
2.  public void test1() {
3.      System.out.println("Test 1");
4.  }
5.
6.  // ------------------
7.  // Perform test 2.
8.  // ------------------
9. @Test
10. public void test2() {
11.     System.out.println("Test 2");
12. }
13.
14. @Test
15. public void test3() {
16.     System.out.println("Test 3");
17. }
18. ...

RESULT:
6.  // ------------------
7.  // Perform test 2.
8.  // ------------------
9. @Test
10. public void test2() {
11.     System.out.println("Test 1");
12. }

Private Methods

private _fillBucketRange(array: *, start: *, end: *) source

Adds indentations to the array from the start to the end index, inclusive.

Params:

NameTypeAttributeDescription
array *

Array of lines of code.
start *

Start index of where to add indentations.
end *

End index of where to stop adding indentations.

private _formatPrefix(scopeTree: *, array: *, oldStart: *): Array source

Format the prefix of a snippet. The prefix is defines as all lines above the selection. Performs the following tasks:

  • Removes scopes that close but never open.
  • Removes empty lines at beginning of snippet.

Params:

NameTypeAttributeDescription
scopeTree *

The scope tree of the snippet.
array *

The formatted snippet as an array of lines.
oldStart *

The old start of the snippet in the original file (line number, starting with 1 not 0).

Return:

Array

Formatted prefix string with the new beginning of the snippet in the original file (again index starting with 1).

private _formatSuffix(codeArray: *, oldEnd: *): Array source

Format the suffix of a snippet. The suffix is defines as all lines below the selection. Performs the following tasks:

  • Removes methods and comments belonging to method below selection.
  • Removes empty lines at end of snippet.

Params:

NameTypeAttributeDescription
codeArray *

The formatted suffix as an array of lines.
oldEnd *

The old end of the snippet in the original file (line number, starting with 1 not 0).

Return:

Array

Formatted suffix string with the new end of the snippet in the original file (again index starting with 1).

private _handleOpenComments(codeArray: *, startLine: *): Array source

If an open comment is met, take all lines necessary to close it from the original file and append them to the snippet.

Params:

NameTypeAttributeDescription
codeArray *

Array of lines of code.
startLine *

The start line of the snippet in the original file.

Return:

Array

A snippet as an array of lines of code with no more open comments.

private _preFormatArray(array: *, node: *) source

Pre-formats an empty array by adding the indentations (the specified format unit).

Params:

NameTypeAttributeDescription
array *

Array of lines of code.
node *

Node of the scope tree.

private _preFormatSnippet(snippet: *, selection: *): Array source

Performs the following preliminary tasks:

  • Fills open comments
  • Removes extra method signatures (===> scope break so it will be removed later)

Params:

NameTypeAttributeDescription
snippet *

The snippet, as an array of lines, to work on.
selection *

The selection, as an array of lines, within the snippet.

Return:

Array

Array of pre-formatted lines.

private _removeExtraMethodSigAbove(codeArray: *): Array source

Remove method signatures in the prefix that do not belong to the selection.

Params:

NameTypeAttributeDescription
codeArray *

Array of lines of code (prefix).

Return:

Array

Prefix with no more extra method signatures.

private _removeExtraMethodSigBelow(codeArray: *): Array source

Remove method signatures in the suffix that do not belong to the selection.

Params:

NameTypeAttributeDescription
codeArray *

Array of lines of code (suffix).

Return:

Array

Suffix with no more extra method signatures.

private _splitSelection(codeArray: *, selection: *): Array source

Splits the code array into three parts: prefix, selection, suffix.

Prefix: All lines above the selection. Suffix: All lines below the selection.

Params:

NameTypeAttributeDescription
codeArray *

Array of lines of code.
selection *

Selection to split codeArray on.

Return:

Array

An array containing again the prefix, selection and suffix as arrays of lines of code.

private _trimBeginning(codeArray: *): Array source

Removes empty lines at beginning of snippet.

Params:

NameTypeAttributeDescription
codeArray *

Array of lines of code.

Return:

Array

Code array with no empty lines at beginning.

private _trimEnd(codeArray: *): Array source

Removes empty lines at end of snippet.

Params:

NameTypeAttributeDescription
codeArray *

Array of lines of code.

Return:

Array

Code array with no empty lines at end.