# `Macaw.Host.Config.Literal`
[🔗](https://github.com/dcoai/macaw_host/blob/v0.1.4/lib/macaw/host/config/literal.ex#L1)

The literal `config.exs` on a host's data volume: a map that is parsed,
never evaluated.

Anything that isn't a literal (a call, a variable, string interpolation, a
module attribute) is a fault, and **every** fault is reported at once, each
with its line. Literals are atoms, strings, numbers (negative ones
included), lists, maps and tuples of any size. Parsing never creates an
atom: a name that doesn't already exist is a fault, so a typo can't grow
the atom table and can't silently become a new setting.

# `parse`

```elixir
@spec parse(String.t(), Path.t()) :: {:ok, map()} | {:error, [String.t()]}
```

Parses text to a literal map, or `{:error, faults}`, one message per fault.
Also parses a single value someone typed (`ctl config set`) with
`parse_value/2`.

# `parse!`

```elixir
@spec parse!(String.t(), Path.t()) :: map()
```

Parses a config file's text to a map; raises `ArgumentError` listing every fault.

# `parse_value`

```elixir
@spec parse_value(String.t(), String.t()) :: {:ok, term()} | {:error, [String.t()]}
```

Parses one literal value (a string, number, atom, list, map or tuple).

# `read`

```elixir
@spec read(Path.t()) :: {:ok, map()} | {:error, [String.t()]}
```

As `read!/1`, without raising: `{:ok, map}` (`%{}` when the file doesn't
exist) or `{:error, faults}`, every parse fault, or the one reason the
file can't be read.

# `read!`

```elixir
@spec read!(Path.t()) :: map()
```

The map in `path`, or `%{}` when the file doesn't exist. Raises on any fault.

# `write!`

```elixir
@spec write!(Path.t(), map(), String.t()) :: :ok
```

Writes a map as the file's literal text, atomically (a temporary file,
mode 0600, then a rename), so a crash leaves the old file or the new one,
never a partial one. `header` is a comment block for the top.

---

*Consult [api-reference.md](api-reference.md) for complete listing*