Developing Guard Output Theme

Developing the Guard Output Theme can be a bit annoying if you are trying to do it manually just by editing the GuardOutput.tmLanguage and GuardOutput.tmTheme XML files. The easiest way to develop the Guard Output Theme is to use TextMate as Sublime Text 2 uses the same tmLanguage and tmTheme formats as TextMate. TextMate is a bit nicer because it provides the Bundle editor which lets you easily edit and test the tmLanguage and tmTheme files. Details of how to do this are provided below.

1. Push the GuardOutput.tmLanguage and GuardOutput.tmTheme files to TextMate as a bundle so you can dev/test it inside TextMate. I have provided a script in the repository to make this easier. To do this simply run the following:

$ ./dev_tools/push_theme_to_textmate.sh

Be careful. The above will overwrite in changes you have made to the Guard Output theme inside TextMate if you previously ran this and made some changes.

After pushing the source tree version of the GuardOutput theme to TextMate you should tell TextMate to reload the bundles. This is done by going to Bundles -> Bundle Editor -> Reload Bundles.

2. Tell TextMate to use the GuardOutput theme. This is simply done by going to TextMate -> Preferences -> Fonts & Colors and selecting GuardOutput from the drop-down. This simply tells TextMate to use the colors that are defined in the GuardOutput.tmTheme file for the various language components that are matched in the GuardOutput.tmLanguage file.

3. Once you have TextMate using the GuardOutput theme you can open dev_tools/guard_rspec_output_example.txt file and make sure that the Language at the bottom of the window is set to GuardOutput. At this point you should see the example output and it should be appropriately colored as the GuardOutput theme defines.

4. At this point you are ready to edit the GuardOutput language via the TextMate Bundle Editor. This can be done by going to Bundles -> Bundle Editor -> Show Bundle Editor. This will bring up a window with a listing of the bundles on the left. Expand the sublime_guard bundle in the left tree and you should see the GuardOutput language item. Select it, and the editor will open on the right for it.

You can probably determine at this point that it is really definition file defining language structures using regular expressions and mapping those to the theme identifiers. For more details on defining Language Grammars check out the TextMate documentation here. Once you take it in a bit you will probably have an example case where you know that the theme is not coloring some output correctly. If you add that example output to the dev_tools/guard_rspec_output_example.txt file you should see that it is not correctly coloring the output there as well.

Once you see it incorrectly coloring the output you are ready to modify the the regular expressions to match the case you are wanting to fix correctly.

5. Once you have made the necessary changes and are ready to copy the changes back to your source tree from TextMate you can do so by using the following script:

$ ./dev_tools/pull_theme_from_textmate.sh

Then as usual you would make a pull request as you would with any code contribution.