stringifier

stringifier
================================

Yet another stringify function.

[![Build Status][travis-image]][travis-url]
[![NPM package][npm-image]][npm-url]
[![Bower package][bower-image]][bower-url]
[![License][license-image]][license-url]

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

$3

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

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

$3

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.

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


INSTALL
---------------------------------------

$3

Install

$ npm install --save stringifier

Use

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

#### use stringifier npm module on browser

stringifier function is exported

$3

Install

$ bower install --save stringifier

Load (stringifier function is exported)

Use

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


EXAMPLE
---------------------------------------

For given context,

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

`javascript
var stringify = stringifier();
console.log(stringify(values));
`
result:

`javascript
["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.

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

result:

`javascript
[
"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.

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

result:

`javascript
[
"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.

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


#### omit specific property from output

Customize options.handlers

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

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

$3


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


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

`javascript
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.

$3

For given Student pseudo-class and a stringifier,

`javascript
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').

`javascript
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.

`javascript
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.

`javascript
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 #.

`javascript
var stringify = stringifier({
handlers: {
'Student': s.prune()
}
});
assert(stringify(student) === '#Student#');
`

#### newLike

newLike strategy emulates "new constructor call pattern".

`javascript
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.

`javascript
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.

`javascript
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.

`javascript
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.

[travis-url]: https://travis-ci.org/twada/stringifier
[travis-image]: https://secure.travis-ci.org/twada/stringifier.svg?branch=master

[npm-url]: https://npmjs.org/package/stringifier
[npm-image]: https://badge.fury.io/js/stringifier.svg

[bower-url]: https://badge.fury.io/bo/stringifier
[bower-image]: https://badge.fury.io/bo/stringifier.svg

[license-url]: https://twada.mit-license.org/2014-2024
[license-image]: https://img.shields.io/badge/license-MIT-brightgreen.svg