This repository provides a TextMate grammar for Cylc workflow configuration (suite.rc and .cylc) files, enabling syntax highlighting and other features.
cylc.tmLanguage.json is the grammar file used by plugins for editors:
- VSCode - cylc/vscode-cylc
- Atom - cylc/language-cylc
It is also used to build a TextMate bundle at cylc/Cylc.tmLanguage which is compatible with:
- TextMate
- PyCharm
- WebStorm
- Sublime Text 3
If you're using an editor listed above, follow the link next to it for instructions. If not, check cylc/cylc-flow/issues/2752 for support.
Copyright (C) 2008-2024 NIWA & British Crown (Met Office) & Contributors.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Note: the cylc.tmLanguage.json file is generated from the JavaScript file(s) in src/. Contributors should edit the JavaScript files, not the JSON file; the JSON file should only be generated using the build script (using node).
If you are new to TextMate grammars, there are a number of resources to look at:
- TextMate manual - language grammars
- VSCode syntax highlight guide
- Atom flight manual - creating a legacy TextMate grammar
As noted above, instead of editing the cylc.tmLanguage.json file directly (as is done in the VSCode guide, for example) you should edit src/cylc.tmLanguage.js instead.
Each distinct tmLanguage pattern should be represented by a class, whose constructor sets a property called pattern that is an object, e.g.:
class LineComment {
constructor() {
this.pattern = {
name: 'comment.line.cylc',
match: '(#).*',
captures: {
1: {name: 'punctuation.definition.comment.cylc'}
}
};
}
}or a property called patterns that is an array, e.g.:
class GraphSyntax {
constructor() {
this.patterns = [
{include: '#comments'},
new Task().pattern,
{
name: 'keyword.control.trigger.cylc',
match: '=>'
},
// etc.Notice above the inclusion of the class Task's pattern object.
Remember that the regex escape character \ needs to be itself escaped. E.g., for the regex \s you need to write \\s.
The exports.tmLanguage object is where the collection of patterns should go, i.e.:
exports.tmLanguage = {
scopeName: 'source.cylc',
name: 'cylc',
patterns: [
{include: '#comments'},
]
repository: {
comments: {
patterns: [
new LineComment().pattern,
]
},
graphSyntax: {
patterns: [
...new GraphSyntax().patterns,
]
},
// etc.where the spread syntax operator (3 dots) is used to expand the GraphSyntax().patterns array.
To generate the JSON file, you will need NodeJS. After you've made changes to the js grammar file, generate the JSON file using
npm run buildThe compiled result of the examples above would be the following cylc.tmLanguage.json:
{
"scopeName": "source.cylc",
"name": "cylc",
"patterns": [
{"include": "#comments"}
],
"repository": {
"comments": {
"patterns": [
{
"name": "comment.line.cylc",
"match": "(#).*",
"captures": {
"1": {"name": "punctuation.definition.comment.cylc"}
}
}
]
},
"graphSyntax": {
"patterns": [
{"include": "#comments"},
{
"name": "meta.variable.task.cylc",
"match": "\\b\\w[\\w\\+\\-@%]*"
},
{
"name": "keyword.control.trigger.cylc",
"match": "=>"
},
]
}
}
}(Note: if you're unable to run the tests locally, GitHub Actions are set up to automatically run the tests on pull requests.)
If you haven't already installed the development dependencies, run
npm install
To run ESLint for style testing JavaScript files:
npm run lint
We're using vscode-tmgrammar-test for testing the textmate grammar. Test files reside in the /tests directory. These are essentially Cylc workflow files that are annotated with comments. The comments detail what the expected scopes of the test line are. The comments are read in by vscode-tmgrammar-test and compared to the actual applied scopes. An example test might be:
foo = bar
# ^^^ variable.other.key.cylc
# ^ keyword.operator.assignment.cylc
# ^^^ meta.value.cylc string.unquoted.value.cylc
# ^^^^^^^^^ meta.setting.cylcFor docs, follow the link to vscode-tmgrammar-test above.
To run the unit tests:
npm test