Appearance
| 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 |