# CSON Status of the GitHub Workflow: bevry NPM version NPM downloads
GitHub Sponsors donate button ThanksDev donate button Patreon donate button Liberapay donate button Buy Me A Coffee donate button Open Collective donate button crypto donate button PayPal donate button
Discord server badge Twitch community badge CoffeeScript-Object-Notation. Same as JSON but for CoffeeScript objects. [Projects using CSON.](https://www.npmjs.org/browse/depended/cson) [Projects using CSON Parser directly.](https://www.npmjs.org/browse/depended/cson-parser) Since v2, this CSON package is a higher-level wrapper around the lower-level [CSON Parser](https://www.npmjs.com/package/cson-parser). ## What is CSON? Everyone knows JSON, it's the thing that looks like this: ``` javascript { "greatDocumentaries": [ "earthlings.com", "forksoverknives.com", "cowspiracy.com" ], "importantFacts": { "emissions": "Livestock and their byproducts account for at least 32,000 million tons of carbon dioxide (CO2) per year, or 51% of all worldwide greenhouse gas emissions.\nGoodland, R Anhang, J. “Livestock and Climate Change: What if the key actors in climate change were pigs, chickens and cows?”\nWorldWatch, November/December 2009. Worldwatch Institute, Washington, DC, USA. Pp. 10–19.\nhttp://www.worldwatch.org/node/6294", "landuse": "Livestock covers 45% of the earth’s total land.\nThornton, Phillip, Mario Herrero, and Polly Ericksen. “Livestock and Climate Change.” Livestock Exchange, no. 3 (2011).\nhttps://cgspace.cgiar.org/bitstream/handle/10568/10601/IssueBrief3.pdf", "burger": "One hamburger requires 660 gallons of water to produce – the equivalent of 2 months’ worth of showers.\nCatanese, Christina. “Virtual Water, Real Impacts.” Greenversations: Official Blog of the U.S. EPA. 2012.\nhttp://blog.epa.gov/healthywaters/2012/03/virtual-water-real-impacts-world-water-day-2012/\n“50 Ways to Save Your River.” Friends of the River.\nhttp://www.friendsoftheriver.org/site/PageServer?pagename=50ways", "milk": "1,000 gallons of water are required to produce 1 gallon of milk.\n“Water trivia facts.” United States Environmental Protection Agency.\nhttp://water.epa.gov/learn/kids/drinkingwater/water_trivia_facts.cfm#_edn11", "more": "http://cowspiracy.com/facts" } } ``` Now let's write the same thing in CSON: ``` coffeescript # Comments!!! # An Array with no commas! greatDocumentaries: [ 'earthlings.com' 'forksoverknives.com' 'cowspiracy.com' ] # An Object without braces! importantFacts: # Multi-Line Strings! Without Quote Escaping! emissions: ''' Livestock and their byproducts account for at least 32,000 million tons of carbon dioxide (CO2) per year, or 51% of all worldwide greenhouse gas emissions. Goodland, R Anhang, J. “Livestock and Climate Change: What if the key actors in climate change were pigs, chickens and cows?” WorldWatch, November/December 2009. Worldwatch Institute, Washington, DC, USA. Pp. 10–19. http://www.worldwatch.org/node/6294 ''' landuse: ''' Livestock covers 45% of the earth’s total land. Thornton, Phillip, Mario Herrero, and Polly Ericksen. “Livestock and Climate Change.” Livestock Exchange, no. 3 (2011). https://cgspace.cgiar.org/bitstream/handle/10568/10601/IssueBrief3.pdf ''' burger: ''' One hamburger requires 660 gallons of water to produce – the equivalent of 2 months’ worth of showers. Catanese, Christina. “Virtual Water, Real Impacts.” Greenversations: Official Blog of the U.S. EPA. 2012. http://blog.epa.gov/healthywaters/2012/03/virtual-water-real-impacts-world-water-day-2012/ “50 Ways to Save Your River.” Friends of the River. http://www.friendsoftheriver.org/site/PageServer?pagename=50ways ''' milk: ''' 1,000 gallons of water are required to produce 1 gallon of milk. “Water trivia facts.” United States Environmental Protection Agency. http://water.epa.gov/learn/kids/drinkingwater/water_trivia_facts.cfm#_edn11 ''' more: 'http://cowspiracy.com/facts' ``` Which is far more lenient than JSON, way nicer to write and read, no need to quote and escape everything, has comments and readable multi-line strings, and won't fail if you forget a comma. ## Using CSON ### Via the Command Line Use CSON with the command line with: ``` bash # Convert a JSON file into a CSON file json2cson in.json > out.cson # Same thing via piping cat in.json | json2cson > out.cson # Convert a CSON file into a JSON file cson2json in.cson > out.json # Same thing via piping cat in.cson | cson2json > out.json ``` Requires a global CSON install: `npm install -g cson` ### Via the API Include CSON: ``` javascript var CSON = require('cson') ``` Each method can be executed without a callback like so: ``` javascript var result = CSON.createCSONString({a:{b:'c'}}, {/* optional options argument */}) if ( result instanceof Error ) { console.log(result.stack) } else { console.log(result) } ``` Or via a callback like so: ``` javascript CSON.createCSONString({a:{b:'c'}}, {/* optional options argument */}, function(err,result){ console.log(err, result) }) ``` Executing the method with a callback still executes the method synchronously. Click the below function names to open more detailed documentation. #### Create Strings - String CSON.stringify(data, replacer?, indent?)
Converts an Object into a CSON String - String CSON.createCSONString(data, opts?, next?)
Converts an Object into a CSON String - String CSON.createJSONString(data, opts?, next?)
Converts an Object into a JSON String - String CSON.createString(data, opts?, next?)
Converts an Object into a String of the desired format If the format option is not specified, we default to CSON ### Parse Strings - Object CSON.parse(data, opts?, next?)
Parses a CSON String into an Object - Object CSON.parseCSONString(data, opts?, next?)
Parses a CSON String into an Object - Object CSON.parseJSONString(data, opts?, next?)
Parses a JSON String into an Object - Object CSON.parseCSString(data, opts?, next?)
Parses a CoffeeScript String into an Object - Object CSON.parseJSString(data, opts?, next?)
Parses a JavaScript String into an Object - Object CSON.parseString(data, opts?, next?)
Converts a String of the desired format into an Object If the format option is not specified, we default to CSON #### Parse Files - Object CSON.load(filePath, opts?, next?)
Parses a CSON file into an Object - Object CSON.parseCSONFile(filePath, opts?, next?)
Parses a CSON file into an Object - Object CSON.parseJSONFile(filePath, opts?, next?)
Parses a JSON file into an Object - Object CSON.parseCSFile(filePath, opts?, next?)
Parses a CoffeeScript file into an Object - Object CSON.parseJSFile(filePath, opts?, next?)
Parses a JavaScript file into an Object - Object CSON.parseFile(filePath, opts?, next?)
Parses a file path of the desired format into an Object If the format option is not specified, we use the filename to detect what it should be, otherwise we default to CSON ### Require Files - Object CSON.requireCSFile(filePath, opts?, next?)
Requires a CoffeeScript file and returns the result Object - Object CSON.requireJSFile(filePath, opts?, next?)
Requires a JavaScript file and returns the result Object - Object CSON.requireFile(filePath, opts?, next?)
Requires or parses a file path of the desired format into an Object If the format option is not specified, we use the filename to detect what it should be, otherwise we default to parsing CSON ## Install ### [npm](https://npmjs.com "npm is a package manager for javascript") #### Install Globally - Install: `npm install --global cson` - Executables: `cson`, `cson2json`, `json2cson` #### Install Locally - Install: `npm install --save cson` - Executables: `npx cson`, `npx cson2json`, `npx json2cson` - Import: `import * as pkg from ('cson')` - Require: `const pkg = require('cson')` ### [Editions](https://editions.bevry.me "Editions are the best way to produce and consume packages you care about.") This package is published with the following editions: - `cson/source/index.coffee` is [CoffeeScript](https://coffeescript.org "CoffeeScript is a little language that compiles into JavaScript") source code with [Require](https://nodejs.org/dist/latest-v5.x/docs/api/modules.html "Node/CJS Modules") for modules - `cson` aliases `cson/edition-esnext/index.js` - `cson/edition-esnext/index.js` is [CoffeeScript](https://coffeescript.org "CoffeeScript is a little language that compiles into JavaScript") compiled for [Node.js](https://nodejs.org "Node.js is a JavaScript runtime built on Chrome's V8 JavaScript engine") 6 || 8 || 10 || 12 || 14 || 16 || 18 || 20 || 21 with [Require](https://nodejs.org/dist/latest-v5.x/docs/api/modules.html "Node/CJS Modules") for modules ## History [Discover the release history by heading on over to the `HISTORY.md` file.](https://github.com/bevry/cson/blob/HEAD/HISTORY.md#files) ## Backers ### Code [Discover how to contribute via the `CONTRIBUTING.md` file.](https://github.com/bevry/cson/blob/HEAD/CONTRIBUTING.md#files) #### Authors - [Benjamin Lupton](https://balupton.com) — Accelerating collaborative wisdom. #### Maintainers - [Benjamin Lupton](https://balupton.com) — Accelerating collaborative wisdom. #### Contributors - [Attila Oláh](https://github.com/attilaolah) — [view contributions](https://github.com/bevry/cson/commits?author=attilaolah "View the GitHub contributions of Attila Oláh on repository bevry/cson") - [Attila Oláh](https://attilaolah.eu) - [Benjamin Lupton](https://github.com/balupton) — [view contributions](https://github.com/bevry/cson/commits?author=balupton "View the GitHub contributions of Benjamin Lupton on repository bevry/cson") - [Claudius Nicolae](https://github.com/clyfe) — [view contributions](https://github.com/bevry/cson/commits?author=clyfe "View the GitHub contributions of Claudius Nicolae on repository bevry/cson") - [evinugur](https://github.com/evinugur) — [view contributions](https://github.com/bevry/cson/commits?author=evinugur "View the GitHub contributions of evinugur on repository bevry/cson") - [Jason Karns](https://github.com/jasonkarns) — [view contributions](https://github.com/bevry/cson/commits?author=jasonkarns "View the GitHub contributions of Jason Karns on repository bevry/cson") - [Joël Perras](https://github.com/jperras) — [view contributions](https://github.com/bevry/cson/commits?author=jperras "View the GitHub contributions of Joël Perras on repository bevry/cson") - [Linus G Thiel](https://github.com/linus) — [view contributions](https://github.com/bevry/cson/commits?author=linus "View the GitHub contributions of Linus G Thiel on repository bevry/cson") - [Rob Loach](https://github.com/RobLoach) — [view contributions](https://github.com/bevry/cson/commits?author=RobLoach "View the GitHub contributions of Rob Loach on repository bevry/cson") - [Ryan LeFevre](https://github.com/meltingice) — [view contributions](https://github.com/bevry/cson/commits?author=meltingice "View the GitHub contributions of Ryan LeFevre on repository bevry/cson") - [Tushar Kant](https://github.com/nanuclickity) — [view contributions](https://github.com/bevry/cson/commits?author=nanuclickity "View the GitHub contributions of Tushar Kant on repository bevry/cson") - [Zearin](https://github.com/Zearin) — [view contributions](https://github.com/bevry/cson/commits?author=Zearin "View the GitHub contributions of Zearin on repository bevry/cson") - [ZHANG Cheng](https://github.com/zhangcheng) — [view contributions](https://github.com/bevry/cson/commits?author=zhangcheng "View the GitHub contributions of ZHANG Cheng on repository bevry/cson") ### Finances GitHub Sponsors donate button ThanksDev donate button Patreon donate button Liberapay donate button Buy Me A Coffee donate button Open Collective donate button crypto donate button PayPal donate button #### Sponsors - [Andrew Nesbitt](https://nesbitt.io) — Software engineer and researcher - [Balsa](https://balsa.com) — We're Balsa, and we're building tools for builders. - [Codecov](https://codecov.io) — Empower developers with tools to improve code quality and testing. - [Poonacha Medappa](https://poonachamedappa.com) - [Rob Morris](https://github.com/Rob-Morris) - [Sentry](https://sentry.io) — Real-time crash reporting for your web apps, mobile apps, and games. - [Syntax](https://syntax.fm) — Syntax Podcast #### Donors - [Andrew Nesbitt](https://nesbitt.io) - [Armen Mkrtchian](https://mogoni.dev) - [Balsa](https://balsa.com) - [Chad](https://opencollective.com/chad8) - [Codecov](https://codecov.io) - [dr.dimitru](https://veliovgroup.com) - [Elliott Ditman](https://elliottditman.com) - [entroniq](https://gitlab.com/entroniq) - [GitHub](https://github.com/about) - [Hunter Beast](https://cryptoquick.com) - [Jean-Luc Geering](https://github.com/jlgeering) - [Michael Duane Mooring](https://mdm.cc) - [Michael Harry Scepaniak](https://michaelscepaniak.com) - [Mohammed Shah](https://github.com/smashah) - [Mr. Henry](https://mrhenry.be) - [Nermal](https://arjunaditya.vercel.app) - [Pleo](https://pleo.io) - [Poonacha Medappa](https://poonachamedappa.com) - [Rob Morris](https://github.com/Rob-Morris) - [Robert de Forest](https://github.com/rdeforest) - [Sentry](https://sentry.io) - [ServieJS](https://github.com/serviejs) - [Skunk Team](https://skunk.team) - [Syntax](https://syntax.fm) - [WriterJohnBuck](https://github.com/WriterJohnBuck) ## License Unless stated otherwise all works are: - Copyright © [Benjamin Lupton](https://balupton.com) and licensed under: - [Artistic License 2.0](http://spdx.org/licenses/Artistic-2.0.html)