Typeful reader API

[LVMVRQUXL]

Description

Based on #14, introduce a new reader API in the kotools.csv package for reading CSV files and deprecate the old one in the io.github.kotools.csv package.

Declarations in kotools.csv should use explicit types from Kotools Types for having a typeful design.

Dependencies

This issue needs the following ones to be done:

• CSV path extensions #47.

Checklist

• Implement and test a basic reader API.
• Improve the reader for filtering returned records.
• Improve the reader for paginating returned records.
• Improve the reader for returning a custom type.
• Deprecate the old reader.
• Refactor.
• Update Work in progress section in changelog.

[LVMVRQUXL]

Here's the code for retrieving the file from the "resources" or the "${user.home}/.kotools/csv" folders:

data class CsvFile(val file: File)

/**
 * Returns the [CSV file][CsvFile] matching the given [path], or returns `null`
 * if no file was found from the `"resources"` and the
 * `"${user.home}/.kotools/csv"` folders.
 *
 * The `.csv` extension is **optional** in the [path].
 * For example, calling this function with `"folder/file.csv"` produces the same
 * output as calling it with `"folder/file"`.
 */
fun csvFileOrNull(path: NotBlankString): CsvFile? {
    val filePath: NotBlankString = path.takeIf { it.value.endsWith(".csv") }
        ?: NotBlankString("$path.csv")
    val file: File? = ClassLoader.getSystemResource(filePath.value)
        ?.let { File(it.path) }
        ?: System.getProperty("user.home")
            .let(::Path)
            .resolve(".kotools")
            .resolve("csv")
            .resolve(filePath.value)
            .takeIf { it.exists() }
            ?.toFile()
    return file?.let(::CsvFile)
}

[LVMVRQUXL]

For converting a record to a custom type, we could use the serialization pattern (see kotlinx.serialization library).