Struct DeclarationProvider 

pub struct DeclarationProvider<'a> {
    pub ast: Arc<Node>,
    /* private fields */
}

Provider for finding declarations in Perl source code.

This provider implements LSP go-to-declaration functionality with enhanced workspace navigation support. Maintains ≤1ms response time for symbol lookup operations through optimized AST traversal and parent mapping.

Performance Characteristics

• Declaration resolution: <500μs for typical Perl files
• Memory usage: O(n) where n is AST node count
• Parent map validation: Debug-only with cycle detection

LSP Workflow Integration

Parse → Index → Navigate → Complete → Analyze pipeline integration:

1. Parse: AST generation from Perl source
2. Index: Symbol table construction with qualified name resolution
3. Navigate: Declaration provider for go-to-definition requests
4. Complete: Symbol context for completion providers
5. Analyze: Cross-reference analysis for workspace refactoring

Fields

ast: Arc<Node>

The parsed AST for the current document

Implementations

impl<'a> DeclarationProvider<'a>

pub fn new( ast: Arc<Node>, content: String, document_uri: String, ) -> DeclarationProvider<'a>

Creates a new declaration provider for the given AST and document.

Arguments

• ast - The parsed AST tree for declaration lookup
• content - The source code content for text extraction
• document_uri - The URI of the document being analyzed

Performance

• Initialization: <10μs for typical Perl files
• Memory overhead: Minimal, shares AST reference

Examples

use perl_parser::declaration::DeclarationProvider;
use perl_parser::ast::Node;
use std::sync::Arc;

let ast = Arc::new(Node::new_root());
let provider = DeclarationProvider::new(
    ast,
    "package MyPackage; sub example { }".to_string(),
    "file:///path/to/file.pl".to_string()
);

pub fn with_parent_map( self, parent_map: &'a HashMap<*const Node, *const Node, FxBuildHasher>, ) -> DeclarationProvider<'a>

Configures the provider with a pre-built parent map for enhanced traversal.

The parent map enables efficient upward AST traversal for scope resolution and context analysis. Debug builds include comprehensive validation.

Arguments

• parent_map - Mapping from child nodes to their parents

Performance

• Parent lookup: O(1) hash table access
• Validation overhead: Debug-only, ~100μs for large files

Panics

In debug builds, panics if:

• Parent map is empty for non-trivial AST
• Root node has a parent (cycle detection)
• Cycles detected in parent relationships

Examples

use perl_parser::declaration::{DeclarationProvider, ParentMap};
use perl_parser::ast::Node;
use std::sync::Arc;

let ast = Arc::new(Node::new_root());
let mut parent_map = ParentMap::default();
DeclarationProvider::build_parent_map(&ast, &mut parent_map, None);

let provider = DeclarationProvider::new(
    ast, "content".to_string(), "uri".to_string()
).with_parent_map(&parent_map);

pub fn with_doc_version(self, version: i32) -> DeclarationProvider<'a>

Sets the document version for staleness detection.

Version tracking ensures the provider operates on current data and prevents usage after document updates in LSP workflows.

Arguments

• version - Document version number from LSP client

Performance

• Version check: <1μs per operation
• Debug validation: Additional consistency checks

Examples

use perl_parser::declaration::DeclarationProvider;
use perl_parser::ast::Node;
use std::sync::Arc;

let provider = DeclarationProvider::new(
    Arc::new(Node::new_root()),
    "content".to_string(),
    "uri".to_string()
).with_doc_version(42);

pub fn build_parent_map( node: &Node, map: &mut HashMap<*const Node, *const Node, FxBuildHasher>, parent: Option<*const Node>, )

Build a parent map for efficient scope walking Builds a parent map for efficient upward AST traversal.

Recursively traverses the AST to construct a mapping from each node to its parent, enabling O(1) parent lookups for scope resolution.

Arguments

• node - Current node to process
• map - Mutable parent map to populate
• parent - Parent of the current node (None for root)

Performance

• Time complexity: O(n) where n is node count
• Space complexity: O(n) for parent pointers
• Typical build time: <100μs for 1000-node AST

Safety

Uses raw pointers for performance. Safe as long as AST nodes remain valid during provider lifetime.

Examples

use perl_parser::declaration::{DeclarationProvider, ParentMap};
use perl_parser::ast::Node;

let ast = Node::new_root();
let mut parent_map = ParentMap::default();
DeclarationProvider::build_parent_map(&ast, &mut parent_map, None);

pub fn find_declaration( &self, offset: usize, current_version: i32, ) -> Option<Vec<LocationLink>>

Find the declaration of the symbol at the given position

pub fn get_node_text(&self, node: &Node) -> String

Extracts the source code text for a given AST node.

Returns the substring of the document content corresponding to the node’s location range. Used for symbol name extraction and text-based analysis.

Arguments

• node - AST node to extract text from

Performance

• Time complexity: O(m) where m is node text length
• Memory: Creates owned string copy
• Typical latency: <10μs for identifier names

Examples

use perl_parser::declaration::DeclarationProvider;
use perl_parser::ast::Node;
use std::sync::Arc;

let provider = DeclarationProvider::new(
    Arc::new(Node::new_root()),
    "sub example { }".to_string(),
    "uri".to_string()
);
// let text = provider.get_node_text(&some_node);