com.google.template.soy.jbcsrc.restricted

Class Expression

java.lang.Object

com.google.template.soy.jbcsrc.restricted.BytecodeProducer

com.google.template.soy.jbcsrc.restricted.Expression

Direct Known Subclasses:

LocalVariable, SoyExpression

public abstract class Expression
extends BytecodeProducer

An expression has a resultType() and can generate code to evaluate the expression.

Expressions should:

• have no side effects
• be idempotent (you can compose them multiple times and get sensible results)
• produce exactly 1 value onto the runtime stack
• not consume stack items

These rules make it easier to compose and reason about the effect of composing expressions. In particular it makes it easier to maintain the stack height and type invariants of the JVM.

Due to these constraints there are some natural consequences, a few examples include:

• An expression should never branch to a label outside of the same expression. (Note: return and throw are special cases that are allowed)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Expression.Feature Expression features track additional metadata for expressions.
static class	Expression.Features An immutable wrapper of an EnumSet of Expression.Feature.

Field Summary

Fields inherited from class com.google.template.soy.jbcsrc.restricted.BytecodeProducer

location

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Expression(org.objectweb.asm.Type resultType)
protected	Expression(org.objectweb.asm.Type resultType, Expression.Feature first, Expression.Feature... rest)
protected	Expression(org.objectweb.asm.Type resultType, Expression.Features features)
protected	Expression(org.objectweb.asm.Type resultType, Expression.Features features, SourceLocation location)

Method Summary

Modifier and Type	Method and Description
static boolean	areAllCheap(Expression first, Expression... rest) Returns true if all referenced expressions are cheap.
static boolean	areAllCheap(Iterable<? extends Expression> args) Returns true if all referenced expressions are cheap.
Expression	asCheap() Returns an equivalent expression where isCheap() returns true.
Expression	asNonNullable() Returns an equivalent expression where isNonNullable() returns true.
Expression	asNullable()
void	checkAssignableTo(org.objectweb.asm.Type expected) Check that this expression is assignable to expected.
void	checkAssignableTo(org.objectweb.asm.Type expected, String fmt, Object... args) Check that this expression is assignable to expected.
Expression	checkedCast(Class<?> target) Returns an expression that performs a checked cast from the current type to the target type.
Expression	checkedCast(org.objectweb.asm.Type target) Returns an expression that performs a checked cast from the current type to the target type.
static void	checkTypes(com.google.common.collect.ImmutableList<org.objectweb.asm.Type> types, Expression... exprs) Checks that the given expressions are compatible with the given types.
protected abstract void	doGen(CodeBuilder adapter) Generate code to evaluate the expression.
protected void	extraToStringProperties(com.google.common.base.MoreObjects.ToStringHelper helper) Subclasses can override this to supply extra properties for the toString method.
Expression.Features	features() Returns all the feature bits.
Expression	invoke(MethodRef method, Expression... args) A simple helper that calls through to MethodRef.invoke(Expression...), but allows a more natural fluent call style.
Statement	invokeVoid(MethodRef method, Expression... args) A simple helper that calls through to MethodRef.invokeVoid(Expression...), but allows a more natural fluent call style.
boolean	isCheap() Whether or not this expression is cheap.
boolean	isNonNullable() Whether or not this expression is non nullable.
Expression	labelEnd(org.objectweb.asm.Label label) Returns a new expression identical to this one but with the given label applied at the end of the expression.
Expression	labelStart(org.objectweb.asm.Label label) Returns a new expression identical to this one but with the given label applied at the start of the expression.
org.objectweb.asm.Type	resultType() The type of the expression.
Statement	toStatement() Convert this expression to a statement, by executing it and throwing away the result.
String	toString()
Expression	withSourceLocation(SourceLocation location) Returns an identical Expression with the given source location.

Methods inherited from class com.google.template.soy.jbcsrc.restricted.BytecodeProducer

gen, trace

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Expression

protected Expression(org.objectweb.asm.Type resultType)

Expression

protected Expression(org.objectweb.asm.Type resultType,
                     Expression.Feature first,
                     Expression.Feature... rest)

Expression

protected Expression(org.objectweb.asm.Type resultType,
                     Expression.Features features)

Expression

protected Expression(org.objectweb.asm.Type resultType,
                     Expression.Features features,
                     SourceLocation location)

Method Detail

areAllCheap

public static boolean areAllCheap(Iterable<? extends Expression> args)

Returns true if all referenced expressions are cheap.

areAllCheap

public static boolean areAllCheap(Expression first,
                                  Expression... rest)

Returns true if all referenced expressions are cheap.

checkTypes

public static void checkTypes(com.google.common.collect.ImmutableList<org.objectweb.asm.Type> types,
                              Expression... exprs)

Checks that the given expressions are compatible with the given types.

doGen

protected abstract void doGen(CodeBuilder adapter)

Generate code to evaluate the expression.

The generated code satisfies the invariant that the top of the runtime stack will contain a value with this resultType() immediately after evaluation of the code.

Specified by:

doGen in class BytecodeProducer

withSourceLocation

public Expression withSourceLocation(SourceLocation location)

Returns an identical Expression with the given source location.

resultType

public final org.objectweb.asm.Type resultType()

The type of the expression.

isCheap

public boolean isCheap()

Whether or not this expression is cheap.

isNonNullable

public boolean isNonNullable()

Whether or not this expression is non nullable.

features

public Expression.Features features()

Returns all the feature bits. Typically, users will want to invoke one of the convenience accessors isCheap() or isNonNullable().

checkAssignableTo

public final void checkAssignableTo(org.objectweb.asm.Type expected)

Check that this expression is assignable to expected.

checkAssignableTo

public final void checkAssignableTo(org.objectweb.asm.Type expected,
                                    String fmt,
                                    Object... args)

Check that this expression is assignable to expected.

toStatement

public Statement toStatement()

Convert this expression to a statement, by executing it and throwing away the result.

This is useful for invoking non-void methods when we don't care about the result.

asCheap

public Expression asCheap()

Returns an equivalent expression where isCheap() returns true.

asNonNullable

public Expression asNonNullable()

Returns an equivalent expression where isNonNullable() returns true.

asNullable

public Expression asNullable()

checkedCast

public Expression checkedCast(org.objectweb.asm.Type target)

Returns an expression that performs a checked cast from the current type to the target type.

Throws:

IllegalArgumentException - if either type is not a reference type.

checkedCast

public Expression checkedCast(Class<?> target)

Returns an expression that performs a checked cast from the current type to the target type.

Throws:

IllegalArgumentException - if either type is not a reference type.

invoke

public Expression invoke(MethodRef method,
                         Expression... args)

A simple helper that calls through to MethodRef.invoke(Expression...), but allows a more natural fluent call style.

invokeVoid

public Statement invokeVoid(MethodRef method,
                            Expression... args)

A simple helper that calls through to MethodRef.invokeVoid(Expression...), but allows a more natural fluent call style.

labelStart

public Expression labelStart(org.objectweb.asm.Label label)

Returns a new expression identical to this one but with the given label applied at the start of the expression.

labelEnd

public Expression labelEnd(org.objectweb.asm.Label label)

Returns a new expression identical to this one but with the given label applied at the end of the expression.

extraToStringProperties

protected void extraToStringProperties(com.google.common.base.MoreObjects.ToStringHelper helper)

Subclasses can override this to supply extra properties for the toString method.

toString

public String toString()

Overrides:

toString in class Object