Skip to content
← Back

src/syntax/process/check_name_conventions.ghul

1
namespace Syntax.Process is
2
use Source.LOCATION
3
use Trees
4
5
use Logging.Logger
6
7
// Walks the AST after resolve-ancestors and emits warnings for
8
// ghūl-source declarations whose names don't match the case
9
// convention for their kind:
10
//
11
// snake_case — locals (via `let`, `for`, `catch`,
12
// function arguments), fields, properties,
13
// methods, free functions.
14
// Slug: non-snake-case-name.
15
//
16
// PascalCase — abstract classes, exception classes (any
17
// class with Exception among its ancestors),
18
// traits, unions, enums.
19
// Slug: non-pascal-case-name.
20
//
21
// UPPER_SNAKE_CASE — concrete (instantiable) classes, structs,
22
// variants, enum members.
23
// Slug: non-upper-snake-case-name.
24
//
25
// Each is independently suppressable via the standard
26
// `@suppress("<slug>")` pragma — pin per declaration, per file,
27
// or project-wide as the project's conventions require. Unit-test
28
// projects with the `Calling__foo__should_X` long-name idiom are
29
// the typical project-wide suppression for non-snake-case-name.
30
//
31
// What this pass DOESN'T flag:
32
// - User-defined operator names like `+`, `==`, `##`, `\/` —
33
// the tokenizer emits them as IDENTIFIER too but they have
34
// no case-style form. Filtered by the leading-character
35
// check below.
36
// - Compiler-synthesised `$`-prefixed names.
37
// - Imported .NET members — the symbol factory auto-converts
38
// them; this pass only sees ghūl-source AST.
39
class CHECK_NAME_CONVENTIONS: Visitor is
40
_logger: Logger
41
_symbol_table: Semantic.SYMBOL_TABLE
42
_innate_symbol_lookup: Semantic.Lookups.InnateSymbolLookup
43
44
init(
45
logger: Logger,
46
symbol_table: Semantic.SYMBOL_TABLE,
47
innate_symbol_lookup: Semantic.Lookups.InnateSymbolLookup
48
) is
49
super.init()
50
51
_logger = logger
52
_symbol_table = symbol_table
53
_innate_symbol_lookup = innate_symbol_lookup
54
si
55
56
apply(source_file: Compiler.SOURCE_FILE) is
57
source_file.definition.walk(self)
58
si
59
60
visit(variable: Trees.Variables.VARIABLE) is
61
// A static field is a named constant and conventionally
62
// UPPER_SNAKE_CASE; a snake_case static field is fine too.
63
// Instance fields and locals stay snake_case.
64
for identifier in variable.left.names! do
65
if variable.is_static then
66
_check_snake_or_upper_snake(identifier, "name")
67
else
68
_check_snake(identifier, "name")
69
fi
70
od
71
si
72
73
visit(function: Trees.Definitions.FUNCTION) is
74
if !function.name? then
75
return
76
fi
77
78
// Skip compiler-synthesised accessor functions. Property
79
// accessors carry a `$` prefix that the leading-character
80
// check filters; indexer accessors must use the
81
// CLR-required `get_<Name>` / `set_<Name>` shape and
82
// aren't named by the user, so we gate on the AST link.
83
if function.for_property? \/ function.for_indexer? then
84
return
85
fi
86
87
_check_snake(function.name, "name")
88
si
89
90
visit(property: Trees.Definitions.PROPERTY) is
91
if !property.name? then
92
return
93
fi
94
95
// A static property may name a constant and so may be
96
// UPPER_SNAKE_CASE; snake_case is fine too.
97
if property.modifiers.is_static then
98
_check_snake_or_upper_snake(property.name, "name")
99
else
100
_check_snake(property.name, "name")
101
fi
102
si
103
104
visit(`class: Trees.Definitions.CLASS) is
105
106
// Abstract classes follow PascalCase. Abstractness is read
107
// from the declared symbol so both explicitly-`abstract`
108
// classes and implicitly-abstract ones (a class with a
109
// user-written body-less instance method, marked during
110
// declare-symbols) are recognised uniformly — this pass runs
111
// after declare-symbols for that reason. A class with no
112
// primary-constructor parameters whose every instance-shaped
113
// member is `static` is a static-utility container — never
114
// constructed — and conventionally either PascalCase or
115
// UPPER_SNAKE_CASE, so either passes.
116
// An exception class is named where it is thrown and where it
117
// is caught, which is where naming the concrete type is right,
118
// and every exception imported from .NET is PascalCase already.
119
if _is_exception_class(`class) then
120
_check_pascal(`class.name, "exception class")
121
elif _is_abstract_class(`class) then
122
_check_pascal(`class.name, "abstract class")
123
elif _is_static_only_class(`class) then
124
_check_pascal_or_upper_snake(`class.name, "class")
125
else
126
_check_upper_snake(`class.name, "class")
127
fi
128
si
129
130
visit(`struct: Trees.Definitions.STRUCT) is
131
132
_check_upper_snake(`struct.name, "struct")
133
si
134
135
visit(`trait: Trees.Definitions.TRAIT) is
136
137
_check_pascal(`trait.name, "trait")
138
si
139
140
visit(`union: Trees.Definitions.UNION) is
141
142
_check_pascal(`union.name, "union")
143
si
144
145
visit(variant: Trees.Definitions.VARIANT) is
146
_check_upper_snake(variant.name, "variant")
147
si
148
149
visit(`enum: Trees.Definitions.ENUM) is
150
151
_check_pascal(`enum.name, "enum")
152
si
153
154
visit(enum_member: Trees.Definitions.ENUM_MEMBER) is
155
156
_check_upper_snake(enum_member.name, "enum member")
157
si
158
159
_check_snake(identifier: Trees.Identifiers.Identifier, kind: string) is
160
let bare = _prepare(identifier)
161
162
if !bare? \/ _is_snake_case(bare) then
163
return
164
fi
165
166
_warn(identifier, kind, "non-snake-case-name", "snake_case")
167
si
168
169
_check_pascal(identifier: Trees.Identifiers.Identifier, kind: string) is
170
let bare = _prepare(identifier)
171
172
if !bare? \/ _is_pascal_case(bare) then
173
return
174
fi
175
176
_warn(identifier, kind, "non-pascal-case-name", "PascalCase")
177
si
178
179
_check_upper_snake(identifier: Trees.Identifiers.Identifier, kind: string) is
180
let bare = _prepare(identifier)
181
182
if !bare? \/ _is_upper_snake_case(bare) then
183
return
184
fi
185
186
_warn(identifier, kind, "non-upper-snake-case-name", "UPPER_SNAKE_CASE")
187
si
188
189
_check_pascal_or_upper_snake(identifier: Trees.Identifiers.Identifier, kind: string) is
190
let bare = _prepare(identifier)
191
192
if !bare? \/ _is_pascal_case(bare) \/ _is_upper_snake_case(bare) then
193
return
194
fi
195
196
_warn(identifier, kind, "non-upper-snake-case-name", "UPPER_SNAKE_CASE")
197
si
198
199
_check_snake_or_upper_snake(identifier: Trees.Identifiers.Identifier, kind: string) is
200
let bare = _prepare(identifier)
201
202
if !bare? \/ _is_snake_case(bare) \/ _is_upper_snake_case(bare) then
203
return
204
fi
205
206
_warn(identifier, kind, "non-snake-case-name", "snake_case")
207
si
208
209
// A class is an exception when it is the root exception type, as a
210
// core library declares it, or when that type is among its resolved
211
// ancestors, at any depth. A class whose ancestors did not resolve
212
// has none to find it among, so it is checked as any other class.
213
_is_exception_class(`class: Trees.Definitions.CLASS) -> bool is
214
let classy = cast Semantic.Symbols.Classy?(_symbol_table.scope_for(`class))
215
216
if !classy? then
217
return false
218
fi
219
220
let exception_type = _innate_symbol_lookup.find_exception_type()
221
222
if !exception_type? then
223
return false
224
fi
225
226
let exception = exception_type.symbol
227
228
if classy == exception then
229
return true
230
fi
231
let seen = Collections.SET[Semantic.Symbols.Classy]()
232
let pending = Collections.STACK[Semantic.Symbols.Classy]()
233
234
pending.push(classy)
235
236
while pending.count > 0 do
237
let next = pending.pop()
238
239
if !seen.add(next) then
240
continue
241
fi
242
243
for ancestor in next.ancestors do
244
let symbol = ancestor.symbol
245
246
if symbol == exception then
247
return true
248
fi
249
250
if let ancestor_classy: Semantic.Symbols.Classy = symbol then
251
pending.push(ancestor_classy)
252
fi
253
od
254
od
255
256
return false
257
si
258
259
// A class is abstract — and so follows PascalCase — when its
260
// declared symbol reports `is_abstract`, which folds together an
261
// explicit `abstract` modifier and implicit abstractness from a
262
// user-written body-less instance method. The symbol is reached
263
// through the node-to-scope map populated by declare-symbols;
264
// the syntactic modifier is a fallback for the rare case where
265
// the class has no associated symbol.
266
_is_abstract_class(`class: Trees.Definitions.CLASS) -> bool is
267
let classy = cast Semantic.Symbols.Classy?(_symbol_table.scope_for(`class))
268
269
if classy? then
270
return classy.is_abstract
271
fi
272
273
return `class.modifiers.is_abstract
274
si
275
276
// Returns the bare identifier (backticks stripped) when it
277
// starts with a letter or underscore — i.e. is in scope for
278
// any case-style rule. Returns null when the identifier is
279
// an operator, a `$`-prefixed compiler-synthesised name, or
280
// would be empty after stripping. Backticks themselves are
281
// escape/disambiguation syntax (`\`field\``, `list\`[T]`) and
282
// not part of the name semantically.
283
_prepare(identifier: Trees.Identifiers.Identifier) -> string? static is
284
if identifier.name.length == 0 then
285
return null
286
fi
287
288
let bare = _strip_backticks(identifier.name)
289
290
if bare.length == 0 \/ !_starts_with_identifier_char(bare) then
291
return null
292
fi
293
294
return bare
295
si
296
297
// A class is "static-only" — and therefore not meaningfully
298
// instantiable — when it has no primary-constructor params
299
// and every instance-shaped member (function, property, field)
300
// is `static`. Nested type definitions don't count either way;
301
// a class containing only nested types is also non-instantiable.
302
// An empty class is *not* considered static-only: a bare
303
// `class FOO is si` is presumed to be a soon-to-be-populated
304
// instantiable shell.
305
_is_static_only_class(`class: Trees.Definitions.CLASS) -> bool static is
306
if let `class.primary_params? /\ primary_params.count > 0 then
307
return false
308
fi
309
310
311
let saw_instance_shaped mut = false
312
313
for member in `class.body do
314
let bare = member.without_pragmas
315
316
if isa Trees.Definitions.FUNCTION(bare) then
317
let function = cast Trees.Definitions.FUNCTION(bare)
318
319
// What the author wrote is what says whether this is
320
// a container of statics. A member the compiler adds
321
// - an equality operator, a hash, a bridge - is not
322
// the author's instance member and must not take the
323
// class out of the exemption.
324
if function.is_synthesized then
325
continue
326
fi
327
328
saw_instance_shaped = true
329
330
if !function.modifiers.is_static then
331
return false
332
fi
333
elif isa Trees.Definitions.PROPERTY(bare) then
334
saw_instance_shaped = true
335
let property = cast Trees.Definitions.PROPERTY(bare)
336
if !property.modifiers.is_static then
337
return false
338
fi
339
elif isa Trees.Variables.VARIABLE(bare) then
340
saw_instance_shaped = true
341
let variable = cast Trees.Variables.VARIABLE(bare)
342
if !variable.is_static then
343
return false
344
fi
345
fi
346
od
347
348
return saw_instance_shaped
349
si
350
351
_warn(identifier: Trees.Identifiers.Identifier, kind: string, slug: string, case_label: string) is
352
_logger.warn(
353
identifier.location,
354
slug,
355
"non-{case_label} {kind} '{identifier.name}'"
356
)
357
si
358
359
_strip_backticks(name: string) -> string static is
360
let buffer = System.Text.StringBuilder()
361
for i in 0..name.length do
362
let c = name[i]
363
if c != '`' then
364
buffer.append(c)
365
fi
366
od
367
return buffer.to_string()
368
si
369
370
_starts_with_identifier_char(name: string) -> bool static =>
371
Lexical.TOKENIZER.is_identifier_start(name[0])
372
373
// A character with an upper and a lower form is read against
374
// the convention; one with neither, as in Chinese or Arabic,
375
// says nothing about case and so is correct wherever it sits.
376
_is_cased(c: char) -> bool static =>
377
char.is_upper(c) \/ char.is_lower(c) \/ _is_titlecase(c)
378
379
@IF.dotnet()
380
_is_titlecase(c: char) -> bool static =>
381
char.get_unicode_category(c) == System.Globalization.UnicodeCategory.TITLECASE_LETTER
382
383
// The titlecase letters of the basic plane: the Latin digraphs and
384
// the Greek capitals with a prosgegrammeni.
385
@IF.not.dotnet()
386
_is_titlecase(c: char) -> bool static is
387
let code = cast int(c)
388
389
return
390
code == 0x1C5 \/ code == 0x1C8 \/ code == 0x1CB \/ code == 0x1F2 \/
391
code >= 0x1F88 /\ code <= 0x1F8F \/ code >= 0x1F98 /\ code <= 0x1F9F \/
392
code >= 0x1FA8 /\ code <= 0x1FAF \/ code == 0x1FBC \/ code == 0x1FCC \/ code == 0x1FFC
393
si
394
395
_is_snake_case(name: string) -> bool static is
396
for i in 0..name.length do
397
let c = name[i]
398
399
if _is_cased(c) /\ !char.is_lower(c) then
400
return false
401
fi
402
od
403
404
return true
405
si
406
407
// PascalCase: no underscore except leading ones, which mark
408
// a private name (e.g. `_Helper`). The first character after
409
// them is upper-case where it has a case.
410
_is_pascal_case(name: string) -> bool static is
411
let i mut = 0
412
413
while i < name.length /\ name[i] == '_' do
414
i = i + 1
415
od
416
417
if i >= name.length then
418
return false
419
fi
420
421
let first = name[i]
422
423
if _is_cased(first) /\ !char.is_upper(first) then
424
return false
425
fi
426
427
i = i + 1
428
429
while i < name.length do
430
if name[i] == '_' then
431
return false
432
fi
433
434
i = i + 1
435
od
436
437
return true
438
si
439
440
// UPPER_SNAKE_CASE: every cased character is upper-case, and
441
// at least one letter is present so a bare `_` or `_123`
442
// doesn't pass. An uncased letter counts towards that: a name
443
// written in a script with no case has no upper form to show.
444
_is_upper_snake_case(name: string) -> bool static is
445
let saw_letter mut = false
446
447
for i in 0..name.length do
448
let c = name[i]
449
450
if _is_cased(c) /\ !char.is_upper(c) then
451
return false
452
fi
453
454
if char.is_letter(c) then
455
saw_letter = true
456
fi
457
od
458
459
return saw_letter
460
si
461
si
462
si