Skip to content
A Coffescript Object Notation (CSON) parser for Python 2 and Python 3.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
cson Support uppercase E in floats Jan 22, 2019
test Support uppercase E in floats Jan 22, 2019
.gitignore Support wheels Jan 22, 2019
.travis.yml Drop official support for Python 3.4 Jan 22, 2019
LICENSE initial commit Sep 15, 2015 Correct some typographical errors. Apr 16, 2019 Fix Markdown linting issues Aug 18, 2018
setup.cfg Support wheels Jan 22, 2019 Bump version to 0.8 Jan 22, 2019
tox.ini Drop official support for Python 3.4 Jan 22, 2019


Build Status

A python parser for the Coffeescript Object Notation (CSON).


The parser is tested on Python 2.7 and 3.5.

pip install cson

The interface is the same as for the standard json package.

>>> import cson
>>> cson.loads('a: 1')
{'a': 1}
>>> with open('file.cson', 'rb') as fin:
...     obj = cson.load(fin)
>>> obj
{'a': 1}

The language

There is not formal definition of CSON, only an informal note in one project's readme. Informally, CSON is a JSON, but with a Coffeescript syntax. Sadly Coffescript has no formal grammar either; it instead has a canonical implementation.

This means that bugs in the implementation translate into bugs in the language itself.

Worse, this particular implementation inserts a "rewriter" between the typical lexer/parser pair, purporting that it makes the grammar simpler. Unfortunately, it adds weird corner cases to the language.

This parser does away with the corner cases, in exchange for changing the semantics of documents in a few unlikely circumstances. In other words, some documents may be parsed differently by the Coffescript parser and pycson.

Here are some important highlights (see the formal grammar for details).

  • String interpolations ("#{test}") are allowed, but are treated literally.
  • Whitespace is ignored in arrays and in objects enclosed in braces (CoffeeScript requires consistent indentation).
  • Unbraced objects greedily consume as many key/value pairs as they can.
  • All lines in an unbraced object must have the same indentation. This is the only place where whitespace is significant. There are no special provisions for partial dedents. For two lines to have the same indent, their maximal sequences of leading spaces and tabs must be the same (CoffeScript only tracks the number of whitespace characters).
  • Unbraced objects that don't start on their own line will never span multiple lines.
  • Commas at the end of the line can always be removed without changing the output.

I believe the above rules make the parse unambiguous.

This example demonstrates the effect of indentation.

# An array containing a single element: an object with three keys.
  a: 1
  b: 2
  c: 3

# An array containing three elements: objects with one key.
  a: 1
   b: 2
  c: 3

# An array containing two objects, the first of which having one key.
[ a: 1
  b: 2
  c: 3 ]

Note that pycson can parse all JSON documents correctly (CoffeeScript can't because of whitespace and string interpolations).

You can’t perform that action at this time.