0
# Groovy NIO Extensions
1

2
Groovy NIO Extensions provides enhanced file system operations and path handling capabilities for Apache Groovy. This package extends Groovy's existing I/O functionality with modern Java NIO.2 features, enabling more efficient file system access, path manipulation, and stream operations with Groovy's characteristic closure-based programming model.
3

4
## Package Information
5

6
- **Package Name**: groovy-nio
7
- **Package Type**: maven
8
- **Language**: Java (Groovy)
9
- **Installation**: 
10
  ```gradle
11
  implementation 'org.codehaus.groovy:groovy-nio:3.0.25'
12
  ```
13
- **Maven**:
14
  ```xml
15
  <dependency>
16
    <groupId>org.codehaus.groovy</groupId>
17
    <artifactId>groovy-nio</artifactId>
18
    <version>3.0.25</version>
19
  </dependency>
20
  ```
21

22
## Core Imports
23

24
```groovy
25
import java.nio.file.Path
26
import java.nio.file.Paths
27
// Extension methods are automatically available on Path objects
28
```
29

30
## Basic Usage
31

32
```groovy
33
import java.nio.file.Path
34
import java.nio.file.Paths
35

36
// Create a path
37
Path myFile = Paths.get("example.txt")
38

39
// Write text to file
40
myFile.text = "Hello, World!"
41

42
// Read text from file
43
String content = myFile.getText()
44

45
// Append text
46
myFile << " Additional content"
47

48
// Process lines with closure
49
myFile.eachLine { line ->
50
    println line
51
}
52

53
// Directory traversal
54
Path myDir = Paths.get("my-directory")
55
myDir.eachFile { file ->
56
    println "Found: ${file.fileName}"
57
}
58
```
59

60
## Architecture
61

62
Groovy NIO Extensions is built around several key components:
63

64
- **Extension Methods**: The `NioExtensions` class provides static extension methods that are automatically applied to `java.nio.file.Path` objects
65
- **Closure Integration**: Extensive use of Groovy closures for resource management, iteration, and filtering operations
66
- **Writable Interface**: Integration with Groovy's `Writable` interface for streaming operations
67
- **Resource Management**: Automatic resource management using try-with-resources patterns
68
- **Charset Support**: Comprehensive character encoding support with optional BOM handling
69

70
## Capabilities
71

72
### File Reading and Writing
73

74
Core file I/O operations for reading and writing text, binary data, and objects to files. Provides both simple text operations and advanced charset handling.
75

76
```java { .api }
77
// Text operations
78
String getText(Path self);
79
String getText(Path self, String charset);
80
void write(Path self, String text);
81
void write(Path self, String text, String charset);
82
void setText(Path self, String text);
83

84
// Binary operations  
85
byte[] getBytes(Path self);
86
byte[] readBytes(Path self);
87
void setBytes(Path self, byte[] bytes);
88

89
// Line operations
90
List<String> readLines(Path self);
91
List<String> readLines(Path self, String charset);
92
```
93

94
[File I/O Operations](./file-io.md)
95

96
### File Appending Operations
97

98
Append data to existing files with support for text, binary data, and various input sources including streams and closures.
99

100
```java { .api }
101
// Text appending
102
void append(Path self, Object text);
103
void append(Path self, Object text, String charset);
104
Path leftShift(Path self, Object text);
105

106
// Binary appending
107
void append(Path self, byte[] bytes);
108
void append(Path self, InputStream stream);
109
Path leftShift(Path self, byte[] bytes);
110
```
111

112
[File Appending](./file-appending.md)
113

114
### Line Processing
115

116
Process files line-by-line with closures, including splitting, filtering, and transformation operations with charset support.
117

118
```java { .api }
119
<T> T eachLine(Path self, Closure<T> closure);
120
<T> T eachLine(Path self, String charset, Closure<T> closure);
121
<T> T splitEachLine(Path self, String regex, Closure<T> closure);
122
Writable filterLine(Path self, Closure closure);
123
```
124

125
[Line Processing](./line-processing.md)
126

127
### Directory Traversal
128

129
Traverse directory structures with filtering, sorting, and recursion options. Support for file type filtering and advanced traversal patterns.
130

131
```java { .api }
132
void eachFile(Path self, Closure closure);
133
void eachFile(Path self, FileType fileType, Closure closure);
134
void eachFileRecurse(Path self, Closure closure);
135
void traverse(Path self, Map<String, Object> options, Closure closure);
136
```
137

138
[Directory Operations](./directory-operations.md)
139

140
### Stream Management
141

142
Create and manage various stream types with automatic resource management using closures for safe operation.
143

144
```java { .api }
145
BufferedReader newReader(Path self);
146
BufferedWriter newWriter(Path self);
147
<T> T withReader(Path self, Closure<T> closure);
148
<T> T withWriter(Path self, Closure<T> closure);
149
BufferedInputStream newInputStream(Path self);
150
BufferedOutputStream newOutputStream(Path self);
151
```
152

153
[Stream Operations](./stream-operations.md)
154

155
### Object Serialization
156

157
Handle Java object serialization and deserialization with support for custom class loaders and closure-based processing.
158

159
```java { .api }
160
ObjectInputStream newObjectInputStream(Path self);
161
ObjectOutputStream newObjectOutputStream(Path self);
162
<T> T withObjectInputStream(Path self, Closure<T> closure);
163
void eachObject(Path self, Closure closure);
164
```
165

166
[Object Serialization](./object-serialization.md)
167

168
### Writable Conversion
169

170
Convert Path objects to Groovy's Writable interface for streaming and output operations.
171

172
```java { .api }
173
Path asWritable(Path self);
174
Path asWritable(Path self, String encoding);
175
<T> T asType(Path path, Class<T> c);
176
```
177

178
[Stream Operations](./stream-operations.md)
179

180
## Types
181

182
```java { .api }
183
// Core Groovy types used throughout the API
184
interface Closure<T> {
185
    T call(Object... args);
186
}
187

188
// File type enumeration for filtering
189
enum FileType {
190
    FILES,      // Regular files only
191
    DIRECTORIES, // Directories only  
192
    ANY         // Both files and directories
193
}
194

195
// Writable interface for streaming
196
interface Writable {
197
    Writer writeTo(Writer out);
198
}
199

200
// WritablePath - Path wrapper implementing Writable
201
class WritablePath implements Path, Writable {
202
    WritablePath(Path delegate);
203
    WritablePath(Path delegate, String encoding);
204
    Writer writeTo(Writer out);
205
}
206
```