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}