File Appending Operations

/**
 * Write the text to the Path using left-shift operator
 * @param self a Path
 * @param text the text to write to the Path
 * @return the original file
 * @throws IOException if an IOException occurs
 */
Path leftShift(Path self, Object text);

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

/**
 * Append binary data to the file using left-shift operator
 * @param path a Path
 * @param data an InputStream of data to write to the file
 * @return the file
 * @throws IOException if an IOException occurs
 */
Path leftShift(Path path, InputStream data);

import java.nio.file.Path
import java.nio.file.Paths

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

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

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

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

// Chain operations (returns the Path)
file << "First line\n" << "Second line\n"

/**
 * Append the text at the end of the Path without writing a BOM
 * @param self a Path
 * @param text the text to append at the end of the Path
 * @throws IOException if an IOException occurs
 */
void append(Path self, Object text);

/**
 * Append the text at the end of the Path with BOM option
 * @param self a Path
 * @param text the text to append at the end of the Path
 * @param writeBom whether to write the BOM
 * @throws IOException if an IOException occurs
 */
void append(Path self, Object text, boolean writeBom);

/**
 * Append the text at the end of the Path without writing a BOM, using a specified encoding
 * @param self a Path
 * @param text the text to append at the end of the Path
 * @param charset the charset used
 * @throws IOException if an IOException occurs
 */
void append(Path self, Object text, String charset);

/**
 * Append the text at the end of the Path, using a specified encoding with BOM option
 * @param self a Path
 * @param text the text to append at the end of the Path
 * @param charset the charset used
 * @param writeBom whether to write the BOM
 * @throws IOException if an IOException occurs
 */
void append(Path self, Object text, String charset, boolean writeBom);

Path logFile = Paths.get("application.log")

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

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

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

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

/**
 * Append bytes to the end of a Path. It will not be interpreted as text
 * @param self a Path
 * @param bytes the byte array to append to the end of the Path
 * @throws IOException if an IOException occurs
 */
void append(Path self, byte[] bytes);

/**
 * Append binary data to the file. It will not be interpreted as text
 * @param self a Path
 * @param stream stream to read data from
 * @throws IOException if an IOException occurs
 */
void append(Path self, InputStream stream);

Path binaryFile = Paths.get("data.bin")

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

// Append from input stream
new FileInputStream("additional-data.bin").withStream { stream ->
    binaryFile.append(stream)
}

/**
 * Append the text supplied by the Reader at the end of the File without writing a BOM
 * @param file a Path
 * @param reader the Reader supplying the text to append at the end of the File
 * @throws IOException if an IOException occurs
 */
void append(Path file, Reader reader);

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

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

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

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

/**
 * Append the text supplied by the Writer at the end of the File, using a specified encoding with BOM option
 * @param file a File
 * @param writer the Writer supplying the text to append at the end of the File
 * @param charset the charset used
 * @param writeBom whether to write the BOM
 * @throws IOException if an IOException occurs
 */
void append(Path file, Writer writer, String charset, boolean writeBom);

Path outputFile = Paths.get("combined.txt")

// Append from Reader
new StringReader("Content from reader").withReader { reader ->
    outputFile.append(reader)
}

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

// Append from Writer
def writer = new StringWriter()
writer.write("Content from writer")
outputFile.append(writer)

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