rocambole-indent

Helpers to manipulate rocambole Indent tokens.

Used mainly by esformatter and its plugins.

API

var indent = require('rocambole-indent');

setOptions(opts)

setOptions used to set the indent value.

setOptions({
  // sets "value" used by `Indent` tokens (defaults to two spaces)
  value: '  ',
  // amount of indents added on `alignComments` if comment is inside an empty
  // block (surrounded by `{}`, `[]` or `()`) - defaults to `1`
  CommentInsideEmptyBlock: 1
});

inBetween(startToken, endToken, level)

Increase/Decrease the indent level in between the startToken and endToken.

It will not include the start and end tokens on the indentation range, only the tokens in between them.

// increase the indent level by 1
inBetween(node.startToken, node.endToken, 1);
// decrease the indent level by 1
inBetween(node.startToken, node.endToken, -1);
// zero does nothing
inBetween(node.endToken, 0);

Important: negative values only work if original Indent token contains a level property since there is no reliable way to infer this value (probably will only work if indent was added by this lib).

addLevel(token, level)

Increases/decreases the indent level at the beginning of the line that includes the given token.

// adds 2 indents
addLevel(node.startToken, 2);
// decrease indent level in 1 step
addLevel(node.endToken, -1);
// zero does nothing
addLevel(node.endToken, 0);

sanitize(astOrNode)

Removes any Indent tokens that don't have a level property (this is usually the original indentation of the program parsed by rocambole) or that are not at the beginning of the line. Also removing WhiteSpace tokens that are at the beginning of the line to avoid mistakes.

// sanitize a single node
sanitize(node);
// sanitize whole AST
sanitize(ast);

updateBlockComment(token)

Updates BlockComment raw value to make sure all the lines have the same Indent level.

This is called internally by the addLevel and indentInBetween methods (if first token of line is a BlockComment), so as long as you only use those methods to edit the indent level you shouldn't need to call this.

alignComments(astOrNode)

Align all the comments based on the next/previous lines inside a given ast or node.

It will align the comments with the next line unless the comment block is followed by an empty line, in that case it will use the previous non-empty line as a reference.

Example output:

// aligned with next line
switch (foo) {
  // aligned with next non-empty line

  case bar:
    // aligned with next line
    baz();
    // this should be aligned with previous line since comment block is
    // followed by an empty line

  // aligned with next line
  case biz:
    // aligned with next line
    what();
// aligned with next line
}

function noop() {
  // indented since it's inside an empty block
}

// aligned with previous line since it's at the end of program

whiteSpaceToIndent(token, [indentValue])

Convert WhiteSpace token into Indent if it's the first token of the line.

You can pass a custom indentValue or it will use the value set by setOptions() to calculate the indent level (basically count how many times this string repeats inside the token.value).

var token = {
  type: 'WhiteSpace',
  value: '\t\t\t',
  prev: { type: 'LineBreak', value: '\n' }
};
whiteSpaceToIndent(token, '\t');
// edits properties in place
console.log(token.type);  // > "Indent"
console.log(token.level); // > 3

This is useful in case you want to make sure sanitize won't remove the original indents.

Debug

This module uses debug internally. To make it easier to identify what is wrong we sometimes run the esformatter tests with a DEBUG flag, like:

DEBUG=rocambole:indent npm test