# `Predicator.Errors.LocationError`
[🔗](https://github.com/riddler/predicator-ex/blob/v9.4.1/lib/predicator/errors/location_error.ex#L1)

Error struct for location expression validation failures.

This error is raised when attempting to resolve a location path for assignment
operations, but the expression does not represent a valid assignable location.
It also covers the write-time failures of `Predicator.ContextLocation.put/3`.

## Error Types

Resolution failures:

- `:not_assignable` - Expression cannot be used as an assignment target
- `:invalid_node` - Unknown or unsupported AST node type
- `:undefined_variable` - Variable referenced in bracket key is not defined
- `:invalid_key` - Bracket key is not a valid string or integer
- `:computed_key` - Computed expressions cannot be used as assignment keys

Write failures:

- `:not_a_container` - Path traverses a value that is neither a map nor a list
- `:invalid_index` - List index in the path is out of range (negative)

## Examples

    # Cannot assign to literal values
    %LocationError{
      type: :not_assignable,
      message: "Cannot assign to literal value",
      details: %{expression_type: "literal value", value: 42}
    }

    # Cannot assign to function calls
    %LocationError{
      type: :not_assignable,
      message: "Cannot assign to function call",
      details: %{expression_type: "function call", value: "len"}
    }

    # Invalid bracket key type
    %LocationError{
      type: :invalid_key,
      message: "Bracket key must be string or integer",
      details: %{key_type: "boolean", key_value: true}
    }

# `error_type`

```elixir
@type error_type() ::
  :not_assignable
  | :invalid_node
  | :undefined_variable
  | :invalid_key
  | :computed_key
  | :not_a_container
  | :invalid_index
```

# `t`

```elixir
@type t() :: %Predicator.Errors.LocationError{
  details: map(),
  message: binary(),
  type: error_type()
}
```

# `computed_key`

```elixir
@spec computed_key(binary(), term()) :: t()
```

Creates a LocationError for computed expressions used as bracket keys.

# `invalid_index`

```elixir
@spec invalid_index(binary(), integer(), non_neg_integer() | nil) :: t()
```

Creates a LocationError for an out-of-range list index in a location path.

`path_index` is the failing segment's 0-based index in the root-first location
path, or `nil` when the caller cannot identify one - see `not_a_container/4`.
It is unrelated to `index`: `index` is the out-of-range *list* index the
segment held, `path_index` is where that segment sits in the path itself, and
the two are different integers that happen to share a neighborhood in
`details`.

# `invalid_key`

```elixir
@spec invalid_key(binary(), term()) :: t()
```

Creates a LocationError for invalid bracket key types.

# `invalid_node`

```elixir
@spec invalid_node(binary(), term()) :: t()
```

Creates a LocationError for invalid or unknown AST node types.

# `not_a_container`

```elixir
@spec not_a_container(binary(), term(), term(), non_neg_integer() | nil) :: t()
```

Creates a LocationError for assignment through a non-container value.

Used when a location path traverses a value that is neither a map nor a list,
so intermediate structure cannot be created without destroying existing data.

`path_index` is the failing segment's 0-based index in the root-first location
path, or `nil` when the caller cannot identify one. `Predicator.Evaluator`'s
`store` path joins it with the run's segment-position table to point a store
failure at the segment that failed rather than at the location's root (px-ids).
It is deliberately a `details` key rather than a struct field: this struct is
shared with `Predicator.ContextLocation.resolve/2` and
`Predicator.Context.assign/3`, which have no path to index.

# `not_assignable`

```elixir
@spec not_assignable(binary(), term()) :: t()
```

Creates a LocationError for non-assignable expressions.

Used when an expression cannot be used as an assignment target (l-value).

# `undefined_variable`

```elixir
@spec undefined_variable(binary(), binary()) :: t()
```

Creates a LocationError for undefined variables in bracket keys.

---

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