vnfmarket/src/main/webapp/vnfmarket/node_modules/handlebars/docs/compiler-api.md

   1 # Handlebars Compiler APIs
   2
   3 There are a number of formal APIs that tool implementors may interact with.
   4
   5 ## AST
   6
   7 Other tools may interact with the formal AST as defined below. Any JSON structure matching this pattern may be used and passed into the `compile` and `precompile` methods in the same way as the text for a template.
   8
   9 AST structures may be generated either with the `Handlebars.parse` method and then manipulated, via the `Handlebars.AST` objects of the same name, or constructed manually as a generic JavaScript object matching the structure defined below.
  10
  11 ```javascript
  12 var ast = Handlebars.parse(myTemplate);
  13
  14 // Modify ast
  15
  16 Handlebars.precompile(ast);
  17 ```
  18
  19
  20 ### Basic
  21
  22 ```java
  23 interface Node {
  24     type: string;
  25     loc: SourceLocation | null;
  26 }
  27
  28 interface SourceLocation {
  29     source: string | null;
  30     start: Position;
  31     end: Position;
  32 }
  33
  34 interface Position {
  35     line: uint >= 1;
  36     column: uint >= 0;
  37 }
  38 ```
  39
  40 ### Programs
  41
  42 ```java
  43 interface Program <: Node {
  44     type: "Program";
  45     body: [ Statement ];
  46
  47     blockParams: [ string ];
  48 }
  49 ```
  50
  51 ### Statements
  52
  53 ```java
  54 interface Statement <: Node { }
  55
  56 interface MustacheStatement <: Statement {
  57     type: "MustacheStatement";
  58
  59     path: PathExpression | Literal;
  60     params: [ Expression ];
  61     hash: Hash;
  62
  63     escaped: boolean;
  64     strip: StripFlags | null;
  65 }
  66
  67 interface BlockStatement <: Statement {
  68     type: "BlockStatement";
  69     path: PathExpression;
  70     params: [ Expression ];
  71     hash: Hash;
  72
  73     program: Program | null;
  74     inverse: Program | null;
  75
  76     openStrip: StripFlags | null;
  77     inverseStrip: StripFlags | null;
  78     closeStrip: StripFlags | null;
  79 }
  80
  81 interface PartialStatement <: Statement {
  82     type: "PartialStatement";
  83     name: PathExpression | SubExpression;
  84     params: [ Expression ];
  85     hash: Hash;
  86
  87     indent: string;
  88     strip: StripFlags | null;
  89 }
  90
  91 interface PartialBlockStatement <: Statement {
  92     type: "PartialBlockStatement";
  93     name: PathExpression | SubExpression;
  94     params: [ Expression ];
  95     hash: Hash;
  96
  97     program: Program | null;
  98
  99     indent: string;
 100     openStrip: StripFlags | null;
 101     closeStrip: StripFlags | null;
 102 }
 103 ```
 104
 105 `name` will be a `SubExpression` when tied to a dynamic partial, i.e. `{{> (foo) }}`, otherwise this is a path or literal whose `original` value is used to lookup the desired partial.
 106
 107
 108 ```java
 109 interface ContentStatement <: Statement {
 110     type: "ContentStatement";
 111     value: string;
 112     original: string;
 113 }
 114
 115 interface CommentStatement <: Statement {
 116     type: "CommentStatement";
 117     value: string;
 118
 119     strip: StripFlags | null;
 120 }
 121 ```
 122
 123
 124 ```java
 125 interface Decorator <: Statement {
 126     type: "Decorator";
 127
 128     path: PathExpression | Literal;
 129     params: [ Expression ];
 130     hash: Hash;
 131
 132     strip: StripFlags | null;
 133 }
 134
 135 interface DecoratorBlock <: Statement {
 136     type: "DecoratorBlock";
 137     path: PathExpression | Literal;
 138     params: [ Expression ];
 139     hash: Hash;
 140
 141     program: Program | null;
 142
 143     openStrip: StripFlags | null;
 144     closeStrip: StripFlags | null;
 145 }
 146 ```
 147
 148 Decorator paths only utilize the `path.original` value and as a consequence do not support depthed evaluation.
 149
 150 ### Expressions
 151
 152 ```java
 153 interface Expression <: Node { }
 154 ```
 155
 156 ##### SubExpressions
 157
 158 ```java
 159 interface SubExpression <: Expression {
 160     type: "SubExpression";
 161     path: PathExpression;
 162     params: [ Expression ];
 163     hash: Hash;
 164 }
 165 ```
 166
 167 ##### Paths
 168
 169 ```java
 170 interface PathExpression <: Expression {
 171     type: "PathExpression";
 172     data: boolean;
 173     depth: uint >= 0;
 174     parts: [ string ];
 175     original: string;
 176 }
 177 ```
 178
 179 - `data` is true when the given expression is a `@data` reference.
 180 - `depth` is an integer representation of which context the expression references. `0` represents the current context, `1` would be `../`, etc.
 181 - `parts` is an array of the names in the path. `foo.bar` would be `['foo', 'bar']`. Scope references, `.`, `..`, and `this` should be omitted from this array.
 182 - `original` is the path as entered by the user. Separator and scope references are left untouched.
 183
 184
 185 ##### Literals
 186
 187 ```java
 188 interface Literal <: Expression { }
 189
 190 interface StringLiteral <: Literal {
 191     type: "StringLiteral";
 192     value: string;
 193     original: string;
 194 }
 195
 196 interface BooleanLiteral <: Literal {
 197     type: "BooleanLiteral";
 198     value: boolean;
 199     original: boolean;
 200 }
 201
 202 interface NumberLiteral <: Literal {
 203     type: "NumberLiteral";
 204     value: number;
 205     original: number;
 206 }
 207
 208 interface UndefinedLiteral <: Literal {
 209     type: "UndefinedLiteral";
 210 }
 211
 212 interface NullLiteral <: Literal {
 213     type: "NullLiteral";
 214 }
 215 ```
 216
 217
 218 ### Miscellaneous
 219
 220 ```java
 221 interface Hash <: Node {
 222     type: "Hash";
 223     pairs: [ HashPair ];
 224 }
 225
 226 interface HashPair <: Node {
 227     type: "HashPair";
 228     key: string;
 229     value: Expression;
 230 }
 231
 232 interface StripFlags {
 233     open: boolean;
 234     close: boolean;
 235 }
 236 ```
 237
 238 `StripFlags` are used to signify whitespace control character that may have been entered on a given statement.
 239
 240 ## AST Visitor
 241
 242 `Handlebars.Visitor` is available as a base class for general interaction with AST structures. This will by default traverse the entire tree and individual methods may be overridden to provide specific responses to particular nodes.
 243
 244 Recording all referenced partial names:
 245
 246 ```javascript
 247 var Visitor = Handlebars.Visitor;
 248
 249 function ImportScanner() {
 250   this.partials = [];
 251 }
 252 ImportScanner.prototype = new Visitor();
 253
 254 ImportScanner.prototype.PartialStatement = function(partial) {
 255   this.partials.push({request: partial.name.original});
 256
 257   Visitor.prototype.PartialStatement.call(this, partial);
 258 };
 259
 260 var scanner = new ImportScanner();
 261 scanner.accept(ast);
 262 ```
 263
 264 The current node's ancestors will be maintained in the `parents` array, with the most recent parent listed first.
 265
 266 The visitor may also be configured to operate in mutation mode by setting the `mutation` field to true. When in this mode, handler methods may return any valid AST node and it will replace the one they are currently operating on. Returning `false` will remove the given value (if valid) and returning `undefined` will leave the node in tact. This return structure only apply to mutation mode and non-mutation mode visitors are free to return whatever values they wish.
 267
 268 Implementors that may need to support mutation mode are encouraged to utilize the `acceptKey`, `acceptRequired` and `acceptArray` helpers which provide the conditional overwrite behavior as well as implement sanity checks where pertinent.
 269
 270 ## JavaScript Compiler
 271
 272 The `Handlebars.JavaScriptCompiler` object has a number of methods that may be customized to alter the output of the compiler:
 273
 274 - `nameLookup(parent, name, type)`
 275   Used to generate the code to resolve a give path component.
 276
 277   - `parent` is the existing code in the path resolution
 278   - `name` is the current path component
 279   - `type` is the type of name being evaluated. May be one of `context`, `data`, `helper`, `decorator`, or `partial`.
 280
 281   Note that this does not impact dynamic partials, which implementors need to be aware of. Overriding `VM.resolvePartial` may be required to support dynamic cases.
 282
 283 - `depthedLookup(name)`
 284   Used to generate code that resolves parameters within any context in the stack. Is only used in `compat` mode.
 285
 286 - `compilerInfo()`
 287   Allows for custom compiler flags used in the runtime version checking logic.
 288
 289 - `appendToBuffer(source, location, explicit)`
 290     Allows for code buffer emitting code. Defaults behavior is string concatenation.
 291
 292     - `source` is the source code whose result is to be appending
 293     - `location` is the location of the source in the source map.
 294     - `explicit` is a flag signaling that the emit operation must occur, vs. the lazy evaled options otherwise.
 295
 296 - `initializeBuffer()`
 297     Allows for buffers other than the default string buffer to be used. Generally needs to be paired with a custom `appendToBuffer` implementation.
 298
 299 ```javascript
 300 function MyCompiler() {
 301   Handlebars.JavaScriptCompiler.apply(this, arguments);
 302 }
 303 MyCompiler.prototype = Object.create(Handlebars.JavaScriptCompiler);
 304
 305 MyCompiler.nameLookup = function(parent, name, type) {
 306   if (type === 'partial') {
 307     return 'MyPartialList[' + JSON.stringify(name) ']';
 308   } else {
 309     return Handlebars.JavaScriptCompiler.prototype.nameLookup.call(this, parent, name, type);
 310   }
 311 };
 312
 313 var env = Handlebars.create();
 314 env.JavaScriptCompiler = MyCompiler;
 315 env.compile('my template');
 316 ```