Skip to main content

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}