ION-PARSER

ion-parser is the fastest and lightest Javascript parser for TOML and ION files.

TOML stands for Tom's Obvious and Minimal Language and it is an awesome language for your configuration files, better than JSON and YAML in many aspects. Learn here what is TOML and how to use it (it's definitely worth the ten minutes learning).

ION stands for Intuitive Object Notation. It is a variation of TOML and, compared to TOML, ION eases the creation of arrays and completely removes the need to use commas. Any TOML file is a valid ION file, though the opposite is not true.

See below the differences between TOML and ION.

Usage

First, install ion-parser : npm i ion-parser.

Then, let's suppose we have the following ION / TOML file :

# myFile.ion
title = 'Hey universe'

[soundOptions]
volume = 68
soundName = 'Hey universe'
file = 'sounds/hey-universe.mp3'

We read the file and transform it into a javascript object this way :

const ION = require('ion-parser')
const fs = require('fs')

const data = ION.parse(fs.readFileSync('myFile.ion'))
console.log(data.title)  // 'Hey universe'
console.log(data.soundOptions.volume)  // 68

ION.parseFile

If you want to read from a file, you can directly use the ION.parseFile function :

const ION = require('ion-parser')

// sync (will throw an error in case of bad syntax or bad file reading)
const data = ION.parseFile('myFile.ion')
console.log(data)

// async
ION.parseFile('myFile.ion', (err, data) => {
  console.log(err || data)
})

Javascript template strings

You also can use the parser with Javascript template strings :

const ION = require('ion-parser')
const data = ION `
  title = 'Hey universe'

  [soundOptions]
  volume = 68
  soundName = 'Hey universe'
  file = 'sounds/hey-universe.mp3'
`
console.log(data.title)  // 'Hey universe'
console.log(data.soundOptions.volume)  // 68

Using in browser

You can download the browser version of ion-parser here.

Just add the file to your project and require it with a script tag.

Differences between ION and TOML

There are not so many differences between ION and TOML. Basically, every TOML file is a valid ION file. Still, ION improves TOML on the following points :

1. Unnecessary commas

Adding commas before every end of line is not always pleasant and not necessary for neither a computer nor a human to understand the code. What must be written this way in TOML :

# TOML
point = {
  x = 12,
  y = 152
}
colors = [
  'red',
  'green',
  'pink',
]

can be written this way with ION files :

# ION
point = {
  x = 12
  y = 152
}
colors = [
  'red'
  'green'
  'pink'
]

# This is the same as :
colors = [
  'red', 'green'
  'pink'
]

2. Intelligent array creation

There is another way to create array with ION files. Let's use our previous exemple :

# TOML
colors = [
  'red',
  'green',
  'pink',
]

# ION
[colors]
'red'
'green'
'pink'

Any value without a key will be considered as an array's element.

3. String values with no quotation marks

A human know what is a number and what is not. Obviously. And so does ion-parser.

Using quotation marks is not necessary with .ion files, although it is always a good practice and should be used in any case of ambiguity.

This is valid :

# ION
title = Hey universe 

[colors]
red
green
pink

Comparison with other parsers

I want to parse TOML files. Why should I use ion-parser?

Here is the comparison between ion-parser and the other 0.5.0-compliant TOML parsers for Javascript :

• Iarna's Toml
• LongTengDao's Toml
• Bombadil (wich use the Chevrotain Parser Building Toolkit)

	ion-parser	Iarna's toml	LongTengDao's j-toml	Bombadil
Require	2.375	14.720	5.969	196.741
First round	9.489	13.911	12.267	69.970
One-use (require+first round)	11.864	28.631	18.236	266.711
Warm round	1.483	7.275	1.420	34.878
Hot round	0.501	0.604	0.627	6.639
Package size (Including other modules, readme, sourcemaps, ...)	20.9 Ko	93.1 Ko	261 Ko	+3000 Ko

(All time values are milliseconds)

The comparison has been made in a Node 11.2.0 environment with this medium-size sample TOML file, which covers about all the different ways to use TOML.

The comparison has been made in three rounds because of the way Javascript works :

• For the first round, the Javascript engine has done no compilation yet. The functions are directly interpreted when evaluated.
• After a fisrt round, the Javascript engine will do some light compilation called warming. That's why the second call is faster than the first.
• If a function is called many times, the Javascript engine will do hot compilation optimisations so that the function runs super-fast.

Bombadil is so big and slow compared to others parsers because it uses a third-party library (Chevrotain).

ion-parser is also robust. Errors are prettily handled, giving you informations about any bad syntax.