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
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
//! Bash's role rows. The Halstead keyword roles (#1693), the
//! paying-construct roles — `Comparison`, `ShortCircuit`, `EagerLogical`,
//! `Ternary`, `CaseArm`, `Guard`, `NullSafe` (#1694, #1695) — the space
//! tree (#1696) and the control flow — `Branch`, `Switch`, `Loop`,
//! `Catch`, `ElseIf`, `Exit` (#1697) — and
//! the documentation rows (#1699) are declared.
use crate::lang_helpers::bash::bash_test_connective;
use crate::lang_helpers::case_arms::bash_case_item_is_bare_wildcard;
use crate::role_table;
use crate::{Ancestors, Bash, Node};
/// Whether a `case_item` is a decision arm rather than the `*)`
/// catch-all: exactly one `value` field spelling `*` (lesson 11, #469).
/// `a|b)` and `*|b)` are not bare and still count.
fn is_decision_item(node: &Node<'_>, code: &[u8]) -> bool {
!bash_case_item_is_bare_wildcard(node, code)
}
/// Whether a `test_operator` is a comparison rather than one of the
/// `-a` / `-o` connectives: the grammar gives `-z`, `-n`, `-eq`, `-lt`,
/// `-a`, `-o`, … one kind, so only the bytes tell them apart (#1536).
fn is_test_comparison<'a>(node: &Node<'a>, code: &[u8], ancestors: Ancestors<'a, '_>) -> bool {
ancestors
.parent(node)
.is_none_or(|parent| bash_test_connective(node, &parent, code).is_none())
}
/// Whether a `test_operator` is an `-a` / `-o` connective.
fn is_test_connective<'a>(node: &Node<'a>, code: &[u8], ancestors: Ancestors<'a, '_>) -> bool {
ancestors
.parent(node)
.is_some_and(|parent| bash_test_connective(node, &parent, code).is_some())
}
/// Whether a `binary_expression`'s `operator` field is one of the
/// `Comparison` payers, with a `test_operator` read for its bytes.
fn comparison_operator(node: &Node<'_>, code: &[u8]) -> bool {
comparison::project(node).is_some_and(|op| {
comparison::PAYERS.contains(&op.kind_id())
&& (op.kind_id() != Bash::TestOperator as u16
|| bash_test_connective(&op, node, code).is_none())
})
}
/// Whether a `binary_expression`'s `operator` field is a short-circuit
/// payer, with a `test_operator` read for its bytes.
fn short_circuit_operator(node: &Node<'_>, code: &[u8]) -> bool {
short_circuit::project(node).is_some_and(|op| {
let kind = op.kind_id();
if kind == Bash::TestOperator as u16 {
bash_test_connective(&op, node, code).is_some()
} else {
short_circuit::PAYERS.contains(&kind)
}
})
}
/// Whether a `command` is the `return` or `exit` builtin, by the text of
/// its `name` field. Invalid UTF-8 reads as no match.
fn return_or_exit(node: &Node<'_>, code: &[u8]) -> bool {
node.child_by_field_name("name")
.is_some_and(|name| matches!(name.utf8_text(code), Some("return" | "exit")))
}
role_table! {
lang: Bash;
// Every command is a call: Bash has no other call kind, and the
// `command` node covers the builtin, the function and the external
// program alike.
Call { owns [Command] }
// The heredoc body is `HeredocBody2`: tree-sitter-bash 0.25.1 emits
// only that `heredoc_body` parser-node symbol in observed trees; the
// duplicate `HeredocBody` entry plus the hidden `_heredoc_body`
// (`HeredocBody3`) and `_simple_heredoc_body` (`SimpleHeredocBody`)
// rules never surface and are left out. An expanding string
// `wraps` the four expansion kinds, whose inner names are billed on
// their own (#180); `raw_string` and `ansi_c_string` cannot expand,
// and the `translated_string` (`$"…"`) is one `$` and a `string`
// child that is the keeper in argument position (#1358), so the
// operand arm bills the child rather than the wrapper.
StringLit {
owns [String, RawString, AnsiCString, TranslatedString, HeredocBody2]
wraps [SimpleExpansion, Expansion, CommandSubstitution, ArithmeticExpansion]
}
// A comparison inside `[[ … ]]` / `(( … ))` is a `binary_expression`
// (`BinaryExpression3` at the pinned grammar; the four siblings are
// listed defensively) owning one of `==` `!=` `<=` `>=` `=~`, or `<`
// / `>` under that parent (any alias) since the same two tokens
// spell an I/O redirection (`cmd > out`, `read x < in`), which the
// grammar parents under `file_redirect` (#1280). Inside `[ … ]` the
// comparison is a `test_operator` —
// `-eq`, `-lt`, `-z`, `-n`, … — one kind the grammar shares with the
// `-a` / `-o` connectives, so that payer is text-gated: a
// `test_operator` pays as a comparison exactly when its bytes are
// not a connective. `=` compares inside a test and assigns inside
// `(( … ))`, which only the test's descent can tell (#1536); the
// ABC consumer counts it from the test, as its own extra.
Comparison {
owns [
BinaryExpression(gated_by comparison_operator no_chain),
BinaryExpression2(gated_by comparison_operator no_chain),
BinaryExpression3(gated_by comparison_operator no_chain),
BinaryExpression4(gated_by comparison_operator no_chain),
BinaryExpression5(gated_by comparison_operator no_chain),
]
pays [
EQEQ, BANGEQ, LTEQ, GTEQ, EQTILDE,
LT under [
BinaryExpression, BinaryExpression2, BinaryExpression3, BinaryExpression4,
BinaryExpression5,
],
GT under [
BinaryExpression, BinaryExpression2, BinaryExpression3, BinaryExpression4,
BinaryExpression5,
],
TestOperator text_gated_by is_test_comparison,
]
project "operator"
}
// `&&` / `||` join two commands in a `list` and two tests inside
// `[[ … ]]` / `(( … ))` in a `binary_expression`; inside `[ … ]` the
// same join is the `-a` / `-o` spelling of `test_operator`, read by
// text. Bash's `&&` / `||` are command-list separators, so the ABC
// consumer reads this row for nothing (#1536 — Fitzpatrick Rule 9
// does not map onto its grammar) where cyclomatic and cognitive
// read it.
ShortCircuit {
owns [
List,
BinaryExpression(gated_by short_circuit_operator no_chain),
BinaryExpression2(gated_by short_circuit_operator no_chain),
BinaryExpression3(gated_by short_circuit_operator no_chain),
BinaryExpression4(gated_by short_circuit_operator no_chain),
BinaryExpression5(gated_by short_circuit_operator no_chain),
]
pays [AMPAMP, PIPEPIPE, TestOperator text_gated_by is_test_connective]
project "operator"
}
// `-a` / `-o` inside `[ ]` are arguments to the `test` builtin,
// which evaluates both sides (`[ 1 -eq 2 -a nope -eq 1 ]` still
// complains about `nope`), so by the language they are eager. Every
// consumer scores them as the `[[ … && … ]]` twin they spell
// (#1536), so they are the `ShortCircuit` row's text-gated payer
// above: a policy this package records and does not move. The
// bitwise `&` / `|` / `^` inside `(( … ))` are the only other
// candidates, and are integral.
EagerLogical {
owns []
excludes [
TestOperator "`-a` / `-o` are scored as the `&&` / `||` they spell (#1536), so the \
`ShortCircuit` row claims them; the builtin's eager evaluation is recorded here",
]
}
// The arithmetic `(( a ? b : c ))` is Bash's only ternary: the
// `ternary_expression` owns it (`TernaryExpression2` is the second
// id carrying the kind, listed per grammar-dispatch §1 and
// unreachable at the pinned grammar) and its `?` pays, gated to that
// owner since `${y?msg}` spells the same token. `QMARK2` is the
// grammar's second `?` id, which no spelling at the pinned grammar
// emits — `bash_ternary_expression_alias_is_unreachable` in the
// cyclomatic tests pins that beside the owner alias — so it is
// recorded as considered rather than paid; the getter still bills
// it as the operator it names, should a bump start emitting it.
Ternary {
owns [TernaryExpression, TernaryExpression2]
pays [QMARK under [TernaryExpression, TernaryExpression2]]
project "operator"
excludes [QMARK2 "the second `?` id, which no spelling at the pinned grammar emits"]
}
NullSafe { absent "Bash has no optional navigation or null coalescing" }
// A `case_item` (`CaseItem2` the second id carrying the kind, per
// grammar-dispatch §1) owns a decision and pays at the node — the
// arm has no keyword; `case` and `esac` are the statement's and bill
// as the keywords they are — unless its sole pattern is `*`, the
// catch-all (lesson 11, #469), which only the bytes tell.
CaseArm {
owns [CaseItem(text_gated_by is_decision_item no_chain), CaseItem2(text_gated_by is_decision_item no_chain)]
}
Guard { absent "Bash has no guard clause; a `case` pattern is a glob, not a condition" }
// Bash counts statement nodes, so every row here is plain (#1697).
Branch { owns [IfStatement] }
Switch { owns [CaseStatement] }
// `for x in …`, the C-style `for ((…))`, `while` and `until` (one
// `while_statement` kind for both).
Loop { owns [ForStatement, CStyleForStatement, WhileStatement] }
Catch { absent "Bash has no exception handling; `trap` is a command" }
// The grammar gives `elif` a clause node of its own, a direct child of
// the `if_statement`, so the clause *is* the else-if and pays for
// itself; no nested `if` is ever an else-if here.
ElseIf { owns [ElifClause(pays_itself)] pays [] }
// Bash has no `return_statement` node: `return` and `exit` are
// ordinary builtins parsed as a `command` whose `name` field is a
// `command_name`, told by text.
Exit { owns [Command(text_gated_by return_or_exit no_chain)] }
Modifier { absent "Bash declares with builtins (`local`, `readonly`), which are commands, not \
modifier keywords" }
// The declaration builtins the grammar gives a kind of their own:
// `function`, and `local` / `declare` / `typeset` / `export` /
// `readonly`, each the leaf of a `declaration_command` or a
// `function_definition`, neither listed. `unset` / `unsetenv` are
// the inverse and bill with the commands.
DeclKeyword { owns [Function, Local, Declare, Typeset, Export, Readonly] }
Primitive { absent "Bash has no type names" }
FuncOpener { owns [FunctionDefinition(callable opens Function)] }
Container { owns [Program(opens Unit)] }
Closure { absent "Bash has no anonymous function" }
Member { absent "Bash has no container to hold a member" }
// The one comment kind. The grammar marks no comment as
// documentation, and no convention a tool reads over a comment run
// (shdoc's `# @description` blocks) is recognised here, so the six
// documentation rows are absent — unsupported, not nonexistent —
// and `is_comment` is this row's kind table alone (#1699).
Comment { owns [Comment] }
DocComment { absent "the grammar marks no comment as documentation; no tool's convention is read" }
Docstring { absent "Bash documents with comments, not string literals" }
DocTarget { absent "no comment is recognised as documentation, so nothing is its target" }
DocRunOpener { absent "no comment-run convention (shdoc) is recognised" }
DocRunDirective { absent "no comment-run convention (shdoc) is recognised" }
DocBodyResidual { absent "no kind holds documentation in a body beyond the function" }
}
#[cfg(test)]
mod tests {
use super::*;
use crate::BashCode;
use crate::test_support::for_each_node_with_chain;
// The `Ternary` row's `?` is the arithmetic ternary's alone: an
// expansion's `${y?msg}` spells the same bare token and pays
// nothing, and `$?` is a token of its own (#1695). ABC reads the
// row at its wrapper and Halstead's byte-less arm keeps billing the
// expansion's `?`, so this is the one place the payer gate is
// observed.
#[cfg(feature = "bash")]
#[test]
fn ternary_pays_at_the_arithmetic_question_mark_only() {
let source = b"c=$(( a ? b : x ))\necho ${y?msg} $?\n";
let (mut owned, mut paid) = (Vec::new(), Vec::new());
for_each_node_with_chain::<BashCode>(source, |node, chain| {
let ancestors = Ancestors::known(chain);
let text = || node.utf8_text(source).expect("fixture is UTF-8").to_owned();
if ternary::owns(node, source, ancestors) {
owned.push(text());
}
if ternary::pays_at_leaf(node, source, ancestors) {
paid.push((node.start_byte(), text()));
}
});
assert_eq!(owned, ["a ? b : x"]);
assert_eq!(paid, [(8, "?".to_owned())]);
}
// The `Comparison` and `ShortCircuit` owner gates read the one
// `test_operator` kind for its bytes, as the payer gates do: a
// `binary_expression` holding `-lt` / `-gt` owns a comparison and
// one holding `-a` / `-o` owns a chain, never both. The consumers
// read these rows at the token, so only this pins the owner side,
// and each payer's parent is held to its own row. The first test's
// operators nest left — `(($a -lt $b) -a $c) -gt 1` — so its
// outermost node holds `-gt` and the chain is its left operand; the
// `=` of the second is the `EQ` kind, which the row leaves to the
// consumer (#1536), so that node owns nothing. (`-a` / `-o` are
// `[ ]`'s; inside `[[ ]]` they are a syntax error.)
#[cfg(feature = "bash")]
#[test]
fn test_operators_sort_their_owners_by_their_bytes() {
let source = b"if [ $a -lt $b -a $c -gt 1 ]; then :; fi\n\
if [ \"$s\" = x -o \"$t\" != y ]; then :; fi\n";
let mut owned: [Vec<String>; 2] = Default::default();
let mut paid: [Vec<String>; 2] = Default::default();
for_each_node_with_chain::<BashCode>(source, |node, chain| {
let ancestors = Ancestors::known(chain);
let text = || node.utf8_text(source).expect("fixture is UTF-8").to_owned();
let rows = [
(
comparison::owns(node, source, ancestors),
comparison::pays_at_leaf(node, source, ancestors),
),
(
short_circuit::owns(node, source, ancestors),
short_circuit::pays_at_leaf(node, source, ancestors),
),
];
assert!(!(rows[0].0 && rows[1].0), "{}", text());
assert!(!(rows[0].1 && rows[1].1), "{}", text());
for (row, (owns, pays)) in rows.into_iter().enumerate() {
if owns {
owned[row].push(text());
}
if pays {
paid[row].push(text());
// The payer's parent is the owner, asked with the
// chain above it.
let (parent, above) = chain.split_last().expect("a payer has a parent");
let row_owns = [comparison::owns, short_circuit::owns][row];
assert!(
row_owns(parent, source, Ancestors::known(above)),
"{}",
text()
);
}
}
});
assert_eq!(
owned[0],
["$a -lt $b -a $c -gt 1", "$a -lt $b", "x -o \"$t\" != y"]
);
assert_eq!(owned[1], ["$a -lt $b -a $c", "x -o \"$t\""]);
assert_eq!(paid[0], ["-lt", "-gt", "!="]);
assert_eq!(paid[1], ["-a", "-o"]);
}
}