# `TerminusDB.WOQL.Path`
[🔗](https://github.com/thanos/terminusdb-client-elixir/blob/v0.3.3/lib/terminus_db/woql/path.ex#L1)

Path pattern parser and structured builders for WOQL path queries.

Supports two modes:

## String-compiled parser

    TerminusDB.WOQL.Path.parse("friend*{1,3}")
    #=> {:times, {:pred, "friend"}, 1, 3}

Grammar: `predicate`, `<inverse`, `*` (star), `+` (plus), `{n}` / `{n,m}`
(bounded), `|` (or), `,` (sequence), `.` (any), `(...)` (grouping).

## Structured builders

    WOQL.Path.path_star(WOQL.Path.path_pred("friend"))
    #=> {:star, {:pred, "friend"}}

## Serialization

`to_jsonld/1` serializes a Path AST to the WOQL JSON-LD wire format.
`from_jsonld/1` deserializes back. `normalize/1` accepts either a string
or an AST tuple and returns an AST tuple.

This module is used internally by `WOQL.path/3` and `WOQL.path/4` but
can also be used directly for building path patterns programmatically.

# `from_jsonld`

```elixir
@spec from_jsonld(map()) :: tuple()
```

Deserializes a WOQL JSON-LD path pattern back into a Path AST.

# `normalize`

```elixir
@spec normalize(String.t() | tuple()) :: tuple()
```

Normalizes a pattern — if it's a string, parses it; if it's already an AST
tuple, returns it as-is.

# `parse`

```elixir
@spec parse(String.t()) :: tuple()
```

Parses a path pattern string into a Path AST.

## Examples

    iex> TerminusDB.WOQL.Path.parse("friend")
    {:pred, "friend"}

    iex> TerminusDB.WOQL.Path.parse("friend*")
    {:star, {:pred, "friend"}}

    iex> TerminusDB.WOQL.Path.parse("<friend")
    {:inverse, "friend"}

    iex> TerminusDB.WOQL.Path.parse("friend|foe")
    {:or, [{:pred, "friend"}, {:pred, "foe"}]}

# `path_any`

```elixir
@spec path_any() :: tuple()
```

Builds a path "any predicate" node (matches `.` in the string grammar).

# `path_inverse`

```elixir
@spec path_inverse(String.t()) :: tuple()
```

Builds an inverse path — traverses the predicate in reverse direction.

# `path_or`

```elixir
@spec path_or([tuple()]) :: tuple()
```

Builds a path alternation — any branch may be taken.

# `path_plus`

```elixir
@spec path_plus(tuple()) :: tuple()
```

Builds a path plus — one or more repetitions.

# `path_pred`

```elixir
@spec path_pred(String.t()) :: tuple()
```

Builds a path predicate node for the given predicate name.

# `path_seq`

```elixir
@spec path_seq([tuple()]) :: tuple()
```

Builds a path sequence — each step is traversed in order.

# `path_star`

```elixir
@spec path_star(tuple()) :: tuple()
```

Builds a path star — zero or more repetitions.

# `path_times`

```elixir
@spec path_times(tuple(), non_neg_integer(), non_neg_integer() | nil) :: tuple()
```

Builds a path times — `from` to `to` repetitions. `to` may be `nil` for
unbounded.

# `to_jsonld`

```elixir
@spec to_jsonld(tuple()) :: map()
```

Serializes a Path AST node to the WOQL JSON-LD wire format.

---

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