Enum NodeKind 

pub enum NodeKind {
    Program {
        statements: Vec<Node>,
    },
    ExpressionStatement {
        expression: Box<Node>,
    },
    VariableDeclaration {
        declarator: String,
        variable: Box<Node>,
        attributes: Vec<String>,
        initializer: Option<Box<Node>>,
    },
    VariableListDeclaration {
        declarator: String,
        variables: Vec<Node>,
        attributes: Vec<String>,
        initializer: Option<Box<Node>>,
    },
    Variable {
        sigil: String,
        name: String,
    },
    VariableWithAttributes {
        variable: Box<Node>,
        attributes: Vec<String>,
    },
    Assignment {
        lhs: Box<Node>,
        rhs: Box<Node>,
        op: String,
    },
    Binary {
        op: String,
        left: Box<Node>,
        right: Box<Node>,
    },
    Ternary {
        condition: Box<Node>,
        then_expr: Box<Node>,
        else_expr: Box<Node>,
    },
    Unary {
        op: String,
        operand: Box<Node>,
    },
    Diamond,
    Ellipsis,
    Undef,
    Readline {
        filehandle: Option<String>,
    },
    Glob {
        pattern: String,
    },
    Typeglob {
        name: String,
    },
    Number {
        value: String,
    },
    String {
        value: String,
        interpolated: bool,
    },
    Heredoc {
        delimiter: String,
        content: String,
        interpolated: bool,
        indented: bool,
        command: bool,
        body_span: Option<ByteSpan>,
    },
    ArrayLiteral {
        elements: Vec<Node>,
    },
    HashLiteral {
        pairs: Vec<(Node, Node)>,
    },
    Block {
        statements: Vec<Node>,
    },
    Eval {
        block: Box<Node>,
    },
    Do {
        block: Box<Node>,
    },
    Try {
        body: Box<Node>,
        catch_blocks: Vec<(Option<String>, Box<Node>)>,
        finally_block: Option<Box<Node>>,
    },
    If {
        condition: Box<Node>,
        then_branch: Box<Node>,
        elsif_branches: Vec<(Box<Node>, Box<Node>)>,
        else_branch: Option<Box<Node>>,
    },
    LabeledStatement {
        label: String,
        statement: Box<Node>,
    },
    While {
        condition: Box<Node>,
        body: Box<Node>,
        continue_block: Option<Box<Node>>,
    },
    Tie {
        variable: Box<Node>,
        package: Box<Node>,
        args: Vec<Node>,
    },
    Untie {
        variable: Box<Node>,
    },
    For {
        init: Option<Box<Node>>,
        condition: Option<Box<Node>>,
        update: Option<Box<Node>>,
        body: Box<Node>,
        continue_block: Option<Box<Node>>,
    },
    Foreach {
        variable: Box<Node>,
        list: Box<Node>,
        body: Box<Node>,
        continue_block: Option<Box<Node>>,
    },
    Given {
        expr: Box<Node>,
        body: Box<Node>,
    },
    When {
        condition: Box<Node>,
        body: Box<Node>,
    },
    Default {
        body: Box<Node>,
    },
    StatementModifier {
        statement: Box<Node>,
        modifier: String,
        condition: Box<Node>,
    },
    Subroutine {
        name: Option<String>,
        name_span: Option<ByteSpan>,
        prototype: Option<Box<Node>>,
        signature: Option<Box<Node>>,
        attributes: Vec<String>,
        body: Box<Node>,
    },
    Prototype {
        content: String,
    },
    Signature {
        parameters: Vec<Node>,
    },
    MandatoryParameter {
        variable: Box<Node>,
    },
    OptionalParameter {
        variable: Box<Node>,
        default_value: Box<Node>,
    },
    SlurpyParameter {
        variable: Box<Node>,
    },
    NamedParameter {
        variable: Box<Node>,
    },
    Method {
        name: String,
        signature: Option<Box<Node>>,
        attributes: Vec<String>,
        body: Box<Node>,
    },
    Return {
        value: Option<Box<Node>>,
    },
    LoopControl {
        op: String,
        label: Option<String>,
    },
    Goto {
        target: Box<Node>,
    },
    MethodCall {
        object: Box<Node>,
        method: String,
        args: Vec<Node>,
    },
    FunctionCall {
        name: String,
        args: Vec<Node>,
    },
    IndirectCall {
        method: String,
        object: Box<Node>,
        args: Vec<Node>,
    },
    Regex {
        pattern: String,
        replacement: Option<String>,
        modifiers: String,
        has_embedded_code: bool,
    },
    Match {
        expr: Box<Node>,
        pattern: String,
        modifiers: String,
        has_embedded_code: bool,
        negated: bool,
    },
    Substitution {
        expr: Box<Node>,
        pattern: String,
        replacement: String,
        modifiers: String,
        has_embedded_code: bool,
        negated: bool,
    },
    Transliteration {
        expr: Box<Node>,
        search: String,
        replace: String,
        modifiers: String,
        negated: bool,
    },
    Package {
        name: String,
        name_span: ByteSpan,
        block: Option<Box<Node>>,
    },
    Use {
        module: String,
        args: Vec<String>,
        has_filter_risk: bool,
    },
    No {
        module: String,
        args: Vec<String>,
        has_filter_risk: bool,
    },
    PhaseBlock {
        phase: String,
        phase_span: Option<ByteSpan>,
        block: Box<Node>,
    },
    DataSection {
        marker: String,
        body: Option<String>,
    },
    Class {
        name: String,
        body: Box<Node>,
    },
    Format {
        name: String,
        body: String,
    },
    Identifier {
        name: String,
    },
    Error {
        message: String,
        expected: Vec<TokenKind>,
        found: Option<Token>,
        partial: Option<Box<Node>>,
    },
    MissingExpression,
    MissingStatement,
    MissingIdentifier,
    MissingBlock,
    UnknownRest,
}

AST node, node kind enum, and source location types. Comprehensive enumeration of all Perl language constructs supported by the parser.

This enum represents every possible AST node type that can be parsed from Perl code during the Parse → Index → Navigate → Complete → Analyze workflow. Each variant captures the semantic meaning and structural relationships needed for complete script analysis and transformation.

LSP Workflow Integration

Node kinds are processed differently across workflow stages:

• Parse: All variants are produced by the parser
• Index: Symbol-bearing variants feed workspace indexing
• Navigate: Call and reference variants support navigation features
• Complete: Expression variants provide completion context
• Analyze: Semantic variants drive diagnostics and refactoring

Examples

Pattern-match on node kinds to extract semantic information:

use perl_ast::{Node, NodeKind, SourceLocation};

let loc = SourceLocation { start: 0, end: 5 };
let node = Node::new(
    NodeKind::Variable { sigil: "$".to_string(), name: "foo".to_string() },
    loc,
);

match &node.kind {
    NodeKind::Variable { sigil, name } => {
        assert_eq!(sigil, "$");
        assert_eq!(name, "foo");
    }
    _ => panic!("expected Variable"),
}

Use kind_name() for debugging and diagnostics:

use perl_ast::NodeKind;

let kind = NodeKind::Number { value: "99".to_string() };
assert_eq!(kind.kind_name(), "Number");

let kind = NodeKind::Variable { sigil: "@".to_string(), name: "list".to_string() };
assert_eq!(kind.kind_name(), "Variable");

Performance Considerations

The enum design optimizes for large codebases:

• Box pointers minimize stack usage for recursive structures
• Vector storage enables efficient bulk operations on child nodes
• Clone operations optimized for concurrent analysis workflows
• Pattern matching performance tuned for common Perl constructs

Variants

Program

Top-level program containing all statements in an Perl script

This is the root node for any parsed Perl script content, containing all top-level statements found during the Parse stage of LSP workflow.

Fields

statements: Vec<Node>

All top-level statements in the Perl script

ExpressionStatement

Statement wrapper for expressions that appear at statement level

Used during Analyze stage to distinguish between expressions used as statements versus expressions within other contexts during Perl parsing.

Fields

expression: Box<Node>

The expression being used as a statement

VariableDeclaration

Variable declaration with scope declarator in Perl script processing

Represents declarations like my $var, our $global, local $dynamic, etc. Critical for Analyze stage symbol table construction during Perl parsing.

Fields

declarator: String

Scope declarator: “my”, “our”, “local”, “state”

variable: Box<Node>

The variable being declared

attributes: Vec<String>

Variable attributes (e.g., “:shared”, “:locked”)

initializer: Option<Box<Node>>

Optional initializer expression

VariableListDeclaration

Multiple variable declaration in a single statement

Handles constructs like my ($x, $y) = @values common in Perl script processing. Supports efficient bulk variable analysis during Navigate stage operations.

Fields

declarator: String

Scope declarator for all variables in the list

variables: Vec<Node>

All variables being declared in the list

attributes: Vec<String>

Attributes applied to the variable list

initializer: Option<Box<Node>>

Optional initializer for the entire variable list

Variable

Perl variable reference (scalar, array, hash, etc.) in Perl parsing workflow

Fields

sigil: String

Variable sigil indicating type: $, @, %, &, *

name: String

Variable name without sigil

VariableWithAttributes

Variable with additional attributes for enhanced LSP workflow

Fields

variable: Box<Node>

The base variable node

attributes: Vec<String>

List of attribute names applied to the variable

Assignment

Assignment operation for LSP data processing workflows

Fields

lhs: Box<Node>

Left-hand side of assignment

rhs: Box<Node>

Right-hand side of assignment

op: String

Assignment operator: =, +=, -=, etc.

Binary

Binary operation for Perl parsing workflow calculations

Fields

op: String

Binary operator

left: Box<Node>

Left operand

right: Box<Node>

Right operand

Ternary

Ternary conditional expression for Perl parsing workflow logic

Fields

condition: Box<Node>

Condition to evaluate

then_expr: Box<Node>

Expression when condition is true

else_expr: Box<Node>

Expression when condition is false

Unary

Unary operation for Perl parsing workflow

Fields

op: String

Unary operator

operand: Box<Node>

Operand to apply operator to

Diamond

Diamond operator for file input in Perl parsing workflow

Ellipsis

Ellipsis operator for Perl parsing workflow

Undef

Undef value for Perl parsing workflow

Readline

Readline operation for LSP file processing

Fields

filehandle: Option<String>

Optional filehandle: <STDIN>, <$fh>, etc.

Glob

Glob pattern for LSP workspace file matching

Fields

pattern: String

Pattern string for file matching

Typeglob

Typeglob expression: *foo or *main::bar

Provides access to all symbol table entries for a given name.

Fields

name: String

Name of the symbol (including package qualification)

Number

Numeric literal in Perl code (integer, float, hex, octal, binary)

Represents all numeric literal forms: 42, 3.14, 0x1A, 0o755, 0b1010.

Fields

value: String

String representation preserving original format

String

String literal with optional interpolation

Handles both single-quoted ('literal') and double-quoted ("$interpolated") strings.

Fields

value: String

String content (after quote processing)

interpolated: bool

Whether the string supports variable interpolation

Heredoc

Heredoc string literal for multi-line content

Supports all heredoc forms: <<EOF, <<'EOF', <<"EOF", <<~EOF (indented).

Fields

delimiter: String

Delimiter marking heredoc boundaries

content: String

Content between delimiters

interpolated: bool

Whether content supports variable interpolation

indented: bool

Whether leading whitespace is stripped (<<~ form)

command: bool

Whether this is a command execution heredoc (<<EOF)

body_span: Option<ByteSpan>

Body span for breakpoint detection (populated by drain_pending_heredocs)

ArrayLiteral

Array literal expression: (1, 2, 3) or [1, 2, 3]

Fields

elements: Vec<Node>

Elements in the array

HashLiteral

Hash literal expression: (key => 'value') or {key => 'value'}

Fields

pairs: Vec<(Node, Node)>

Key-value pairs in the hash

Block

Block of statements: { ... }

Used for control structures, subroutine bodies, and bare blocks.

Fields

statements: Vec<Node>

Statements within the block

Eval

Eval block for exception handling: eval { ... }

Fields

block: Box<Node>

Block to evaluate with exception trapping

Do

Do block for file inclusion or expression evaluation: do { ... } or do "file"

Fields

block: Box<Node>

Block to execute or file expression

Try

Try-catch-finally for modern exception handling (Syntax::Keyword::Try style)

Fields

body: Box<Node>

Try block body

catch_blocks: Vec<(Option<String>, Box<Node>)>

Catch blocks: (optional exception variable, handler block)

finally_block: Option<Box<Node>>

Optional finally block

If

If-elsif-else conditional statement

Fields

condition: Box<Node>

Condition expression

then_branch: Box<Node>

Then branch block

elsif_branches: Vec<(Box<Node>, Box<Node>)>

Elsif branches: (condition, block) pairs

else_branch: Option<Box<Node>>

Optional else branch

LabeledStatement

Statement with a label for loop control: LABEL: while (...)

Fields

label: String

Label name (e.g., “OUTER”, “LINE”)

statement: Box<Node>

Labeled statement (typically a loop)

While

While loop: while (condition) { ... }

Fields

condition: Box<Node>

Loop condition

body: Box<Node>

Loop body

continue_block: Option<Box<Node>>

Optional continue block

Tie

Tie operation for binding variables to objects: tie %hash, 'Package', @args

Fields

variable: Box<Node>

Variable being tied

package: Box<Node>

Class/package name to tie to

args: Vec<Node>

Arguments passed to TIE* method

Untie

Untie operation for unbinding variables: untie %hash

Fields

variable: Box<Node>

Variable being untied

For

C-style for loop: for (init; cond; update) { ... }

Fields

init: Option<Box<Node>>

Initialization expression

condition: Option<Box<Node>>

Loop condition

update: Option<Box<Node>>

Update expression

body: Box<Node>

Loop body

continue_block: Option<Box<Node>>

Optional continue block

Foreach

Foreach loop: foreach my $item (@list) { ... }

Fields

variable: Box<Node>

Iterator variable

list: Box<Node>

List to iterate

body: Box<Node>

Loop body

continue_block: Option<Box<Node>>

Optional continue block

Given

Given statement for switch-like matching (Perl 5.10+)

Fields

expr: Box<Node>

Expression to match against

body: Box<Node>

Body containing when/default blocks

When

When clause in given/switch: when ($pattern) { ... }

Fields

condition: Box<Node>

Pattern to match

body: Box<Node>

Handler block

Default

Default clause in given/switch: default { ... }

Fields

body: Box<Node>

Handler block for unmatched cases

StatementModifier

Statement modifier syntax: print "ok" if $condition

Fields

statement: Box<Node>

Statement to conditionally execute

modifier: String

Modifier keyword: if, unless, while, until, for, foreach

condition: Box<Node>

Modifier condition

Subroutine

Subroutine declaration (function) including name, prototype, signature and body.

Fields

name: Option<String>

Name of the subroutine

Precise Navigation Support

• Added name_span for exact LSP navigation
• Enables precise go-to-definition and hover behavior
• O(1) span lookup in workspace symbols

Integration Points

• Semantic token providers
• Cross-reference generation
• Symbol renaming

name_span: Option<ByteSpan>

Source location span of the subroutine name

Usage Notes

• Always corresponds to the name field
• Provides constant-time position information
• Essential for precise editor interactions

prototype: Option<Box<Node>>

Optional prototype node (e.g. ($;@)).

signature: Option<Box<Node>>

Optional signature node (Perl 5.20+ feature).

attributes: Vec<String>

Attributes attached to the subroutine (:lvalue, etc.).

body: Box<Node>

The body block of the subroutine.

Prototype

Subroutine prototype specification: sub foo ($;@) { ... }

Fields

content: String

Prototype string defining argument behavior

Signature

Subroutine signature (Perl 5.20+): sub foo ($x, $y = 0) { ... }

Fields

parameters: Vec<Node>

List of signature parameters

MandatoryParameter

Mandatory signature parameter: $x in sub foo ($x) { }

Fields

variable: Box<Node>

Variable being bound

OptionalParameter

Optional signature parameter with default: $y = 0 in sub foo ($y = 0) { }

Fields

variable: Box<Node>

Variable being bound

default_value: Box<Node>

Default value expression

SlurpyParameter

Slurpy parameter collecting remaining args: @rest or %opts in signature

Fields

variable: Box<Node>

Array or hash variable to receive remaining arguments

NamedParameter

Named parameter placeholder in signature (future Perl feature)

Fields

variable: Box<Node>

Variable for named parameter binding

Method

Method declaration (Perl 5.38+ with use feature 'class')

Fields

name: String

Method name

signature: Option<Box<Node>>

Optional signature

attributes: Vec<String>

Method attributes (e.g., :lvalue)

body: Box<Node>

Method body

Return

Return statement: return; or return $value;

Fields

value: Option<Box<Node>>

Optional return value

LoopControl

Loop control statement: next, last, or redo

Fields

op: String

Control keyword: “next”, “last”, or “redo”

label: Option<String>

Optional label: next LABEL

Goto

Goto statement: goto LABEL, goto &sub, or goto $expr

Fields

target: Box<Node>

The target of the goto (label identifier, sub reference, or expression)

MethodCall

Method call: $obj->method(@args) or $obj->method

Fields

object: Box<Node>

Object or class expression

method: String

Method name being called

args: Vec<Node>

Method arguments

FunctionCall

Function call: foo(@args) or foo()

Fields

name: String

Function name (may be qualified: Package::func)

args: Vec<Node>

Function arguments

IndirectCall

Indirect object call (legacy syntax): new Class @args

Fields

method: String

Method name

object: Box<Node>

Object or class

args: Vec<Node>

Arguments

Regex

Regex literal: /pattern/modifiers or qr/pattern/modifiers

Fields

pattern: String

Regular expression pattern

replacement: Option<String>

Replacement string (for s/// when parsed as regex)

modifiers: String

Regex modifiers (i, m, s, x, g, etc.)

has_embedded_code: bool

Whether the regex contains embedded code (?{...})

Match

Match operation: $str =~ /pattern/modifiers or $str !~ /pattern/modifiers

Fields

expr: Box<Node>

Expression to match against

pattern: String

Pattern to match

modifiers: String

Match modifiers

has_embedded_code: bool

Whether the regex contains embedded code (?{...})

negated: bool

Whether the binding operator was !~ (negated match)

Substitution

Substitution operation: $str =~ s/pattern/replacement/modifiers

Fields

expr: Box<Node>

Expression to substitute in

pattern: String

Pattern to find

replacement: String

Replacement string

modifiers: String

Substitution modifiers (g, e, r, etc.)

has_embedded_code: bool

Whether the regex contains embedded code (?{...})

negated: bool

Whether the binding operator was !~ (negated match)

Transliteration

Transliteration operation: $str =~ tr/search/replace/ or y///

Fields

expr: Box<Node>

Expression to transliterate

search: String

Characters to search for

replace: String

Replacement characters

modifiers: String

Transliteration modifiers (c, d, s, r)

negated: bool

Whether the binding operator was !~ (negated match)

Package

Package declaration (e.g. package Foo;) and optional inline block form.

Fields

name: String

Name of the package

Precise Navigation Support

• Added name_span for exact LSP navigation
• Enables precise go-to-definition and hover behavior
• O(1) span lookup in workspace symbols

Integration Points

• Workspace indexing
• Cross-module symbol resolution
• Code action providers

name_span: ByteSpan

Source location span of the package name

Usage Notes

• Always corresponds to the name field
• Provides constant-time position information
• Essential for precise editor interactions

block: Option<Box<Node>>

Optional inline block for package Foo { ... } declarations.

Use

Use statement for module loading: use Module qw(imports);

Fields

module: String

Module name to load

args: Vec<String>

Import arguments (symbols to import)

has_filter_risk: bool

Whether this module is a known source filter (security risk)

No

No statement for disabling features: no strict;

Fields

module: String

Module/pragma name to disable

args: Vec<String>

Arguments for the no statement

has_filter_risk: bool

Whether this module is a known source filter (security risk)

PhaseBlock

Phase block for compile/runtime hooks: BEGIN, END, CHECK, INIT, UNITCHECK

Fields

phase: String

Phase name: BEGIN, END, CHECK, INIT, UNITCHECK

phase_span: Option<ByteSpan>

Source location span of the phase block name for precise navigation

block: Box<Node>

Block to execute during the specified phase

DataSection

Data section marker: __DATA__ or __END__

Fields

marker: String

Section marker (DATA or END)

body: Option<String>

Content following the marker (if any)

Class

Class declaration (Perl 5.38+ with use feature 'class')

Fields

name: String

Class name

body: Box<Node>

Class body containing methods and attributes

Format

Format declaration for legacy report generation

Fields

name: String

Format name (defaults to filehandle name)

body: String

Format specification body

Identifier

Bare identifier (bareword or package-qualified name)

Fields

name: String

Identifier string

Error

Parse error placeholder with error message and recovery context

Fields

message: String

Error description

expected: Vec<TokenKind>

Expected token types (if any)

found: Option<Token>

The token actually found (if any)

partial: Option<Box<Node>>

Partial AST node parsed before error (if any)

MissingExpression

Missing expression where one was expected

MissingStatement

Missing statement where one was expected

MissingIdentifier

Missing identifier where one was expected

MissingBlock

Missing block where one was expected

UnknownRest

Lexer budget exceeded marker preserving partial parse results

Used when recursion or token limits are hit to preserve already-parsed content.

Implementations

impl NodeKind

pub const ALL_KIND_NAMES: &'static [&'static str]

Canonical list of all kind_name() strings, in alphabetical order.

Every consumer that needs the full set of NodeKind names should reference this constant instead of maintaining a hand-written copy.

pub const RECOVERY_KIND_NAMES: &'static [&'static str]

Subset of ALL_KIND_NAMES that represent synthetic/recovery nodes.

These kinds are only produced by parse_with_recovery() on malformed input and should not be expected in clean parses.

pub fn kind_name(&self) -> &'static str

Get the name of this NodeKind as a static string.

Useful for diagnostics, logging, and human-readable AST dumps.

Examples

use perl_ast::NodeKind;

let kind = NodeKind::Variable { sigil: "$".to_string(), name: "x".to_string() };
assert_eq!(kind.kind_name(), "Variable");

let kind = NodeKind::Program { statements: vec![] };
assert_eq!(kind.kind_name(), "Program");

Trait Implementations

impl Clone for NodeKind

fn clone(&self) -> NodeKind

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for NodeKind

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

Formats the value using the given formatter.

impl PartialEq for NodeKind

fn eq(&self, other: &NodeKind) -> 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 StructuralPartialEq for NodeKind