@spec decode(binary(), options()) :: {:ok, map()} | {:error, Exception.t()}

Decode toml string to map.

Options

• :spec - The TOML specification version to follow. Can be :"1.1.0" (default) or :"1.0.0".

• :keys - How table keys are returned. Conversion runs after TOML validation, including duplicate-key checks, and applies to nested tables, inline tables, and arrays of tables.

  • :strings (default) - keep keys as strings.
  • :atoms! - convert keys to existing atoms with String.to_existing_atom/1. A key with no existing atom fails decoding. New atoms are never created, because atoms are not garbage-collected; existing atoms are still not an application-specific allowlist.
  • a 1-arity function - called with each string key, returning the key to use. Raise to reject a key; decode/2 then returns an error. Pass an explicit mapping for the tightest control, for example &Map.fetch!(%{"port" => :port}, &1).

  Two keys in one table that convert to the same term fail decoding instead of overwriting each other. Key conversion errors have no line or column.

• :transform - a 2-arity function called as transform.(path, value) for every value in the document, returning the value to use. Use it to convert selected strings to known values, validate settings, or build structs from tables.

  • Values are visited children first, so a table's callback receives its transformed children. The order between sibling keys is unspecified.
  • path lists the TOML keys from the document root as strings, with integer indexes for array elements, such as ["servers", 0, "port"]. It uses the original keys even when :keys converts them; the value's nested maps have converted keys.
  • The callback is not called for the document map itself, so decoding always returns a map.
  • Raise to reject a value; decode/2 then returns an error naming the path, with no line or column.

  This runs after decoding, so it cannot recover precision or formatting already lost during scalar parsing.

Example

TomlElixir.decode("toml = true", spec: :"1.1.0")

@spec decode!(binary(), options()) :: map()

Same as decode/2, but raises error on failure.

Example

TomlElixir.decode!("toml = true")

@spec encode(map(), options()) ::
  {:ok, binary()} | {:error, TomlElixir.Encoder.Error.t()}

Encode map to toml string.

Keys are sorted and output is deterministic. The options change the layout of generated output; they do not preserve the formatting of a decoded document.

Options

• :multiline_arrays - when true, write each element of a non-empty array value on its own line with a trailing comma. Arrays nested inside elements or inside inline tables stay on one line, since TOML 1.0.0 restricts newlines in inline tables. Defaults to false.
• :inline_tables - list of key paths whose tables, or arrays of tables, are written as inline values such as point = {x = 1, y = 2} instead of [point] sections. Paths are lists of string or atom keys without array indexes, so [[:products, :dims]] applies to dims in every products entry. Everything below an inline table is inline too. Defaults to [].

Example

TomlElixir.encode(%{a: 1})

@spec encode!(map(), options()) :: binary()

Same as encode/2, but raises error on failure.

Example

TomlElixir.encode!(%{a: 1})

@spec encode_to_iodata(map(), options()) ::
  {:ok, iodata()} | {:error, TomlElixir.Encoder.Error.t()}

Encode map to TOML as iodata.

Accepts the same options as encode/2. Use this when the output goes to an API that accepts iodata, such as File.write/3 or :gen_tcp.send/2, to skip building one contiguous binary. The whole output is still built in memory; this is not streaming encoding.

Example

{:ok, iodata} = TomlElixir.encode_to_iodata(%{a: 1})
File.write!("config.toml", iodata)

@spec encode_to_iodata!(map(), options()) :: iodata()

Same as encode_to_iodata/2, but raises error on failure.

Example

TomlElixir.encode_to_iodata!(%{a: 1})