CONTRIBUTING.md

Contributing

This is an open source plugin, and your PRs are welcome!

Installing the package

To try this on your own macOS or Linux system, make sure you have Sublime installed. Then fork this repo, download your fork, and symlink it into place. Be sure you change the name of the downloaded repo! This affects the way Sublime displays the syntax, and whether tests will run successfully.

~ $ git clone https://github.com/<YOUR-GITHUB-HANDLE>/just_sublime.git Just
~ $ cd Just
Just $ ln -s $PWD ~/Library/Application\ Support/Sublime\ Text/Packages/Just

Now the package is installed. You don't have to relaunch Sublime, although you will need to re-open any .just files that are already open.

Running tests

Sublime contains a built-in syntax testing system. In fact, it will run whenever code is pushed to GitHub. But before you push any changes, you will want to make sure the tests are running correctly on your local system. To do that, make sure the plugin (with the syntax definition) is installed as above. Then open one of the syntax_test_ files in the tests directory. Then use Cmd+B (Build) to run the tests. Alternatively, open the Command Palette (Cmd+Shift+P) and run the Build With: Syntax Tests command.

This will open the console and show you the result of the tests.

In this case, the test on line 67 is failing both at column 1, and also in columns 25, 26, 28, and 29.

Writing tests

There are several shortcuts which can help speed up writing tests in syntax_test_ files. These are in the PackageDev package.

1. Start a line with a # and then press Tab. Sublime will insert sufficient spaces to get you one beyond the last tested character on the line, then insert the necessary number of carets for a string with a contiguous scope, and then also add all scopes which match the selected string.

tab_key_tests.mp4

2. If you want to quickly skip columns, you can use Shift+Tab to insert 4 spaces as a time. (.sublime-syntax files must use spaces for all indentation.)

3. To reduce the verbosity of the test lines, you can quickly insert ranges of scopes using the ^ key. Press it successively to zoom out to ever larger scopes, although it will only auto-generate scopes forward from the initial caret position. When you add assertions below that one, Sublime will exclude the scopes you've already applied above. This is particularly useful for meta scopes which can span many characters and a number of different concrete scopes.

Documentation and Tools

• Sublime has great documentation:
  • Syntax definitions
  • Scope naming
  • Scope naming guidelines
  • Default syntax definitions are available to view and copy, for example Python and Makefile
• Sublime auto-indenting is covered in the community docs and this extensive Forum post.
• The ScopeHunter package is on PackageControl, and it is essential. With the Instant Scoper, you will get the scope under the cursor as you move around the file.
• This is a good blog post covering Sublime syntax
• There is a really useful thread on GitHub with tips and advice for building Sublime syntax definitions
• Learn about the regex syntax of the Oniguruma regex engine which Sublime's syntax parser uses
• The Sublime Forum has several users who are very knowledgeable and active with syntax questions. Searching the archives can also be a big help.
• Sublime also runs a Discord server with the same very helpful folks on it!