ScalaEmitter

ScalaEmitter is the core emission engine that converts IR models to formatted Scala source code. It provides the main entry point and methods to emit any IR construct as a properly formatted string.

Use Cases

• Converting a complete ScalaFile IR to a Scala source string
• Emitting individual type definitions as Scala code
• Generating imports, annotations, methods, and type references
• Formatting code with consistent indentation and style

Main Emission Method

Emit a complete Scala file:

import zio.blocks.codegen.ir._
import zio.blocks.codegen.emit._

val file = ScalaFile(
  packageDecl = PackageDecl("com.example"),
  types = List(
    CaseClass("User", List(Field("id", TypeRef.Long)))
  )
)

val config = EmitterConfig()
val sourceCode = ScalaEmitter.emit(file, config)
// sourceCode is a String ready to write to a .scala file

Key Operations

All core operations are shown below:

Emitting Type References

Convert a type reference to Scala syntax:

import zio.blocks.codegen.ir._
import zio.blocks.codegen.emit._

// These methods are used internally by emit, but available if you need them:
ScalaEmitter.emitTypeRef(TypeRef.String)
// Returns: "String"

ScalaEmitter.emitTypeRef(TypeRef.list(TypeRef.Int))
// Returns: "List[Int]"

ScalaEmitter.emitTypeRef(TypeRef.map(TypeRef.String, TypeRef.Int))
// Returns: "Map[String, Int]"

Emitting Type Parameters

Emit generic type parameters with bounds:

import zio.blocks.codegen.ir._

val unbounded = TypeParam("T")
// Emits: "T"

val bounded = TypeParam("T", upperBound = Some(TypeRef("Serializable")))
// Emits: "T <: Serializable"

val covariant = TypeParam("T", variance = Variance.Covariant)
// Emits: "+T"

Emitting Annotations

Convert annotations to Scala syntax:

import zio.blocks.codegen.ir._

val deprecated = Annotation("deprecated")
// Emits: "@deprecated"

val withArg = Annotation("Deprecated", args = List("message" -> "\"Use newMethod instead\""))
// Emits: "@Deprecated(message = \"Use newMethod instead\")"

Configuration

The emitter respects EmitterConfig settings:

import zio.blocks.codegen.ir._
import zio.blocks.codegen.emit._

val file = ScalaFile(PackageDecl("com.example"))

val config = EmitterConfig(
  indentWidth = 2,              // Spaces per indent level
  sortImports = true,           // Sort import statements
  trailingCommas = true,        // Add trailing commas in collections
  scala3Syntax = true           // Scala 3 syntax features
)

ScalaEmitter.emit(file, config)

See EmitterConfig for all available options.

Examples

Practical examples demonstrate common usage:

Example 1: Emit a Complete File

Generate a Scala file with multiple types:

import zio.blocks.codegen.ir._
import zio.blocks.codegen.emit._

val file = ScalaFile(
  packageDecl = PackageDecl("com.api"),
  imports = List(
    Import.WildcardImport("zio"),
    Import.SingleImport("scala.collection", "Seq")
  ),
  types = List(
    CaseClass(
      "ApiResponse",
      List(
        Field("status", TypeRef.Int),
        Field("data", TypeRef.optional(TypeRef.String))
      )
    )
  )
)

val config = EmitterConfig(indentWidth = 2)

Emits:

import zio.blocks.codegen.emit._
ScalaEmitter.emit(file, config)
// res6: String = """package com.api
// 
// import scala.collection.Seq
// import zio.*
// 
// case class ApiResponse(
//   status: Int,
//   data: Option[String],
// )
// """

Example 2: Cross-Scala Compatibility

Generate code for different Scala versions:

import zio.blocks.codegen.ir._
import zio.blocks.codegen.emit._

val file = ScalaFile(
  packageDecl = PackageDecl("com.example"),
  types = List(
    Enum(
      name = "Status",
      cases = List(
        EnumCase.SimpleCase("Active"),
        EnumCase.SimpleCase("Inactive")
      )
    )
  )
)

// For Scala 3: emits actual enum
val scala3Config = EmitterConfig(
  scala3Syntax = true
)
val scala3Code = ScalaEmitter.emit(file, scala3Config)

// For Scala 2: emits sealed trait (fallback)
val scala2Config = EmitterConfig(
  scala3Syntax = false
)
val scala2Code = ScalaEmitter.emit(file, scala2Config)

Scala 3 emits:

import zio.blocks.codegen.emit._
scala3Code
// res8: String = """package com.example
// 
// enum Status {
//   case Active, Inactive
// }
// """

Scala 2 emits:

import zio.blocks.codegen.emit._
scala2Code
// res9: String = """package com.example
// 
// sealed trait Status
// 
// object Status {
//   case object Active extends Status
//   case object Inactive extends Status
// }
// """

Example 3: Sealed Trait with Multiple Cases

Emit a complete ADT:

import zio.blocks.codegen.ir._
import zio.blocks.codegen.emit._

val file = ScalaFile(
  packageDecl = PackageDecl("com.errors"),
  types = List(
    SealedTrait(
      name = "DomainError",
      cases = List(
        SealedTraitCase.CaseClassCase(
          CaseClass("ValidationError", List(
            Field("field", TypeRef.String),
            Field("message", TypeRef.String)
          ))
        ),
        SealedTraitCase.CaseClassCase(
          CaseClass("NotFound", List(
            Field("resource", TypeRef.String),
            Field("id", TypeRef.Long)
          ))
        ),
        SealedTraitCase.CaseObjectCase("Unauthorized"),
        SealedTraitCase.CaseObjectCase("InternalError")
      )
    )
  )
)

val config = EmitterConfig(trailingCommas = true)

Emits:

import zio.blocks.codegen.emit._
ScalaEmitter.emit(file, config)
// res11: String = """package com.errors
// 
// sealed trait DomainError
// 
// object DomainError {
//   case class ValidationError(
//     field: String,
//     message: String,
//   ) extends DomainError
//   case class NotFound(
//     resource: String,
//     id: Long,
//   ) extends DomainError
//   case object Unauthorized extends DomainError
//   case object InternalError extends DomainError
// }
// """

Example 4: Generic Types

Emit polymorphic types with proper type parameter syntax:

import zio.blocks.codegen.ir._
import zio.blocks.codegen.emit._

val file = ScalaFile(
  packageDecl = PackageDecl("com.containers"),
  types = List(
    CaseClass(
      name = "Wrapper",
      fields = List(Field("value", TypeRef("A"))),
      typeParams = List(
        TypeParam("A")
      )
    ),
    CaseClass(
      name = "Pair",
      fields = List(
        Field("left", TypeRef("A")),
        Field("right", TypeRef("B"))
      ),
      typeParams = List(
        TypeParam("A"),
        TypeParam("B")
      )
    )
  )
)

Emits:

import zio.blocks.codegen.emit._
ScalaEmitter.emit(file, EmitterConfig())
// res13: String = """package com.containers
// 
// case class Wrapper[A](
//   value: A,
// )
// 
// case class Pair[A, B](
//   left: A,
//   right: B,
// )
// """

Example 5: Formatting Customization

Control code style with configuration:

import zio.blocks.codegen.ir._
import zio.blocks.codegen.emit._

val file = ScalaFile(
  packageDecl = PackageDecl("com.example"),
  imports = List(
    Import.WildcardImport("scala.collection"),
    Import.SingleImport("java.time", "Instant")
  ),
  types = List(
    CaseClass(
      name = "Record",
      fields = List(
        Field("a", TypeRef.String),
        Field("b", TypeRef.Int),
        Field("c", TypeRef.Boolean)
      )
    )
  )
)

// Wide indentation, sorted imports, trailing commas
val config = EmitterConfig(
  indentWidth = 4,
  sortImports = true,
  trailingCommas = true
)

Emits:

import zio.blocks.codegen.emit._
ScalaEmitter.emit(file, config)
// res15: String = """package com.example
// 
// import java.time.Instant
// import scala.collection.*
// 
// case class Record(
//     a: String,
//     b: Int,
//     c: Boolean,
// )
// """

Design Philosophy

ScalaEmitter follows three principles:

1. Pure: No side effects. Takes IR + config, returns a string. Your code writes files.
2. Configurable: EmitterConfig controls formatting. Add options as needed for your generator.
3. Cross-Scala: Targets both Scala 3 (enums, derives, * imports) and Scala 2 (sealed traits, _ imports) from the same IR.