# `RustQ.Syn`
[🔗](https://github.com/dannote/rustq/blob/v0.11.1/lib/rustq/syn.ex#L1)

Structural metadata for Rust source parsed with [`syn`](https://docs.rs/syn).

`RustQ.Syn` is for introspecting existing Rust source. It returns Elixir
metadata for Rust items such as enums, structs, free functions, `impl` blocks,
methods, docs, arguments, return types, and common Rust type shapes.

This is **Rust AST metadata**, not Rusty Elixir AST and not `RustQ.Rust.AST`.
Use it when a generator needs to understand Rust that already exists in an
upstream crate, for example to discover a crate's methods or enum variants
without parsing Rust text with regex.

## Example

    file = RustQ.Syn.parse_file!("native/my_crate/src/lib.rs")

    file
    |> RustQ.Syn.methods()
    |> Enum.find(&(&1.name == "draw_rect"))

Arguments and returns keep both the rendered Rust type string and a structured
type node:

    %RustQ.Syn.Arg{
      name: "paint",
      type: "& Paint",
      type_ast: %RustQ.Syn.Type.Ref{
        inner: %RustQ.Syn.Type.Path{name: "Paint"}
      }
    }

The structured type vocabulary is intentionally partial. Unknown or currently
unsupported Rust type forms are represented as `%RustQ.Syn.Type.Raw{}` with
the original rendered code preserved.

# `item`

```elixir
@type item() ::
  RustQ.Syn.Enum.t()
  | RustQ.Syn.Use.t()
  | RustQ.Syn.Static.t()
  | RustQ.Syn.TypeAlias.t()
  | RustQ.Syn.Struct.t()
  | RustQ.Syn.Function.t()
  | RustQ.Syn.Impl.t()
```

# `type`

```elixir
@type type() ::
  RustQ.Syn.Type.Path.t()
  | RustQ.Syn.Type.Ref.t()
  | RustQ.Syn.Type.Tuple.t()
  | RustQ.Syn.Type.Option.t()
  | RustQ.Syn.Type.Result.t()
  | RustQ.Syn.Type.ImplTrait.t()
  | RustQ.Syn.Type.Slice.t()
  | RustQ.Syn.Type.Array.t()
  | RustQ.Syn.Type.Self.t()
  | RustQ.Syn.Type.Fn.t()
  | RustQ.Syn.Type.Raw.t()
```

# `atom_references`

```elixir
@spec atom_references(
  String.t(),
  keyword()
) :: {:ok, [String.t()]} | {:error, term()}
```

Returns atom names referenced as `atoms::name()` calls in Rust source.

Pass `module: "a"` to discover calls through another atom module. This is
intended for generators that need to keep `rustler::atoms!` in sync with
existing Rust code without scraping source text. The source is parsed by
`syn`; invalid Rust returns a normal RustQ parse error.

# `atom_references!`

```elixir
@spec atom_references!(
  String.t(),
  keyword()
) :: [String.t()]
```

Returns referenced atom names in Rust source, raising on failure.

# `enum_variants`

```elixir
@spec enum_variants(String.t(), String.t()) :: {:ok, [String.t()]} | {:error, term()}
```

Returns variants for a named top-level enum from Rust source.

This is a focused helper for code generators that only need enum variants and
do not need the full `RustQ.Syn.File` metadata.

# `enum_variants!`

```elixir
@spec enum_variants!(String.t(), String.t()) :: [String.t()]
```

Returns variants for a named top-level enum from Rust source, raising on failure.

# `enums`

```elixir
@spec enums(RustQ.Syn.File.t()) :: [RustQ.Syn.Enum.t()]
```

Returns top-level Rust enum metadata from a parsed file.

# `functions`

```elixir
@spec functions(RustQ.Syn.File.t()) :: [RustQ.Syn.Function.t()]
```

Returns top-level Rust free function metadata from a parsed file.

# `impls`

```elixir
@spec impls(RustQ.Syn.File.t()) :: [RustQ.Syn.Impl.t()]
```

Returns top-level Rust impl block metadata from a parsed file.

# `method_calls`

```elixir
@spec method_calls(String.t()) :: {:ok, [RustQ.Syn.MethodCall.t()]} | {:error, term()}
```

Returns receiver method calls found in Rust source.

For example, `canvas.draw_rect(...)` contributes
`%RustQ.Syn.MethodCall{receiver: "canvas", method: "draw_rect"}`.

# `method_calls!`

```elixir
@spec method_calls!(String.t()) :: [RustQ.Syn.MethodCall.t()]
```

Returns receiver method calls found in Rust source, raising on failure.

# `method_references`

```elixir
@spec method_references(String.t()) :: {:ok, [String.t()]} | {:error, term()}
```

Returns method names referenced as receiver method calls in Rust source.

For example, `canvas.draw_rect(...)` contributes `"draw_rect"`.

# `method_references!`

```elixir
@spec method_references!(String.t()) :: [String.t()]
```

Returns method names referenced as receiver method calls in Rust source, raising on failure.

# `methods`

```elixir
@spec methods(RustQ.Syn.File.t()) :: [RustQ.Syn.Method.t()]
```

Returns methods from all top-level Rust impl blocks in a parsed file.

Use `impls/1` when the containing impl target or trait matters.

# `parse`

```elixir
@spec parse(String.t()) :: {:ok, RustQ.Syn.File.t()} | {:error, term()}
```

Parses Rust source into structural metadata.

Returns `{:ok, %RustQ.Syn.File{}}` on success. Parser errors are returned in
RustQ's normal template-error shape.

# `parse!`

```elixir
@spec parse!(String.t()) :: RustQ.Syn.File.t()
```

Parses Rust source into structural metadata, raising `RustQ.Error` on failure.

# `parse_file`

```elixir
@spec parse_file(Path.t()) :: {:ok, RustQ.Syn.File.t()} | {:error, term()}
```

Reads and parses a Rust source file.

File read errors are returned as `{:error, reason}`. Rust parse errors are
returned as `{:error, errors}`.

# `parse_file!`

```elixir
@spec parse_file!(Path.t()) :: RustQ.Syn.File.t()
```

Reads and parses a Rust source file, raising on file or Rust parse errors.

# `statics`

```elixir
@spec statics(RustQ.Syn.File.t()) :: [RustQ.Syn.Static.t()]
```

Returns top-level Rust static item metadata from a parsed file.

# `structs`

```elixir
@spec structs(RustQ.Syn.File.t()) :: [RustQ.Syn.Struct.t()]
```

Returns top-level Rust struct metadata from a parsed file.

# `type_aliases`

```elixir
@spec type_aliases(RustQ.Syn.File.t()) :: [RustQ.Syn.TypeAlias.t()]
```

Returns top-level Rust type alias metadata from a parsed file.

# `uses`

```elixir
@spec uses(RustQ.Syn.File.t()) :: [RustQ.Syn.Use.t()]
```

Returns top-level Rust `use` alias metadata from a parsed file.

---

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