ymlr - A YAML Encoder for Elixir

ymlr - A YAML encoder for Elixir.

Installation

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

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

Examples

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

Encode a single document - optionally with comments:

  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'
  """

Encode a multiple documents

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

---
b: 2
"""

Support for atoms

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
"""

Encode maps with keys sorted

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
...

Benchmark

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

Running the script

cd benchmark/
elixir run.exs

Development

We're using mise-en-place to install and manage tooling. Please install it and run mise init before you start coding. This installs the toolchain and sets up the git hooks via hk.

The hooks are configured in hk.pkl:

• pre-commit runs mix format (fixes are staged automatically) followed by mix credo --strict
• pre-push runs mix dialyzer

You can run the checks yourself at any time:

hk check --all   # everything, read-only
hk fix --all     # apply formatting fixes