Placeholders

Most of the API from DartPoet uses immutable objects from Kotlin. There are also builder, method chaining and other parts to make the API as friendly as possible.

DartPoet contains

%S or %C for Strings

When emitting code that includes string literals, we can use %S or %C to emit a string, complete with wrapping quotation marks and escaping.

Example which emits the string with %S:

val function = FunctionSpec.builder("greet")
    .parameters(
        ParameterSpec.builder("value", String::class).build()
    )
    .returns(Void::class)
    .addCode("print(%S: %S)", "This is a nice message ","value")
    //addCode("print(%C: %C)", "This is a nice message ","value")
    .build()

Creates this function:

// With %S

void greet(String value) {
  print("This is a nice message: $value");
}

// With %C
void greet(String value) {
  print('This is a nice message: $value');
}

%T for Types

When you want to use a type for the generation, you can use %T. Note: DartPoet can't generate an import for that class automatically. This must be done by the user.

val dateClass = ClassName("DateTime")
val dateFunction = FunctionSpec.builder("today")
    .returns(dateClass)
    .lambda(true)
    .addCode("%T.now();", dateClass)
    .build()

Results in this generated function:

DateTime today() => DateTime.now();

Nullable Types

The written code for Dart should ideally be Null-Safe. Specifically, this means avoiding values that can be null. However, it is still possible to define variables as nullable. When creating parameters or variables, one must explicitly state that the value can be nullable.

To create a nullable value, we need to make a difference between type which are parameterized or not:

Parameterized values:

val property = List::class.parameterizedBy(Int::class).copy(nullable: true)

val property = PropertySpec.builder("name", String::class).nullable(true).build()

Which returns the following generated variable:

String? name;

%L for Literals

PropertySpec.builder("counter", Integer::class).initializer("%L", "10").build()

Results in the following generation:

int counter = 10;

Literals are emitted directly to the output code with no escaping. Arguments for literals may be strings, primitives, and a few KotlinPoet types described below.

Last modified: 11 March 2024