RustQ.Syn (rustq v0.6.0)

Structural metadata for Rust source parsed with 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.

Summary

Types

item()

type()

Functions

atom_references(source)

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

atom_references!(source)

Returns atom names referenced as atoms::name() calls in Rust source, raising on failure.

enum_variants(source, enum_name)

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

enum_variants!(source, enum_name)

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

enums(file)

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

functions(file)

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

impls(file)

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

method_calls(source)

Returns receiver method calls found in Rust source.

method_calls!(source)

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

method_references(source)

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

method_references!(source)

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

methods(file)

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

parse(source)

Parses Rust source into structural metadata.

parse!(source)

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

parse_file(path)

Reads and parses a Rust source file.

parse_file!(path)

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

structs(file)

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

type_aliases(file)

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

uses(file)

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

Types

item()

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

type()

@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.Raw.t()

Functions

atom_references(source)

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

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

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!(source)

@spec atom_references!(String.t()) :: [String.t()]

Returns atom names referenced as atoms::name() calls in Rust source, raising on failure.

enum_variants(source, enum_name)

@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!(source, enum_name)

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

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

enums(file)

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

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

functions(file)

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

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

impls(file)

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

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

method_calls(source)

@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!(source)

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

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

method_references(source)

@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!(source)

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

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

methods(file)

@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(source)

@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!(source)

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

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

parse_file(path)

@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!(path)

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

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

structs(file)

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

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

type_aliases(file)

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

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

uses(file)

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

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