Understanding Whitespace in the ClearHead Ecosystem
For some languages, whitespace is syntactically significant. Python uses indentation to define code blocks, and YAML relies on spacing to denote structure. However, in the ClearHead ecosystem, whitespace is intentionally designed to be syntactically insignificant. This means that the presence or absence of spaces, tabs, or newlines does not affect the meaning of the code or data.
If one reviews the File Format specification, it becomes clear that explicit markers are used to define structure and meaning. This design choice simplifies parsing significantly, as parsers do not need to account for varying whitespace patterns.
This also means the specification if relatively liberal about what it will allow in the various structures such that its fine for an action to have a newline character in the middle of it
Another way to think about it is in phases, with the file format parsing phase being distinct from the formatting/linting phase, which itself is separate from the process phase.
Leveraging Parse Trees
While whitespace is not semantically significant, it IS important for human readability and we dont want to have people tinkering around with whitespace all day to make their perfect file.
To this end, formatters can leverage the parse tree generated during the parsing phase to apply consistent formatting rules. By operating on the parse tree, formatters can ensure that the structure of the code remains intact while applying desired formatting styles.
This works in tandem with linters which can provide feedback on non-whitespace style issues without being concerned about whitespace itself such as the order in which metadata appears or which metadata is available when