@zio.dev/zio-blocks 0.0.33 → 0.0.55

package/{path-interpolator.md → reference/schema/path-interpolator.md}

@@ -3,13 +3,20 @@ id: path-interpolator
 title: "Path Interpolator"
 ---
 
+:::note
+To use the path interpolator `p"..."`, you must import the schema package: `import zio.blocks.schema._`
+:::
+
 The path interpolator `p"..."` is a compile-time string interpolator for constructing `DynamicOptic` instances in ZIO Blocks. It provides a clean, concise syntax for building optic paths that navigate through complex data structures, with all parsing and validation happening at compile time for zero runtime overhead.
 
 **Why use the path interpolator?**
 
 Instead of manually constructing optics like this:
 
+
 ```scala
+import zio.blocks.schema._
+
 DynamicOptic(Vector(
   DynamicOptic.Node.Field("users"),
   DynamicOptic.Node.Elements,
@@ -20,6 +27,8 @@ DynamicOptic(Vector(
 You can write:
 
 ```scala
+import zio.blocks.schema._
+
 p".users[*].email"
 ```
 
@@ -46,9 +55,11 @@ val path = p".users[0].name"
 
 ## Syntax Reference
 
+This section documents the complete path syntax with examples for each component type.
+
 ### Field Access
 
-Access fields in records using dot notation. The leading dot is optional.
+Access fields in records using dot notation. The leading dot is optional:
 
 ```scala
 // With leading dot
@@ -64,7 +75,7 @@ p".user.address.street"
 // Equivalent to: Field("user") → Field("address") → Field("street")
 ```
 
-**Special cases:**
+Field names can also include special characters and keywords:
 
 ```scala
 p"._private"       // Fields starting with underscore
@@ -77,7 +88,7 @@ p".true"           // Keywords as field names (true, false, null)
 
 Access sequence elements by index, multiple indices, or ranges.
 
-**Single index:**
+To access a single element by index:
 
 ```scala
 p"[0]"             // AtIndex(0)
@@ -85,7 +96,7 @@ p"[42]"            // AtIndex(42)
 p"[2147483647]"    // AtIndex(Int.MaxValue)
 ```
 
-**Multiple indices:**
+To access multiple elements at specific indices:
 
 ```scala
 p"[0,1,2]"         // AtIndices(Seq(0, 1, 2))
@@ -93,7 +104,7 @@ p"[0, 2, 5]"       // AtIndices(Seq(0, 2, 5)) - spaces allowed
 p"[5,2,8,1]"       // Order preserved
 ```
 
-**Ranges:**
+To select a range of consecutive elements:
 
 ```scala
 p"[0:5]"           // AtIndices(Seq(0, 1, 2, 3, 4))
@@ -105,14 +116,14 @@ p"[10:5]"          // AtIndices(Seq.empty) - inverted range
 
 ### Element Selectors
 
-Select all elements in a sequence using wildcard syntax.
+Select all elements in a sequence using wildcard syntax:
 
 ```scala
 p"[*]"             // Elements - all elements
 p"[:*]"            // Elements - alternative syntax
 ```
 
-**Chained selectors:**
+To navigate nested sequences:
 
 ```scala
 p"[*][*]"          // Nested sequences: all elements of all elements
@@ -123,7 +134,7 @@ p"[*][0]"          // First element of each sequence
 
 Access map values by key, where keys can be strings, integers, booleans, or characters.
 
-**String keys:**
+To use string keys:
 
 ```scala
 p"""{"host"}"""              // AtMapKey(String("host"))
@@ -133,7 +144,7 @@ p"""{"🎉"}"""                 // Emoji keys
 p"""{""}"""                  // Empty string key
 ```
 
-**Integer keys:**
+To use integer keys:
 
 ```scala
 p"{42}"                      // AtMapKey(Int(42))
@@ -143,14 +154,14 @@ p"{2147483647}"              // AtMapKey(Int.MaxValue)
 p"{-2147483648}"             // AtMapKey(Int.MinValue)
 ```
 
-**Boolean keys:**
+To use boolean keys:
 
 ```scala
 p"{true}"                    // AtMapKey(Boolean(true))
 p"{false}"                   // AtMapKey(Boolean(false))
 ```
 
-**Char keys:**
+To use character keys:
 
 ```scala
 p"{'a'}"                     // AtMapKey(Char('a'))
@@ -158,7 +169,7 @@ p"{' '}"                     // AtMapKey(Char(' '))
 p"{'9'}"                     // AtMapKey(Char('9'))
 ```
 
-**Multiple keys:**
+To use multiple keys of the same or mixed types:
 
 ```scala
 p"""{"foo", "bar", "baz"}""" // AtMapKeys(Seq(...))
@@ -172,7 +183,7 @@ p"""{"s", 'c', 42, true}"""  // All supported types
 
 ### Map Selectors
 
-Select all keys or all values in a map.
+Select all keys or all values in a map:
 
 ```scala
 p"{*}"             // MapValues - all values
@@ -180,7 +191,7 @@ p"{:*}"            // MapValues - alternative syntax
 p"{*:}"            // MapKeys - all keys
 ```
 
-**Examples:**
+To apply map selectors to nested maps:
 
 ```scala
 p"{*}{*}"          // Nested maps: all values of all values
@@ -189,7 +200,7 @@ p"{*:}{*:}"        // All keys of all keys
 
 ### Variant Case Access
 
-Navigate into a specific variant case using angle brackets.
+Navigate into a specific variant case using angle brackets:
 
 ```scala
 p"<Left>"          // Case("Left")
@@ -198,7 +209,7 @@ p"<Some>"          // Case("Some")
 p"<None>"          // Case("None")
 ```
 
-**Special cases:**
+Variant case names can include special characters and keywords:
 
 ```scala
 p"<_Empty>"        // Cases starting with underscore
@@ -206,7 +217,7 @@ p"<Case1>"         // Cases with digits
 p"<café>"          // Unicode case names
 ```
 
-**Chained cases:**
+To navigate nested variant cases:
 
 ```scala
 p"<A><B><C>"       // Nested variants
@@ -216,7 +227,7 @@ p"<A><B><C>"       // Nested variants
 
 Search for values matching a schema pattern anywhere in a data structure using the `#` prefix.
 
-**Nominal types:**
+To search for nominal types by name:
 
 ```scala
 p"#Person"         // Find all values of type Person
@@ -224,7 +235,7 @@ p"#User"           // Find all values of type User
 p"#Address"        // Find all values of type Address
 ```
 
-**Primitive types:**
+To search for primitive types:
 
 ```scala
 p"#string"         // Find all string values
@@ -233,7 +244,7 @@ p"#boolean"        // Find all boolean values
 p"#uuid"           // Find all UUID values
 ```
 
-**Structural records:**
+To search for records with specific field structures:
 
 ```scala
 p"#record { name: string }"                // Find records with a string 'name' field
@@ -241,13 +252,13 @@ p"#record { name: string, age: int }"      // Find records with both fields
 p"#record { items: list(Person) }"         // Nested schema
 ```
 
-**Structural variants:**
+To search for variants with specific case structures:
 
 ```scala
 p"#variant { Left: int, Right: string }"   // Find Either-like variants
 ```
 
-**Collections:**
+To search for collection types:
 
 ```scala
 p"#list(string)"                           // Find lists of strings
@@ -256,13 +267,15 @@ p"#map(string, int)"                       // Find maps from string to int
 p"#option(Person)"                         // Find optional Person values
 ```
 
-**Wildcard:**
+`set(...)` and `vector(...)` work as synonyms for `list(...)` — all three parse to the same `SchemaRepr.Sequence` pattern, since the pattern only cares about the element type, not which collection it comes from.
+
+To match any value regardless of type:
 
 ```scala
 p"#_"              // Find any value (matches everything)
 ```
 
-**Combined paths with search:**
+To combine path navigation with schema search:
 
 ```scala
 p".users#Person"               // Search for Person in users field
@@ -284,7 +297,7 @@ String and character literals support standard escape sequences:
 | `\"`   | `"`     | Double quote    |
 | `\\`   | `\`     | Backslash       |
 
-**Examples:**
+Here are some examples of escape sequences in use:
 
 ```scala
 p"""{"foo\nbar"}"""          // String key with newline
@@ -300,6 +313,8 @@ Combine different path elements to navigate complex nested structures.
 
 ### Field → Sequence
 
+Access sequence elements by index or range through a field:
+
 ```scala
 p".items[0]"                 // First item
 p".items[*]"                 // All items
@@ -309,6 +324,8 @@ p".items[0:5]"               // Items 0 through 4
 
 ### Field → Map
 
+Access map values by key through a field:
+
 ```scala
 p""".config{"host"}"""       // Map lookup
 p".settings{42}"             // Integer key
@@ -318,6 +335,8 @@ p".lookup{*:}"               // All map keys
 
 ### Field → Variant
 
+Navigate into variant cases through a field:
+
 ```scala
 p".result<Success>"          // Variant case
 p".response<Ok>"             // HTTP response variant
@@ -325,6 +344,8 @@ p".response<Ok>"             // HTTP response variant
 
 ### Nested Structures
 
+Combine different path elements to build complex navigation through nested data:
+
 ```scala
 // Record in sequence
 p".users[0].name"
@@ -345,6 +366,8 @@ p".response<Ok>.body"
 
 ### Deeply Nested Paths
 
+Chain multiple path operators for deeply nested data structures:
+
 ```scala
 // Complex nested navigation
 p""".root.children[*].metadata{"tags"}[0]"""
@@ -359,35 +382,47 @@ p""".a[0]{"k"}<V>.b[*]{*}.c{*:}"""
 
 ## Root and Empty Paths
 
+An empty path refers to the root of the data structure:
+
 ```scala
 p""                          // Empty path = root
-// Equivalent to: DynamicOptic.root
-// Equivalent to: DynamicOptic(Vector.empty)
 ```
 
 ## Compile-Time Safety
 
 The path interpolator **rejects runtime interpolation** to prevent unsafe dynamic path construction.
 
-**❌ This will fail to compile:**
+### Examples of Safety Checks
+
+Runtime interpolation will fail to compile:
 
 ```scala
+import zio.blocks.schema._
+
 val fieldName = "email"
 val path = p".$fieldName"
 // Error: Path interpolator does not support runtime arguments.
-//        Use only literal strings like p".field[0]"
+// error:
+// Path interpolator does not support runtime arguments. Use only literal strings like p".field[0]"
+// val path = p".$fieldName"
+//            ^^^^^^^^^^^^^
 ```
 
-**❌ This will also fail:**
+Array indices also cannot be interpolated at runtime:
 
 ```scala
+import zio.blocks.schema._
+
 val idx = 5
 val path = p"[$idx]"
 // Error: Path interpolator does not support runtime arguments.
-//        Use only literal strings like p".field[0]"
+// error:
+// Path interpolator does not support runtime arguments. Use only literal strings like p".field[0]"
+// val path = p"[$idx]"
+//            ^^^^^^^^^
 ```
 
-**✅ Use only literal strings:**
+Instead, use only literal strings at compile time:
 
 ```scala
 val path = p".users[0].email"  // ✓ Works
@@ -395,31 +430,46 @@ val path = p".users[0].email"  // ✓ Works
 
 ### Parse Error Examples
 
-Invalid syntax is caught at compile time:
+Invalid syntax is caught at compile time. Here are examples of common errors:
 
 ```scala
+import zio.blocks.schema._
+
 // Unterminated string
 p"""{"foo"""
-// Error: Unterminated string literal starting at position 1
+// Error: Unterminated string literal
 
-// Invalid escape sequence
+// Invalid escape sequence  
 p"""{"foo\x"}"""
-// Error: Invalid escape sequence '\x' at position 6
+// Error: Invalid escape sequence
 
 // Unexpected character
 p".field@"
-// Error: Unexpected character '@' at position 6
+// Error: Unexpected character '@'
 
 // Invalid identifier
 p"."
-// Error: Invalid identifier at position 1
+// Error: Invalid identifier
+// error: 
+// Unterminated string literal starting at position 1
+// error: 
+// Invalid escape sequence '\x' at position 6
+// error: 
+// Unexpected character '@' at position 6. Expected field, index, map, or variant accessor
+// error: 
+// Invalid identifier at position 1
+// error: 
+// Conflicting definitions:
+// val path: zio.blocks.schema.DynamicOptic in object MdocApp at line 14 and
+// val path: zio.blocks.schema.DynamicOptic in object MdocApp at line 114
+//
 ```
 
 ## Performance
 
 **Zero Runtime Overhead**
 
-All path parsing and validation occurs at **compile time**. The interpolator generates the exact same bytecode as manual `DynamicOptic` construction:
+All path parsing and validation occurs at **compile time**. The interpolator generates the exact same bytecode as manual `DynamicOptic` construction. Here's the comparison:
 
 ```scala
 // These produce identical bytecode:
@@ -436,8 +486,12 @@ There is **no runtime parsing**, **no reflection**, and **no performance penalty
 
 ## Examples
 
+This section shows practical examples of using the path interpolator with realistic data structures.
+
 ### Accessing Nested Fields
 
+To access deeply nested fields in a data structure:
+
 ```scala
 import zio.blocks.schema._
 
@@ -447,14 +501,18 @@ case class Person(name: String, age: Int, address: Address)
 // Access nested street field
 val streetPath = p".address.street"
 
-// Use with DynamicValue
-val person = DynamicValue.fromPerson(...)
+// Use with DynamicValue - example (requires actual DynamicValue instance)
+val person: DynamicValue = ???
 val street = person.get(streetPath)
 ```
 
 ### Working with Collections
 
+To work with sequences and access elements by index or range:
+
 ```scala
+import zio.blocks.schema._
+
 case class User(id: Int, email: String, tags: Seq[String])
 case class Company(name: String, users: Seq[User])
 
@@ -470,7 +528,11 @@ val specificUsersPath = p".users[0,2,5]"
 
 ### Map Lookups
 
+To work with map data structures and access values by key:
+
 ```scala
+import zio.blocks.schema._
+
 case class Config(
   settings: Map[String, String],
   ports: Map[Int, String]
@@ -491,13 +553,21 @@ val allPortsPath = p"ports{*:}"
 
 ### Variant Case Handling
 
+To navigate variant cases in your data structures:
+
 ```scala
+import zio.blocks.schema._
+
 sealed trait Result[+A]
 case class Success[A](value: A) extends Result[A]
 case class Failure(error: String) extends Result[Nothing]
 
 case class Response(result: Result[User])
+```
+
+Use paths to navigate into specific cases:
 
+```scala
 // Navigate into Success case
 val successValuePath = p".result<Success>.value"
 
@@ -507,7 +577,11 @@ val errorPath = p".result<Failure>.error"
 
 ### Real-World Example: API Response
 
+To extract specific data from complex nested API response structures:
+
 ```scala
+import zio.blocks.schema._
+
 case class Metadata(tags: Seq[String], version: Int)
 case class Item(id: String, data: String, metadata: Metadata)
 case class ApiResponse(
@@ -531,8 +605,12 @@ val apiKeyPath = p"""config{"api_key"}"""
 
 ## Before & After Comparison
 
+This comparison shows how the path interpolator simplifies optic path construction compared to manual approaches.
+
 ### Manual Construction (Before)
 
+Manual path construction requires verbose imports and careful construction:
+
 ```scala
 import zio.blocks.schema.DynamicOptic
 import zio.blocks.schema.DynamicOptic.Node
@@ -582,7 +660,7 @@ val path2 = p""".root.children[*].metadata{"tags"}[0]"""
 val path3 = p"""data{"foo", "bar", 42}"""
 ```
 
-**Benefits:**
+The path interpolator provides significant benefits:
 
 - **90% less code** for typical paths
 - **Easier to read** and understand intent
@@ -592,9 +670,15 @@ val path3 = p"""data{"foo", "bar", 42}"""
 
 ## Practical Usage Patterns
 
+These patterns demonstrate effective ways to use the path interpolator in real-world scenarios.
+
 ### Building Paths Dynamically (at Compile Time)
 
+While runtime variables are not supported, you can compose literal paths at compile time:
+
 ```scala
+import zio.blocks.schema._
+
 // You can't use runtime variables, but you can compose literal paths:
 val basePath = p".data.items"
 val emailPath = basePath(p"[*].email")
@@ -603,26 +687,31 @@ val emailPath = basePath(p"[*].email")
 
 ### Working with DynamicValue
 
+To navigate and extract values from dynamic data:
+
 ```scala
 import zio.blocks.schema._
 
-val data: DynamicValue = ...
+val data: DynamicValue = ???
 
 // Navigate and extract
 val value = data.get(p".users[0].email")
 
-// Update at path
-val updated = data.set(p".users[0].age", DynamicValue.fromInt(30))
+// Update at path (using appropriate constructor)
+val ageValue: DynamicValue = ???
+val updated = data.set(p".users[0].age", ageValue)
 ```
 
 ### Integration with Schema Optics
 
+To use path interpolators with schema-based optics:
+
 ```scala
 import zio.blocks.schema._
 
-case class User(name: String, email: String)
-object User extends CompanionOptics[User] {
-  implicit val schema: Schema[User] = Schema.derived
+case class UserRecord(name: String, email: String)
+object UserRecord extends CompanionOptics[UserRecord] {
+  implicit val schema: Schema[UserRecord] = Schema.derived
   
   // Use path interpolator for complex lenses
   val email = $(_.email)
@@ -634,23 +723,22 @@ val dynamicPath = p".email"
 
 ## Tips and Best Practices
 
-1. **Use the leading dot for clarity**: While optional, `p".field"` is more explicit than `p"field"`
+1. **Use the leading dot for clarity**: While optional, `p".field"` is more explicit than `p"field"`:
 
-2. **Leverage compile-time validation**: Let the compiler catch typos and syntax errors early
-
-3. **Compose paths when needed**: Break complex paths into reusable components
-   ```scala
+   ```scala mdoc:compile-only
    val userPath = p".users[0]"
    val emailPath = userPath(p".email")
    ```
 
-4. **Use raw strings for map keys**: Triple-quoted strings avoid escape hell
-   ```scala
+4. **Use raw strings for map keys**: Triple-quoted strings avoid escape hell:
+
+   ```scala mdoc:compile-only
    p"""config{"api.key"}"""  // Better than p"config{\"api.key\"}"
    ```
 
-5. **Document complex paths**: Add comments explaining what nested paths navigate
-   ```scala
+5. **Document complex paths**: Add comments explaining what nested paths navigate:
+
+   ```scala mdoc:compile-only
    // Get the first tag from each user's metadata
    val tagsPath = p".users[*].metadata.tags[0]"
    ```
@@ -670,29 +758,36 @@ These limitations ensure compile-time safety and zero runtime overhead.
 
 ```scala
 val optic = DynamicOptic.root.field("users").elements.field("email")
+// optic: DynamicOptic = DynamicOptic(
+//   IndexedSeq(Field("users"), Elements, Field("email"))
+// )
 println(optic)  // Output: .users[*].email
+// .users[*].email
 
 // The output can be copy-pasted into p"..."
 val same = p".users[*].email"
+// same: DynamicOptic = DynamicOptic(
+//   Vector(Field("users"), Elements, Field("email"))
+// )
 ```
 
 **Examples:**
 
-| DynamicOptic Construction                            | toString Output   |
-|------------------------------------------------------|-------------------|
-| `DynamicOptic.root.field("name")`                    | `.name`           |
-| `DynamicOptic.root.field("address").field("street")` | `.address.street` |
-| `DynamicOptic.root.caseOf("Some")`                                      | `<Some>`          |
-| `DynamicOptic.root.at(0)`                                               | `[0]`             |
-| `DynamicOptic.root.atIndices(0, 2, 5)`                                  | `[0,2,5]`         |
-| `DynamicOptic.elements`                                                 | `[*]`             |
-| `DynamicOptic.root.atKey("host")`                                       | `{"host"}`        |
-| `DynamicOptic.root.atKey(80)`                                           | `{80}`            |
-| `DynamicOptic.mapValues`                                                | `{*}`             |
-| `DynamicOptic.mapKeys`                                                  | `{*:}`            |
-| `DynamicOptic.wrapped`                                                  | `.~`              |
-| `DynamicOptic.root.searchSchema(SchemaRepr.Nominal("Person"))`          | `#Person`         |
-| `DynamicOptic.root.searchSchema(SchemaRepr.Primitive("string"))`        | `#string`         |
+| DynamicOptic Construction                            | Interpolator Syntax |
+|------------------------------------------------------|---------------------|
+| `DynamicOptic.root.field("name")`                    | `p".name"`           |
+| `DynamicOptic.root.field("address").field("street")` | `p".address.street"` |
+| `DynamicOptic.root.caseOf("Some")`                    | `p"<Some>"`          |
+| `DynamicOptic.root.at(0)`                             | `p"[0]"`             |
+| `DynamicOptic.root.atIndices(0, 2, 5)`                 | `p"[0,2,5]"`         |
+| `DynamicOptic.elements`                                | `p"[*]"`             |
+| `DynamicOptic.root.atKey("host")`                      | `p"{"host"}"`        |
+| `DynamicOptic.root.atKey(80)`                          | `p"{80}"`            |
+| `DynamicOptic.mapValues`                               | `p"{*}"`             |
+| `DynamicOptic.mapKeys`                                 | `p"{*:}"`            |
+| `DynamicOptic.wrapped`                                 | `p".~"`              |
+| `DynamicOptic.root.searchSchema(SchemaRepr.Nominal("Person"))` | `p"#Person"` |
+| `DynamicOptic.root.searchSchema(SchemaRepr.Primitive("string"))` | `p"#string"` |
 
 ## Summary