CodeChunk (Closure Templates)

java.lang.Object
- com.google.template.soy.jssrc.dsl.CodeChunk

Direct Known Subclasses:

CodeChunk.WithValue, DoWhile, VariableDeclaration
```
public abstract class CodeChunk
extends Object
```
DSL for constructing sequences of JavaScript code. Unlike JsExpr, it can handle code that cannot be represented as single expressions.
Sample usage: CodeChunk.WithValue fraction = cg.declare( number(3) .divideBy(number(4))); cg .newChunk(fraction) .if_( fraction.doubleEqualsNull(), id("someFunction").call()) .endif() .assign(fraction.times(number(5))) .build() .getCode(); produces var $$tmp0 = 3 / 4; if ($$tmp0 == null) { someFunction(); } $$tmp0 = $$tmp0 * 5; TODO(user): do all JS code generation with this DSL (that is, remove JsCodeBuilder).

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`CodeChunk.Generator` Code chunks in a single Soy template emit code into a shared JavaScript lexical scope, so they must use distinct variable names.
`static interface`	`CodeChunk.RequiresCollector` A trivial interface for `collectRequires(RequiresCollector)` that can be used to collect all required namespaces from a code chunk.
`static class`	`CodeChunk.WithValue` Marker class for a chunk of code that represents a value.

Field Summary

Fields
Modifier and Type	Field and Description
`static CodeChunk.WithValue`	`EMPTY_OBJECT_LITERAL`
`static CodeChunk.WithValue`	`LITERAL_EMPTY_STRING`
`static CodeChunk.WithValue`	`LITERAL_FALSE`
`static CodeChunk.WithValue`	`LITERAL_NULL`
`static CodeChunk.WithValue`	`LITERAL_TRUE`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`static CodeChunk.WithValue`	`arrayLiteral(Iterable<? extends CodeChunk.WithValue> elements)` Creates a code chunk representing a javascript array literal.
`JsExpr`	`assertExpr()` Temporary method to ease migration to the CodeChunk DSL.
`JsExpr`	`assertExprAndCollectRequires(CodeChunk.RequiresCollector collector)` Temporary method to ease migration to the CodeChunk DSL.
`static CodeChunk`	`assign(String varName, CodeChunk.WithValue rhs)` Creates a code chunk that assigns value to a preexisting variable with the given name.
`abstract void`	`collectRequires(CodeChunk.RequiresCollector collector)` Adds all the 'goog.require' identifiers needed by this CodeChunk to the given collection.
`static CodeChunk.WithValue`	`dontTrustPrecedenceOf(JsExpr couldHaveWrongPrecedence, Iterable<GoogRequire> requires)` Wraps a `JsExpr` that could have incorrect precedence in parens.
`static CodeChunk.WithValue`	`dottedIdNoRequire(String dotSeparatedIdentifiers)` Creates a code chunk representing a JavaScript "dotted identifier" which needs no `goog.require` statements to be added.
`static CodeChunk`	`forLoop(String localVar, CodeChunk.WithValue initial, CodeChunk.WithValue limit, CodeChunk.WithValue increment, CodeChunk body)` Creates a code chunk representing a for loop.
`static CodeChunk`	`forLoop(String localVar, CodeChunk.WithValue limit, CodeChunk body)` Creates a code chunk representing a for loop, with default values for initial & increment.
`static CodeChunk.WithValue`	`fromExpr(JsExpr expr, Iterable<GoogRequire> requires)` Creates a new code chunk from the given expression.
`static CodeChunk.WithValue`	`function(Iterable<String> parameters, CodeChunk body)` Creates a code chunk representing an anonymous function literal.
`String`	`getCode()` Returns a sequence of JavaScript statements.
`String`	`getStatementsForInsertingIntoForeignCodeAtIndent(int startingIndent)` Returns a sequence of JavaScript statements suitable for inserting into JS code that is not managed by the CodeChunk DSL.
`static CodeChunk.WithValue`	`id(String id)` Creates a code chunk representing a JavaScript identifier.
`static ConditionalExpressionBuilder`	`ifExpression(CodeChunk.WithValue predicate, CodeChunk.WithValue consequent)` Starts a conditional expression beginning with the given predicate and consequent chunks.
`static ConditionalBuilder`	`ifStatement(CodeChunk.WithValue predicate, CodeChunk consequent)` Starts a conditional statement beginning with the given predicate and consequent chunks.
`static CodeChunk.WithValue`	`mapLiteral(Iterable<? extends CodeChunk.WithValue> keys, Iterable<? extends CodeChunk.WithValue> values)` Creates a code chunk representing a javascript map literal.
`static CodeChunk.WithValue`	`new_(CodeChunk.WithValue ctor)` Creates a code chunk representing the `new` operator applied to the given constructor.
`static CodeChunk.WithValue`	`not(CodeChunk.WithValue arg)` Creates a code chunk representing the logical negation `!` of the given chunk.
`static CodeChunk.WithValue`	`number(double value)` Creates a code chunk representing a JavaScript number literal.
`static CodeChunk.WithValue`	`number(long value)` Creates a code chunk representing a JavaScript number literal.
`static CodeChunk.WithValue`	`operation(Operator op, List<CodeChunk.WithValue> operands)` Creates a code chunk representing the given Soy operator applied to the given operands.
`static CodeChunk.WithValue`	`regexLiteral(String contents)` Creates a code chunk representing a JavaScript regular expression literal.
`static CodeChunk`	`return_(CodeChunk.WithValue returnValue)` Creates a code chunk that represents a return statement returning the given value.
`static CodeChunk`	`statements(CodeChunk first, CodeChunk... rest)` Creates a new code chunk representing the concatenation of the given chunks.
`static CodeChunk`	`statements(Iterable<CodeChunk> stmts)` Creates a new code chunk representing the concatenation of the given chunks.
`static CodeChunk.WithValue`	`stringLiteral(String contents)` Creates a code chunk representing a JavaScript string literal.
`static SwitchBuilder`	`switch_(CodeChunk.WithValue switchOn)` Starts a `switch` statement dispatching on the given chunk.
`static CodeChunk`	`throw_(CodeChunk.WithValue throwValue)` Creates a code chunk that represents a throw statement.
`static CodeChunk`	`treatRawStringAsStatementLegacyOnly(String rawString, Iterable<GoogRequire> requires)` Creates a code chunk from the given text, treating it as a series of statements rather than an expression.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - LITERAL_TRUE
```
public static final CodeChunk.WithValue LITERAL_TRUE
```
  - LITERAL_FALSE
```
public static final CodeChunk.WithValue LITERAL_FALSE
```
  - LITERAL_NULL
```
public static final CodeChunk.WithValue LITERAL_NULL
```
  - LITERAL_EMPTY_STRING
```
public static final CodeChunk.WithValue LITERAL_EMPTY_STRING
```
  - EMPTY_OBJECT_LITERAL
```
public static final CodeChunk.WithValue EMPTY_OBJECT_LITERAL
```
- Method Detail
  - statements
```
public static CodeChunk statements(CodeChunk first,
                                   CodeChunk... rest)
```
    Creates a new code chunk representing the concatenation of the given chunks.
  - statements
```
public static CodeChunk statements(Iterable<CodeChunk> stmts)
```
    Creates a new code chunk representing the concatenation of the given chunks.
  - ifStatement
```
public static ConditionalBuilder ifStatement(CodeChunk.WithValue predicate,
                                             CodeChunk consequent)
```
    Starts a conditional statement beginning with the given predicate and consequent chunks.
  - ifExpression
```
public static ConditionalExpressionBuilder ifExpression(CodeChunk.WithValue predicate,
                                                        CodeChunk.WithValue consequent)
```
    Starts a conditional expression beginning with the given predicate and consequent chunks.
  - fromExpr
```
public static CodeChunk.WithValue fromExpr(JsExpr expr,
                                           Iterable<GoogRequire> requires)
```
    Creates a new code chunk from the given expression. The expression's precedence is preserved.
  - id
```
public static CodeChunk.WithValue id(String id)
```
    Creates a code chunk representing a JavaScript identifier.
    
    Throws:
    
    IllegalArgumentException - if id is not a valid JavaScript identifier.
  - dottedIdNoRequire
```
public static CodeChunk.WithValue dottedIdNoRequire(String dotSeparatedIdentifiers)
```
    Creates a code chunk representing a JavaScript "dotted identifier" which needs no goog.require statements to be added.
    "Dotted identifiers" are really just sequences of dot-access operations off some base identifier, so this method is just a convenience for id(...).dotAccess(...).... It's provided because working with raw dot-separated strings is common.
    Most dotted identifiers should be accessed via the GoogRequire api.
  - stringLiteral
```
public static CodeChunk.WithValue stringLiteral(String contents)
```
    Creates a code chunk representing a JavaScript string literal.
    
    Parameters:
    
    contents - The contents of the string literal. The contents will be escaped appropriately and embedded inside single quotes.
  - regexLiteral
```
public static CodeChunk.WithValue regexLiteral(String contents)
```
    Creates a code chunk representing a JavaScript regular expression literal.
    
    Parameters:
    
    contents - The regex literal (including the opening and closing slashes).
  - number
```
public static CodeChunk.WithValue number(long value)
```
    Creates a code chunk representing a JavaScript number literal.
  - number
```
public static CodeChunk.WithValue number(double value)
```
    Creates a code chunk representing a JavaScript number literal.
  - assign
```
public static CodeChunk assign(String varName,
                               CodeChunk.WithValue rhs)
```
    Creates a code chunk that assigns value to a preexisting variable with the given name.
  - function
```
public static CodeChunk.WithValue function(Iterable<String> parameters,
                                           CodeChunk body)
```
    Creates a code chunk representing an anonymous function literal.
  - not
```
public static CodeChunk.WithValue not(CodeChunk.WithValue arg)
```
    Creates a code chunk representing the logical negation ! of the given chunk.
  - switch_
```
public static SwitchBuilder switch_(CodeChunk.WithValue switchOn)
```
    Starts a switch statement dispatching on the given chunk.
  - new_
```
public static CodeChunk.WithValue new_(CodeChunk.WithValue ctor)
```
    Creates a code chunk representing the new operator applied to the given constructor. If you need to call the constructor with arguments, call CodeChunk.WithValue.call(com.google.template.soy.jssrc.dsl.CodeChunk.WithValue...) on the returned chunk.
  - operation
```
public static CodeChunk.WithValue operation(Operator op,
                                            List<CodeChunk.WithValue> operands)
```
    Creates a code chunk representing the given Soy operator applied to the given operands.
    Cannot be used for Operator.AND, Operator.OR, or Operator.CONDITIONAL, as they require access to a CodeChunk.Generator to generate temporary variables for short-circuiting. Use CodeChunk.WithValue.and(com.google.template.soy.jssrc.dsl.CodeChunk.WithValue, com.google.template.soy.jssrc.dsl.CodeChunk.Generator), CodeChunk.WithValue.or(com.google.template.soy.jssrc.dsl.CodeChunk.WithValue, com.google.template.soy.jssrc.dsl.CodeChunk.Generator), and CodeChunk.Generator.conditionalExpression(com.google.template.soy.jssrc.dsl.CodeChunk.WithValue, com.google.template.soy.jssrc.dsl.CodeChunk.WithValue, com.google.template.soy.jssrc.dsl.CodeChunk.WithValue) instead.
  - arrayLiteral
```
public static CodeChunk.WithValue arrayLiteral(Iterable<? extends CodeChunk.WithValue> elements)
```
    Creates a code chunk representing a javascript array literal.
  - mapLiteral
```
public static CodeChunk.WithValue mapLiteral(Iterable<? extends CodeChunk.WithValue> keys,
                                             Iterable<? extends CodeChunk.WithValue> values)
```
    Creates a code chunk representing a javascript map literal.
  - forLoop
```
public static CodeChunk forLoop(String localVar,
                                CodeChunk.WithValue initial,
                                CodeChunk.WithValue limit,
                                CodeChunk.WithValue increment,
                                CodeChunk body)
```
    Creates a code chunk representing a for loop.
  - forLoop
```
public static CodeChunk forLoop(String localVar,
                                CodeChunk.WithValue limit,
                                CodeChunk body)
```
    Creates a code chunk representing a for loop, with default values for initial & increment.
  - return_
```
public static CodeChunk return_(CodeChunk.WithValue returnValue)
```
    Creates a code chunk that represents a return statement returning the given value.
  - throw_
```
public static CodeChunk throw_(CodeChunk.WithValue throwValue)
```
    Creates a code chunk that represents a throw statement.
  - dontTrustPrecedenceOf
```
public static CodeChunk.WithValue dontTrustPrecedenceOf(JsExpr couldHaveWrongPrecedence,
                                                        Iterable<GoogRequire> requires)
```
    Wraps a JsExpr that could have incorrect precedence in parens.
    The JsExpr constructor is inherently error-prone. It allows callers to pass a precedence unrelated to the topmost operator in the text string. While JsExprs created in the Soy codebase can be audited, JsExprs are also returned by functions and print directives owned by others. This method should be used to wrap the results of those plugins.
  - treatRawStringAsStatementLegacyOnly
```
public static CodeChunk treatRawStringAsStatementLegacyOnly(String rawString,
                                                            Iterable<GoogRequire> requires)
```
    Creates a code chunk from the given text, treating it as a series of statements rather than an expression. For use only by com.google.template.soy.jssrc.internal.GenJsCodeVisitor#visitReturningCodeChunk.
    TODO(user): remove.
  - collectRequires
```
public abstract void collectRequires(CodeChunk.RequiresCollector collector)
```
    Adds all the 'goog.require' identifiers needed by this CodeChunk to the given collection.
  - getCode
```
public final String getCode()
```
    Returns a sequence of JavaScript statements. In the special case that this chunk is representable as a single expression, returns that expression followed by a semicolon.
    This method is intended to be used at the end of codegen to emit the entire gencode. It should not be used within the codegen system for intermediate representations.
    Because the returned code is intended to be used at the end of codegen, it does not end in a newline.
  - getStatementsForInsertingIntoForeignCodeAtIndent
```
public final String getStatementsForInsertingIntoForeignCodeAtIndent(int startingIndent)
```
    Returns a sequence of JavaScript statements suitable for inserting into JS code that is not managed by the CodeChunk DSL. The string is guaranteed to end in a newline.
    Callers should use getCode() when the CodeChunk DSL is managing the entire code generation. getCode may drop variable declarations if there is no other code referencing those variables.
    By contrast, this method is provided for incremental migration to the CodeChunk DSL. Variable declarations will not be dropped, since there may be gencode not managed by the CodeChunk DSL that references them.
    TODO(b/33382980): remove.
    
    Parameters:
    
    startingIndent - The indent level of the foreign code into which this code will be inserted. This doesn't affect the correctness of the composed code, only its readability.
  - assertExpr
```
public final JsExpr assertExpr()
```
    Temporary method to ease migration to the CodeChunk DSL.
    Because of the recursive nature of the JS codegen system, it is generally not possible to convert one codegen method at a time to use the CodeChunk DSL. However, the business logic inside those methods can be migrated incrementally. Methods that do not yet use the CodeChunk DSL can "unwrap" inputs using this method and "wrap" results using CodeChunk#fromExpr(JsExpr). This is safe as long as each CodeChunk generated for production code is CodeChunk.WithValue.isRepresentableAsSingleExpression(). TODO(user): remove.
  - assertExprAndCollectRequires
```
public final JsExpr assertExprAndCollectRequires(CodeChunk.RequiresCollector collector)
```
    Temporary method to ease migration to the CodeChunk DSL.
    Because of the recursive nature of the JS codegen system, it is generally not possible to convert one codegen method at a time to use the CodeChunk DSL. However, the business logic inside those methods can be migrated incrementally. Methods that do not yet use the CodeChunk DSL can "unwrap" inputs using this method and "wrap" results using CodeChunk#fromExpr(JsExpr). This is safe as long as each CodeChunk generated for production code is CodeChunk.WithValue.isRepresentableAsSingleExpression().
    TODO(user): remove.

Class CodeChunk

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

LITERAL_TRUE

LITERAL_FALSE

LITERAL_NULL

LITERAL_EMPTY_STRING

EMPTY_OBJECT_LITERAL

Method Detail

statements

statements

ifStatement

ifExpression

fromExpr

id

dottedIdNoRequire

stringLiteral

regexLiteral

number

number

assign

function

not

switch_

new_

operation

arrayLiteral

mapLiteral

forLoop

forLoop

return_

throw_

dontTrustPrecedenceOf

treatRawStringAsStatementLegacyOnly

collectRequires

getCode

getStatementsForInsertingIntoForeignCodeAtIndent

assertExpr

assertExprAndCollectRequires