SwiftPoet

To release a new version of SwiftPoet, follow these steps to update documentation, set version variables, update project files via sed, tag the release in Git, and prepare the development branch for the next version.

1. Update Changelog

Update CHANGELOG.md with the new release details.

2. Set Version Environment Variables

Define the current release version and the subsequent snapshot version:

export RELEASE_VERSION=X.Y.Z
export NEXT_VERSION=X.Y.Z-SNAPSHOT

3. Update Project Files

Use sed to update version strings in README.md and gradle.properties. This ensures that dependency references, documentation URLs, and Gradle properties reflect the new $RELEASE_VERSION.

4. Tag and Push the Release

Create a release branch, commit the changes, tag it, and push to GitHub:

git checkout -b release.$RELEASE_VERSION
git commit -am "Prepare for release $RELEASE_VERSION."
git tag -a $RELEASE_VERSION -m "Version $RELEASE_VERSION"
git push && git push --tags

5. Merge and Automate

Merge the release branch once CI passes. The CI pipeline will automatically release the artifacts upon merge.

6. Prepare for Ongoing Development

Switch to a new development branch and update gradle.properties to the $NEXT_VERSION to prepare for the next development cycle:

git checkout -b dev.$NEXT_VERSION
sed -i "" "s/releaseVersion=.*/releaseVersion=$NEXT_VERSION/g" `find . -name "gradle.properties"`
git commit -am "Prepare next development version."
git push

Once pushed, CI will release the artifact and publish the documentation.

SwiftPoet uses a builder pattern inspired by JavaPoet to construct Swift code structures like classes, properties, and functions. You build a TypeSpec, add it to a FileSpec, and then write the file to a destination (such as a StringWriter or a file system).

val observableTypeName = DeclaredTypeName.typeName("RxSwift.Observable")

val testClass = TypeSpec.classBuilder("Greeter")
   .addProperty("name", STRING, Modifier.PRIVATE)
   .addFunction(
      FunctionSpec.constructorBuilder()
         .addParameter("name", STRING)
         .addCode("self.name = name\n")
         .build()
   )
   .addFunction(
      FunctionSpec.builder("greet")
         .returns(observableTypeName.parameterizedBy(STRING))
         .addCode("return %T.from(\"Hello \\(name)\")\n", observableTypeName)
         .build()
   )
   .build()

val file = FileSpec.builder("Greeter")
   .addType(testClass)
   .build()

val out = StringWriter()
file.writeTo(out)

Use FileSpec.Builder to programmatically construct a Swift file. The builder provides methods to add various Swift constructs and configure file-level metadata.

Builder Methods:

• addComment(format: String, vararg args: Any): Adds a comment to the top of the file.
• addMember(memberSpec: FileMemberSpec): Adds a generic member.
• addType(typeSpec: AnyTypeSpec): Adds a type (class, struct, enum, etc.).
• addFunction(functionSpec: FunctionSpec): Adds a top-level function. Note: Constructors and accessors cannot be added directly to a file; they must be members of a type.
• addProperty(propertySpec: PropertySpec): Adds a top-level property.
• addExtension(extensionSpec: ExtensionSpec): Adds a top-level extension.
• addImport(importSpec: ImportSpec): Adds a specific import.
• addImport(moduleName: String, vararg attributes: AttributeSpec): Adds an import for a module with optional attributes.
• indent(indent: String): Sets the indentation string (defaults to `

Use PropertySpec.Builder to construct Swift property declarations. You can define simple properties (constants with let or variables with var), computed properties using getters and setters, or subscripts.

Key Capabilities

• Simple Properties: Use builder(name, type) for let constants and varBuilder(name, type) for var variables.
• Computed Properties: Add a getter or setter using FunctionSpec. Note that you cannot combine computed accessors with property observers (willSet/didSet).
• Property Observers: Add willSet or didSet using FunctionSpec. These cannot be added to computed properties.
• Subscripts: Use subscriptBuilder(signature) to define a subscript. Subscripts cannot be mutable or have initializers.
• Modifiers & Documentation: Add visibility modifiers (e.g., PUBLIC, PRIVATE) and documentation blocks using addDoc().
• Initializers: Set an initial value for simple properties using initializer(format, *args) or initializer(codeBlock).

Constraints

• Subscripts require at least one parameter.
• Computed properties (those with getter or setter) cannot have willSet or didSet observers.
• Property observers (willSet/didSet) cannot be added to computed properties.

// Create a simple variable
val myVar = PropertySpec.varBuilder("count", Int::class.asTypeName())
    .initializer("%L", 0)
    .build()

// Create a computed property with a getter
val computed = PropertySpec.builder("isReady", Boolean::class.asTypeName())
    .getter(FunctionSpec.getterBuilder().addCode("return true").build())
    .build()

PropertySpec.Builder allows you to define how a property is accessed or how it reacts to changes.

Accessors (Computed Properties)

Use these for computed properties. They are incompatible with property observers.

• getter(getter: FunctionSpec): Sets the getter. The FunctionSpec must have the name GETTER.
• setter(setter: FunctionSpec): Sets the setter. The FunctionSpec must have the name SETTER.
• abstractGetter(): A convenience method to create an abstract getter.
• abstractSetter(): A convenience method to create an abstract setter.

Observers (Stored Properties)

Use these for stored properties. They are incompatible with computed accessors.

• willSet(willSet: FunctionSpec): Sets the willSet observer. The FunctionSpec must have the name WILL_SET.
• didSet(didSet: FunctionSpec): Sets the didSet observer. The FunctionSpec must have the name DID_SET.