rocambole-indent

    2.0.4 • Public • Published

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

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

    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

    License

    Released under the MIT License

    Install

    npm i rocambole-indent

    DownloadsWeekly Downloads

    6,748

    Version

    2.0.4

    License

    MIT

    Last publish

    Collaborators

    • avatar