|
| 1 | +# Custom colors |
| 2 | + |
| 3 | +Since 23.0.6 Ada Language Server provides |
| 4 | +[Semantic token provider](https://code.visualstudio.com/api/language-extensions/semantic-highlight-guide). |
| 5 | +The VS Code extension leverages it to colorize source code by mapping semantic colors to predefined "TextMate scopes". |
| 6 | +See `semanticTokenScope` in the |
| 7 | +[package.json](https://github.com/AdaCore/ada_language_server/blob/master/integration/vscode/ada/package.json). |
| 8 | +But not all token types and modifier combination are visually distinguishable this way. |
| 9 | + |
| 10 | +Users are welcome to [customize colors](https://code.visualstudio.com/docs/getstarted/themes#_customizing-a-color-theme) to visualize more token types and modifier combinations. This guide provides more details for this and a customization example. |
| 11 | + |
| 12 | +In addition to semantic highlighting, users can customize syntax highlighting for keywords, strings, comments or numbers: syntax highlighting will be used for those when the corresponding tokens are not associated with any modifier. Syntax highlighting customization should be made via TextMate rules, which associate _scopes_ and a given style (color, font etc.). |
| 13 | + |
| 14 | +You can use the [Developer: Inspect editor tokens and scopes](https://www.youtube.com/watch?v=mC_htrJ1QPg&ab_channel=Code2020) command to know the scope of a given token (see the screenshot below). |
| 15 | + |
| 16 | + |
| 17 | + |
| 18 | +You can also find more documentation about TextMat scopes [here](https://macromates.com/manual/en/language_grammars). |
| 19 | + |
| 20 | +## Supported token types |
| 21 | + |
| 22 | +Ada Language Server uses next types of tokens: |
| 23 | + |
| 24 | +| Token type | Ada element | |
| 25 | +|---------------|----------------------------------| |
| 26 | +| namespace | package |
| 27 | +| class | tagged type |
| 28 | +| enum | enumeration type |
| 29 | +| interface | interface type |
| 30 | +| type | any other type |
| 31 | +| typeParameter | type discriminant |
| 32 | +| parameter | subprogram or generic parameter |
| 33 | +| variable | object declaration |
| 34 | +| property | component declaration |
| 35 | +| enumMember | enumeration literal |
| 36 | +| function | subprogram |
| 37 | +| modifier | any other identifier |
| 38 | +| keyword | keyword |
| 39 | +| comment | comment |
| 40 | +| string | string literal |
| 41 | +| number | numeric literal or named number |
| 42 | +| operator | operator |
| 43 | + |
| 44 | +## Supported token modifiers |
| 45 | + |
| 46 | +Ada Language Server uses next modifiers of tokens: |
| 47 | + |
| 48 | +| Modifier | Usage |
| 49 | +|----------------|----------------------------------| |
| 50 | +| declaration | declaration with completion part |
| 51 | +| definition | body or completion for a declaration |
| 52 | +| readonly | constant or parameter with `in` mode |
| 53 | +| static | static subtype or function |
| 54 | +| deprecated | declaration with `Obsolescent` aspect/pragma |
| 55 | +| abstract | abstract type or subprogram |
| 56 | +| modification | write access to a name |
| 57 | +| documentation | ghost code or aspect |
| 58 | +| defaultLibrary | predefined name |
| 59 | + |
| 60 | +## Example |
| 61 | + |
| 62 | +This example is based on Dark+ color theme. We have: |
| 63 | + |
| 64 | +* **bold** writing for write access |
| 65 | +* _italic_ writing for parameters, type discriminants, abstract entities and interfaces |
| 66 | +* ~~strikethrough~~ writing for declaration with `Obsolescent` aspect/pragma |
| 67 | +* constants and read-only names have a brighter color then variables and `in out` parameters |
| 68 | +* ghost code is green as comments |
| 69 | + |
| 70 | + |
| 71 | + |
| 72 | +Open `settings.json` and append next: |
| 73 | + |
| 74 | +```json |
| 75 | + // Syntax highlighting |
| 76 | + "editor.tokenColorCustomizations": { |
| 77 | + "textMateRules": [ |
| 78 | + { |
| 79 | + "scope": "keyword", |
| 80 | + "settings": { |
| 81 | + "foreground": "#569cd6" |
| 82 | + }, |
| 83 | + }, |
| 84 | + { |
| 85 | + "scope": "entity.name.operator", |
| 86 | + "settings": { |
| 87 | + "foreground": "#cebff5", |
| 88 | + }, |
| 89 | + }, |
| 90 | + { |
| 91 | + "scope": "comment", |
| 92 | + "settings": { |
| 93 | + "foreground": "#6A9955" |
| 94 | + }, |
| 95 | + }, |
| 96 | + { |
| 97 | + "scope": "constant.numeric", |
| 98 | + "settings": { |
| 99 | + "foreground": "#b5cea8", |
| 100 | + }, |
| 101 | + }, |
| 102 | + { |
| 103 | + "scope": "string", |
| 104 | + "settings": { |
| 105 | + "foreground": "#ce9178", |
| 106 | + }, |
| 107 | + } |
| 108 | + ] |
| 109 | + } |
| 110 | + |
| 111 | + // Semantic highlighting |
| 112 | + "editor.semanticTokenColorCustomizations": { |
| 113 | + "[Default Dark+]": { |
| 114 | + "rules": { |
| 115 | + "namespace": "#C8C8C8", |
| 116 | + "type": "#4EC9B0", |
| 117 | + "class": "#4CD5E0", |
| 118 | + "enum": "#4CE099", |
| 119 | + "interface": {"foreground": "#4CD5E0", "italic": true}, |
| 120 | + "struct": "#49D66A", |
| 121 | + "typeParameter": {"foreground": "#3E52EB", "italic": true}, |
| 122 | + "parameter": {"foreground": "#9CDCFE", "italic": true}, |
| 123 | + "variable": "#9CDCFE", |
| 124 | + "property": "#8F9DFF", |
| 125 | + "enumMember": "#93E6BE", |
| 126 | + "function": "#DCDCAA", |
| 127 | + "keyword": "#569cd6", |
| 128 | + "modifier": "#569cd6", |
| 129 | + "comment": "#6A9955", |
| 130 | + "string": "#ce9178", |
| 131 | + "number": "#b5cea8", |
| 132 | + "operator": "#C586C0", |
| 133 | + |
| 134 | + "*.abstract": {"italic": true}, |
| 135 | + "*.modification": {"bold": true}, |
| 136 | + "*.deprecated": {"strikethrough": true}, |
| 137 | + "*.readonly": "#4FC1FF", |
| 138 | + "property.readonly": "#3E52EB", |
| 139 | + "typeParameter.readonly": {"foreground": "#3E52EB", "italic": true}, |
| 140 | + "*.documentation": "#6A9955", |
| 141 | + |
| 142 | + "keyword.documentation": {"bold": true}, |
| 143 | + "operator.documentation": {"bold": true} |
| 144 | + }, |
| 145 | + } |
| 146 | + } |
| 147 | + |
| 148 | +``` |
0 commit comments