doc/assets.md · bat · git.iko.soy

git.iko.soy/bat

bat/doc/assets.md

100 lines 6.2 kB history raw

1## Adding new builtin languages for syntax highlighting

3Should you find that a particular syntax is not available within `bat` and think it should be included in `bat` by default, you can follow the instructions outlined below.

5`bat` uses the excellent [syntect](https://github.com/trishume/syntect) library to highlight source

6code. As a basis, syntect uses [Sublime Text](https://www.sublimetext.com/) syntax definitions

7in the `.sublime-syntax` format.

9**Important:** Before proceeding, verify that the syntax you wish to add meets the [criteria for inclusion](#Criteria-for-inclusion-of-new-syntaxes).

111. Find a Sublime Text syntax for the given language, preferably in a separate Git repository

12 which can be included as a submodule (under `assets/syntaxes`) using

13 `git submodule add <https github link> ./assets/syntaxes/02_Extra/<repo name>`, replacing

14 the contents of the angle brackets as appropriate.

162. If the Sublime Text syntax is only available as a `.tmLanguage` file, open the file in

17 Sublime Text and convert it to a `.sublime-syntax` file via *Tools* -> *Developer* ->

18 *New Syntax from XXX.tmLanguage...*. Save the new file in the `assets/syntaxes` folder.

203. Run the `assets/create.sh` script. It calls `bat cache --build` to parse all available

21 `.sublime-syntax` files and serialize them to a `syntaxes.bin` file.

234. Re-compile `bat`. At compilation time, the `syntaxes.bin` file will be stored inside the

24 `bat` binary.

265. Use `bat --list-languages` to check if the new languages are available.

286. Add a syntax test for the new language. See [below](#Syntax-tests) for details.

307. If you send a pull request with your changes, please do *not* include the changed `syntaxes.bin`

31 file. A new binary cache file will be created once before every new release of `bat`. This

32 avoids bloating the repository size unnecessarily.

34### Syntax tests

36`bat` has a set of syntax highlighting regression tests in `tests/syntax-tests`. The main idea is

37make sure that we do not run into issues we had in the past where either (1) syntax highlighting

38for some language is suddenly not working anymore or (2) `bat` suddenly crashes for some input (due

39to `regex` incompatibilities between `syntect` and Sublime Text).

41In order to add a new test file, please follow these steps (let's take "Ruby" as an example):

431. Make sure that you are running the **latest version of `bat`** and that `bat` is available on

44 the path. If you are creating a syntax test for a new builtin syntax (see above), make sure that

45 your version of `bat` already has the new syntax builtin.

462. Find an example Ruby source file or write one yourself. If possible, the file should aim to be

47 "comprehensive" (i.e. include a lot of the possible syntax), but this is not strictly necessary.

48 A simple file is better than none at all. Also, the files shouldn't be gigantic.

493. Save the file in `tests/syntax-tests/source/Ruby` (adapt for your language). The file name could

50 be `test.rb` (adapt extension) but can also be adapted if that is necessary in order for `bat` to

51 highlight it correctly (e.g. `Makefile`).

524. If you have copied the file from somewhere else, please make sure that the file *may* be copied

53 under the respective license and that the license is compatible with `bat`s license. If it

54 requires attribution, please add a `LICENSE.md` in the same folder with a text like this:

55 ```

56 The `test.rb` file has been added from [enter source here] under the following license:

58 [add license text here]

59 ```

605. Go to `tests/syntax-tests` and run the `update.sh` Bash script. A new file should be generated

61 in the `highlighted` folder (e.g. `highlighted/Ruby/test.rb`).

626. Use `cat` or `bat --language=txt` to display the content of this file and make sure that the

63 syntax highlighting looks correct.

647. `git add` the new files in the `source` folder as well as the autogenerated files in the

65 `highlighted` folder.

67### Troubleshooting

69Make sure that the local cache does not interfere with the internally stored syntaxes and

70themes (`bat cache --clear`).

72## Criteria for inclusion of new syntaxes

74* More than 10,000 downloads at [Package Control](https://packagecontrol.io)

76### Manual modifications

78The following files have been manually modified after converting from a `.tmLanguage` file:

80* `Apache.sublime_syntax`=> removed `.conf` and `.CONF` file types.

81* `Dart.sublime-syntax` => removed `#regex.dart` include.

82* `INI.sublime-syntax` => added `.hgrc`, `hgrc`, and `desktop` file types and support for comments after section headers

83* `Org mode.sublime-syntax` => removed `task` file type.

84* `SML.sublime_syntax` => removed `ml` file type.

85* `Robot.sublime_syntax` => changed name to "Robot Framework", added `.resource` extension

87### Non-submodule additions

89* `Assembly (x86_64)` has been manually added from https://github.com/13xforever/x86-assembly-textmate-bundle due to `git clone` recursion problems

90* `Nim.sublime-syntax` has been added manually from https://github.com/getzola/zola/blob/master/sublime_syntaxes/Nim.sublime-syntax as there was no suitable Git repository for it. The original syntax seems to originate from https://github.com/Varriount/NimLime

91* `Rego.sublime-syntax` has been added manually from https://github.com/open-policy-agent/opa/blob/master/misc/syntax/sublime/rego.sublime-syntax

92 as it is not kept in a standalone repository. The file is generated from

93 https://github.com/open-policy-agent/opa/blob/master/misc/syntax/textmate/Rego.tmLanguage

94* `SML.sublime_syntax` has been added manually from

95 https://github.com/seanjames777/SML-Language-Definitiona as it is not

96 kept in a standalone repository. The file generated is from

97 https://github.com/seanjames777/SML-Language-Definition/blob/master/sml.tmLanguage

98* `Cabal.sublime_syntax` has been added manually from

99 https://github.com/SublimeHaskell/SublimeHaskell/ - we don't want to include the whole submodule because it includes other syntaxes ("Haskell improved") as well.

100* `Lean.sublime-syntax` has been added manually from https://github.com/leanprover/vscode-lean/blob/master/syntaxes/lean.json via conversion.