0
# File I/O Operations
1

2
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 with optional BOM support.
3

4
## Capabilities
5

6
### Text Reading Operations
7

8
Read file content as strings with optional charset specification.
9

10
```java { .api }
11
/**
12
 * Read the content of the Path and returns it as a String using default charset
13
 * @param self the file whose content we want to read
14
 * @return a String containing the content of the file
15
 * @throws IOException if an IOException occurs
16
 */
17
String getText(Path self);
18

19
/**
20
 * Read the content of the Path using the specified encoding and return it as a String
21
 * @param self the file whose content we want to read
22
 * @param charset the charset used to read the content of the file
23
 * @return a String containing the content of the file
24
 * @throws IOException if an IOException occurs
25
 */
26
String getText(Path self, String charset);
27

28
/**
29
 * Reads the file into a list of Strings, with one item for each line
30
 * @param self a Path
31
 * @return a List of lines
32
 * @throws IOException if an IOException occurs
33
 */
34
List<String> readLines(Path self);
35

36
/**
37
 * Reads the file into a list of Strings, with one item for each line
38
 * @param self a Path
39
 * @param charset opens the file with a specified charset
40
 * @return a List of lines
41
 * @throws IOException if an IOException occurs
42
 */
43
List<String> readLines(Path self, String charset);
44
```
45

46
**Usage Examples:**
47

48
```groovy
49
import java.nio.file.Path
50
import java.nio.file.Paths
51

52
Path file = Paths.get("data.txt")
53

54
// Read entire file as string
55
String content = file.getText()
56

57
// Read with specific charset
58
String content = file.getText("UTF-8")
59

60
// Read as lines
61
List<String> lines = file.readLines()
62

63
// Read lines with charset
64
List<String> lines = file.readLines("UTF-8")
65

66
// Using property syntax (Groovy feature)
67
String content = file.text
68
```
69

70
### Binary Reading Operations
71

72
Read file content as byte arrays for binary data handling.
73

74
```java { .api }
75
/**
76
 * Read the content of the Path and returns it as a byte[]
77
 * @param self the file whose content we want to read
78
 * @return a byte array containing the content of the file
79
 * @throws IOException if an IOException occurs
80
 */
81
byte[] getBytes(Path self);
82

83
/**
84
 * Reads the content of the file into a byte array
85
 * @param self a Path
86
 * @return a byte array with the contents of the file
87
 * @throws IOException if an IOException occurs
88
 */
89
byte[] readBytes(Path self);
90
```
91

92
**Usage Examples:**
93

94
```groovy
95
Path binaryFile = Paths.get("image.png")
96

97
// Read as byte array
98
byte[] data = binaryFile.getBytes()
99
// or
100
byte[] data = binaryFile.readBytes()
101

102
// Using property syntax
103
byte[] data = binaryFile.bytes
104
```
105

106
### Text Writing Operations
107

108
Write text content to files with charset and BOM support.
109

110
```java { .api }
111
/**
112
 * Write the text to the Path without writing a BOM
113
 * @param self a Path
114
 * @param text the text to write to the Path
115
 * @throws IOException if an IOException occurs
116
 */
117
void write(Path self, String text);
118

119
/**
120
 * Write the text to the Path with BOM option
121
 * @param self a Path
122
 * @param text the text to write to the Path
123
 * @param writeBom whether to write the BOM
124
 * @throws IOException if an IOException occurs
125
 */
126
void write(Path self, String text, boolean writeBom);
127

128
/**
129
 * Write the text to the Path using the specified encoding without writing a BOM
130
 * @param self a Path
131
 * @param text the text to write to the Path
132
 * @param charset the charset used
133
 * @throws IOException if an IOException occurs
134
 */
135
void write(Path self, String text, String charset);
136

137
/**
138
 * Write the text to the Path using the specified encoding with BOM option
139
 * @param self a Path
140
 * @param text the text to write to the Path
141
 * @param charset the charset used
142
 * @param writeBom whether to write a BOM
143
 * @throws IOException if an IOException occurs
144
 */
145
void write(Path self, String text, String charset, boolean writeBom);
146

147
/**
148
 * Synonym for write(text) allowing file.text = 'foo'
149
 * @param self a Path
150
 * @param text the text to write to the Path
151
 * @throws IOException if an IOException occurs
152
 */
153
void setText(Path self, String text);
154

155
/**
156
 * Synonym for write(text, charset)
157
 * @param self A Path
158
 * @param text The text to write to the Path
159
 * @param charset The charset used when writing to the file
160
 * @throws IOException if an IOException occurs
161
 */
162
void setText(Path self, String text, String charset);
163
```
164

165
**Usage Examples:**
166

167
```groovy
168
Path file = Paths.get("output.txt")
169

170
// Simple text writing
171
file.write("Hello, World!")
172

173
// Using property syntax
174
file.text = "Hello, World!"
175

176
// Write with charset
177
file.write("Hello, World!", "UTF-8")
178
file.setText("Hello, World!", "UTF-8")
179

180
// Write with BOM for UTF-16
181
file.write("Hello, World!", "UTF-16LE", true)
182
```
183

184
### Binary Writing Operations
185

186
Write binary data to files.
187

188
```java { .api }
189
/**
190
 * Write the bytes from the byte array to the Path
191
 * @param self the file to write to
192
 * @param bytes the byte[] to write to the file
193
 * @throws IOException if an IOException occurs
194
 */
195
void setBytes(Path self, byte[] bytes);
196
```
197

198
**Usage Examples:**
199

200
```groovy
201
Path binaryFile = Paths.get("output.bin")
202
byte[] data = [0x48, 0x65, 0x6C, 0x6C, 0x6F] as byte[]
203

204
// Write byte array
205
binaryFile.setBytes(data)
206

207
// Using property syntax
208
binaryFile.bytes = data
209
```
210

211
### File Size Operations
212

213
Get file size information.
214

215
```java { .api }
216
/**
217
 * Provide the standard Groovy size() method for Path
218
 * @param self a Path object
219
 * @return the file's size (length)
220
 * @throws IOException if an IOException occurs
221
 */
222
long size(Path self);
223
```
224

225
**Usage Examples:**
226

227
```groovy
228
Path file = Paths.get("data.txt")
229

230
// Get file size
231
long fileSize = file.size()
232
```