Home

Awesome

TOML for Elixir

Main Hex.pm Version Hex Docs Total Download Last Updated

This is a TOML library for Elixir projects.

It is compliant with version 1.0 of the official TOML specification. You can find a brief overview of the feature set below, but you are encouraged to read the full spec at the link above (it is short and easy to read!).

Features

Comparison To Other Libraries

I compared toml to four other libraries:

Of these four, none correctly implement the 0.5.0 specification. Either they are targeting older versions of the spec (in etoml, it is built against pre-0.1), are not fully implemented (i.e. don't support all features), or have bugs which prevent them from properly parsing a 0.5.0 example file (the test/fixtures/example.toml file in this repository).

If you are looking for a TOML library, at present toml is the only one which full implements the spec and correctly decodes example.toml.

Installation

This library is available on Hex as :toml, and can be added to your deps like so:

def deps do
  [
    {:toml, "~> 0.7"}
  ]
end

NOTE: You can determine the latest version on Hex by running mix hex.info toml.

Type Conversions

In case you are curious how TOML types are translated to Elixir types, the following table provides the conversions.

NOTE: The various possible representations of each type, such as hex/octal/binary integers, quoted/literal strings, etc., are considered to be the same base type (e.g. integer and string respectively in the examples given).

TOMLElixir
StringString.t (binary)
Integerinteger
inf:infinity
+inf:infinity
-inf:negative_infinity
nan:nan
+nan:nan
-nan:negative_nan
Booleanboolean
Offset Date-TimeDateTime.t
Local Date-TimeNaiveDateTime.t
Local DateDate.t
Local TimeTime.t
Arraylist
Tablemap
Table Arraylist(map)

Implementation-specific Behaviors

Certain features of TOML have implementation-specific behavior:

Example Usage

The following is a brief overview of how to use this library. First, let's take a look at an example TOML file, as borrowed from the TOML homepage:

# This is a TOML document.

title = "TOML Example"

[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00-08:00 # First class dates

[database]
server = "192.168.1.1"
ports = [ 8001, 8001, 8002 ]
connection_max = 5000
enabled = true

[servers]

  # Indentation (tabs and/or spaces) is allowed but not required
  [servers.alpha]
  ip = "10.0.0.1"
  dc = "eqdc10"

  [servers.beta]
  ip = "10.0.0.2"
  dc = "eqdc10"

[clients]
data = [ ["gamma", "delta"], [1, 2] ]

# Line breaks are OK when inside arrays
hosts = [
  "alpha",
  "omega"
]

Parsing

iex> input = """
[database]
server = "192.168.1.1"
"""
...> {:ok, %{"database" => %{"server" => "192.168.1.1"}}} = Toml.decode(input)
...> {:ok, %{database: %{server: "192.168.1.1"}}} = Toml.decode(input, keys: :atoms)
...> stream = File.stream!("example.toml")
...> {:ok, %{"database" => %{"server" => "192.168.1.1"}}} = Toml.decode_stream(stream)
...> {:ok, %{"database" => %{"server" => "192.168.1.1"}}} = Toml.decode_file("example.toml")
...> invalid = """
[invalid]
a = 1 b = 2
"""
...> {:error, {:invalid_toml, reason}} = Toml.decode(invalid); IO.puts(reason)
expected '\n', but got 'b' in nofile on line 2:

    a = 1 b = 2
         ^

:ok

Transforms

Support for extending value conversions is provided by the Toml.Transform behavior. An example is shown below:

Given the following TOML document:

[servers.alpha]
ip = "192.168.1.1"
ports = [8080, 8081]

[servers.beta]
ip = "192.168.1.2"
ports = [8082, 8083]

And the following modules:

defmodule Server do
  defstruct [:name, :ip, :ports]
end

defmodule IPStringToCharlist do
  use Toml.Transform
  
  def transform(:ip, v) when is_binary(v) do
    String.to_charlist(v)
  end
  def transform(_k, v), do: v
end

defmodule CharlistToIP do
  use Toml.Transform
  
  def transform(:ip, v) when is_list(v) do
    case :inet.parse_ipv4_address(v) do
      {:ok, address} ->
        address
      {:error, reason} ->
        {:error, {:invalid_ip_address, reason}}
    end
  end
  def transform(:ip, v), do: {:error, {:invalid_ip_address, v}}
  def transform(_k, v), do: v
end

defmodule ServerMapToList do
  use Toml.Transform
  
  def transform(:servers, v) when is_map(v) do
    for {name, server} <- v, do: struct(Server, Map.put(server, :name, name))
  end
  def transform(_k, v), do: v
end

You can convert the TOML document to a more strongly-typed version using the above transforms like so:

iex> transforms = [IPStringToCharlist, CharlistToIP, ServerMapToList]
...> {:ok, result} = Toml.decode("example.toml", keys: :atoms, transforms: transforms)
%{servers: [%Server{name: :alpha, ip: {192,168,1,1}}, ports: [8080, 8081] | _]}

The transforms given here are intended to show how they can be composed: they are applied in the order provided, and the document is transformed using a depth-first, bottom-up traversal. Put another way, you transform the leaves of the tree before the branches; as shown in the example above, this means the :ip key is converted to an address tuple before the :servers key is transformed into a list of Server structs.

Using with Elixir Releases (1.9+)

To use this library as a configuration provider in Elixir, use the following example of how one might use it in their release configuration, and tailor it to your needs:

config_providers: [
  {Toml.Provider, [
    path: {:system, "XDG_CONFIG_DIR", "myapp.toml"},
    transforms: [...]
  ]}
]

See the "Using as a Config Provider" section for more info.

Using with Distillery

Like the above, use the following example as a guideline for how you use this in your own release configuration (i.e. in rel/config.exs):

release :myapp do
  # ...snip...
  set config_providers: [
    {Toml.Provider, [path: "${XDG_CONFIG_DIR}/myapp.toml", transforms: [...]]}
  ]
end

Using as a Config Provider

The usages described above will result in Toml.Provider being invoked during boot, at which point it will evaluate the given path and read the TOML file it finds. If one is not found, or is not accessible, the provider will raise an error, and the boot sequence will terminate unsuccessfully. If it succeeds, it persists settings in the file to the application environment (i.e. you access it via Application.get_env/2).

You can pass the same options in the arguments list for Toml.Provider as you can to Toml.decode/2, but :path is required, and :keys only supports :atoms and :atoms! values.

The config provider expects a certain format to the TOML file, namely that keys at the root of the document correspond to applications which need to be configured. If it encounters keys at the root of the document which are not tables, they are ignored.

# This is an example of something that would be ignored
title = "My config file"

# We're expecting something like this:
[myapp]
key = "value"

# To use a bit of Phoenix config, you translate to TOML like so:
[myapp."MyApp.Endpoint"]
cache_static_manifest = "priv/static/cache_manifest.json"

[myapp."MyApp.Endpoint".http]
port = "4000"

[myapp."MyApp.Endpoint".force_ssl]
hsts = true

# Or logger..
[logger]
level = "info"

[logger.console]
format = "[$level] $message \n"

Roadmap

License

This project is licensed Apache 2.0, see the LICENSE file in this repo for details.