stringifier (original) (raw)

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

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

API

stringifier(options)

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

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

stringifier.stringify(val, options)

For more simplified usage, stringifier has a function stringify, that simply takes target object/value and returns stringified result string. stringifier.stringify accepts options as optional parameter 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));

use stringifier npm module on browser

stringifier function is exported

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

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 options.handlers

var stringify;

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

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

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

// whitelist by property value stringify = stringifier({ handlers: { '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({ handlers: { '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: numberDefault value: null

Max depth for recursive Object tree traversal

options.indent

Type: StringDefault value: null

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

options.lineSeparator

Type: StringDefault value: '\n'

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

options.anonymous

Type: StringDefault value: '@Anonymous'

Type name string alternative for displaying Object created by anonymous constructor

options.circular

Type: StringDefault value: '#@Circular#'

Alternative string for displaying Circular reference

options.snip

Type: StringDefault value: '..(snip)'

For displaying truncated string

options.handlers

options.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(), 'symbol': s.toStr(), 'RegExp': s.toStr(), 'String': s.newLike(), 'Boolean': s.newLike(), 'Number': s.newLike(), 'Date': s.newLike(), 'Array': s.array(), 'Object': s.object(), 'Error': s.object(null, ['message', 'code']), '@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({ handlers: { '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({ handlers: { '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({ handlers: { '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({ handlers: { 'Student': s.prune() } }); assert(stringify(student) === '#Student#');

newLike

newLike strategy emulates "new constructor call pattern".

var stringify = stringifier({ handlers: { '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({ handlers: { '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({ handlers: { '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({ handlers: { '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.