perl-semantic-analyzer 0.13.3

//! Semantic token types and modifiers for LSP syntax highlighting.

use crate::SourceLocation;

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
/// Semantic token types for syntax highlighting in the Parse/Complete workflow.
pub enum SemanticTokenType {
    // Variables
    /// Variable reference (scalar, array, or hash)
    Variable,
    /// Variable declaration site
    VariableDeclaration,
    /// Read-only variable (constant)
    VariableReadonly,
    /// Function parameter
    Parameter,

    // Functions
    /// Function/subroutine reference
    Function,
    /// Function/subroutine declaration
    FunctionDeclaration,
    /// Object method call
    Method,

    // Types
    /// Class/package name
    Class,
    /// Package namespace
    Namespace,
    /// Type annotation (modern Perl)
    Type,

    // Keywords
    /// Language keyword (if, while, etc.)
    Keyword,
    /// Control flow keyword (return, next, last)
    KeywordControl,
    /// Variable modifier (my, our, local, state)
    Modifier,

    // Literals
    /// Numeric literal
    Number,
    /// String literal
    String,
    /// Regular expression
    Regex,

    // Comments
    /// Regular comment
    Comment,
    /// Documentation comment (POD)
    CommentDoc,

    // Other
    /// Operator (+, -, =~, etc.)
    Operator,
    /// Punctuation marks and delimiters
    Punctuation,
    /// Code label for goto statements
    Label,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
/// Semantic token modifiers for Analyze/Complete stage highlighting.
///
/// Provides additional context about semantic tokens beyond their base type,
/// enabling rich editor highlighting with detailed symbol information.
///
/// # LSP Integration
/// Maps to LSP `SemanticTokenModifiers` for consistent editor experience
/// across different LSP clients with full Perl language semantics.
pub enum SemanticTokenModifier {
    /// Symbol is being declared at this location
    Declaration,
    /// Symbol is being defined at this location
    Definition,
    /// Symbol is read-only (constant)
    Readonly,
    /// Symbol has static storage duration (state variables)
    Static,
    /// Symbol is deprecated and should not be used
    Deprecated,
    /// Symbol is abstract (method without implementation)
    Abstract,
    /// Symbol represents an asynchronous operation
    Async,
    /// Symbol is being modified (written to)
    Modification,
    /// Symbol is documentation-related (POD)
    Documentation,
    /// Symbol is from the Perl standard library
    DefaultLibrary,
}

#[derive(Debug, Clone)]
/// A semantic token with type and modifiers for LSP syntax highlighting.
///
/// Represents a single semantic unit in Perl source code with precise location
/// and rich type information for enhanced editor experience.
///
/// # Performance Characteristics
/// - Memory: ~32 bytes per token (optimized for large files)
/// - Serialization: Direct LSP protocol mapping
/// - Batch processing: Efficient delta updates for incremental parsing
///
/// # LSP Workflow Integration
/// Core component in Parse → Index → Navigate → Complete → Analyze pipeline
/// for real-time syntax highlighting with ≤1ms update latency.
pub struct SemanticToken {
    /// Source location of the token
    pub location: SourceLocation,
    /// Semantic classification of the token
    pub token_type: SemanticTokenType,
    /// Additional modifiers for enhanced highlighting
    pub modifiers: Vec<SemanticTokenModifier>,
}