bolgia

var Bolgia  = require( 'bolgia' );

/*
 * Property that holds all possible types/strings returned by Object#toString,
 * with some custom types like for node Buffers: "[object Buffer]".
 *
 * See Bolgia#toString method.
 *
 */
Bolgia#circles : Object

 
/*
 * simple object/hash cloning
 */
Bolgia#clone( Object obj ) : Object
 
/*
 * mix/update dest object with all properties
 * from src, with no recursion.
 * It brutally overwrites dest properties/values.
 * It returns the dest Object.
 */
Bolgia#mix( Object dest, Object src ) : Object
 
/* 
 * improve a dest object with all properties/values
 * from a src object, with recursion.
 * It doesn't overwrite properties/values that already
 * exist in the dest object.
 * It returns the dest Object.
 */
Bolgia#improve( Object dest, Object src ) : Object
 
/* 
 * update a dest object with all properties/values
 * from a src object, with recursion.
 * It brutally overwrites dest properties/values.
 * It returns the dest object.
 */
Bolgia#update( Object dest, Object src ) : Object
 
/* 
 * A methods that returns a toString() representation of an object.
 *
 * NOTE: It differs from Object.toString(), because for default, it
 * returns:
 *
 * - "[object Buffer]" for node Buffers
 * - "[object Null]" for NaN
 * - "[object Null]" for empty string ''
 *
 * NOTE: If custom is true, it returns:
 *
 * - "[object NaN]" for NaN
 * - "[object NullString]" for ''
 */
Bolgia#toString( Object o [, Boolean custom ] ) : String
 
/*
 * #toString alias.
 */
Bolgia#doString( Object o [, Boolean custom ] ) : String
 
/*
 * Recursively convert an obj/hash to an array.
 * It optionally accepts a boolean to activate recursion
 * and an array to collect results.
 *
 * NOTE: when using indexed arrays, every element will be
 * preceded by its index.
 */
Bolgia#toArray( Object obj [, Boolean recur [, Array result ] ] ) : Array
 
/*
 * Recursively convert an indexed array to an hash/obj;
 * optionally it converts Buffers to Strings and Strings
 * representing numbers to Numbers.
 *
 * NOTE: Array elements are interpreted as a series of key/value pairs.
 * NOTE: Pay attention to possible keys collisions/overwritings.
 * NOTE: Every nested array will be converted to an obj/hash.
 */
Bolgia#toHash( Array array [, Boolean recur [, Object result [, Boolean convert ] ] ] ) : Object
 
/*
 * Recursively convert a nested Array of Buffer items to Strings and Numbers.
 *
 * NOTE the max integer precision is +/- 2^53, if a string/buffer represents a numeber
 * that is >= 9007199254740992, or <= -9007199254740992, than it will be not converted
 * to Number.
 *
 * NOTE: It returns/converts the same array instance passed as argument.
 */
Bolgia#reveal( Array array ) : Array
 
/*
 * Recursively count obj properties, or
 * only non-object properties (leafs).
 */
Bolgia#count( Object obj [, Boolean leaf ] ) : Number
 
/*
 * Method to output a (query)string representation of an hash.
 * It requires an object to parse and optionally a configuration object.
 * It is possible to specify custom symbols for delimiting and equality,
 * defaults are '&' and '='.
 *
 * NOTE: for default, null, undefined and function values are filtered
 * away; to bypass this behaviour, it is possible to specify a custom 
 * function, for choosing which types are allowed for querystring.
 * This function gets 3 args: Object field, String ftype, Object circles.
 *
 * default configuration:
 *
 * {
 *   dl : '&'
 *   , eq : '='
 *   , filter : function ( field, ftype, circles ) {
 *      switch ( ftype ) {
 *          case circles.nul:
 *          case circles.und:
 *          case circles.fun:
 *          break;
 *          default:
 *              return true;
 *          break;
 *      };
 *   }
 * }
 */
Bolgia#qs( Object hash [, Object opt ] ) : String
 
/*
 * Method to output a (query)object representation of an hash.
 * It converts all paths, to the object's nested values ( leafs ),
 * to querystring keys.
 */
Bolgia#flatten( Object hash ) : Object

var log = console.log,
    , util = require( 'util' )
    , Bolgia = require( 'bolgia' );

 
var cfg = {
    letters : [ 'aaa', 'bbb', 'ccc','ddd' ]
    , numbers : {
        1 : false
        , 2 : false
        , 3 : false
        , 4 : false
    }
    , hell : {
        h1 : {
            a : [ 'a1!', 'a2!', 'a3!' ]
            , b : [ 'b1!', 'b2!', 'b3!' ]
        }
        , h3 : {
            1 : 0
            , 2 : 0
        }
    }
};

 
var upd = {
    letters : [ undefined, 'BBB', 'CCC', undefined, 'EEE' ]
    , numbers : {
        1 : true
        , 3 : Infinity
        , 4 : null
    }
    , hell : {
        h1 : {
            a : [ undefined, 'A2!' ]
            , b : [ 'B1!', undefined, 'B3!' ]
            , e : [ undefined, 'E2!', 'E3!' ]
        }
        , h2 : 'BLAH'
        , h3 : {
            2 : new Date( '1913' )
        }
    }
};

 
Bolgia.update( cfg, upd );
 
log( util.inspect( cfg, !true, null, true ) );
 
/* 
 * NOTE: sub-properties like arrays and hashes 
 * are not brutally overwritten, but finely updated
 */
 
{
    letters: [ 'aaa', 'BBB', 'CCC', 'ddd', 'EEE' ]
    , numbers : {
        1 : true
        , 2 : false
        , 3 : Infinity
        , 4 : null
    }
    , hell : {
        h1 : { a: [ 'a1!', 'A2!', 'a3!' ]
        , h2 : 'BLAH'
            b : [ 'B1!', 'b2!', 'B3!' ]
            , e : [ undefined, 'E2!', 'E3!' ] }
        h3 : {
            1 : 0
            , 2 : Wed Jan 01 1913 01:00:00 GMT+0100 (CET)
        }
    }
}