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 on 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 90% inspired by TOML and, compared to TOML, facilitate the creation of arrays and completely remove the need to use commas. Any TOML file is a valid ION file, although 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.toml
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.toml'))
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.toml')
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. You can then use the globally defined ION object.

Speed and size comparison with other parsers

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)

(All time values are milliseconds)

| | 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 |

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) - even though Chevrotain is describing itself as 'blazing fast'.

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

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