Skip to main content

big_code_analysis_ast/getter/
perl.rs

1//! `Getter` implementation for Perl.
2#![allow(clippy::wildcard_imports, clippy::enum_glob_use)]
3
4use super::*;
5use crate::lang_helpers::perl::{
6    perl_and_is_operator, perl_bareword_key_sign, perl_dash_signs_key, perl_file_test_is_dash_key,
7    perl_is_dash_key_word, perl_key_is_signed, perl_not_is_key,
8};
9
10impl Getter for PerlCode {
11    // The mapping is the `opens` annotations of `roles/perl.rs`
12    // (#1696). The rows read no bytes and no chain, so the byte-less
13    // spelling forwards with none.
14    impl_byte_less_space_kind!(perl);
15
16    fn get_space_kind_with_code<'a>(
17        node: &Node<'a>,
18        code: &[u8],
19        ancestors: Ancestors<'a, '_>,
20    ) -> SpaceKind {
21        crate::roles::perl::opens_space(node, code, ancestors)
22    }
23
24    keyword_roles!(perl);
25
26    paying_roles!(perl);
27
28    fn get_op_type<'a>(node: &Node<'a>, ancestors: Ancestors<'a, '_>) -> TokenRole {
29        use Perl as P;
30
31        if let Some(role) = auto_quoted_key_role(node, ancestors) {
32            return role;
33        }
34        match node.kind_id().into() {
35            // Regex delimiter punctuation. The bare match form is the
36            // only one of Perl's five regex literals that spells its
37            // delimiters with an operator token kind: `bca dump` at the
38            // pinned grammar shows `/abc/` emitting two `SLASH` under
39            // `PatternMatcher`, while `m//`, `qr//`, `s///` and `tr///`
40            // use the dedicated `StartDelimiter` / `SeparatorDelimiter`
41            // / `EndDelimiter` kinds that no arm here classifies. So
42            // `$s =~ /abc/` fabricated two division operators (#1312,
43            // the Perl sibling of Elixir #1256). Suppress them exactly
44            // when their parent is the literal — the compound-leaf
45            // guard of grammar-dispatch §5 — which leaves the bare form
46            // contributing what its three synonyms already contribute
47            // (#1314 made that "one operand" rather than "nothing";
48            // see the pattern-value arm below).
49            P::SLASH
50                if ancestors.parent_has_kind(node, P::PatternMatcher as u16) =>
51            {
52                TokenRole::Unknown
53            }
54            // The bare form's pattern text is one operand, billed on the
55            // `PatternMatcher` wrapper, but the grammar spells four of its
56            // characters as anonymous tokens under `regex_pattern_content`:
57            // `[`, `]`, `\` and `#`. They are literal regex text, which
58            // `m//` and `qr//` emit no node for, so `/[a]/` billed a `[]`
59            // operator that `m/[a]/` does not (#1549). `#` is also in no
60            // operator arm, because its only other position is a comment's
61            // leading `#` under `comments`, and a comment is not code.
62            // `$#a` and the `#` delimiters of `qw#…#` / `s#a#b#` are
63            // distinct token kinds.
64            _ if ancestors.parent_has_kind(node, P::RegexPatternContent as u16) => {
65                TokenRole::Unknown
66            }
67            // The comparison and short-circuit tokens — numeric, string,
68            // the bindings and the word forms — sit in this arm for the
69            // spellings the `Comparison` / `ShortCircuit` rows' gates
70            // leave out: a readline's `<FH>` brackets, an auto-quoted
71            // `and` key (#1539), a recovered token. Those billed before
72            // the rows existed; the rows pay the applied spellings
73            // through `get_paying_role` (#1695), so for these kinds the
74            // vocabulary is the union of the two. `xor`, the ternary `?`
75            // and the defined-or `//` are not here: the `EagerLogical`,
76            // `Ternary` and `NullSafe` rows pay them ungated; `//=` is
77            // excluded on the last and bills below as the assignment it
78            // is.
79            // role-bypass: allow(Comparison, ShortCircuit) — the operator classification of the
80            // spellings the rows' gates leave out
81            P::EQTILDE | P::BANGTILDE | P::EQEQ | P::BANGEQ | P::LT | P::GT
82            | P::LTEQ | P::GTEQ | P::LTEQGT | P::AMPAMP | P::PIPEPIPE | P::And | P::Or
83            | P::Eq | P::Ne | P::Lt | P::Gt | P::Le | P::Ge | P::Cmp
84            // Control-flow keywords. The declaration keywords (`sub`,
85            // `package`, `my`, …) are not here: `roles/perl.rs` declares
86            // them and `get_keyword_role` bills them (#1693).
87            | P::If | P::Unless | P::Else | P::Elsif | P::While | P::Until | P::For
88            | P::Foreach | P::When | P::Continue | P::Next | P::Last | P::Redo | P::Goto
89            | P::Return | P::Use | P::No | P::Require | P::Bless
90            | P::Not
91            // Punctuation acting as operators
92            | P::SEMI | P::COMMA | P::COLON | P::COLONCOLON | P::LBRACE | P::LBRACK
93            | P::LPAREN | P::DOT | P::DOTDOT | P::DOTDOTDOT | P::FatComma | P::DASHGT
94            | P::BSLASH | P::DOLLAR | P::DOLLARHASH | P::AT | P::PERCENT
95            // Arithmetic / logical / bitwise / assignment operators
96            | P::EQ | P::PLUS | P::DASH | P::STAR | P::SLASH | P::STARSTAR | P::BANG
97            | P::TILDE | P::PIPE
98            | P::CARET | P::LTLT | P::GTGT | P::TILDETILDE | P::PLUSPLUS | P::DASHDASH
99            | P::PLUSEQ | P::DASHEQ | P::STAREQ | P::SLASHEQ | P::PERCENTEQ | P::STARSTAREQ
100            | P::AMPEQ | P::PIPEEQ | P::CARETEQ | P::LTLTEQ | P::GTGTEQ | P::AMPAMPEQ
101            | P::PIPEPIPEEQ | P::SLASHSLASHEQ | P::DOTEQ | P::XEQ
102            | P::AMPDOTEQ | P::PIPEDOTEQ | P::CARETDOTEQ | P::Isa
103            // Substitution and transliteration. These are *operations
104            // applied to a target*, not pattern values, so they are
105            // operators while the three pattern spellings below are
106            // operands (#1314). `y///` is a synonym of `tr///` and
107            // shares `TransliterationTrOrY`, so the two fold to one
108            // entry, which is what synonyms should do.
109            //
110            // Their *literal* pattern and replacement text is
111            // invisible either way: `bca dump` shows `s/a/b/` emitting
112            // only the `s` keyword and its `start` / `separator` /
113            // `end` delimiters, with no content node, so classifying
114            // them as operators loses nothing that treating them as
115            // values would have kept. An *interpolated* `s/$x/$y/` does
116            // emit `Interpolation` children, and those count as
117            // operands under either choice — so the reason for the
118            // split is the semantic one above, not this. `get_operator_id_as_str` below renders them
119            // `s///` and `tr///` rather than as raw kind names.
120            | P::SubstitutionPatternS | P::TransliterationTrOrY
121                => TokenRole::Operator,
122            // `package_name`, `package_variable` and `typeglob` each
123            // spell a whole name — `Data::Dumper`, `$Foo::count`,
124            // `*STDOUT` — and are operands in their own right below, so
125            // an operand-classified node they *contain* is already
126            // billed by the wrapper. Before #1355 the wrapper and its
127            // contents both counted: `use strict;` scored N2 2 for one
128            // name, `require Data::Dumper;` n2 3 / N2 3 for one, and
129            // `our $Foo::count = 3;` n2 5 / N2 6 for two — the
130            // vocabulary even growing a bare `::` entry, because a
131            // `package_variable` spells its separator as a second,
132            // childless `package_name` beside the qualifier.
133            //
134            // Keyed on the parent alone rather than on a list of child
135            // kinds, because the invariant is positional: a wrapper's
136            // span contains its children's, so whatever sits directly
137            // inside one is already paid for. node-types.json admits ten
138            // (wrapper, child) pairings across eight operand kinds, all
139            // of them reachable — `package_name` ⊃ `typeglob` is
140            // `*Foo::glob`, `package_name` ⊃ `package_variable` the
141            // `$Foo::Bar::baz` nesting — and enumerating them here would
142            // be a coverage claim to re-derive on every grammar bump for
143            // no gain, the trade grammar-dispatch §1 recommends taking.
144            // `perl_name_wrappers_bill_the_name_once_1355` witnesses all
145            // ten and fails on an eleventh. Naming the three wrappers as
146            // *parents* also resolves arbitrary qualifier depth to the
147            // outermost, the way PHP handles `$$$x` (#1259).
148            //
149            // It sits below the operator arm on purpose: the `::` token
150            // inside a bareword `package_name` (`Data::Dumper`), and `*`
151            // and the opening `{` inside a `typeglob`, are matched there
152            // and keep their operator reading. A sigil-qualified name
153            // has no such token — its separator is the childless
154            // `package_name` above, which the guard drops with the rest
155            // of the wrapper — so `$Foo::count` bills no `::` where
156            // `Data::Dumper` bills one. That asymmetry is the grammar's:
157            // `main` billed that node as a bogus `::` operand and never
158            // as an operator, so n1/N1 are unchanged here. The typeglob
159            // `*` stays an operator because this getter already bills
160            // the `$` sigil on every scalar reference (`my $x` → n1
161            // {my, $, =, ;}), so the typeglob sigil follows the sigil
162            // convention rather than #1312's delimiter suppression; the
163            // cost is that it shares `Perl::STAR` with multiplication,
164            // so both fold into one n1 entry, and `*Foo` and `*{Foo}`
165            // differ by one `{}` operator. (The closing `}` has never
166            // been classified — `get_operator_id_as_str` folds the pair
167            // to one `{}` glyph — so the guard changes nothing for it.)
168            //
169            // Guarded, not deleted, per grammar-dispatch §6: these
170            // leaves are ordinary operands everywhere else (`my $x`,
171            // `foo()`, the `bar` of `Foo::bar()`, which is a *sibling*
172            // of the `package_name` rather than a child).
173            //
174            // Keeping the wrapper's whole span is the opposite call from
175            // PHP's `qualified_name` (#1293) and Groovy's
176            // `QualifiedName` (#1263 / #1352), which bill the leaves and
177            // drop the wrapper. Three reasons it goes the other way in
178            // Perl. `package_variable` and `typeglob` are sigil-bearing
179            // *variable references*, the shape #1259 settled by keeping
180            // the wrapper — the leaves-only reading detaches the sigil
181            // from the variable and glues it to the qualifier, billing
182            // `$Foo::Bar::baz` as `$Foo` + `Bar` + `baz`, three operands
183            // for one variable. The three kinds nest into each other, so
184            // they must be decided together; splitting `package_name`
185            // off would need a grandparent-aware guard. And the
186            // vocabulary-sharing argument of #1293 / #1352 — that
187            // `java.util.List` and `List` name the same class — has no
188            // Perl analogue, since a package is always spelled in full.
189            //
190            // `module_name` is not here, though #1355 expected it to
191            // be: it is the quoted `use 'Foo.pm'` form, and it holds
192            // nothing but its two quote tokens — not the `identifier`
193            // the issue thought it shared. It stays an operand, pinned
194            // by `perl_qualified_name_leaves_still_count_elsewhere_1355`.
195            _ if matches!(
196                ancestors.parent(node).map(|p| p.kind_id().into()),
197                Some(P::PackageName | P::PackageVariable | P::Typeglob)
198            ) =>
199            {
200                TokenRole::Unknown
201            }
202            // Operands: identifiers and literals. Non-interpolating
203            // string literals (`'…'`, `q{…}`) are leaf operands; the
204            // interpolating kinds (`"…"`, `qq{…}`, `` `…` ``, `qx{…}`)
205            // are handled separately below so their inner
206            // scalar/array/hash variables are not double-counted.
207            //
208            // `ListItem` is one element of a `qw(a b c)` list — a leaf
209            // the grammar emits under `word_list_qw` and nowhere else,
210            // so it cannot double-bill another construct. Until it was
211            // listed the whole `qw()` was invisible to Halstead: neither
212            // the elements nor the wrapper nor the `qw` keyword had an
213            // arm, so `my @a = qw(a b c)` billed `@a` alone while its
214            // synonym `("a", "b", "c")` billed four operands. The
215            // wrapper is gated below, the Ruby `%w[]` shape of #1353.
216            //
217            // `__FILE__`, `__LINE__`, `__PACKAGE__` and `__SUB__` are
218            // the keyword leaves, each billed once as the constant it
219            // names. Their `special_literal` wrapper is not listed
220            // (#1644): it is one kind for two things — a wrapper around
221            // one of those four, and the `__END__` / `__DATA__` marker
222            // together with the `data_not_for_compiler` leaf holding
223            // every byte after it — and billing it by text made the
224            // constant two operands and the whole data section one. The
225            // leaf is the keeper (grammar-dispatch §6): it is the node
226            // present in every spelling, since `__SUB__->(1)` emits the
227            // bare token under `call_expression_recursive` with no
228            // wrapper at all. `__END__`, `__DATA__` and the section
229            // after them end the program and bill nothing.
230            // role-bypass: allow(StringLit) — the operand classification of the
231            // non-interpolating literals and of the `list_item` the row `wraps`, a
232            // projection the row does not answer
233            P::Identifier | P::ScalarVariable | P::ArrayVariable | P::HashVariable
234            | P::PackageVariable | P::SpecialScalarVariable | P::PackageName | P::ModuleName
235            | P::BarewordImport | P::Typeglob | P::FileHandle | P::ListItem
236            | P::Integer | P::FloatingPoint | P::ScientificNotation | P::Hexadecimal | P::Octal
237            | P::True | P::False
238            | P::StringSingleQuoted | P::StringQQuoted
239            | P::FILE | P::LINE | P::SUB | P::PACKAGE
240                => TokenRole::Operand,
241            // Perl's interpolating string-like literals count as one
242            // operand when inert. When they carry an `Interpolation`
243            // child the inner scalar / array / hash variables are
244            // already walked and classified as operands; counting the
245            // wrapping literal too would double-count the inner
246            // variables' contribution to `N2` (issue #199, same
247            // pattern as #180 for Elixir/Bash, #183 for C#, #184 for
248            // PHP, #191 for Kotlin). `HeredocBodyStatement` is the
249            // visible body of `<<TAG ... TAG` heredocs (issue #287);
250            // it is interpolation-capable, so it joins the same
251            // dispatch — inert heredocs are one operand, interpolating
252            // heredocs let the inner variables carry the count.
253            // The pattern *values* — `/abc/`, `m/abc/`, `qr/abc/` —
254            // join the same dispatch (#1314). `m/abc/` is exactly
255            // `/abc/` and `qr/abc/` is the same pattern as a value, so
256            // all three must score alike; that equality is what
257            // `perl_every_pattern_value_spelling_scores_alike` protects
258            // and why #1312 declined to promote the bare form on its
259            // own. Promoting the three together closes the gap without
260            // reintroducing the spelling sensitivity: each contributes
261            // one operand, matching Ruby's `Regex` and Elixir's
262            // `Sigil`. `s///` and `tr///` are *not* here — they are
263            // operations applied to a target and sit in the operator
264            // arm above.
265            //
266            // Sharing the string dispatch is not incidental, which is
267            // why the arms are merged rather than duplicated: the bare
268            // form keeps an interpolated variable inside an
269            // unclassified `regex_pattern_content`, but `m/$x/` and
270            // `qr/$x/` emit a real `Interpolation` whose
271            // `scalar_variable` is already counted. A plain operand arm
272            // would score `/$x/` at one operand and `m/$x/` at two —
273            // the very divergence the equality above exists to prevent.
274            //
275            // `WordListQw` holds classified `ListItem` operands rather
276            // than interpolation, so the same guard gives it "one
277            // operand per element, or one for the empty `qw()`" — the
278            // rule #1353 settled for Ruby's `%w[]`. One list serves
279            // both groups because no string kind admits a `list_item`
280            // and `word_list_qw` admits no `interpolation`.
281            // role-bypass: allow(StringLit) — the operand classification of the literals
282            // under the row's `wraps` list, a projection the row does not answer
283            P::StringDoubleQuoted | P::StringQqQuoted | P::BacktickQuoted
284            | P::CommandQxQuoted | P::HeredocBodyStatement
285            | P::PatternMatcher | P::PatternMatcherM | P::RegexPatternQr | P::WordListQw => {
286                Self::string_operand_type(node, crate::roles::perl::string_lit::WRAPS)
287            }
288            _ => TokenRole::Unknown,
289        }
290    }
291
292    /// Spells a `-bareword` key whole (#1545). A key that is exactly a
293    /// file test (`(-x => 1)`) has swallowed the `=>` and the value into
294    /// its node, so the key is the sign and the word after it; a
295    /// `-and` / `-not` key gets back the sign its `-` token stopped
296    /// billing, spelled the same however the two are spaced, since Perl
297    /// keys `(- not => 1)` as `"-not"` too. The sign is read off the tree
298    /// (`perl_key_is_signed`), not the byte before the key, which can
299    /// equally be an infix `-` or the end of a comment.
300    ///
301    /// Any other `-bareword` key (`(-name => 1)`, `$h{-name}`) bills its
302    /// word spelled from the sign (#1572). That is a source slice, so a
303    /// sign spaced off its word (`(- name => 1)`, rare) keeps the space,
304    /// and a comment between the two (`(- # c⏎ name => 1)`) is carried
305    /// along in it: one operand, distinct from `name`, but not merged
306    /// with `-name`, and listed by `bca ops` as written.
307    fn get_operand_id<'a>(
308        node: &Node<'a>,
309        code: &'a [u8],
310        ancestors: Ancestors<'a, '_>,
311    ) -> &'a [u8] {
312        let (start, end) = (node.start_byte(), node.end_byte());
313        match node.kind_id().into() {
314            Perl::FileHandleOperator => {
315                let word = code[start + 1..end]
316                    .iter()
317                    .take_while(|byte| byte.is_ascii_alphanumeric() || **byte == b'_')
318                    .count();
319                &code[start..=start + word]
320            }
321            // role-bypass: allow(ShortCircuit) — naming: how an auto-quoted `and` key spells
322            // its operand, not whether the token is an operator
323            Perl::And if perl_key_is_signed(node, ancestors) => b"-and",
324            Perl::Not if perl_key_is_signed(node, ancestors) => b"-not",
325            Perl::Identifier => perl_bareword_key_sign(node, ancestors)
326                .map_or(&code[start..end], |dash| &code[dash.start_byte()..end]),
327            _ => &code[start..end],
328        }
329    }
330
331    /// Folds paired delimiters to one glyph, and names the two
332    /// pattern *operations* after their source spelling.
333    ///
334    /// Hand-written rather than `get_operator!(Perl)` because
335    /// `SubstitutionPatternS` and `TransliterationTrOrY` are named
336    /// nodes rather than punctuation tokens (#1314): the macro's
337    /// fallback renders a kind's own name, so `bca ops` would list
338    /// `substitution_pattern_s` and `transliteration_tr_or_y` among
339    /// the operators, which reads as a bug rather than as `s///`.
340    /// `tr///` covers `y///` too — one kind, one glyph, because they
341    /// are synonyms. `=>` is the named `fat_comma` node for the same
342    /// reason.
343    #[inline]
344    fn get_operator_id_as_str(id: u16) -> &'static str {
345        let typ = id.into();
346        match typ {
347            Perl::LPAREN => "()",
348            Perl::LBRACK => "[]",
349            Perl::LBRACE => "{}",
350            Perl::SubstitutionPatternS => "s///",
351            Perl::TransliterationTrOrY => "tr///",
352            Perl::FatComma => "=>",
353            _ => typ.into(),
354        }
355    }
356}
357
358/// The role of a token tree-sitter-perl 1.1.2 misparses inside an
359/// auto-quoted hash key, or `None` for any other token. Perl quotes a
360/// bareword before `=>` and alone in a hash subscript, keywords and a
361/// leading `-` included, and the grammar reads some of those keys as
362/// operators. Every arm is an upstream workaround; drop each with its
363/// issue once the pin carries the fix.
364fn auto_quoted_key_role<'a>(node: &Node<'a>, ancestors: Ancestors<'a, '_>) -> Option<TokenRole> {
365    use Perl as P;
366
367    let role = match node.kind_id().into() {
368        // FIXME(#1539 upstream): an auto-quoted `and` key (`$h{and}`,
369        // `(and => 1)`) lexes as the operator keyword. It is a
370        // string key, so it bills what `$h{or}` bills: the
371        // `identifier` operand the grammar gives every other
372        // bareword key. The `ShortCircuit` row's `applied_and` gate is
373        // what leaves it to this arm.
374        // role-bypass: allow(ShortCircuit) — the operand classification of the spelling the row's
375        // `applied_and` gate leaves out
376        P::And
377            if !ancestors
378                .parent(node)
379                .is_some_and(|parent| perl_and_is_operator(node, &parent)) =>
380        {
381            TokenRole::Operand
382        }
383        // FIXME(#1541 upstream): the same for an auto-quoted `not`
384        // key (`$h{not}`, `(not => 1)`); see `perl_not_is_key`.
385        P::Not
386            if ancestors
387                .parent(node)
388                .is_some_and(|parent| perl_not_is_key(node, &parent)) =>
389        {
390            TokenRole::Operand
391        }
392        // FIXME(#1545 upstream): a `-bareword` key (`$h{-foo}`,
393        // `(-text => 1)`) lexes as a file test on the rest of the
394        // word. It is one string key, so the test node bills it as
395        // one operand spelling the whole key, and the word inside
396        // bills nothing. A `-and` / `-not` key splits instead into
397        // a `-` and the keyword, which the arms above bill as the
398        // key, and any other `-bareword` key (`(-name => 1)`) into a
399        // `-` and a bareword call, whose `identifier` bills the key
400        // (#1572, the local workaround for upstream #1571); in both
401        // the `-` is part of the key and bills nothing. See
402        // `perl_file_test_is_dash_key` and `perl_bareword_is_key`.
403        P::FileHandleOperator if perl_file_test_is_dash_key(node, ancestors) => TokenRole::Operand,
404        P::Identifier
405            if ancestors
406                .iter(node)
407                .next()
408                .is_some_and(|(word, above)| perl_is_dash_key_word(&word, above)) =>
409        {
410            TokenRole::Unknown
411        }
412        P::DASH if perl_dash_signs_key(node, ancestors) => TokenRole::Unknown,
413        _ => return None,
414    };
415    Some(role)
416}