Enum UniversalElementRole 

#[non_exhaustive]
pub enum UniversalElementRole {
    Root,
    Container,
    Definition,
    Binding,
    Reference,
    Typing,
    Documentation,
    Metadata,
    Attribute,
    AttributeKey,
    Detail,
    Name,
    Statement,
    Expression,
    Call,
    Value,
    Embedded,
    Error,
    None,
}

Represents the general structural role of a syntax tree element.

Universal Grammar

This mechanism is inspired by Noam Chomsky’s Universal Grammar theory, applied here to the structural hierarchy of syntax trees. It posits that while the “Surface Structure” (the specific production rules of a grammar) varies across languages, they share a common “Deep Structure” (structural intent).

In the Oak framework, syntax tree elements are categorized by their role:

• Surface Structure: Refers to specific node kinds defined by a language (e.g., Rust’s FnDeclaration, SQL’s SelectStatement, or YAML’s Mapping).
• Deep Structure: Refers to the universal structural patterns defined in this enum.

By mapping to these roles, we can perform sophisticated analysis across diverse language families:

• Containers & Statements: Identify hierarchical scopes and their constituents (e.g., a SQL table is a container, its clauses are statements).
• Bindings & References: Identify the flow of information and identifiers (e.g., an ASM label is a binding, a jump instruction is a reference).
• Values: Identify the atomic data payload or expression results.

Design Philosophy: The 99% Rule

This enum is designed to provide a “sufficiently complete” abstraction for common tool requirements (Highlighting, Outline, Navigation, and Refactoring) while maintaining language-agnostic simplicity.

1. Structural Identity (The “What”)

Roles describe a node’s primary structural responsibility in the tree, not its domain-specific semantic meaning. For example:

• A “Class” or “Function” is structurally a [Definition] and often a [Container].
• An “Import” is structurally a [Statement] that contains a [Reference].

2. Broad Categories (The “How”)

We categorize elements into four major structural groups:

• Flow Control & logic: [Statement], [Expression], [Call], and [Root].
• Symbol Management: [Definition], [Binding], and [Reference].
• Hierarchy & Scoping: [Container].
• Metadata & Auxiliaries: [Typing], [Metadata], [Attribute], [Documentation], etc.

3. Intent-Based Selection

When a node could fit multiple roles, choose the one that represents its primary structural intent.

• Example: In Rust, an if expression is both an Expression and a Container. However, its primary role in the tree is as an [Expression] (producing a value), whereas its children (the blocks) are [Container]s.
• Example: In Markdown, a “List” is a [Container], while each “ListItem” is a [Statement] within that container.

4. Intentional Exclusions

We intentionally exclude roles that can be represented by combining existing roles or that require deep semantic analysis:

• Keyword-specific roles: Roles like “Loop”, “Conditional”, or “Module” are excluded. These are surface-level distinctions. In the Deep Structure, they are all [Container]s or [Statement]s.
• Semantic Relationships: Roles like “Inheritance”, “Implementation”, or “Dependency” are excluded. These are better handled by semantic graph analysis rather than syntactic tree roles.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Root

The top-level root of the syntax tree, representing the entire document or source file.

Container

A high-level structural container that defines a scope or logical grouping.

Definition

A node that represents the entire declaration or definition of a symbol.

This role identifies the “whole” entity that defines something in the code, which is crucial for building symbol trees and navigation outlines.

Examples

• Rust: The entire Fn declaration block, Struct item, or Enum.
• Markdown: Heading or LinkDefinition.
• SQL: The whole CREATE TABLE or CREATE PROCEDURE statement.
• ASM: A Proc (procedure) block or a multi-line data definition.
• YAML: A schema-defined object or a complex configuration block.

Binding

A node that specifically performs the act of binding a name to an entity.

Unlike Definition, which represents the entire construct, Binding targets the specific part (usually the identifier) that introduces the name.

Examples

• Rust: The identifier node in a let pattern or function name.
• Markdown: LinkLabel in a reference link definition.
• SQL: The Table name identifier in CREATE TABLE.
• ASM: A Label node (e.g., main:).
• YAML: The Key in a key-value mapping.

Reference

A node that refers to an existing name or entity defined elsewhere.

Examples

• Rust: PathExpr (variable usage) or MethodCall.
• Markdown: LinkReference or FootnoteReference.
• SQL: ColumnName in a SELECT clause or TableName in FROM.
• ASM: A Label reference in a jump (e.g., JMP main).
• YAML: An Alias anchor (e.g., *anchor_name).

Typing

A node representing a type signature, constraint, or type reference.

This role distinguishes type information from general logic or values, which is essential for type checking and intelligent completion.

Examples

• Rust: TypePath (e.g., : i32), GenericArgument, or WhereClause.
• SQL: DataType (e.g., VARCHAR(255) or INT).
• ASM: Size specifiers (e.g., DWORD, PTR).
• TypeScript: TypeAnnotation or InterfaceDeclaration.

Documentation

Structured comments or documentation nodes attached to other elements.

Unlike raw Comment tokens, these are syntax nodes that may contain their own internal structure (like Markdown or Tagged parameters).

Examples

• Rust: DocComment (e.g., /// ...).
• Java: Javadoc blocks.
• Python: Docstring literals.

Metadata

High-level annotations, decorators, or macros that provide extra semantic info.

Metadata vs Attribute

• Metadata: Usually refers to language-level extensions that “decorate” an element from the outside, often affecting compilation or runtime behavior (e.g., Rust attributes).
• Attribute: Usually refers to built-in, structural properties that are part of the element’s native definition (e.g., HTML attributes).

Examples

• Rust: Attribute (e.g., #[derive(...)]) or MacroCall.
• Markdown: Frontmatter (YAML/TOML header).
• Java/TS: @Decorator or @Annotation.
• Python: @decorator syntax.

Attribute

A specific property, flag, or attribute-value pair.

Unlike Metadata, which decorates an element with external logic, Attribute represents intrinsic properties defined by the language’s schema or structure.

Examples

• HTML/XML: An Attribute (e.g., id="main").
• Markdown: LinkTitle or ImageAlt text.
• YAML: A specific configuration property.
• ASM: Segment attributes (e.g., READONLY, EXECUTE).

AttributeKey

The key part of an attribute, property, or configuration entry.

This role is distinct because:

• It is not a Reference (it doesn’t refer to an external symbol).
• It is not a traditional Binding (it doesn’t define a symbol in a global or lexical scope).
• It is not a Keyword (it is typically a user-defined or schema-defined identifier).

Examples

• HTML: The id in id="main".
• Markdown: AttributeName (in Pandoc-style { #id .class }).
• YAML: The key in a property mapping.
• TOML: The key in a table entry.

Detail

A node that provides additional details or secondary information for another element.

Examples

• Rust: GenericParameter list, FunctionParameter list.
• SQL: Constraint details.

Name

A node that represents the name of an element, typically used in declarations.

Examples

• Rust: The name identifier in a function or struct definition.
• HTML: The tag name in an element.

Statement

A discrete syntactic unit within a container, representing a single logical entry or instruction.

This typically maps to a Statement in programming languages, or a standalone instruction in assembly. In markup, it could represent a list item or a table row.

Examples

• Rust: A Stmt inside a block.
• Markdown: ListItem or TableCell.
• SQL: A standalone Statement or a Clause (like WHERE).
• ASM: A single Instruction (e.g., NOP).

Expression

A node representing a computed result or a complex logical operation.

Unlike a simple Value (which is an atomic literal), an Expression involves operators or logic that must be evaluated.

Examples

• Rust: BinaryExpr, UnaryExpr, or RangeExpr.
• SQL: BinaryOp in a WHERE clause.
• Python: ListComprehension or Lambda.

Call

A node that performs an invocation or call to a function, method, or macro.

This role identifies the active execution of a named entity with optional arguments.

Examples

• Rust: CallExpr, MethodCallExpr, or MacroInvocation.
• SQL: FunctionCall (e.g., COUNT(*)).
• Excel: A formula call.

Value

A node representing an atomic data value or a primitive constant.

This role is strictly for atomic values like numbers, strings, or booleans. It does not include composite structures like arrays [] or objects {}, which should be categorized as UniversalElementRole::Container.

Examples

• Rust: Literal (strings, numbers, booleans).
• Markdown: InlineCode, Emphasis, or Strong.
• SQL: Literal values.
• JSON/YAML: Atomic Scalar values (strings, integers, nulls).

Embedded

A node that acts as a host for content in a different language or a raw fragment requiring a separate parsing pass (Language Injection).

Examples

• HTML: A <script> or <style> block containing JS/CSS.
• Markdown: CodeBlock (host for other languages).
• Rust/Java: A string literal containing SQL (if marked for injection).
• PHP: Raw HTML fragments outside of <?php ... ?> tags.

Error

A node specifically created to represent a syntax error or recovery point in the source code.

None

No specific structural role assigned or recognized for this element.

Trait Implementations

impl Clone for UniversalElementRole

fn clone(&self) -> UniversalElementRole

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for UniversalElementRole

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for UniversalElementRole

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl ElementRole for UniversalElementRole

fn universal(&self) -> UniversalElementRole

Maps this role to a universal, language-agnostic role.

fn name(&self) -> &str

Returns a specific name for this role, used for granular highlighting.

impl Hash for UniversalElementRole

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for UniversalElementRole

fn eq(&self, other: &UniversalElementRole) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for UniversalElementRole

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Copy for UniversalElementRole

impl Eq for UniversalElementRole

impl StructuralPartialEq for UniversalElementRole