@zio.dev/zio-blocks 0.0.33 → 0.0.51

package/reference/codegen/scala-emitter.md

@@ -0,0 +1,392 @@
+---
+id: scala-emitter
+title: "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:
+
+```scala
+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:
+
+```scala
+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:
+
+```scala
+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:
+
+```scala
+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:
+
+```scala
+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](./emitter-config.md) for all available options.
+
+## Examples
+
+Practical examples demonstrate common usage:
+
+### Example 1: Emit a Complete File
+
+Generate a Scala file with multiple types:
+
+```scala
+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:
+
+```scala
+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:
+
+```scala
+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:
+
+```scala
+import zio.blocks.codegen.emit._
+scala3Code
+// res8: String = """package com.example
+// 
+// enum Status {
+//   case Active, Inactive
+// }
+// """
+```
+
+Scala 2 emits:
+
+```scala
+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:
+
+```scala
+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:
+
+```scala
+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:
+
+```scala
+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:
+
+```scala
+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:
+
+```scala
+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:
+
+```scala
+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.

package/reference/codegen/scala-file.md

@@ -0,0 +1,276 @@
+---
+id: scala-file
+title: "ScalaFile"
+---
+
+`ScalaFile` is the root IR node representing a complete Scala source file. It holds everything needed to emit a compilable file: the package declaration, imports, and type definitions.
+
+## Use Cases
+
+- As the entry point to `ScalaEmitter.emit(file, config)` to generate source code
+- As a container when building complex file structures with multiple types
+- As the canonical representation of "what I want to emit as Scala"
+
+## Construction
+
+Build a `ScalaFile` with a package declaration, optional imports, and optional types:
+
+```scala
+import zio.blocks.codegen.ir._
+
+val simpleFile = ScalaFile(
+  packageDecl = PackageDecl("com.example")
+)
+```
+
+With imports and types:
+
+```scala
+import zio.blocks.codegen.ir._
+
+val file = ScalaFile(
+  packageDecl = PackageDecl("com.example"),
+  imports = List(
+    Import.WildcardImport("zio")
+  ),
+  types = List(
+    CaseClass(
+      name = "User",
+      fields = List(Field("id", TypeRef.Long))
+    )
+  )
+)
+```
+
+## Key Operations
+
+All core operations are shown below:
+
+### Accessing Components
+
+Extract the parts of a `ScalaFile`:
+
+```scala
+import zio.blocks.codegen.emit._
+// Read-only access to all components
+file.packageDecl    // PackageDecl
+// res1: PackageDecl = PackageDecl("com.example")
+file.imports        // List[Import]
+// res2: List[Import] = List(WildcardImport("zio"))
+file.types          // List[TypeDefinition]
+// res3: List[TypeDefinition] = List(
+//   CaseClass(
+//     name = "User",
+//     fields = List(
+//       Field(
+//         name = "id",
+//         typeRef = TypeRef(name = "Long", typeArgs = List()),
+//         defaultValue = None,
+//         annotations = List(),
+//         doc = None
+//       )
+//     ),
+//     typeParams = List(),
+//     extendsTypes = List(),
+//     derives = List(),
+//     annotations = List(),
+//     companion = None,
+//     doc = None,
+//     isValueClass = false
+//   )
+// )
+```
+
+### Building with Copy
+
+Modify a file by copying with new values:
+
+```scala
+import zio.blocks.codegen.emit._
+val updatedFile = file.copy(
+  types = file.types :+ CaseClass(
+    name = "Product",
+    fields = List(Field("name", TypeRef.String))
+  )
+)
+// updatedFile: ScalaFile = ScalaFile(
+//   packageDecl = PackageDecl("com.example"),
+//   imports = List(WildcardImport("zio")),
+//   types = List(
+//     CaseClass(
+//       name = "User",
+//       fields = List(
+//         Field(
+//           name = "id",
+//           typeRef = TypeRef(name = "Long", typeArgs = List()),
+//           defaultValue = None,
+//           annotations = List(),
+//           doc = None
+//         )
+//       ),
+//       typeParams = List(),
+//       extendsTypes = List(),
+//       derives = List(),
+//       annotations = List(),
+//       companion = None,
+//       doc = None,
+//       isValueClass = false
+//     ),
+//     CaseClass(
+//       name = "Product",
+//       fields = List(
+//         Field(
+//           name = "name",
+//           typeRef = TypeRef(name = "String", typeArgs = List()),
+//           defaultValue = None,
+//           annotations = List(),
+//           doc = None
+//         )
+//       ),
+//       typeParams = List(),
+//       extendsTypes = List(),
+//       derives = List(),
+//       annotations = List(),
+//       companion = None,
+//       doc = None,
+//       isValueClass = false
+//     )
+//   )
+// )
+```
+
+### Emitting to Source
+
+Generate Scala source from the file:
+
+```scala
+import zio.blocks.codegen.emit._
+
+val config = EmitterConfig()
+val sourceCode = ScalaEmitter.emit(file, config)
+// sourceCode is a String ready to write to a .scala file
+```
+
+## Examples
+
+Practical examples demonstrate common usage. Each builds a `ScalaFile`, calls `ScalaEmitter.emit()`, and displays the resulting output:
+
+### Example 1: Minimal File
+
+A file with just a package and one case class (all examples use `zio.blocks.codegen.ir._` and `zio.blocks.codegen.emit._` imports):
+
+```scala
+import zio.blocks.codegen.ir._
+import zio.blocks.codegen.emit._
+
+val minimal = ScalaFile(
+  packageDecl = PackageDecl("com.example"),
+  types = List(
+    CaseClass(
+      name = "Empty",
+      fields = Nil
+    )
+  )
+)
+```
+
+Emits:
+
+```scala
+import zio.blocks.codegen.emit._
+ScalaEmitter.emit(minimal, EmitterConfig())
+// res6: String = """package com.example
+// 
+// case class Empty()
+// """
+```
+
+### Example 2: File with Multiple Types
+
+A file with a sealed trait and case classes:
+
+```scala
+import zio.blocks.codegen.ir._
+import zio.blocks.codegen.emit._
+
+val multiType = ScalaFile(
+  packageDecl = PackageDecl("com.payment"),
+  imports = List(Import.WildcardImport("zio")),
+  types = List(
+    SealedTrait(
+      name = "PaymentMethod",
+      cases = List(
+        SealedTraitCase.CaseClassCase(
+          CaseClass(
+            "Card",
+            List(Field("cardNumber", TypeRef.String))
+          )
+        ),
+        SealedTraitCase.CaseObjectCase("Cash")
+      )
+    )
+  )
+)
+```
+
+Emits:
+
+```scala
+import zio.blocks.codegen.emit._
+ScalaEmitter.emit(multiType, EmitterConfig())
+// res8: String = """package com.payment
+// 
+// import zio.*
+// 
+// sealed trait PaymentMethod
+// 
+// object PaymentMethod {
+//   case class Card(
+//     cardNumber: String,
+//   ) extends PaymentMethod
+//   case object Cash extends PaymentMethod
+// }
+// """
+```
+
+### Example 3: File with Imports and Type Parameters
+
+A file demonstrating generic types and selective imports:
+
+```scala
+import zio.blocks.codegen.ir._
+import zio.blocks.codegen.emit._
+
+val generic = ScalaFile(
+  packageDecl = PackageDecl("com.containers"),
+  imports = List(
+    Import.SingleImport("scala.collection", "Seq"),
+    Import.WildcardImport("zio")
+  ),
+  types = List(
+    CaseClass(
+      name = "Wrapper",
+      fields = List(
+        Field("items", TypeRef("Seq", List(TypeRef("T"))))
+      ),
+      typeParams = List(TypeParam("T"))
+    )
+  )
+)
+```
+
+Emits:
+
+```scala
+import zio.blocks.codegen.emit._
+ScalaEmitter.emit(generic, EmitterConfig())
+// res10: String = """package com.containers
+// 
+// import scala.collection.Seq
+// import zio.*
+// 
+// case class Wrapper[T](
+//   items: Seq[T],
+// )
+// """
+```