README.md

bombadil

Copyright Sergio Garcia

A chevrotain based TOML v0.5.0 parser, written in typescript.

Releases

• TOML 0.5: Bombadil 2.3.0
• TOML 0.5: Bombadil 2.0.0
• TOML 0.5: Bombadil 2.0.0-1 (prerelease)
• TOML 0.4: Bombadil 1.0.0 (stable)

Install

npm install @sgarciac/bombadil

Usage

var bombadil = require('@sgarciac/bombadil')
var input = 'whatever = 1'
var reader = new bombadil.TomlReader
reader.readToml(input)
reader.result // -> {whatever: 1}

Errors

If the input is not a valid TOML string, the reader will store undefined in its result property and it will keep the errors in its errors property. Errors can be either:

• Lexer errors: ILexingError
• Parser errors: IRecognitionException
• Table loading errors:

  export interface ITomlException {
  message: string,
  token: ct.IToken
  }

  which uses IToken

Type mapping

By default, the toml reader will map TOML values to javascript values as follows:

• Integers -> Number
• Float -> Number
• String -> String
• Boolean -> Boolean
• Offset Date Time -> Date
• Local Date Time -> Date (using UTC±00:00)
• Local Date -> Date (using UTC±00:00 and time 00:00:00)
• Local Time -> Date (using UTC±00:00 and date 0001-01-01)
• Array -> Array
• Table -> Object

Full typing information

As you can see in the previous example, there is some information loss. If you need the original typing information, you can pass a second parameter to readToml set to true.

This will parse the following TOML:

title = "TOML Example"

[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00Z # First class dates? Why not?

to the following javascript object:

{ type: 'table',
  content:
   { title:
      { type: 'atomicString',
        image: 'TOML Example',
        value: 'TOML Example' },
     owner:
      { type: 'table',
        content:
         { name:
            { type: 'atomicString',
              image: 'Tom Preston-Werner',
              value: 'Tom Preston-Werner' },
           dob:
            { type: 'offsetDateTime',
              image: '1979-05-27T07:32:00Z',
              value: 1979-05-27T07:32:00.000Z } } } } }

Documents are transformed as following:

• Toml's tables (including the root one) and primitive values (string, integer, date, etc) are transformed to javascript objects with a 'type' property that describe their type. For example, tables' type is the string 'table'.
• All Toml's arrays are transformed to javascript arrays
• Toml's tables corresponding javascript objects have a "content" property that contains another javascript object (a dictionary), whose properties are the toml table's keys, and they point to the transformation of the corresponding toml value.
• Toml's primitive values corresponding javascript objects include their toml image (a string), and also the corresponding javascript primitive value.

Keeping the original string image of the value can be helpful, for example when dealing with big integers, which can not be handled by the javascript Number type.

Known problems

Chevrotain is known to rely on function names, which means that minification (such as performed by, for example, Uglify) can break bombadil. There are some solutions to this problem here

Unless you are running the code inside the browser, and using minification, you probably don't need to worry about this.