Skip to content

Commit 631b401

Browse files
Add grammar readme (#17851)
* Add grammar readme * More info
1 parent 52769a0 commit 631b401

File tree

1 file changed

+41
-0
lines changed

1 file changed

+41
-0
lines changed

syntaxes/README.md

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# T-SQL Grammar
2+
3+
This grammar is for the [T-SQL (Transact-SQL)](https://learn.microsoft.com/sql/t-sql/language-reference) language. While it may share many common language elements with other SQL-based languages, its primary purpose is to support the T-SQL Language and as such may include or not include syntax from other languages.
4+
5+
## Syntax Highlighting
6+
7+
Azure Data Studio and VS Code use this grammar to provide syntax highlighting - the color and style of source code - in their respective editors. You can read more about how this is done [here](https://code.visualstudio.com/api/language-extensions/syntax-highlight-guide)
8+
9+
Each token defined in the grammar is then given a color based on the current theme, matching as specific of a token name as possible. For example, `keyword.other.sql` and `keyword.other.create.sql` can be different colors if there's a `tokenColors` setting defined for them specifically. But if not then they will try to match more general scopes - which in the typical case is going to have both resolve to the `keyword` scope.
10+
11+
Because of this, generally tokens are expected to be colored based on the top level scopes (such as `keyword`), with the more specified scopes being used mostly for readability and allowing customers the ability to create custom colors for just a subset of keywords if they wish. But since the color themes will generally not include colors for these tokens they will inherit from the top-level scope by default.
12+
13+
You can see the colors used in the default themes for VS Code and Azure Data Studio [here](https://github.com/microsoft/vscode/tree/main/extensions/theme-defaults/themes).
14+
15+
### Where should I add a new keyword?
16+
17+
For general T-SQL keywords the most common place they will go is the huge regex for `keyword.other.sql`. This means that ANY time this keyword shows up outside of certain special circumstances it will be colored as a keyword. This is often "good enough", although you are also free to add your own match section with a more complex regex if you wish.
18+
19+
## Updating the grammar
20+
21+
### VS Code
22+
23+
First we'll update the grammar in VS Code, which is done through updating the grammar directly in this repo. Once a month VS Code will pull in the latest changes into the [grammar file in its repo](https://github.com/microsoft/vscode/blob/main/extensions/sql/syntaxes/sql.tmLanguage.json).
24+
25+
1. Once you've made your changes to the grammar file, build & run this extension locally (see the [wiki](https://github.com/microsoft/vscode-mssql/wiki/testing-and-debugging#debugging-extension-side-code)) to verify that the colors show up as you expect in a new query editor (`MS SQL: New Query` command)
26+
2. Now submit a PR, making sure to include a screenshot of the colors
27+
28+
### Azure Data Studio
29+
30+
1. After the PR in this repo is merged, clone the [Azure Data Studio](https://github.com/Microsoft/azuredatastudio) repo
31+
2. cd to `extensions` and run `yarn install`
32+
3. Run the following commands to regenerate the grammar file
33+
34+
```powershell
35+
cd extensions/sql/build
36+
npm run update-grammar
37+
```
38+
39+
3. Send out a PR with the changes made to any files that were modified, making sure to link to the original PR in this repo where the changes were made
40+
41+
*Note*: You can test Azure Data Studio locally by building and running it and verifying the colors are correct in a new editor window

0 commit comments

Comments
 (0)