Package Exports

stringifier

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (stringifier) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

stringifier

Yet another stringify function.

DESCRIPTION

stringifier is a function like JSON.stringify but intended to be more customizable. For example,

Max depth for recursive object tree traversal
Per-type output customization
Circular reference handling

Please note that stringifier is a beta version product. Pull-requests, issue reports and patches are always welcomed. stringifier is a spin-off product of power-assert project.

API

stringifier(options, handlers)

require('stringifier') exports single function stringifier that accepts options and handlers as optional parameters and returns configured function for stringify. This is the comprehensive usage.

var stringifier = require('stringifier');
var stringify = stringifier(options, handlers);
console.log(stringify(anyVar));

stringifier.stringify(val, options, handlers)

For more simplified usage, stringifier has a function stringify, that simply takes target object/value and returns stringified result string. stringifier.stringify accepts options and handlers as second and third optional parameters too.

var stringify = require('stringifier').stringify;
console.log(stringify(anyVar));

INSTALL

via npm

Install

$ npm install --save stringifier

Use

var stringify = require('stringifier').stringify;
console.log(stringify(anyVar));

via bower

Install

$ bower install --save stringifier

Load (stringifier function is exported)

<script type="text/javascript" src="./path/to/bower_components/stringifier/build/stringifier.js"></script>

Use

console.log(stringifier.stringify(anyVar));

EXAMPLE

For given context,

var stringifier = require('stringifier'),
    assert = require('assert');

function Student (name, age, gender) {
    this.name = name;
    this.age = age;
    this.gender = gender;
}

var AnonStudent = function(name, age, gender) {
    this.name = name;
    this.age = age;
    this.gender = gender;
};

var student = new Student('tom', 10, 'M');
var anonStudent = new AnonStudent('mary', 9, 'F');

var values = [
    'string', 
    [null, undefined],
    {
        primitives: [true, false, -5, 98.6],
        specific: {
            regex: /^not/,
            numbers: [NaN, Infinity, -Infinity]
        },
        userDefined: [
            student,
            anonStudent
        ]
    }
];

default single-line output

var stringify = stringifier();
console.log(stringify(values));

result:

["string",[null,undefined],Object{primitives:[true,false,-5,98.6],specific:Object{regex:/^not/,numbers:[NaN,Infinity,-Infinity]},userDefined:[Student{name:"tom",age:10,gender:"M"},@Anonymous{name:"mary",age:9,gender:"F"}]}]

pretty printing with indentation

Use indent option for pretty printing. Using four spaces for indentation in this case.

var stringify = stringifier({indent: '    '});
console.log(stringify(values));

result:

[
    "string",
    [
        null,
        undefined
    ],
    Object{
        primitives: [
            true,
            false,
            -5,
            98.6
        ],
        specific: Object{
            regex: /^not/,
            numbers: [
                NaN,
                Infinity,
                -Infinity
            ]
        },
        userDefined: [
            Student{
                name: "tom",
                age: 10,
                gender: "M"
            },
            @Anonymous{
                name: "mary",
                age: 9,
                gender: "F"
            }
        ]
    }
]

depth limitation

Use maxDepth option to stringify at most specified levels.

var stringify = stringifier({maxDepth: 3, indent: '    '});
console.log(stringify(values));

result:

[
    "string",
    [
        null,
        undefined
    ],
    Object{
        primitives: [
            true,
            false,
            -5,
            98.6
        ],
        specific: Object{
            regex: /^not/,
            numbers: #Array#
        },
        userDefined: [
            #Student#,
            #@Anonymous#
        ]
    }
]

anonymous class label

Use anonymous option to specify alternate type name for anonymous constructors.

var stringify = stringifier({anonymous: 'ANON'});
assert(stringify(anonStudent) === 'ANON{name:"mary",age:9,gender:"F"}');

omit specific property from output

Customize handlers argument

var stringify;

// property whitelist and reordering
stringify = stringifier(null, {
    'Student': s.object(null, ['gender', 'age'])
});
assert(stringify(student) === 'Student{gender:"M",age:10}');

// blacklist by property name
stringify = stringifier(null, {
    'Student': s.object(function (kvp) {
        return ['age', 'gender'].indexOf(kvp.key) === -1;
    })
});
assert(stringify(student) === 'Student{name:"tom"}');

// blacklist by property value
stringify = stringifier(null, {
    'Student': s.object(function (kvp) {
        return kvp.value !== 'M';
    })
});
assert(stringify(student) === 'Student{name:"tom",age:10}');

// whitelist by property value
stringify = stringifier(null, {
    'Student': s.object(function (kvp) {
        return typeName(kvp.value) === 'string';
    })
});
assert(stringify(student) === 'Student{name:"tom",gender:"M"}');

truncate property value

Return number from object predicate

stringify = stringifier(null, {
    'Student': s.object(function (kvp) {
        if (kvp.key === 'name') {
            return 3;
        }
        return true;
    })
});
assert(stringify(student) === 'Student{name:"to..(snip),age:10,gender:"M"}');

CONFIGURATION

options

options.maxDepth

Type: number Default value: null

Max depth for recursive Object tree traversal

options.indent

Type: String Default value: null

string value for indentation. If this value is not empty, stringified result may contain multiple lines.

options.lineSeparator

Type: String Default value: '\n'

string value for line-separator. Makes sense only if options.indent is not empty.

options.anonymous

Type: String Default value: '@Anonymous'

Type name string alternative for displaying Object created by anonymous constructor

options.circular

Type: String Default value: '#@Circular#'

Alternative string for displaying Circular reference

options.snip

Type: String Default value: '..(snip)'

For displaying truncated string

handlers

handlers is a object where property names are type names (string, number, ...) and values are per-type stringify strategy functions. Various strategies are defined in stringifier.strategies, and default strategies are defined as follows.

var s = require('./strategies');
function defaultHandlers () {
    return {
        'null': s.always('null'),
        'undefined': s.always('undefined'),
        'function': s.prune(),
        'string': s.json(),
        'boolean': s.json(),
        'number': s.number(),
        'RegExp': s.toStr(),
        'String': s.newLike(),
        'Boolean': s.newLike(),
        'Number': s.newLike(),
        'Date': s.newLike(),
        'Array': s.array(),
        'Object': s.object(),
        '@default': s.object()
    };
}

If unknown type is detected, strategy function registered by '@default' key will be used.

strategies

For given Student pseudo-class and a stringifier,

var stringifier = require('stringifier'),
    s = stringifier.strategies,
    assert = require('assert'),

function Student (name, age, gender) {
    this.name = name;
    this.age = age;
    this.gender = gender;
}

var student = new Student('tom', 10, 'M');

always

always strategy always returns passed constant (In this case, 'foo').

var stringify = stringifier(null, {
  'Student': s.always('foo')
});
assert(stringify(student) === 'foo');

json

json strategy applies JSON.stringify to input value then return the result string.

var stringify = stringifier(null, {
  'Student': s.json()
});
assert(stringify(student) === '{"name":"tom","age":10,"gender":"M"}');

toStr

toStr strategy calls toString() to input value then return the result string.

var stringify = stringifier(null, {
  'Student': s.toStr()
});
assert(stringify(student) === '[object Object]');

prune

prune strategy does not serialize target value but returns target type name surrounded by #.

var stringify = stringifier(null, {
  'Student': s.prune()
});
assert(stringify(student) === '#Student#');

newLike

newLike strategy emulates "new constructor call pattern".

var stringify = stringifier(null, {
  'Student': s.newLike()
});
assert(stringify(student) === 'new Student({"name":"tom","age":10,"gender":"M"})');

object

object strategy stringifies target object recursively and decorate object literal-like syntax with its type name. object is a default strategy for objects, and any other unknown types.

var stringify = stringifier(null, {
  'Student': s.object()
});
assert(stringify(student) === 'Student{name:"tom",age:10,gender:"M"}');

array

array strategy is an array specific stringification strategy, and is a default strategy for arrays.

var stringify = stringifier(null, {
  'Array': s.array()
});
assert(stringify(['foo', 'bar', 'baz']) === '["foo","bar","baz"]');

number

number strategy is a number specific stringification strategy, and is a default strategy for number. number strategy also provides NaN,Infinity and -Infinity handling.

var stringify = stringifier(null, {
  'Array': s.array(),
  'number': s.number()
});
assert(stringify([NaN, 0, Infinity, -0, -Infinity]) === '[NaN,0,Infinity,0,-Infinity]');

AUTHOR

Takuto Wada

LICENSE

Licensed under the MIT license.