tomlify-j0.4

TOMLify-j0.4

As its name TOMLify-j0.4 says, this is a TOML v0.4.0 compliant encoder. (JavaScript Object -> TOML text)

Live Demo

https://jakwings.github.io/tomlify-j0.4/demo/

You can see the result from tomlify-j0.4 in the debug console of your browser.

The parser used in the demo is toml-j0.4

Usage

You can install it via npm install tomlify-j0.4, or just include the script tomlify.js or dist/tomlify.min.js in your web pages.

var tomlify = require('tomlify-j0.4');

var table = {
    about: {
        name: 'tomlify-j0.4',
        maintainers: ['Jak Wings'],
        todos: [
            {
                done: false,
                priority: 'important',
                text: 'Add some test scripts.'
            },
            {
                done: true,
                priority: 'normal',
                text: 'Open source this project.'
            }
        ]
    },
    more: {
        version: [2, 0, 0],
        date: new Date('2017-04-14T00:08:00+08:00')
    }
};

try {
    var text = tomlify(table, null, 2);  // indent with 2 spaces
    /* OUTPUT:
     * [about]
     * name = "tomlify-j0.4"
     * maintainers = [
     *   "Jak Wings"
     * ]
     *
     *   [[about.todos]]
     *   done = false
     *   priority = "important"
     *   text = "Add some test scripts."
     *
     *   [[about.todos]]
     *   done = true
     *   priority = "normal"
     *   text = "Open source this project."
     *
     * [more]
     * version = [
     *   2.0,
     *   0.0,
     *   0.0
     * ]
     * date = 2017-04-13T16:08:00.000Z
     */
    var text = tomlify(table, function (key, value) {
        var context = this;
        var path = tomlify.toKey(context.path);
        if (/^more\.version\.\[\d+\]$/.test(path)) {
            return value.toFixed(0);  // Change the text transformed from the value.
        }
        if (context.path[0] === 'about' &&
            context.path[1] === 'todos' &&
            context.path[2] === 1) {
            return null;  // Drop one table from the todo array.
        }
        return false;  // Let tomlify decide for you.
    }, '  ');
    /* OUTPUT:
     * [about]
     * name = "tomlify-j0.4"
     * maintainers = [
     *   "Jak Wings"
     * ]
     *
     *   [[about.todos]]
     *   done = false
     *   priority = "important"
     *   text = "Add some test scripts."
     *
     * [more]
     * version = [
     *   2,
     *   0,
     *   0
     * ]
     * date = 2017-04-13T16:08:00.000Z
     */
    var text = tomlify({
        null: null,
        undefined: undefined,
        numbers: [1, 2, null, , 3, 4]
    });
    /* OUTPUT:
     * numbers = [1.0, 2.0, 3.0, 4.0]
     */
} catch (err) {
    // do something
}

APIs

tomlify(table, replacer, space)

Use it to transform a table object into TOML text.

• table - {Object}: The object to be transformed.

  It can be any JavaScript object, except for null and undefined. By default, all numbers are transformed into floats and arrays of numbers will become arrays of floats. And null or undefined in an array or object property whose value is null or undefined will be ignored. You can change this behavior through replacer.

  If table is a boolean value, a number, a string, a date or an array, the result will be the same as tomlify.toValue(table, replacer, space).

• replacer - {function(this: Context, key: String|Number, value:Mixed): Mixed}:

  • @this {Context}:
    • @property {Array.<String|Number>} path: The key path to current value.
    • @property {Table|Array} table: The direct parent object.
  • @param {String|Number} key: The key of the value in current parent object.
  • @param {Mixed} value: The current value.
  • @return {Mixed} A string to change the value output, false to cancel, null or undefined to remove the output.

• space - {String|Number}: Specify the padding string for indentation.

  If it is a non-negative integer N, then use N space " " for indentation. If it is a string, then use this string for indentation. Otherwise, no indentation will be performed.

tomlify.toToml(value, replacer, space)

The same as tomlify(table, replacer, space), except that value must be an object other than an instance of Array or Date.

tomlify.toValue(value, replacer, space)

Just like tomlify(table, replacer, space), it is used to transform a value into TOML value for a key-value pair. value cannot be null or undefined.

However, an inline-table always fits into one line, no matter what it contains.

E.g.

tomlify.toValue({one: 1, two: 2});
//=> {one = 1.0, two = 2.0}

tomlify.toValue(["apple", "banana"], null, 2);
//=>
//[
//  "apple",
//  "banana"
//]

tomlify.toValue([
  {people: ["Alice", "Bob"]},
  {fruits: ["apple", "banana"]}
], null, 2);
//=>
//[
//  {people = ["Alice", "Bob"]},
//  {fruits = ["apple", "banana"]}
//]

tomlify.toKey(path, alternative)

• path - {String|Array.<String|Number>}: A key or a key path.
• alternative - {Boolean}: Whether numbers in the key path will be ignored.

Use it to get a TOML key or key path for the key-value pair. E.g.

tomlify.toKey('money');  //=> money
tomlify.toKey('$');      //=> "$"

tomlify.toKey(['sir', 'Mr. Smith']);        //=> sir."Mr. Smith"
tomlify.toKey(['food', 0, 'price']);        //=> food.[0].price
tomlify.toKey(['food', 0, 'price'], true);  //=> food.price

Known Problems

• JavaScript does not have any integer type.

  All numbers are floats in JavaScript. Any integer bigger than Number.MAX_SAFE_INTEGER (9007199254740991 < 2^63 - 1) or smaller than Number.MIN_SAFE_INTEGER (-9007199254740991 > -(2^63 - 1)) is not safe when being converted or used as a pure integer! You should store big integers in strings.

  All numbers are transformed into floats by default. You can change this behavior by using a replacer function with tomlify-j0.4.