Macaw.Host.Config.Literal (macaw_host v0.1.4)

Copy Markdown View Source

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.

Summary

Functions

parse(text, path \\ "config.exs")

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!(text, path \\ "config.exs")

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

parse_value(text, label \\ "value")

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

read(path)

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!(path)

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

write!(path, map, header \\ "")

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.

Functions

parse(text, path \\ "config.exs")

@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!(text, path \\ "config.exs")

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

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

parse_value(text, label \\ "value")

@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(path)

@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!(path)

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

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

write!(path, map, header \\ "")

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