4koma/cc.ekblad.toml/TomlMapper

TomlMapper

A bidirectional TOML transcoder, capable of converting TomlValues into Kotlin values, and vice versa.

A transcoder is intended to make your life easier by keeping custom mappings in sync between your encoder and decoder. Unless you need custom en/decoder functions, using a transcoder instead of a separate encoder and decoder is highly recommended.

Functions

decode

inline fun <T> decode(tomlValue: TomlValue): T

Decodes the receiver TOML value to the type indicated by type parameter T using the default TOML decoder. If the value can't be decoded into the target type, a cc.ekblad.toml.model.TomlException.DecodingError is thrown.

fun <T> decode(targetKType: KType, tomlValue: TomlValue): T

fun <T> decode(targetKType: KType, tomlValue: TomlValue, defaultValue: T): T

decodeWithDefaults

inline fun <T> decodeWithDefaults(defaultValue: T, tomlValue: TomlValue): T

Like decode, but will fill in any missing fields from the defaultValue. Appropriate for use cases such as configuration files, where you may not want to force the user to configure every last thing, but just override the bits they want to customize.

delegate

fun <T : Any> delegate(kClass: KClass<T>, configurator: TomlMapperConfigurator)

encode

fun encode(value: Any): TomlValue

Encodes the given Kotlin value to as into a TomlValue using the receiver TomlEncoder. If the value can't be encoded, a cc.ekblad.toml.model.TomlException.EncodingError is thrown.

Extensions

atomicallyEncodeTo

fun TomlMapper.atomicallyEncodeTo(path: Path, value: Any)

Serializes given value into a valid TOML document and writes it to a temporary file in the same directory as the file indicated by path. The file will then be synced to disk, and finally moved to its final destination, atomically replacing any pre-existing file in that location.

decode

inline fun <T> TomlMapper.decode(string: String): T

Parses the given TOML-formatted string into a TOML document and decodes it into the given type T.

inline fun <T> TomlMapper.decode(stream: InputStream): T

Parses the given TOML-formatted input stream into a TOML document and decodes it into the given type T.

inline fun <T> TomlMapper.decode(path: Path): T

Parses the given TOML-formatted file into a TOML document and decodes it into the given type T.

decodeWithDefaults

inline fun <T> TomlMapper.decodeWithDefaults(defaultValue: T, string: String): T

Like decode, but fills in any values missing from the input string with values from the given defaultValue.

inline fun <T> TomlMapper.decodeWithDefaults(defaultValue: T, stream: InputStream): T

Like decode, but fills in any values missing from the input stream with values from the given defaultValue.

inline fun <T> TomlMapper.decodeWithDefaults(defaultValue: T, path: Path): T

Like decode, but fills in any values missing from the input file with values from the given defaultValue.

encodeTo

fun TomlMapper.encodeTo(output: Appendable, value: Any)

Serializes given value into a valid TOML document and writes it to the given Appendable. If value does not serialize to a valid TOML document (i.e. a map of zero or more keys), an TomlException.SerializationError is thrown.

fun TomlMapper.encodeTo(outputStream: OutputStream, value: Any)

Serializes given value into a valid TOML document and writes it to the given OutputStream. If value does not serialize to a valid TOML document (i.e. a map of zero or more keys), an TomlException.SerializationError is thrown.

fun TomlMapper.encodeTo(path: Path, value: Any)

Serializes given value into a valid TOML document and writes it to the file indicated by the given Path. If value does not serialize to a valid TOML document (i.e. a map of zero or more keys), an TomlException.SerializationError is thrown.

encodeToDocument

fun TomlMapper.encodeToDocument(value: Any): TomlDocument

Encodes the given value into a valid TOML document. If value does not serialize to a valid TOML document (i.e. a map of zero or more keys), an TomlException.SerializationError is thrown.

encodeToString

fun TomlMapper.encodeToString(value: Any): String

Encodes the given value into a valid TOML document and serializes it into a string. If value does not serialize to a valid TOML document (i.e. a map of zero or more keys), an TomlException.SerializationError is thrown.