Spoon provides developers a way of writing code transformations called code templates. Those templates are statically type-checked, in order to ensure statically that the generated code will be correct.

A Spoon template is a regular Java class that taken as input by the Spoon templating engine to perform a transformation. This is summarized in Figure below. A Spoon template can be seen as a higher-order program, which takes program elements as arguments, and returns a transformed program. Like any function, a template can be used in different contexts and give different results, depending on its parameters.

Overview of Spoon's Templating System

Definition of templates

Class CheckBoundTemplate below defines a Spoon template.

public class CheckBoundTemplate extends StatementTemplate {
    TemplateParameter<Collection<?>> _col_;
    @Override
    public void statement() {
        if (_col_.S().size() > 10)
            throw new OutOfBoundException();
    }
}

This template specifies a statement (in method statement) that is a precondition to check that a list is smaller than a certain size. This piece of code will be injected at the beginning of all methods dealing with size-bounded lists. This template has one single template parameter called _col_, typed by TemplateParameter (javadoc). In this case, the template parameter is meant to be an expression (CtExpression) that returns a Collection (see constructor, line 3). All meta-model classes, incl. CtExpression (javadoc), implement interface TemplateParameter. A template parameter has a special method (named S, for Substitution) that is used as a marker to indicate the places where a template parameter substitution should occur. For a CtExpression, method S() returns the return type of the expression.

A method S() is never executed, its only goal is to get the template statically checked. Instead of being executed, the template source code is taken as input by the templating engine which is described above. Consequently, the template source is well-typed, compiles, but the binary code of the template is thrown away.

Template Instantiation

In order to be correctly substituted, the template parameters need to be bound to actual values. This is done during template instantiation.

The code at the end of this page shows how to use the check-bound of template, CheckBoundTemplate, presented in the previous section. One first instantiates a template, then one sets the template parameters, and finally, one calls the template engine. In last line, the bound check is injected at the beginning of a method body.

Since the template is given the first method parameter which is in the scope of the insertion location, the generated code is guaranteed to compile. The Java compiler ensures that the template compiles with a given scope, the developer is responsible for checking that the scope where she uses template-generated code is consistent with the template scope.

// creating a template instance
Template t = new CheckBoundTemplate();
t._col_ = createVariableAccess(method.getParameters().get(0)); 

// getting the final AST
CtStatement injectedCode = t.apply();

// adds the bound check at the beginning of a method
method.getBody().insertBegin(injectedCode);

Kinds of templating

There are different kinds of templating.

Subclassing StatementTemplate

Using method apply() enables to get a new statement (see example CheckBoundTemplate above)

Subclassing BlockTemplate

Using method apply() enables to get a new block.

Subclassing ExpressionTemplate

Using method apply() enables to get a new expression. The core template method must be called expression and only contain a return with the expression to be templated.

Subclassing ExtensionTemplate

Using method apply() enables to get a new class where all possible templating in all methods. In addition, the following class level transformations are made:

1) methods and field of the templates are injected in the target class

public class ATemplate1 extends ExtensionTemplate {
  int i;
  void foo() {};
}

// inject `i` and `foo` in aCtClass
Substitution.insertAll(aCtClass, new ATemplate1());

2) parametrized superinterfaces are injected in the target class

class ATemplate2 extends ExtensionTemplate implements Serializable, A, B {
    // interface templates supports TypeReference
    @Parameter
    Class A;
}

Template t = new ATemplate2();
t.A = Comparable.class
Substitution.insertAll(aCtClass, t);
// aCtClass now implements Serializable and Serializable

3) method parameters are replaced

class ATemplate3 extends ExtensionTemplate {
    public void methodWithTemplatedParameters(Object params) {
        // code
    }

    @Parameter
    public List<CtParameter> params;
}

Template t = new ATemplate3();
t.params = ...
Substitution.insertAll(aCtClass, t);
// aCtClass  contains methodmethodWithTemplatedParameters with specific parameters

Template parameters

AST elements

All meta-model elements can be used as template parameter. For instance, one can template a try/catch block as shown in the class TryCatchOutOfBoundTemplateusing a block as parameter. This template type-checks, and can be used as input by the substitution engine to wrap a method body into a try/catch block. The substitution engine contains various methods that implement different substitution scenarios.

public class TryCatchOutOfBoundTemplate extends BlockTemplate {
    TemplateParameter<Void> _body_; // the body to surround

    @Override
    public void block() {
        try {
            _body_.S();
        } catch (OutOfBoundException e) {
            e.printStackTrace();
        }
    }
}

Similarly, templated invocations require to declare a template parameter

@Parameter
CtInvocation invocation;

and then all invocation.S() will be replaced by the actual invocation.

Inlining foreach expressions

Foreach expressions can be inlined. They have to be declared as follows: java @Parameter CtExpression[] intValues; ... template.intValues = new CtExpression[2]; template.intValues[0] = factory.Code().createLiteral(0); template.intValues[1] = factory.Code().createLiteral(1);

and then,

for(Object x : intValues) {
         System.out.println(x);
}

is transformed into:

{
    java.lang.System.out.println(0);
    java.lang.System.out.println(1);
}

Literal template Parameters

For literals, Spoon provides developers with literal template parameters. When the parameter is known to be a literal (primitive types, String, Class or a one-dimensional array of these types), a template parameter, annotated with @Parameter enables one to have concise template code.

// with literal template parameter
@Parameter
int val;
...
val = 5;
...
if (list.size()>val) {...}

Note that AST elements can also be given as parameter using @Parameter (javadoc) annotation.

class ATemplate extends BlockTemplate {
@Parameter
CtExpression<String> exp;
...
if ("er".equals(val)) {...}
}