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

A variable (spec/02 §5): a term allowed wherever a value can appear, carrying only its
name, a string. Its default is declared once by the document that uses it, so two
fragments cannot disagree about it. A variable is a struct, so it is a leaf of every
walk: it stands for a value rather than being one.

- `bind/2,3` substitutes variables: a literal sets one, another variable renames it
  (§5.1);
- `free/2` lists the variables still open in a stack, each with every path it stands at
  and the layer that set it (§5.2).

Ported from visualize's `Visualize.Chart.Var`, `Use.bind/2` and `Stack.free_vars/1`.

    iex> Macaw.Layers.Var.new(:color)
    %Macaw.Layers.Var{name: "color"}
    iex> Macaw.Layers.Var.bind(%{fill: Macaw.Layers.Var.new(:color)}, %{color: "blue"})
    %{fill: "blue"}

# `t`

```elixir
@type t() :: %Macaw.Layers.Var{name: String.t()}
```

# `bind`

```elixir
@spec bind(term(), map()) :: term()
```

The fragment with its variables substituted (spec/02 §5.1): every `%Var{name: k}`
becomes the value `bindings` gives `k` — a literal sets it, another variable renames it
— read by either spelling, and a variable `bindings` does not name stays. A bound value
is not searched again: binding is single level. Any other struct is a leaf.

# `bind`

```elixir
@spec bind(module(), term(), map()) :: term()
```

`bind/2`, and a value of the type's own syntax (a text's holes) substituted by the type's
`bind_holes/4` at the key it stands at (spec/02 §5.1).

# `free`

```elixir
@spec free(module(), map() | [Macaw.Layers.Fragment.layer()]) :: [
  %{name: String.t(), uses: [map()]}
]
```

One entry per variable still in the stack of `layers` (a fragment is a one-layer stack),
ordered by name (spec/02 §5.2): `%{name, uses}`, each use `%{path, layer}`, ordered by
path. The walk descends into every map and list but a struct, and through the type's
`holes/3` into a value of its own syntax, whose variables stand at its key, each named
once there.

# `new`

```elixir
@spec new(atom() | String.t()) :: t()
```

The variable of a name, an atom read as its string.

---

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