0
# Clojure
1

2
Clojure is a dynamic, general-purpose programming language that combines the approachability and interactive development of a scripting language with an efficient and robust infrastructure for multithreaded programming. This package contains the core Clojure runtime environment and standard library, providing a modern Lisp dialect that runs on the Java Virtual Machine (JVM). It features immutable data structures, a powerful macro system, functional programming paradigms, seamless Java interoperability, and built-in support for concurrent programming through software transactional memory, agents, and atoms.
3

4
## Package Information
5

6
- **Package Name**: org.clojure:clojure
7
- **Package Type**: maven
8
- **Language**: Clojure/Java
9
- **Installation**: Add to Maven `pom.xml`:
10

11
```xml
12
<dependency>
13
    <groupId>org.clojure</groupId>
14
    <artifactId>clojure</artifactId>
15
    <version>1.12.0</version>
16
</dependency>
17
```
18

19
For Leiningen:
20
```clojure
21
[org.clojure/clojure "1.12.0"]
22
```
23

24
## Core Imports
25

26
```clojure
27
(ns your.namespace
28
  (:require [clojure.string :as str]
29
            [clojure.set :as set] 
30
            [clojure.walk :as walk]
31
            [clojure.java.io :as io]
32
            [clojure.math :as math]
33
            [clojure.edn :as edn]
34
            [clojure.zip :as zip]
35
            [clojure.datafy :as datafy]
36
            [clojure.stacktrace :as st]
37
            [clojure.inspector :as inspect]))
38
```
39

40
The `clojure.core` namespace is automatically available in all Clojure code.
41

42
## Basic Usage
43

44
```clojure
45
;; Data structures are immutable by default
46
(def data {:name "Alice" :age 30 :languages ["Clojure" "Java"]})
47

48
;; Functional programming with collections
49
(def numbers [1 2 3 4 5])
50
(def doubled (map #(* 2 %) numbers))
51
(def evens (filter even? numbers))
52

53
;; Working with maps
54
(def updated-data (assoc data :email "alice@example.com"))
55
(def name (get data :name))
56

57
;; Concurrency with atoms
58
(def counter (atom 0))
59
(swap! counter inc)
60
@counter ; => 1
61

62
;; List comprehension equivalent
63
(for [x (range 10)
64
      :when (even? x)]
65
  (* x x))
66
```
67

68
## Architecture
69

70
Clojure is built around several key design principles:
71

72
- **Immutable Data Structures**: All core data structures (lists, vectors, maps, sets) are immutable by default
73
- **Functional Programming**: First-class functions, higher-order functions, and emphasis on pure functions
74
- **Lisp Syntax**: Homoiconic syntax where code is data, enabling powerful macro systems
75
- **JVM Integration**: Seamless interoperability with Java libraries and the JVM ecosystem
76
- **Concurrency Primitives**: Built-in support for concurrent programming through STM, agents, and atoms
77
- **Lazy Evaluation**: Lazy sequences for efficient handling of large or infinite data sets
78

79
## Capabilities
80

81
### Core Language Features
82

83
Fundamental language constructs including data structures, control flow, functions, and macros that form the foundation of Clojure programming.
84

85
```clojure { .api }
86
;; Data structure constructors
87
(list & items) ; => Creates a list
88
(vector & args) ; => Creates a vector  
89
(hash-map & keyvals) ; => Creates a hash map
90
(hash-set & keys) ; => Creates a hash set
91

92
;; Core sequence operations
93
(first coll) ; => First item in collection
94
(rest coll) ; => All but first item
95
(cons x seq) ; => New sequence with x prepended
96
(conj coll & xs) ; => Add items to collection
97
```
98

99
[Core Language Features](./core-language.md)
100

101
### Sequence Operations
102

103
Comprehensive collection processing functions for transforming, filtering, and manipulating sequences with lazy evaluation.
104

105
```clojure { .api }
106
(map f & colls) ; => Apply function to each element
107
(filter pred coll) ; => Lazy sequence of items where pred is true
108
(reduce f coll) ; => Reduce collection using function
109
(take n coll) ; => First n items
110
(drop n coll) ; => All but first n items
111
```
112

113
[Sequence Operations](./sequences.md)
114

115
### Data Structures and Collections
116

117
Immutable, persistent data structures including vectors, maps, sets, and their manipulation functions.
118

119
```clojure { .api }
120
;; Map operations
121
(get map key) ; => Value for key
122
(assoc map key val & kvs) ; => New map with associations
123
(dissoc map & keys) ; => New map without keys
124
(update m k f & args) ; => Update value at key using function
125

126
;; Collection predicates
127
(vector? x) ; => True if x is a vector
128
(map? x) ; => True if x is a map
129
(seq? x) ; => True if x is a sequence
130
```
131

132
[Data Structures](./data-structures.md)
133

134
### Concurrency and State Management
135

136
Safe concurrent programming with atoms, refs, agents, and software transactional memory.
137

138
```clojure { .api }
139
;; Atoms for synchronous updates
140
(atom x & opts) ; => Create atomic reference
141
(swap! atom f & args) ; => Atomically update using function
142
(reset! atom newval) ; => Set new value
143

144
;; Refs for coordinated updates  
145
(ref x & opts) ; => Create transactional reference
146
(dosync & exprs) ; => Execute in transaction
147
```
148

149
[Concurrency](./concurrency.md)
150

151
### String Processing
152

153
Comprehensive string manipulation utilities through the clojure.string namespace.
154

155
```clojure { .api }
156
(clojure.string/join separator coll) ; => Join collection with separator
157
(clojure.string/split s regex) ; => Split string on regex
158
(clojure.string/replace s match replacement) ; => Replace all matches
159
(clojure.string/trim s) ; => Remove leading/trailing whitespace
160
```
161

162
[String Processing](./strings.md)
163

164
### Control Flow and Macros
165

166
Advanced control structures, conditional execution, and macro system for metaprogramming.
167

168
```clojure { .api }
169
;; Conditional macros
170
(when test & then) ; => Execute when test is true
171
(if-not test then else) ; => Inverted conditional
172
(cond & clauses) ; => Multi-branch conditional
173

174
;; Macro definition
175
(defmacro name doc-string? attr-map? [params*] body)
176
```
177

178
[Control Flow and Macros](./control-flow.md)
179

180
### Java Interoperability
181

182
Seamless integration with Java classes, methods, and the broader JVM ecosystem.
183

184
```clojure { .api }
185
;; Java interop syntax
186
(.method object args*) ; => Call instance method
187
(ClassName/staticMethod args*) ; => Call static method
188
(new ClassName args*) ; => Create new instance
189
(import 'java.util.Date) ; => Import Java class
190
```
191

192
[Java Interop](./java-interop.md)
193

194
### I/O and File Operations  
195

196
File system operations, stream processing, and I/O utilities through clojure.java.io.
197

198
```clojure { .api }
199
(slurp f & opts) ; => Read entire file as string
200
(spit f content & opts) ; => Write content to file  
201
(clojure.java.io/reader source) ; => Create BufferedReader
202
(clojure.java.io/writer dest) ; => Create BufferedWriter
203
```
204

205
[I/O Operations](./io.md)
206

207
### Mathematical Functions
208

209
Comprehensive mathematical functions and constants through the clojure.math namespace.
210

211
```clojure { .api }
212
;; Mathematical constants
213
clojure.math/E    ; => Euler's number e
214
clojure.math/PI   ; => Pi constant
215

216
;; Trigonometric functions
217
(clojure.math/sin a) ; => Sine of angle in radians
218
(clojure.math/cos a) ; => Cosine of angle in radians
219
(clojure.math/tan a) ; => Tangent of angle in radians
220

221
;; Exponential and logarithmic
222
(clojure.math/exp a) ; => e raised to power a
223
(clojure.math/log a) ; => Natural logarithm of a
224
(clojure.math/pow a b) ; => a raised to power b
225
```
226

227
[Mathematical Functions](./math.md)
228

229
### Data Structure Utilities
230

231
Generic tree traversal, functional zippers, and data transformation utilities.
232

233
```clojure { .api }
234
;; Tree walking (clojure.walk)
235
(clojure.walk/postwalk f form) ; => Post-order traversal
236
(clojure.walk/prewalk f form) ; => Pre-order traversal
237
(clojure.walk/keywordize-keys m) ; => String keys to keywords
238

239
;; Functional zippers (clojure.zip)  
240
(clojure.zip/vector-zip root) ; => Zipper for nested vectors
241
(clojure.zip/down loc) ; => Navigate to first child
242
(clojure.zip/edit loc f & args) ; => Edit node at location
243

244
;; Data transformation (clojure.datafy)
245
(clojure.datafy/datafy x) ; => Transform object to data
246
```
247

248
[Data Structure Utilities](./data-utilities.md)
249

250
### Data Format Processing
251

252
Utilities for EDN parsing, UUID handling, and XML processing.
253

254
```clojure { .api }
255
;; EDN format (clojure.edn)
256
(clojure.edn/read-string s) ; => Parse EDN string
257
(clojure.edn/read stream) ; => Read EDN from stream
258

259
;; UUID support (clojure.uuid)
260
#uuid "550e8400-e29b-41d4-a716-446655440000" ; => UUID literal
261

262
;; XML processing (clojure.xml)
263
(clojure.xml/parse source) ; => Parse XML to nested maps
264
(clojure.xml/emit element) ; => Emit XML from data
265
```
266

267
[Data Format Processing](./formats.md)
268

269
### Development Tools
270

271
Debugging, inspection, and code generation utilities.
272

273
```clojure { .api }
274
;; Stack trace analysis (clojure.stacktrace)
275
(clojure.stacktrace/print-cause-trace t) ; => Print exception chain
276
(clojure.stacktrace/root-cause t) ; => Get root cause exception
277

278
;; Data inspection (clojure.inspector)  
279
(clojure.inspector/inspect data) ; => Graphical data inspector
280
(clojure.inspector/inspect-tree data) ; => Tree view inspector
281

282
;; Code templates (clojure.template)
283
(clojure.template/do-template argv expr & values) ; => Generate repetitive code
284
```
285

286
[Development Tools](./dev-tools.md)
287

288
### Testing Framework
289

290
Comprehensive unit testing framework through clojure.test namespace.
291

292
```clojure { .api }
293
(deftest name & body) ; => Define test function
294
(is form) ; => Assert that form is true
295
(testing string & body) ; => Group assertions with description
296
(run-tests & namespaces) ; => Execute tests
297
```
298

299
[Testing](./testing.md)
300

301
## Types
302

303
```clojure { .api }
304
;; Core data types (all immutable)
305
java.lang.Object ; Base type for all Clojure values
306
clojure.lang.IPersistentList ; List interface
307
clojure.lang.IPersistentVector ; Vector interface  
308
clojure.lang.IPersistentMap ; Map interface
309
clojure.lang.IPersistentSet ; Set interface
310
clojure.lang.ISeq ; Sequence interface
311
clojure.lang.Keyword ; Keyword type
312
clojure.lang.Symbol ; Symbol type
313

314
;; Reference types for concurrency
315
clojure.lang.Atom ; Atomic reference
316
clojure.lang.Ref ; Transactional reference
317
clojure.lang.Agent ; Asynchronous reference
318
clojure.lang.Var ; Variable binding
319

320
;; Function types
321
clojure.lang.IFn ; Function interface
322
clojure.lang.MultiFn ; Multimethod
323
```