review.tizen.org Git - platform/framework/web/crosswalk-tizen.git/blob

   1 # rocambole-indent
   2
   3 Helpers to manipulate [rocambole](https://github.com/millermedeiros/rocambole)
   4 `Indent` tokens.
   5
   6 Used mainly by [esformatter](https://github.com/millermedeiros/esformatter/) and its plugins.
   7
   8
   9 ## API
  10
  11 ```js
  12 var indent = require('rocambole-indent');
  13 ```
  14
  15 ### setOptions(opts)
  16
  17 `setOptions` used to set the indent value.
  18
  19 ```js
  20 setOptions({
  21   // sets "value" used by `Indent` tokens (defaults to two spaces)
  22   value: '  ',
  23   // amount of indents added on `alignComments` if comment is inside an empty
  24   // block (surrounded by `{}`, `[]` or `()`) - defaults to `1`
  25   CommentInsideEmptyBlock: 1
  26 });
  27 ```
  28
  29 ### inBetween(startToken, endToken, level)
  30
  31 Increase/Decrease the indent level in between the `startToken` and `endToken`.
  32
  33 It will not include the start and end tokens on the indentation range, only the
  34 tokens in between them.
  35
  36 ```js
  37 // increase the indent level by 1
  38 inBetween(node.startToken, node.endToken, 1);
  39 // decrease the indent level by 1
  40 inBetween(node.startToken, node.endToken, -1);
  41 // zero does nothing
  42 inBetween(node.endToken, 0);
  43 ```
  44
  45 **Important:** negative values only work if original `Indent` token contains
  46 a `level` property since there is no reliable way to infer this value (probably
  47 will only work if indent was added by this lib).
  48
  49 ### addLevel(token, level)
  50
  51 Increases/decreases the indent level at the beginning of the line that includes
  52 the given `token`.
  53
  54 ```js
  55 // adds 2 indents
  56 addLevel(node.startToken, 2);
  57 // decrease indent level in 1 step
  58 addLevel(node.endToken, -1);
  59 // zero does nothing
  60 addLevel(node.endToken, 0);
  61 ```
  62
  63 **Important:** negative values only work if original `Indent` token contains
  64 a `level` property since there is no reliable way to infer this value (probably
  65 will only work if indent was added by this lib).
  66
  67 ### sanitize(astOrNode)
  68
  69 Removes any `Indent` tokens that don't have a `level` property (this is
  70 usually the original indentation of the program parsed by rocambole) or that
  71 are not at the beginning of the line. Also removing `WhiteSpace` tokens that
  72 are at the beginning of the line to avoid mistakes.
  73
  74 ```js
  75 // sanitize a single node
  76 sanitize(node);
  77 // sanitize whole AST
  78 sanitize(ast);
  79 ```
  80
  81 ### updateBlockComment(token)
  82
  83 Updates `BlockComment` `raw` value to make sure all the lines have the same
  84 `Indent` level.
  85
  86 This is called internally by the `addLevel` and `indentInBetween` methods (if
  87 first token of line is a `BlockComment`), so as long as you only use those
  88 methods to edit the indent level you shouldn't need to call this.
  89
  90 ### alignComments(astOrNode)
  91
  92 Align all the comments based on the next/previous lines inside a given `ast` or
  93 `node`.
  94
  95 It will align the comments with the next line unless the comment block is
  96 followed by an empty line, in that case it will use the previous non-empty line
  97 as a reference.
  98
  99 Example output:
 100
 101 ```js
 102 // aligned with next line
 103 switch (foo) {
 104   // aligned with next non-empty line
 105
 106   case bar:
 107     // aligned with next line
 108     baz();
 109     // this should be aligned with previous line since comment block is
 110     // followed by an empty line
 111
 112   // aligned with next line
 113   case biz:
 114     // aligned with next line
 115     what();
 116 // aligned with next line
 117 }
 118
 119 function noop() {
 120   // indented since it's inside an empty block
 121 }
 122
 123 // aligned with previous line since it's at the end of program
 124 ```
 125
 126 ### whiteSpaceToIndent(token, [indentValue])
 127
 128 Convert `WhiteSpace` token into `Indent` if it's the first token of the line.
 129
 130 You can pass a custom `indentValue` or it will use the value set by
 131 `setOptions()` to calculate the indent `level` (basically count how many times
 132 this string repeats inside the `token.value`).
 133
 134 ```js
 135 var token = {
 136   type: 'WhiteSpace',
 137   value: '\t\t\t',
 138   prev: { type: 'LineBreak', value: '\n' }
 139 };
 140 whiteSpaceToIndent(token, '\t');
 141 // edits properties in place
 142 console.log(token.type);  // > "Indent"
 143 console.log(token.level); // > 3
 144 ```
 145
 146 This is useful in case you want to make sure `sanitize` won't remove the
 147 original indents.
 148
 149 ## Debug
 150
 151 This module uses [debug](https://www.npmjs.com/package/debug) internally. To
 152 make it easier to identify what is wrong we sometimes run the esformatter tests
 153 with a `DEBUG` flag, like:
 154
 155 ```sh
 156 DEBUG=rocambole:indent npm test
 157 ```
 158
 159 ## License
 160
 161 Released under the MIT License
 162