Package io.github.dornol.excelkit.csv

Class CsvWriter<T>

java.lang.Object
io.github.dornol.excelkit.csv.CsvWriter<T>
Type Parameters:
T - The type of the data row
public class CsvWriter<T> extends Object
CSV writer for streaming large datasets into a temporary file.

Supports building columns dynamically, writing to a file line-by-line, and handling basic CSV escaping (quotes, commas, line breaks).

Since:
2025-07-19

  • Method Details

    • create

      public static <T> CsvWriter<T> create()
      Creates a new CSV writer with default settings.

      Mirrors ExcelWriter.create() for API symmetry. 

      
 CsvWriter.<User>create()
     .column("Name", User::getName)
     .write(users)
     .writeTo(out);
      Type Parameters:
      T - the row type
      Returns:
      a new CsvWriter
      Since:
      0.16.6

    • forMap

      public static CsvWriter<Map<String,Object>> forMap(String... columnNames)
      Creates a CsvWriter pre-configured to write rows of Map<String, Object>, with one column per given column name. Each column reads its value from the map by using the column name as the key.

      The returned writer is a regular CsvWriter, so all of its fluent configuration methods (dialect, delimiter, charset, BOM, quoting, CSV injection defense, afterData, etc.) are available. 

      
 CsvWriter.forMap("Name", "Age", "Email")
     .dialect(CsvDialect.EXCEL)
     .bom(true)
     .write(stream)
     .write(out);
      Parameters:
      columnNames - the column names (used as both header labels and map keys)
      Returns:
      a new CsvWriter with the columns registered
      Since:
      0.11.0

    • dialect

      public CsvWriter<T> dialect(CsvDialect dialect)
      Applies a predefined CSV dialect configuration.

      Sets the delimiter, charset, and BOM settings in one call. Individual settings can be overridden after calling this method.

      Parameters:
      dialect - the dialect to apply
      Returns:
      This writer instance (for chaining)
      Since:
      0.9.2

    • delimiter

      public CsvWriter<T> delimiter(char delimiter)
      Sets the delimiter character used to separate fields. Defaults to comma (',').
      Parameters:
      delimiter - The delimiter character
      Returns:
      This writer instance (for chaining)

    • charset

      public CsvWriter<T> charset(Charset charset)
      Sets the character encoding for the output file. Defaults to StandardCharsets.UTF_8.
      Parameters:
      charset - The charset to use
      Returns:
      This writer instance (for chaining)

    • bom

      public CsvWriter<T> bom(boolean bom)
      Sets whether to write a UTF-8 BOM at the start of the file. Defaults to true.
      Parameters:
      bom - Whether to write the BOM
      Returns:
      This writer instance (for chaining)

    • afterData

      public CsvWriter<T> afterData(CsvAfterDataWriter afterDataWriter)
      Registers a callback that writes custom content after all data rows.

      The callback receives the PrintWriter used to write the CSV, allowing additional lines to be appended after the data rows.

      Parameters:
      afterDataWriter - the callback to invoke after data rows
      Returns:
      This writer instance (for chaining)

    • column

      public CsvWriter<T> column(String name, RowFunction<T,@Nullable Object> function)
      Adds a new column to the CSV output using a row+cursor-based function.
      Parameters:
      name - The column header
      function - A function to compute the value for each row
      Returns:
      This writer instance (for chaining)

    • column

      public CsvWriter<T> column(String name, Function<T,@Nullable Object> function)
      Adds a new column using a basic row-only function.
      Parameters:
      name - The column header
      function - A function to compute the value from the row
      Returns:
      This writer instance

    • columnIf

      public CsvWriter<T> columnIf(String name, boolean condition, RowFunction<T,@Nullable Object> function)
      Conditionally adds a column using a row+cursor-based function. If condition is false, the column is not added.
      Parameters:
      name - The column header
      condition - Whether to include this column
      function - A function to compute the value for each row
      Returns:
      This writer instance

    • columnIf

      public CsvWriter<T> columnIf(String name, boolean condition, Function<T,@Nullable Object> function)
      Conditionally adds a column using a basic row-only function. If condition is false, the column is not added.
      Parameters:
      name - The column header
      condition - Whether to include this column
      function - A function to compute the value from the row
      Returns:
      This writer instance

    • constColumn

      public CsvWriter<T> constColumn(String name, @Nullable Object value)
      Adds a column with a constant value for all rows.
      Parameters:
      name - The column header
      value - The constant value
      Returns:
      This writer instance

    • constColumnIf

      public CsvWriter<T> constColumnIf(String name, boolean condition, @Nullable Object value)
      Conditionally adds a column with a constant value for all rows.
      Parameters:
      name - The column header
      condition - Whether to add the column
      value - The constant value
      Returns:
      This writer instance
      Since:
      0.14.0

    • onProgress

      public CsvWriter<T> onProgress(int interval, ProgressCallback callback)
      Registers a progress callback that fires every interval rows.
      Parameters:
      interval - the number of rows between each callback invocation (must be positive)
      callback - the callback to invoke
      Returns:
      This writer instance (for chaining)

    • quoting

      public CsvWriter<T> quoting(CsvQuoting quoting)
      Sets the quoting strategy for CSV field values.

      Defaults to CsvQuoting.MINIMAL (quote only when necessary).

      Parameters:
      quoting - the quoting strategy
      Returns:
      This writer instance (for chaining)
      Since:
      0.9.2

    • csvInjectionDefense

      public CsvWriter<T> csvInjectionDefense(boolean enabled)
      Enables or disables CSV injection defense.

      When enabled (default), cell values starting with formula characters (=, +, -, @, \t, \r) are prefixed with a single quote to prevent formula injection.

      Disable only when writing trusted data where the prefix would corrupt values.

      Parameters:
      enabled - whether to enable injection defense (default: true)
      Returns:
      This writer instance (for chaining)

    • write

      public CsvHandler write(Stream<T> stream)
      Writes the given stream of rows to a temporary CSV file.

      The returned CsvHandler can be used to write the file to an OutputStream.

      Parameters:
      stream - The row data stream
      Returns:
      A handler for streaming the resulting CSV