Configuring with CSON

All of Pulsar’s config files are written in CSON, short for CoffeeScript Object Notation. Just like its namesake JSON, JavaScript Object Notation, CSON is a text format for storing structured data in the form of simple objects made up of key-value pairs.

key:
  key: value
  key: value
  key: [value, value]

Objects are the backbone of any CSON file, and are delineated by indentation (as in the above example). A key’s value can either be a string, a number, an object, a boolean, null, or an array of any of these data types.

Warning

Just like the more common JSON, CSON’s keys can only be used once per object. If there are duplicate keys, then the last usage of that key overwrites all others, as if they weren’t there. The same holds true for Pulsar’s config files.

Don’t do this:

# Only the second snippet will be loaded
'.source.js':
  'console.log':
    'prefix': 'log'
    'body': 'console.log(${1:"crash"});$2'
'.source.js':
  'console.error':
    'prefix': 'error'
    'body': 'console.error(${1:"crash"});$2'

Why? Because it’s equivalent to this JSON:

{
  ".source.js": {
    "console.log": {
      "prefix": "log",
      "body": "console.log(${1:\"crash\"});$2"
    }
  },
  ".source.js": {
    "console.error": {
      "prefix": "error",
      "body": "console.error(${1:\"crash\"});$2"
    }
  }
}

The second .source.js key will overwrite the first!

Do this instead:

# Both snippets will be loaded
'.source.js':
  'console.log':
    'prefix': 'log'
    'body': 'console.log(${1:"crash"});$2'
  'console.error':
    'prefix': 'error'
    'body': 'console.error(${1:"crash"});$2'

Other than its optional delimiters, the main distinguishing feature of CSON is its string flexibility. Whereas JSON keys must always be single quoted, CSON keys can be single- or double-quoted — or even unquoted altogether (in situations where the equivalent key in a JavaScript object would not need quoting). And string values in CSON can be multi-line, as we’ve already seen, simply by using """ or ''' as starting and ending delimiters:

'.source.js':
  'class skeleton':
    'prefix': 'class'
    'body': """
      class ${1:Foo} {
        constructor($2) {
          $0
        }
      }
    """

On multi-line CSON strings, the string starts on the second line, and the leading whitespace on each line is ignored. This makes triple-quoted strings an especially convenient format to use when defining snippets: you can use literal newline characters instead of \n, and neither single nor double quotation marks need to be escaped.