rocambole-indent

Helpers to manipulate rocambole
Indent tokens.

Used mainly by esformatter and its plugins.

API

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

$3

setOptions used to set the indent value.

`js
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
});
`

$3

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.

`js
// 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).

$3

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

`js
// adds 2 indents
addLevel(node.startToken, 2);
// decrease indent level in 1 step
addLevel(node.endToken, -1);
// zero does nothing
addLevel(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).

$3

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.

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

$3

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.

$3

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:

`js
// 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
`

$3

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).

`js
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:

`sh
DEBUG=rocambole:indent npm test
``

License

Released under the MIT License