ymlr - A YAML encoder for Elixir.

The package can be installed by adding ymlr to your list of dependencies in mix.exs:

def deps do
  [
    {:ymlr, "~> 5.0"}
  ]
end

See The usage livebook usage.livemd for more detailed examples.

  iex> Ymlr.document!(%{a: 1})
  """
  ---
  a: 1
  """

  iex> Ymlr.document!({"comment", %{a: 1}})
  """
  ---
  # comment
  a: 1
  """

  iex> Ymlr.document!({["comment 1", "comment 2"], %{"a" => "a", "b" => :b, "c" => "true", "d" => "100"}})
  """
  ---
  # comment 1
  # comment 2
  a: a
  b: b
  c: 'true'
  d: '100'
  """

iex> Ymlr.documents!([%{a: 1}, %{b: 2}])
"""
---
a: 1

---
b: 2
"""

By default, atoms as map keys are encoded as strings (without the leading colon). If you want atoms to be encoded with a leading colon in order to be able to parse it later using YamlElixir's atoms option, you can pass atoms: true as second argument to any of the Ymlr module's functions:

iex> Ymlr.document!(%{a: 1}, atoms: true)
"""
---
:a: 1
"""

Maps in elixir, implemented by erlang :maps, internally are flatmaps or hashmaps by size. Large maps will be encoded in strange order.

iex> 1..33 |> Map.new(&{&1, &1})|> Ymlr.document!() |> IO.puts
---
4: 4
25: 25
8: 8
...

By using :sort_maps option, ymlr will encode all entries sorted.

iex> 1..33 |> Map.new(&{&1, &1})|> Ymlr.document!(sort_maps: true) |> IO.puts
---
1: 1
2: 2
3: 3
...

This library does not claim to be particularly performant. We do have a script to benchmark encoding so we know if performance gets better or worse with changes.

You can find the last Benchmark in BENCHMARK.md

cd benchmark/
elixir run.exs

We're using mise-en-place to install and manage tooling. Please install it and run mise init before you start coding. This will also setup pre-commit hooks