big_code_analysis_ast/getter/tcl.rs
1//! `Getter` implementation for Tcl.
2#![allow(clippy::wildcard_imports, clippy::enum_glob_use)]
3
4use super::*;
5
6use crate::lang_helpers::tcl::BRACED_WORD_KINDS;
7
8impl Getter for TclCode {
9 // The mapping is the `opens` annotations of `roles/tcl.rs`
10 // (#1696). The rows read no bytes and no chain, so the byte-less
11 // spelling forwards with none.
12 impl_byte_less_space_kind!(tcl);
13
14 fn get_space_kind_with_code<'a>(
15 node: &Node<'a>,
16 code: &[u8],
17 ancestors: Ancestors<'a, '_>,
18 ) -> SpaceKind {
19 crate::roles::tcl::opens_space(node, code, ancestors)
20 }
21
22 keyword_roles!(tcl);
23
24 paying_roles!(tcl);
25
26 fn get_op_type<'a>(node: &Node<'a>, ancestors: Ancestors<'a, '_>) -> TokenRole {
27 match node.kind_id().into() {
28 // The braced-word rule (#1354 / #1317), whose two halves
29 // `Getter::is_subsumed_braced_word` states once for both
30 // dialects. This arm is only its Tcl instantiation, plus
31 // the derivation and the caveats.
32 //
33 // A braced *word* is one literal value: Tcl evaluates
34 // nothing between the braces, so `{$x}` is the
35 // two-character string `$x` and not a variable reference.
36 // The grammar models the interior structurally all the
37 // same — `braced_word_simple` (89) admits `simple_word`,
38 // `escaped_character`, `quoted_word`,
39 // `variable_substitution`, `command_substitution` and a
40 // nested `braced_word_simple` — so the word and every part
41 // of it were billed together: `set x {literal here}` scored
42 // n2 4 / N2 4 for one value, and `set a {braced word}`
43 // reported four operands where its synonym
44 // `set a "quoted word"` reported two.
45 //
46 // The wrapper keeps the operand and its children are
47 // suppressed — the opposite polarity from `QuotedWord`
48 // below, and for the reason that decides it: a quoted word
49 // *does* interpolate, so its `$var` children are real
50 // references the walk has to count, while a braced word's
51 // are letters. Billing the whole word is also what keeps
52 // the two spellings of one literal scoring alike, the
53 // spelling insensitivity #695, #1312 and #1314 each
54 // restored elsewhere — and it is the contract the book
55 // already documents: "a Tcl braced word … contributes *one
56 // operand* — the literal" (`metrics.md`, Halstead).
57 //
58 // The value half is keyed on the parent alone rather than
59 // on a list of child kinds (the #1355 shape): the invariant
60 // is positional — a wrapper's span already contains its
61 // children's — and an enumerated list would be a coverage
62 // claim to re-derive on every grammar bump.
63 // `tcl_braced_word_bills_its_content_once_1354` witnesses all six
64 // child kinds and fails on a seventh.
65 //
66 // It subsumes #1314's narrower `LBRACE` guard: that `{` is
67 // one more child of the word, and reporting it as a `{}`
68 // operator fabricated a block the source does not contain.
69 // A *script* is a `BracedWord` (88) — verified across
70 // `proc`, `if`, `catch`, `eval`, `after` and `uplevel` — an
71 // `if`/`while` condition is an `Expr` (97), and a `proc`
72 // parameter list is `Arguments` (94). All three keep their
73 // braces as operators, which is what makes keying the value
74 // half on `BracedWordSimple` safe. (#1318 later carved one
75 // exception out of that list from the other side: a
76 // *defaulted parameter's* value is a `BracedWord` under an
77 // `Argument` (93), and a default is data, so it loses its
78 // brace — the enclosing `Arguments` list keeps its own.)
79 //
80 // Two limits of the value half, both deliberate and both
81 // pinned rather than left implied.
82 //
83 // It is *parent*-scoped, so "Tcl evaluates nothing between
84 // the braces" holds for what sits directly inside the word
85 // and not for what sits deeper: the grammar parses a `[…]`
86 // command substitution and a `"…"` quoted word inside a
87 // braced word, and the operands *they* contain still count
88 // (`set a {x "$q" v}` bills `$q`). Widening to an ancestor
89 // scan would also swallow the `{` of every `Expr` and
90 // `BracedWord` nested under a value word, which is the
91 // fabrication #1314 removed in the other direction —
92 // `tcl_braced_word_guard_is_parent_scoped_not_ancestor_scoped`
93 // pins the operators, `tcl_braced_word_bills_its_content_once_1354`
94 // the surviving operands. The residual is the same one
95 // #1314 recorded: the grammar models a substitution Tcl
96 // will not perform, and what the classifier sees is what
97 // the metric reports.
98 //
99 // And the grammar emits `BracedWordSimple` only in the
100 // value slot of the commands it special-cases, so
101 // `lappend x {a b}` parses its literal as a `BracedWord`
102 // script and its `{` kept fabricating a block. Guarding
103 // that kind here too would drop every real block, so #1318
104 // closed it out-of-band instead, by the enclosing command's
105 // leading word (grammar-dispatch §9) — in
106 // `get_op_type_with_code` below, because the recognition
107 // needs the source bytes. It touches the brace and nothing
108 // else, so every operand this arm decides is unchanged.
109 //
110 // Cross-walked against the sibling predicates
111 // (grammar-dispatch §7): `Checker::is_string` and
112 // `Alterator::alterate` both list `BracedWord` beside the two
113 // literal forms, and #1381 narrows both for a script body —
114 // `Checker::is_string_with_code` and
115 // `Alterator::keeps_children` ask
116 // `Getter::is_braced_script_word` — so `bca find --type
117 // string` reports `lappend x {a b}`'s `{a b}` and not a
118 // `proc` body, agreeing with this arm. Since #1382 the two
119 // also agree on the value slots of a script-taking command
120 // (`proc {my proc}`, `after {100} {…}`,
121 // `namespace export {…}`): `get_op_type_with_code` asks the
122 // same `Getter::is_braced_script_word` and no longer bills
123 // their `{` as a block. Two disagreements remain, each
124 // recorded where it lives: an interpolating `QuotedWord` is
125 // `Unknown` here and a string there, which predates #1354;
126 // and an empty or comment-only script body is an operand
127 // here and not a string there.
128 //
129 // `Checker::is_call` needs no such follow-up. It calls
130 // every `Command` a call, including the ones inside a value
131 // braced word — and so does this arm, which still bills
132 // their operands. The two agree precisely because #1318
133 // withdrew the brace and not the contents; a rule that
134 // suppressed the contents would have put the getter and
135 // every branching metric on opposite sides of the same
136 // bytes.
137 _ if Self::is_subsumed_braced_word(node, ancestors, &BRACED_WORD_KINDS) => {
138 TokenRole::Unknown
139 }
140 // Anonymous keyword tokens (control-flow keywords). The
141 // declaration keywords (`proc`, `namespace`, `set`, `global`)
142 // are not here: `roles/tcl.rs` declares them and
143 // `get_keyword_role` bills them (#1693).
144 Tcl::If2
145 | Tcl::Elseif2
146 | Tcl::Else2
147 | Tcl::While2
148 | Tcl::Foreach2
149 | Tcl::Try2
150 | Tcl::Catch2
151 | Tcl::Finally2
152 | Tcl::Regexp2
153 | Tcl::Expr2
154 // Structural punctuation. Only the *opening* delimiter is an
155 // operator (the pair folds to one glyph in
156 // `get_operator_id_as_str`); counting the matching closer too
157 // (former `RBRACE`/`RBRACK`/`RPAREN` arms) double-counted every
158 // balanced pair, inflating n1/N1 (#695).
159 // `LPAREN2` is defensive — the runtime collapses it to `LPAREN`
160 // before `kind_id()`, so it never fires (#768; see the Cpp note).
161 | Tcl::LBRACE
162 | Tcl::LBRACK
163 | Tcl::LPAREN
164 | Tcl::LPAREN2
165 | Tcl::SEMI
166 | Tcl::COLON
167 | Tcl::COLONCOLON
168 | Tcl::COLONCOLON2
169 // Arithmetic / exponent operators.
170 | Tcl::PLUS
171 | Tcl::DASH
172 | Tcl::STAR
173 | Tcl::SLASH
174 | Tcl::PERCENT
175 | Tcl::STARSTAR
176 // Bitwise operators.
177 | Tcl::AMP
178 | Tcl::PIPE
179 | Tcl::CARET
180 | Tcl::TILDE
181 | Tcl::LTLT
182 | Tcl::GTGT
183 // The comparison, short-circuit and ternary operators are not
184 // here: the `Comparison`, `ShortCircuit` and `Ternary` rows of
185 // `roles/tcl.rs` pay them and `get_paying_role` bills them
186 // (#1695).
187 | Tcl::BANG => TokenRole::Operator,
188
189 // The anonymous `id` token (`Id2`) is the kind the parser
190 // actually emits, in *both* of its positions: as a standalone
191 // `set` target (`set s …` → `s`, a real operand) and as the
192 // inner leaf of every `variable_substitution` (`$s` →
193 // `(variable_substitution (id "s"))`), whose wrapper is already
194 // the operand for the reference. A blanket `Id2` exclusion
195 // therefore dropped every `set` target from n2/N2 (#1294); the
196 // correct guard is a parent check, the same shape as iRules'
197 // `Id` arm. The named `Id` never surfaces at the pinned grammar
198 // (drift marker: `tcl_named_id_variant_is_unreachable`) and is
199 // listed defensively so a grammar bump that starts emitting it
200 // classifies it identically.
201 Tcl::Id | Tcl::Id2 => {
202 if ancestors.parent_has_kind(node, Tcl::VariableSubstitution as u16) {
203 TokenRole::Unknown
204 } else {
205 TokenRole::Operand
206 }
207 }
208
209 // Operands: identifiers and literals.
210 //
211 // `BracedWord` reaches this arm only when the guard above
212 // let it through, which since #1354 means only when it
213 // holds no command. A script kind holding commands —
214 // a `proc` body, an `if` body, a `catch` or `eval` script —
215 // was billed as one operand spanning its entire text
216 // *beside* the commands the walk descends into, which made
217 // `n2` grow with the size and uniqueness of the code rather
218 // than with its vocabulary; nested bodies compounded it,
219 // one vocabulary entry per block, each containing the next.
220 //
221 // Gated rather than deleted (grammar-dispatch §6): the same
222 // kind is the value slot of every command the grammar does
223 // not special-case, so `lappend l {}` is an empty list
224 // whose brace pair is its only carrier, and deleting the
225 // kind scored it zero where its `lappend l ""` synonym
226 // scores one. An empty or comment-only `proc` body is
227 // spelled identically and so also counts one — #1318 can
228 // now tell the two roles apart, but it revises only the
229 // brace, so nothing here changes.
230 // role-bypass: allow(StringLit) — the operand classification of the braced words
231 // and of the substitution the row `wraps`, a projection the row does not answer
232 Tcl::SimpleWord
233 | Tcl::Number
234 | Tcl::BracedWord
235 | Tcl::BracedWordSimple
236 | Tcl::VariableSubstitution => TokenRole::Operand,
237
238 // Double-quoted strings count as a single operand when inert
239 // (`"hello world"`). When they carry a `$var` or `[cmd]`
240 // interpolation child, the inner `variable_substitution` /
241 // `command_substitution` nodes are walked separately and
242 // contribute their own operands; counting the wrapping
243 // `QuotedWord` too would double-count `N2` (issue #277, same
244 // pattern as #180/#183/#184 for Bash/C#/PHP).
245 // role-bypass: allow(StringLit) — the operand classification of the literals
246 // under the row's `wraps` list, a projection the row does not answer
247 Tcl::QuotedWord => {
248 Self::string_operand_type(node, crate::roles::tcl::string_lit::WRAPS)
249 }
250
251 _ => TokenRole::Unknown,
252 }
253 }
254
255 // The half of the braced-word rule that needs the source bytes
256 // (#1318). `braced_word` serves two roles — the block of
257 // `eval {…}` and the literal of `lappend x {a b}` — and the
258 // grammar spells both the same, so only the enclosing command's
259 // leading word tells them apart (grammar-dispatch §9). This is the
260 // spelling the walk calls (`compute_halstead` →
261 // `get_op_type_with_code`), so the revision reaches every count.
262 fn get_op_type_with_code<'a>(
263 node: &Node<'a>,
264 code: &[u8],
265 ancestors: Ancestors<'a, '_>,
266 ) -> TokenRole {
267 Self::braced_word_op_type(node, code, ancestors, &BRACED_WORD_KINDS)
268 }
269
270 get_operator!(Tcl);
271}