|
1 | 1 | # IDE support for RTL |
2 | 2 |
|
3 | | -This directory ships editor tooling for RTL (Regular Table Language): |
| 3 | +Editor tooling for RTL (Regular Table Language) — the VS Code extension, the |
| 4 | +TextMate grammars for `.rtl` files, and the injection grammars that highlight |
| 5 | +RTL inside Python and Java string literals — lives in its own repository: |
4 | 6 |
|
5 | | -- a TextMate grammar for `.rtl` files (`vscode/syntaxes/rtl.tmLanguage.json`), |
6 | | -- an injection grammar that highlights RTL inside Python string literals |
7 | | - (`vscode/syntaxes/rtl-python-injection.tmLanguage.json`), |
8 | | -- a VS Code extension manifest wiring both together (`vscode/`). |
| 7 | +**https://github.com/regtab/vscode-rtl** |
9 | 8 |
|
10 | | -The same `vscode/` directory doubles as a TextMate bundle for IntelliJ-based IDEs |
11 | | -(PyCharm and friends). |
| 9 | +The extension is universal: it serves every RegTab implementation (jRegTab, |
| 10 | +pyRegTab, future ports) and requires neither Python nor a JDK. |
12 | 11 |
|
13 | | -## VS Code |
| 12 | +- **VS Code**: install “RegTab RTL” from the |
| 13 | + VS Code Marketplace or Open VSX (extension id `regtab.rtl`). |
| 14 | +- **PyCharm / IntelliJ IDEA**: register the extension directory as a TextMate |
| 15 | + bundle (*Settings → Editor → TextMate Bundles*) — see the vscode-rtl README. |
14 | 16 |
|
15 | | -Copy (or symlink) the extension into your local extensions directory and reload: |
16 | | - |
17 | | -``` |
18 | | -# Windows |
19 | | -xcopy /E /I ide\vscode %USERPROFILE%\.vscode\extensions\regtab.rtl-language-0.1.0 |
20 | | -
|
21 | | -# Linux / macOS |
22 | | -cp -r ide/vscode ~/.vscode/extensions/regtab.rtl-language-0.1.0 |
23 | | -``` |
24 | | - |
25 | | -Alternatively, package it properly with [vsce](https://github.com/microsoft/vscode-vsce): |
26 | | -`cd ide/vscode && npx @vscode/vsce package`, then install the produced `.vsix` via |
27 | | -*Extensions → … → Install from VSIX*. |
28 | | - |
29 | | -You get: |
30 | | - |
31 | | -- syntax highlighting for `*.rtl` files; |
32 | | -- highlighting of RTL inside Python strings for these forms: |
33 | | - - `RtlCompiler.compile("""…""")` / `RtlCompiler.compile('''…''')`, |
34 | | - - `RtlCompiler.compile("…")` / `RtlCompiler.compile('…')` (optionally raw: |
35 | | - `r"…"`). |
36 | | - |
37 | | -Limitation (inherent to TextMate): the opening quote must be on the same line as |
38 | | -`RtlCompiler.compile(`. |
39 | | - |
40 | | -## PyCharm / IntelliJ IDEA |
41 | | - |
42 | | -1. *Settings → Editor → TextMate Bundles → “+”* and select the `ide/vscode` directory. |
43 | | -2. `*.rtl` files are now highlighted. |
| 17 | +## Keeping the grammar in sync |
44 | 18 |
|
45 | | -For RTL inside Python string literals, PyCharm's built-in language injection also |
46 | | -recognizes the line-comment marker `# language=RTL` placed on the statement — when the |
47 | | -IDE knows the RTL language (registered TextMate bundle or a dedicated plugin), it injects |
48 | | -RTL into the following literal. Support for injecting TextMate-backed languages varies by |
49 | | -IDE version; where unavailable, you still get `.rtl` file highlighting. |
| 19 | +vscode-rtl is the canonical home of the RTL TextMate grammars. Any change to |
| 20 | +the normative grammar `grammar/RTL.g4` (pinned from jRegTab) must be |
| 21 | +accompanied by an issue/PR in vscode-rtl updating `rtl.tmLanguage.json`; |
| 22 | +its CI runs a keyword-coverage sync-check against the pinned `RTL.g4`. |
50 | 23 |
|
51 | 24 | ## Runtime validation |
52 | 25 |
|
53 | 26 | Python has no compile-time annotation processor (the jRegTab counterpart is |
54 | | -`@RtlSource` + a `javac` processor). In pyRegTab, an invalid RTL string is reported at |
55 | | -call time: `RtlCompiler.compile(...)` raises `RtlCompileError` with the source position |
56 | | -(`line:col`), the expected tokens, and a fragment of the offending input. |
57 | | - |
58 | | -## Keeping the grammar in sync |
59 | | - |
60 | | -The TextMate grammar mirrors the tokens of the normative grammar `grammar/RTL.g4` |
61 | | -(pinned from jRegTab). Any change to `RTL.g4` must be accompanied by a matching update to |
62 | | -`vscode/syntaxes/rtl.tmLanguage.json` in the same PR. The `.rtl` grammar |
63 | | -(`rtl.tmLanguage.json`) and the editor configuration (`language-configuration.json`) are |
64 | | -copied verbatim from jRegTab; only the injection grammar and manifest differ (Python |
65 | | -instead of Java host language). |
| 27 | +`@RtlSource` + a `javac` processor). In pyRegTab, an invalid RTL string is |
| 28 | +reported at call time: `RtlCompiler.compile(...)` raises `RtlCompileError` with |
| 29 | +the source position (`line:col`), the expected tokens, and a fragment of the |
| 30 | +offending input. |
0 commit comments