# `Macaw.Layers.Names`
[🔗](https://github.com/dcoai/macaw_layers/blob/v0.2.2/lib/macaw/layers/names.ex#L1)

Names a document declares (spec/01 §1): a source, a field, a variable, a frame, a style,
a fragment's key.

A name is a string. Elixir input may spell one as an atom, which is read as the string
of the same spelling with `Atom.to_string/1`, which makes no atom; and a category value is
matched by spelling, so `:ok` and `"ok"` are one value. Nothing here makes an atom from
a document's data.

Ported from visualize's `Visualize.Chart.Names`.

# `category`

```elixir
@spec category(term()) :: term()
```

A category value as it is compared: an atom other than `nil`, `true` and `false` by its
spelling, anything else as it is.

# `fetch`

```elixir
@spec fetch(map(), term()) :: {:ok, term()} | :error
```

`Map.fetch/2` by spelling, through `key/2`.

# `is_name`
*macro* 

A name in a guard: a string, or an atom other than `nil`, `true` and `false`.

# `key`

```elixir
@spec key(map(), term()) :: {:ok, term()} | :error
```

The key of `map` that spells `name`: the name itself, or the key of the other spelling.

How a document's name finds a host's entry, keyed as the host keyed it (a source in a
pool, a variable's value), without an atom made.

# `keys`

```elixir
@spec keys(term()) :: term()
```

A plain map's keys as names, values untouched; a struct or a non-map as it is.

# `name`

```elixir
@spec name(term()) :: term()
```

A name as a document holds it: an atom's spelling, a string as it is, and anything else
(a library id `{kind, n}`, a malformed value a validator names) untouched.

    iex> Macaw.Layers.Names.name(:sales)
    "sales"
    iex> Macaw.Layers.Names.name({:id, 1})
    {:id, 1}

# `name?`

```elixir
@spec name?(term()) :: boolean()
```

Whether a value is a name: a non-empty string, or an atom `name/1` reads as one.

# `same?`

```elixir
@spec same?(term(), term()) :: boolean()
```

Whether two category values are one: equal, or the same spelling.

---

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