0
# Alleycats Core
1

2
Alleycats Core provides functional programming type class instances and abstractions that extend Cats but don't satisfy the strict mathematical laws required by Cats core. It offers pragmatic solutions for real-world functional programming scenarios while maintaining the same modular structure and cross-platform compatibility.
3

4
## Package Information
5

6
- **Package Name**: alleycats-core_2.13
7
- **Package Type**: Maven
8
- **Language**: Scala
9
- **Installation**: `libraryDependencies += "org.typelevel" %% "alleycats-core" % "2.13.0"`
10
- **Cross-Platform**: JVM, Scala.js, Scala Native
11

12
## Core Imports
13

14
```scala
15
import alleycats._              // Core type classes
16
import alleycats.std.all._     // All standard library instances  
17
import alleycats.syntax.all._  // All syntax extensions
18
```
19

20
Selective imports:
21
```scala
22
import alleycats.{Pure, EmptyK, Extract}        // Specific type classes
23
import alleycats.std.map._                      // Map instances only
24
import alleycats.syntax.extract._               // Extract syntax only
25
```
26

27
## Basic Usage
28

29
```scala
30
import alleycats._
31
import alleycats.std.all._
32
import alleycats.syntax.all._
33
import cats.syntax.all._
34

35
// Using Pure for lifting values
36
def liftToOption[A](value: A): Option[A] = Pure[Option].pure(value)
37

38
// Using EmptyK for creating empty collections
39
val emptyMap: Map[String, Int] = EmptyK[Map[String, *]].empty[Int]
40
val emptyList: List[String] = EmptyK[List].empty[String]
41

42
// Using Extract for getting values from contexts
43
import scala.util.Try
44
val tryValue = Try(42)
45
// Note: Extract[Try] requires alleycats instance
46
// val extracted = tryValue.extract  // Gets the value or throws
47

48
// Using Empty with standard types
49
import cats.implicits._
50
val emptyString = Empty[String].empty  // From Monoid instance
51
```
52

53
## Architecture
54

55
Alleycats Core is organized into several key modules:
56

57
- **Core Type Classes**: Pure, EmptyK, Extract, Empty, Zero, One, ConsK for essential functional abstractions
58
- **Utility Classes**: ReferentialEq, SystemIdentityHash for identity-based operations  
59
- **Standard Instances**: Type class instances for Map, Set, List, Option, Try, Future, Iterable
60
- **Syntax Extensions**: Convenient methods for working with type classes
61
- **Compatibility Layer**: Version-specific implementations for Scala 2.12/2.13+
62

63
## Capabilities
64

65
### Core Type Classes
66

67
Essential type classes that provide useful abstractions for functional programming.
68

69
```scala
70
// Pure - lift values into contexts
71
Pure[F].pure[A](a: A): F[A]
72

73
// EmptyK - create empty higher-kinded types  
74
EmptyK[F].empty[A]: F[A]
75

76
// Extract - extract values from contexts
77
Extract[F].extract[A](fa: F[A]): A
78

79
// Empty - types with empty values
80
Empty[A].empty: A
81
Empty[A].isEmpty(a: A): Boolean
82

83
// Zero and One - types with zero/one values
84
Zero[A].zero: A  
85
One[A].one: A
86

87
// ConsK - cons elements to front of structures
88
ConsK[F].cons[A](hd: A, tl: F[A]): F[A]
89
```
90

91
[Core Type Classes](./core-typeclasses.md)
92

93
### Utility Type Classes
94

95
Specialized type classes for identity-based operations.
96

97
```scala
98
// ReferentialEq - referential equality
99
ReferentialEq[A <: AnyRef]: Eq[A]  // Uses eq for comparison
100

101
// SystemIdentityHash - identity-based hashing
102
SystemIdentityHash[A <: AnyRef]: Hash[A]  // Uses System.identityHashCode
103
```
104

105
[Utility Type Classes](./utility-typeclasses.md)
106

107
### Standard Library Instances
108

109
Type class instances for Scala standard library types that don't satisfy strict categorical laws.
110

111
```scala
112
// Map instances
113
Traverse[Map[K, *]]
114
TraverseFilter[Map[K, *]]
115
EmptyK[Map[K, *]]
116

117
// Set instances (non-lawful but useful)
118
Monad[Set] & Alternative[Set] & Traverse[Set] & TraverseFilter[Set]
119

120
// List instances
121
EmptyK[List]
122
ConsK[List]
123

124
// Option instances
125
EmptyK[Option]
126

127
// Try instances (non-lawful Monad)
128
Bimonad[Try]
129

130
// Future instances
131
Pure[Future]
132

133
// Iterable instances
134
Traverse[Iterable]
135
TraverseFilter[Iterable]
136
```
137

138
[Standard Library Instances](./standard-instances.md)
139

140
### Syntax Extensions
141

142
Convenient method extensions for type classes.
143

144
```scala
145
// Extract syntax
146
fa.extract  // Extract value from context
147

148
// Empty syntax  
149
a.isEmpty   // Check if value is empty
150
a.nonEmpty  // Check if value is non-empty
151

152
// Foldable syntax
153
fa.foreach(f)  // Side-effecting foreach
154
```
155

156
[Syntax Extensions](./syntax.md)
157

158
## Types
159

160
```scala { .api }
161
// Core type classes
162
trait Pure[F[_]] {
163
  def pure[A](a: A): F[A]
164
}
165

166
trait EmptyK[F[_]] {
167
  def empty[A]: F[A]
168
  def synthesize[A]: Empty[F[A]]
169
}
170

171
trait Extract[F[_]] {
172
  def extract[A](fa: F[A]): A
173
}
174

175
trait Empty[A] {
176
  def empty: A
177
  def isEmpty(a: A)(implicit ev: Eq[A]): Boolean
178
  def nonEmpty(a: A)(implicit ev: Eq[A]): Boolean
179
}
180

181
trait Zero[A] {
182
  def zero: A
183
  def isZero(a: A)(implicit ev: Eq[A]): Boolean
184
  def nonZero(a: A)(implicit ev: Eq[A]): Boolean
185
}
186

187
trait One[A] {
188
  def one: A
189
  def isOne(a: A)(implicit ev: Eq[A]): Boolean
190
  def nonOne(a: A)(implicit ev: Eq[A]): Boolean
191
}
192

193
trait ConsK[F[_]] {
194
  def cons[A](hd: A, tl: F[A]): F[A]
195
}
196

197
trait ReferentialEq[A <: AnyRef] extends Eq[A] {
198
  def eqv(x: A, y: A): Boolean
199
}
200

201
trait SystemIdentityHash[A <: AnyRef] extends ReferentialEq[A] with Hash[A] {
202
  override def hash(a: A): Int
203
}
204
```