Other

Using YAML

Important

The current version of the tool accepts YAML 1.1 parsed by PyYAML. See YAML Specification Changes.

When using YAML it is recommended, when possible, to use either plain style or block-scalars to write regex and code blocks. This is because their contents are interpreted literally and so there is no need to escape values (particularly useful for regex). Writing code with block-scalars provides an experience most similar to a text editor.

Example:

example1: This is an example of plain style
example2: |
  This is an example
  of a block-scalar

However, it is important to know when plain style specifically is not appropriate. In particular, this is the case when values clash with the syntax of YAML. An example of this could be writing a regex or code block using [ ... ], which would be interpreted as a YAML array.

Example:

tokens:
  [: \[ # incorrect
  '[': '\[' # correct

code:
  list: [...] # incorrect: YAML array
  list: '[...]' # correct: Python code
  list: | # correct: Python code using YAML block-scalar
    [...]

Tip

It is recommended to write YAML with a good syntax highlighter as this will give a visual prompt when values may be misinterpreted.

It is possible to write languages with JSON as YAML is a strict superset. However, this is not recommended as it would be far less readable and make writing regex much harder.

Notation

• Along with informal naming, JSONPath notation has been used when referencing Language Configuration properties in this documentation and exclusively when used in the tool.