<!--
DO NOT EDIT THIS FILE
It has been generated from the template `README.md.eex` by Extractly (https://github.com/RobertDober/extractly.git)
and any changes you make in this file will most likely be lost
-->

[![CI](https://github.com/RobertDober/ex_aequo_kwds/actions/workflows/elixir.yml/badge.svg)](https://github.com/RobertDober/ex_aequo_kwds/actions)
[![Hex.pm](https://img.shields.io/hexpm/v/ex_aequo_kwds.svg)](https://hex.pm/packages/ex_aequo_kwds)
[![Hex.pm](https://img.shields.io/hexpm/dw/ex_aequo_kwds.svg)](https://hex.pm/packages/ex_aequo_kwds)
[![Hex.pm](https://img.shields.io/hexpm/dt/ex_aequo_kwds.svg)](https://hex.pm/packages/ex_aequo_kwds)

# ExAequoKwds

 Tools to handle access and constraints to Keyword Lists

## Documentation

Tools to handle access and constraints to Keyword Lists 

### `check_kwds`

All required keys are present

```elixir
    iex(1)> check_kwds([a: 1, b: 2], [:b, :a])
    {:ok, %{a: 1, b: 2}}
```

Defaults can be used

```elixir
    iex(2)> check_kwds([a: 1], [:a, b: 2])
    {:ok, %{a: 1, b: 2}}
```

But might not

```elixir
    iex(3)> check_kwds([a: 1, b: 1], [:a, b: 2])
    {:ok, %{a: 1, b: 1}}
```

We must not have spurious keys

```elixir
    iex(4)> check_kwds([a: 1, b: 1], [:a])
    {:error, "spurious [b: 1]"}
```

Nor missing ones

```elixir
    iex(5)> check_kwds([b: 1], [:a, :b])
    {:error, "missing key a"}
```

But we can ignore_errors

```elixir
    iex(6)> check_kwds([a: 1, b: 1], [:a], ignore_errors: true)
    {:ok, %{a: 1}}
```

```elixir
    iex(7)> check_kwds([b: 1], [:a, :b], ignore_errors: true)
    {:ok, %{a: nil, b: 1}}
```

### `check_kwds!`

All fine or ignoring errors

```elixir
    iex(8)> check_kwds!([a: 1, b: 2], [:b, :a])
    %{a: 1, b: 2}
```

```elixir
    iex(9)> check_kwds!([a: 1], [:a, b: 2])
    %{a: 1, b: 2}
```

```elixir
    iex(10)> check_kwds!([a: 1, b: 1], [:a], ignore_errors: true)
    %{a: 1}
```

```elixir
    iex(11)> check_kwds!([b: 1], [:a, :b], ignore_errors: true)
    %{a: nil, b: 1}
```

 Otherwise `ArgumentError` will be raised

```elixir
    iex(12)> assert_raise(ArgumentError, fn -> check_kwds!([a: 1, b: 1], [:a]) end)
```

Nor missing ones

```elixir
    iex(13)> assert_raise(ArgumentError, fn -> check_kwds!([b: 1], [:a, :b]) end)
```








## Author

Copyright © 2024 Robert Dober robert.dober@gmail.com

# LICENSE

GNU AFFERO GENERAL PUBLIC LICENSE Version 3, 19 November 2007 or later. Please refer to [LICENSE](LICENSE) for details.
<!--SPDX-License-Identifier: AGPL-3.0-or-later-->