0
# File Appending Operations
1

2
Append data to existing files with support for text, binary data, and various input sources including streams, readers, writers, and the convenient left-shift operator.
3

4
## Capabilities
5

6
### Left-Shift Operator Appending
7

8
Use Groovy's left-shift operator (`<<`) for convenient appending operations.
9

10
```java { .api }
11
/**
12
 * Write the text to the Path using left-shift operator
13
 * @param self a Path
14
 * @param text the text to write to the Path
15
 * @return the original file
16
 * @throws IOException if an IOException occurs
17
 */
18
Path leftShift(Path self, Object text);
19

20
/**
21
 * Write bytes to a Path using left-shift operator
22
 * @param self a Path
23
 * @param bytes the byte array to append to the end of the Path
24
 * @return the original file
25
 * @throws IOException if an IOException occurs
26
 */
27
Path leftShift(Path self, byte[] bytes);
28

29
/**
30
 * Append binary data to the file using left-shift operator
31
 * @param path a Path
32
 * @param data an InputStream of data to write to the file
33
 * @return the file
34
 * @throws IOException if an IOException occurs
35
 */
36
Path leftShift(Path path, InputStream data);
37
```
38

39
**Usage Examples:**
40

41
```groovy
42
import java.nio.file.Path
43
import java.nio.file.Paths
44

45
Path file = Paths.get("log.txt")
46

47
// Append text using left-shift operator
48
file << "New log entry\n"
49
file << "Another entry\n"
50

51
// Append binary data
52
byte[] data = "Binary data".getBytes()
53
file << data
54

55
// Append from input stream
56
new FileInputStream("source.txt").withStream { stream ->
57
    file << stream
58
}
59

60
// Chain operations (returns the Path)
61
file << "First line\n" << "Second line\n"
62
```
63

64
### Text Appending Operations
65

66
Append text content with charset and BOM support.
67

68
```java { .api }
69
/**
70
 * Append the text at the end of the Path without writing a BOM
71
 * @param self a Path
72
 * @param text the text to append at the end of the Path
73
 * @throws IOException if an IOException occurs
74
 */
75
void append(Path self, Object text);
76

77
/**
78
 * Append the text at the end of the Path with BOM option
79
 * @param self a Path
80
 * @param text the text to append at the end of the Path
81
 * @param writeBom whether to write the BOM
82
 * @throws IOException if an IOException occurs
83
 */
84
void append(Path self, Object text, boolean writeBom);
85

86
/**
87
 * Append the text at the end of the Path without writing a BOM, using a specified encoding
88
 * @param self a Path
89
 * @param text the text to append at the end of the Path
90
 * @param charset the charset used
91
 * @throws IOException if an IOException occurs
92
 */
93
void append(Path self, Object text, String charset);
94

95
/**
96
 * Append the text at the end of the Path, using a specified encoding with BOM option
97
 * @param self a Path
98
 * @param text the text to append at the end of the Path
99
 * @param charset the charset used
100
 * @param writeBom whether to write the BOM
101
 * @throws IOException if an IOException occurs
102
 */
103
void append(Path self, Object text, String charset, boolean writeBom);
104
```
105

106
**Usage Examples:**
107

108
```groovy
109
Path logFile = Paths.get("application.log")
110

111
// Simple append
112
logFile.append("New log message\n")
113

114
// Append with charset
115
logFile.append("Unicode message: 你好\n", "UTF-8")
116

117
// Append with BOM (useful for UTF-16)
118
logFile.append("BOM message\n", true)
119

120
// Append with charset and BOM
121
logFile.append("Unicode with BOM\n", "UTF-16LE", true)
122
```
123

124
### Binary Appending Operations
125

126
Append binary data from byte arrays and input streams.
127

128
```java { .api }
129
/**
130
 * Append bytes to the end of a Path. It will not be interpreted as text
131
 * @param self a Path
132
 * @param bytes the byte array to append to the end of the Path
133
 * @throws IOException if an IOException occurs
134
 */
135
void append(Path self, byte[] bytes);
136

137
/**
138
 * Append binary data to the file. It will not be interpreted as text
139
 * @param self a Path
140
 * @param stream stream to read data from
141
 * @throws IOException if an IOException occurs
142
 */
143
void append(Path self, InputStream stream);
144
```
145

146
**Usage Examples:**
147

148
```groovy
149
Path binaryFile = Paths.get("data.bin")
150

151
// Append byte array
152
byte[] moreData = [0x01, 0x02, 0x03, 0x04] as byte[]
153
binaryFile.append(moreData)
154

155
// Append from input stream
156
new FileInputStream("additional-data.bin").withStream { stream ->
157
    binaryFile.append(stream)
158
}
159
```
160

161
### Reader and Writer Appending Operations
162

163
Append content from Reader and Writer objects with charset support.
164

165
```java { .api }
166
/**
167
 * Append the text supplied by the Reader at the end of the File without writing a BOM
168
 * @param file a Path
169
 * @param reader the Reader supplying the text to append at the end of the File
170
 * @throws IOException if an IOException occurs
171
 */
172
void append(Path file, Reader reader);
173

174
/**
175
 * Append the text supplied by the Reader at the end of the File without writing a BOM, using a specified encoding
176
 * @param file a File
177
 * @param reader the Reader supplying the text to append at the end of the File
178
 * @param charset the charset used
179
 * @throws IOException if an IOException occurs
180
 */
181
void append(Path file, Reader reader, String charset);
182

183
/**
184
 * Append the text supplied by the Reader at the end of the File, using a specified encoding with BOM option
185
 * @param file a File
186
 * @param reader the Reader supplying the text to append at the end of the File
187
 * @param charset the charset used
188
 * @param writeBom whether to write the BOM
189
 * @throws IOException if an IOException occurs
190
 */
191
void append(Path file, Reader reader, String charset, boolean writeBom);
192

193
/**
194
 * Append the text supplied by the Writer at the end of the File without writing a BOM
195
 * @param file a File
196
 * @param writer the Writer supplying the text to append at the end of the File
197
 * @throws IOException if an IOException occurs
198
 */
199
void append(Path file, Writer writer);
200

201
/**
202
 * Append the text supplied by the Writer at the end of the File without writing a BOM, using a specified encoding
203
 * @param file a File
204
 * @param writer the Writer supplying the text to append at the end of the File
205
 * @param charset the charset used
206
 * @throws IOException if an IOException occurs
207
 */
208
void append(Path file, Writer writer, String charset);
209

210
/**
211
 * Append the text supplied by the Writer at the end of the File, using a specified encoding with BOM option
212
 * @param file a File
213
 * @param writer the Writer supplying the text to append at the end of the File
214
 * @param charset the charset used
215
 * @param writeBom whether to write the BOM
216
 * @throws IOException if an IOException occurs
217
 */
218
void append(Path file, Writer writer, String charset, boolean writeBom);
219
```
220

221
**Usage Examples:**
222

223
```groovy
224
Path outputFile = Paths.get("combined.txt")
225

226
// Append from Reader
227
new StringReader("Content from reader").withReader { reader ->
228
    outputFile.append(reader)
229
}
230

231
// Append from Reader with charset
232
new FileReader("source.txt").withReader { reader ->
233
    outputFile.append(reader, "UTF-8")
234
}
235

236
// Append from Writer
237
def writer = new StringWriter()
238
writer.write("Content from writer")
239
outputFile.append(writer)
240

241
// Append from Writer with charset and BOM
242
def writer = new StringWriter()
243
writer.write("Unicode content")
244
outputFile.append(writer, "UTF-16LE", true)
245
```