Struct Node 

pub struct Node {
    pub kind: NodeKind,
    pub location: ByteSpan,
}

Core AST types re-exported for convenience. Re-exported AST node types used during Parse/Index/Analyze stages. Core AST node representing any Perl language construct within parsing workflows.

This is the fundamental building block for representing parsed Perl code. Each node contains both the semantic information (kind) and positional information (location) necessary for comprehensive script analysis.

LSP Workflow Role

Nodes flow through tooling stages:

• Parse: Created by the parser as it builds the syntax tree
• Index: Visited to build symbol and reference tables
• Navigate: Used to resolve definitions, references, and call hierarchy
• Complete: Provides contextual information for completion and hover
• Analyze: Drives semantic analysis and diagnostics

Memory Optimization

The structure is designed for efficient memory usage during large-scale parsing:

• SourceLocation uses compact position encoding for large files
• NodeKind enum variants minimize memory overhead for common constructs
• Clone operations are optimized for shared analysis workflows

Examples

Construct a variable declaration node manually:

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

let loc = SourceLocation { start: 0, end: 11 };
let var = Node::new(
    NodeKind::Variable { sigil: "$".to_string(), name: "x".to_string() },
    loc,
);
let decl = Node::new(
    NodeKind::VariableDeclaration {
        declarator: "my".to_string(),
        variable: Box::new(var),
        attributes: vec![],
        initializer: None,
    },
    loc,
);
assert_eq!(decl.kind.kind_name(), "VariableDeclaration");

Typically you obtain nodes from the parser rather than constructing them by hand:

use perl_parser::Parser;

let mut parser = Parser::new("my $x = 42;");
let ast = parser.parse()?;
println!("AST: {}", ast.to_sexp());

Fields

kind: NodeKind

The specific type and semantic content of this AST node

location: ByteSpan

Source position information for error reporting and code navigation

Implementations

impl Node

pub fn new(kind: NodeKind, location: ByteSpan) -> Node

Create a new AST node with the given kind and source location.

Examples

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

let node = Node::new(
    NodeKind::Number { value: "42".to_string() },
    SourceLocation { start: 0, end: 2 },
);
assert_eq!(node.kind.kind_name(), "Number");
assert_eq!(node.location.start, 0);

pub fn to_sexp(&self) -> String

Convert the AST to a tree-sitter compatible S-expression.

Produces a parenthesized representation compatible with tree-sitter’s S-expression format, useful for debugging and snapshot testing.

Examples

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

let loc = SourceLocation { start: 0, end: 2 };
let num = Node::new(NodeKind::Number { value: "42".to_string() }, loc);
let program = Node::new(
    NodeKind::Program { statements: vec![num] },
    loc,
);
let sexp = program.to_sexp();
assert!(sexp.starts_with("(source_file"));

pub fn to_sexp_inner(&self) -> String

Convert the AST to S-expression format that unwraps expression statements in programs

pub fn for_each_child_mut<F>(&mut self, f: F)

where F: FnMut(&mut Node),

Call a function on every direct child node of this node.

This enables depth-first traversal for operations like heredoc content attachment. The closure receives a mutable reference to each child node.

pub fn for_each_child<'a, F>(&'a self, f: F)

where F: FnMut(&'a Node),

Call a function on every direct child node of this node (immutable version).

This enables depth-first traversal for read-only operations like AST analysis. The closure receives an immutable reference to each child node.

pub fn count_nodes(&self) -> usize

Count the total number of nodes in this subtree (inclusive).

Examples

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

let loc = SourceLocation { start: 0, end: 1 };
let leaf = Node::new(NodeKind::Number { value: "1".to_string() }, loc);
assert_eq!(leaf.count_nodes(), 1);

let program = Node::new(
    NodeKind::Program { statements: vec![leaf] },
    loc,
);
assert_eq!(program.count_nodes(), 2);

pub fn children(&self) -> Vec<&Node>

Collect direct child nodes into a vector for convenience APIs.

Examples

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

let loc = SourceLocation { start: 0, end: 1 };
let stmt = Node::new(NodeKind::Number { value: "1".to_string() }, loc);
let program = Node::new(
    NodeKind::Program { statements: vec![stmt] },
    loc,
);
assert_eq!(program.children().len(), 1);

pub fn first_child(&self) -> Option<&Node>

Get the first direct child node, if any.

Optimized to avoid allocating the children vector.

Trait Implementations

impl Clone for Node

fn clone(&self) -> Node

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Node

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

Formats the value using the given formatter.

impl PartialEq for Node

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