0
# Shapeless
1

2
Shapeless is a comprehensive generic programming library for Scala that enables type-safe, compile-time generic programming through type classes and dependent types. It provides powerful abstractions for working with heterogeneous lists, coproducts, generic representations, and automatic derivation of type class instances, allowing developers to eliminate boilerplate code while maintaining full type safety.
3

4
## Package Information
5

6
- **Package Name**: com.chuusai:shapeless_2.12
7
- **Package Type**: Maven (SBT)
8
- **Language**: Scala
9
- **Installation**: `libraryDependencies += "com.chuusai" %% "shapeless" % "2.3.13"`
10

11
## Core Imports
12

13
```scala
14
import shapeless._
15
```
16

17
For specific functionality:
18

19
```scala
20
import shapeless.{HList, ::, HNil, Generic, Coproduct, :+:, CNil}
21
import shapeless.ops.hlist._
22
import shapeless.ops.coproduct._
23
import shapeless.syntax.hlist._
24
import shapeless.syntax.coproduct._
25
import shapeless.labelled.FieldType
26
import shapeless.tag.@@
27
```
28

29
Common syntax extensions:
30

31
```scala
32
import shapeless.syntax.singleton._  // Narrow type literals
33
import shapeless.syntax.std.tuple._  // Tuple conversions
34
import shapeless.syntax.std.function._  // Function conversions
35
```
36

37
## Basic Usage
38

39
```scala
40
import shapeless._
41

42
// Define a case class
43
case class Person(name: String, age: Int, active: Boolean)
44

45
// Get generic representation
46
val gen = Generic[Person]
47
val person = Person("Alice", 30, true)
48

49
// Convert to HList
50
val hlist = gen.to(person)  // String :: Int :: Boolean :: HNil
51

52
// Access elements by type
53
val name: String = hlist.select[String]
54
val age: Int = hlist.select[Int]
55

56
// Convert back to case class
57
val reconstructed = gen.from(hlist)
58

59
// Work with heterogeneous lists directly
60
val mixed: String :: Int :: Boolean :: HNil = "test" :: 42 :: true :: HNil
61
val length = mixed.length  // Nat._3 (compile-time known)
62
val head = mixed.head      // "test"
63
val tail = mixed.tail      // Int :: Boolean :: HNil
64
```
65

66
## Architecture
67

68
Shapeless is built around several key architectural concepts:
69

70
- **Type-Level Programming**: Computations performed at compile-time using Scala's type system
71
- **Heterogeneous Data Structures**: Collections that can contain different types while preserving type information
72
- **Generic Representations**: Automatic conversion between user-defined types and generic forms
73
- **Dependent Types**: Types that depend on values, enabling precise type-level constraints
74
- **Automatic Derivation**: Compile-time generation of type class instances using macros
75

76
This design enables zero-runtime-cost abstractions and ensures that all type relationships are verified at compile time, making it impossible to access non-existent fields or perform invalid operations.
77

78
## Capabilities
79

80
### Core Type System and Infrastructure
81

82
Essential type operators, constraints, and dependent types that form the foundation of Shapeless. Includes identity types, logical operators, type inequalities, and basic utilities that underpin all other functionality.
83

84
```scala { .api }
85
type Id[+T] = T
86
type Const[C] = { type λ[T] = C }
87

88
// Type inequalities
89
trait =:!=[A, B] extends Serializable
90
trait <:!<[A, B] extends Serializable
91

92
// Logical type operators
93
type ¬[T] = T => Nothing
94
type ¬¬[T] = ¬[¬[T]]
95
type ∧[T, U] = T with U
96
type ∨[T, U] = ¬[¬[T] ∧ ¬[U]]
97

98
// Type-lambda helpers for context bounds
99
type |∨|[T, U] = { type λ[X] = ¬¬[X] <:< (T ∨ U) }
100
type |¬|[T] = { type λ[U] = U <:!< T }
101

102
// Quantifiers
103
type ∃[P[_]] = P[T] forSome { type T }
104
type ∀[P[_]] = ¬[∃[({ type λ[X] = ¬[P[X]]})#λ]]
105

106
// Dependent function types
107
trait DepFn0 { type Out; def apply(): Out }
108
trait DepFn1[T] { type Out; def apply(t: T): Out }
109
trait DepFn2[T, U] { type Out; def apply(t: T, u: U): Out }
110

111
// Macro-based cached implicit resolution
112
def cachedImplicit[T]: T = macro CachedImplicitMacros.cachedImplicitImpl[T]
113
```
114

115
### HLists and Heterogeneous Collections
116

117
Core heterogeneous data structures that can contain elements of different types while preserving complete type information at compile time. Provides extensive operations for construction, access, and transformation.
118

119
```scala { .api }
120
sealed trait HList
121
final case class ::[+H, +T <: HList](head: H, tail: T) extends HList
122
sealed trait HNil extends HList
123

124
// Construction and access
125
def apply[T](t: T): T :: HNil
126
def select[U]: U  // Select element by type
127
def at[N <: Nat]: Out  // Access by position
128
```
129

130
[HLists and Heterogeneous Collections](./hlist-collections.md)
131

132
### Coproducts and Union Types
133

134
Type-safe sum types representing "one of" relationships, enabling exhaustive pattern matching and safe union operations. The dual concept to HLists for modeling exclusive alternatives.
135

136
```scala { .api }
137
sealed trait Coproduct
138
sealed trait :+:[+H, +T <: Coproduct] extends Coproduct
139
final case class Inl[+H, +T <: Coproduct](head: H) extends (H :+: T)
140
final case class Inr[+H, +T <: Coproduct](tail: T) extends (H :+: T)
141

142
// Injection and selection  
143
def inject[I]: I => Coproduct
144
def select[T]: Option[T]
145
```
146

147
[Coproducts and Union Types](./coproduct-unions.md)
148

149
### Generic Programming and Automatic Derivation
150

151
The core value proposition of Shapeless - automatic derivation of type class instances by converting between user-defined types and generic representations. Eliminates boilerplate code while maintaining type safety.
152

153
```scala { .api }
154
trait Generic[A] {
155
  type Repr
156
  def to(a: A): Repr
157
  def from(repr: Repr): A
158
}
159

160
trait LabelledGeneric[A] {
161
  type Repr
162
  def to(a: A): Repr  // Preserves field names as types
163
  def from(repr: Repr): A
164
}
165
```
166

167
[Generic Programming and Automatic Derivation](./generic-derivation.md)
168

169
### Records and Named Field Access
170

171
Structured data access using field names rather than positions, providing a more user-friendly interface for working with case classes and other product types through symbolic field access.
172

173
```scala { .api }
174
type FieldType[K, +V] = V @@ KeyTag[K, V]
175

176
object field[K] extends FieldOf[K]
177
def selectDynamic(field: String): FieldType[K, V]
178
def updatedDynamic[V](field: String, value: V): Record
179
```
180

181
[Records and Named Field Access](./records-fields.md)
182

183
### Optics - Lenses and Prisms
184

185
Functional programming patterns for composable data access and transformation. Provides type-safe navigation and modification of nested data structures with automatic derivation.
186

187
```scala { .api }
188
case class Lens[S, A](get: S => A, set: S => A => S) {
189
  def modify(s: S)(f: A => A): S
190
}
191

192
case class Prism[S, A](get: S => Option[A], set: S => A => S) {
193
  def modifyOption(s: S)(f: A => A): Option[S]
194
}
195
```
196

197
[Optics - Lenses and Prisms](./optics-lenses.md)
198

199
### Polymorphic Functions and Type-Level Programming
200

201
Advanced type-level computations including polymorphic functions that work across different types, natural transformations, type-level arithmetic with natural numbers, and sophisticated type-level logic.
202

203
```scala { .api }
204
trait Poly {
205
  def apply[A](a: A)(implicit cse: Case.Aux[this.type, A :: HNil, Out]): Out
206
}
207

208
trait ~>[F[_], G[_]] {  // Natural transformation
209
  def apply[A](fa: F[A]): G[A]
210
}
211

212
sealed trait Nat { type N <: Nat }
213
trait Succ[P <: Nat] extends Nat
214
```
215

216
[Polymorphic Functions and Type-Level Programming](./poly-typelevel.md)
217

218
### Advanced Features and Utilities
219

220
Specialized features including functional cursors (zippers), tuple operations, compile-time testing utilities, annotation processing, runtime type information, and various conversion utilities for integration with Scala's standard library.
221

222
```scala { .api }
223
case class Zipper[C, L <: HList](left: L, focus: C, right: L)
224

225
def typed[T](t: => T): Unit  // Assert expression has type T
226
def typeError(t: String): Unit  // Assert code fails to type check
227

228
trait Typeable[T] {
229
  def cast(any: Any): Option[T]
230
}
231
```
232

233
[Advanced Features and Utilities](./advanced-utilities.md)