cson-parser

What is cson-parser?

The cson-parser npm package is a parser for CSON (CoffeeScript-Object-Notation), which is a variant of JSON that allows for more human-readable syntax. It is useful for converting between CSON and JSON formats, making it easier to work with configuration files and data structures in a more readable format.

What are cson-parser's main functionalities?

Parsing CSON to JSON

This feature allows you to parse a CSON string and convert it into a JSON object. This is useful for reading configuration files or other data stored in CSON format.

const cson = require('cson-parser');
const csonString = 'key: "value"';
const jsonObject = cson.parse(csonString);
console.log(jsonObject); // { key: 'value' }

Stringifying JSON to CSON

This feature allows you to convert a JSON object into a CSON string. This is useful for writing data to a file in a more human-readable format.

const cson = require('cson-parser');
const jsonObject = { key: 'value' };
const csonString = cson.stringify(jsonObject);
console.log(csonString); // 'key: "value"'

Handling Errors

This feature demonstrates how to handle errors when parsing CSON. If the CSON string is invalid, an error will be thrown, which can be caught and handled appropriately.

const cson = require('cson-parser');
try {
  const invalidCsonString = 'key: value';
  const jsonObject = cson.parse(invalidCsonString);
} catch (error) {
  console.error('Error parsing CSON:', error.message);
}

Other packages similar to cson-parser

yaml

The yaml package is used for parsing and stringifying YAML, another human-readable data serialization format. YAML is more widely used and supported compared to CSON, and the yaml package offers robust features for working with YAML data.

toml

The toml package is used for parsing and stringifying TOML (Tom's Obvious, Minimal Language), which is designed to be a minimal and easy-to-read configuration file format. TOML is similar to CSON in its goal of human readability but has a different syntax and structure.

json5

The json5 package allows for parsing and stringifying JSON5, an extension of JSON that aims to be more user-friendly by allowing comments, trailing commas, and more. JSON5 is similar to CSON in that it aims to improve the readability and usability of JSON.

README

cson-parser

A minimalistic CSON parser. Offers:

• A strict subset of CSON that allows only data
• Interface is identical to JSON.{parse,stringify}
• Does not run the code, free of intermediate string representations
• Sane parse error messages with line/column
• Regular Expressions are considered data and will be accepted as well

In addition of pure data it allows for simple arithmetic expressions like addition and multiplication. This allows more readable configuration of numbers, the following is a valid strict CSON file:

cachedData:
  refreshIntervalMs: 5 * 60 * 1000

Install

npm install --save cson-parser

Usage

CSON = require 'cson-parser'
# This will print { a: '123' }
console.log CSON.parse "a: '123'"

High-level APIs

cson-parser only offers basic parsing and serialization. But there are some great tools if you want more than that:

• fs-cson, read and write CSON files
• CSON, provides file, coffeescript, javascript handling and a CLI
• season, atom.io's CSON package. Includes CLI tool to convert CSON to JSON
• grunt-cson, converts CSON to JSON as a grunt task
• load-grunt-configs, loads grunt config from CSON files (among other formats)
• fetcher, a declarative way to download (frontend) libraries, supports CSON configs
• csonschema, parses JSON Schema files written in CSON

You can find more on the npm website.

FAQ

Why not just use YAML?

YAML allows for some pretty complex constructs like anchor and alias, which can behave in unexpected ways, especially with nested objects. CSON is simpler while still offering most of the niceties of YAML.

Why not just use JSON?

JSON doesn't offer multi-line strings and is generally a little noisier. Also sometimes it can be nice to have comments in config files.

Why not just use CoffeeScript directly?

You don't want data files being able to run arbitrary code. Even when ran in a proper sandbox, while(true) is still possible.

Changelog

1.3.4

• Compatible with coffee-script 1.11.0 - @jkrems #57
  • ed54c9a fix: Compatible with coffee-script 1.11.0 - see: #56