mago-syntax 1.45.0

A correct, fast, and memory-efficient PHP syntax implementation, including Lexer, Parser, AST, and utilities for Mago.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

use strum::Display;

use mago_allocator::CopyInto;
use mago_span::HasSpan;
use mago_span::Span;

use crate::cst::Sequence;

/// Represents the kind of trivia.
#[derive(Debug, Clone, Copy, Eq, PartialEq, Hash, PartialOrd, Ord, Display)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[cfg_attr(feature = "serde", serde(tag = "type", content = "value"))]
pub enum TriviaKind {
    WhiteSpace,
    SingleLineComment,
    MultiLineComment,
    HashComment,
    DocBlockComment,
}

/// Represents a trivia.
///
/// A trivia is a piece of information that is not part of the syntax tree,
/// such as comments and white spaces.
#[derive(Debug, Clone, Copy, Eq, PartialEq, Hash, PartialOrd, Ord)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub struct Trivia<'arena> {
    pub kind: TriviaKind,
    pub span: Span,
    pub value: &'arena [u8],
}

impl TriviaKind {
    /// Returns `true` if the trivia kind is a comment.
    #[inline]
    #[must_use]
    pub const fn is_comment(&self) -> bool {
        matches!(
            self,
            TriviaKind::SingleLineComment
                | TriviaKind::MultiLineComment
                | TriviaKind::HashComment
                | TriviaKind::DocBlockComment
        )
    }

    #[inline]
    #[must_use]
    pub const fn is_docblock(&self) -> bool {
        matches!(self, TriviaKind::DocBlockComment)
    }

    #[inline]
    #[must_use]
    pub const fn is_block_comment(&self) -> bool {
        matches!(self, TriviaKind::MultiLineComment | TriviaKind::DocBlockComment)
    }

    #[inline]
    #[must_use]
    pub const fn is_single_line_comment(&self) -> bool {
        matches!(self, TriviaKind::HashComment | TriviaKind::SingleLineComment)
    }
}

impl HasSpan for Trivia<'_> {
    fn span(&self) -> Span {
        self.span
    }
}

/// Iteration helpers over a trivia [`Sequence`].
///
/// `Sequence` lives in [`mago_syntax_core`], so PHP-specific helpers are
/// exposed as an extension trait. `use crate::cst::*;` imports it.
pub trait TriviaSequenceExt<'arena> {
    fn comments<'borrow>(&'borrow self) -> impl Iterator<Item = &'borrow Trivia<'arena>>
    where
        'arena: 'borrow;
}

impl<'arena> TriviaSequenceExt<'arena> for Sequence<'arena, Trivia<'arena>> {
    #[inline]
    fn comments<'borrow>(&'borrow self) -> impl Iterator<Item = &'borrow Trivia<'arena>>
    where
        'arena: 'borrow,
    {
        self.iter().filter(|trivia| trivia.kind.is_comment())
    }
}

impl CopyInto for Trivia<'_> {
    type Output<'arena> = Trivia<'arena>;

    fn copy_into<'arena, A>(&self, arena: &'arena A) -> Self::Output<'arena>
    where
        A: mago_allocator::Arena,
    {
        Trivia { kind: self.kind, span: self.span, value: arena.alloc_slice_copy(self.value) }
    }
}