Skip to content

ufirstgroup/ymlr

Repository files navigation

ymlr - A YAML Encoder for Elixir

ymlr - A YAML encoder for Elixir.

Module Version Coverage Status Last Updated

Build Status Code Qualits Build Status Elixir

Hex Docs Total Download License

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