lib/util.js

   1 // Copyright Joyent, Inc. and other Node contributors.
   2 //
   3 // Permission is hereby granted, free of charge, to any person obtaining a
   4 // copy of this software and associated documentation files (the
   5 // "Software"), to deal in the Software without restriction, including
   6 // without limitation the rights to use, copy, modify, merge, publish,
   7 // distribute, sublicense, and/or sell copies of the Software, and to permit
   8 // persons to whom the Software is furnished to do so, subject to the
   9 // following conditions:
  10 //
  11 // The above copyright notice and this permission notice shall be included
  12 // in all copies or substantial portions of the Software.
  13 //
  14 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  15 // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  16 // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
  17 // NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
  18 // DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
  19 // OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
  20 // USE OR OTHER DEALINGS IN THE SOFTWARE.
  21
  22 var formatRegExp = /%[sdj%]/g;
  23 exports.format = function(f) {
  24   if (!IS_STRING(f)) {
  25     var objects = [];
  26     for (var i = 0; i < arguments.length; i++) {
  27       objects.push(inspect(arguments[i]));
  28     }
  29     return objects.join(' ');
  30   }
  31
  32   var i = 1;
  33   var args = arguments;
  34   var len = args.length;
  35   var str = String(f).replace(formatRegExp, function(x) {
  36     if (x === '%%') return '%';
  37     if (i >= len) return x;
  38     switch (x) {
  39       case '%s': return String(args[i++]);
  40       case '%d': return Number(args[i++]);
  41       case '%j': return JSON.stringify(args[i++]);
  42       default:
  43         return x;
  44     }
  45   });
  46   for (var x = args[i]; i < len; x = args[++i]) {
  47     if (IS_NULL(x) || !IS_OBJECT(x)) {
  48       str += ' ' + x;
  49     } else {
  50       str += ' ' + inspect(x);
  51     }
  52   }
  53   return str;
  54 };
  55
  56
  57 // Mark that a method should not be used.
  58 // Returns a modified function which warns once by default.
  59 // If --no-deprecation is set, then it is a no-op.
  60 exports.deprecate = function(fn, msg) {
  61   if (process.noDeprecation === true) {
  62     return fn;
  63   }
  64
  65   var warned = false;
  66   function deprecated() {
  67     if (!warned) {
  68       if (process.throwDeprecation) {
  69         throw new Error(msg);
  70       } else if (process.traceDeprecation) {
  71         console.trace(msg);
  72       } else {
  73         console.error(msg);
  74       }
  75       warned = true;
  76     }
  77     return fn.apply(this, arguments);
  78   }
  79
  80   return deprecated;
  81 };
  82
  83
  84 var debugs = {};
  85 var debugEnviron = process.env.NODE_DEBUG || '';
  86 exports.debuglog = function(set) {
  87   set = set.toUpperCase();
  88   if (!debugs[set]) {
  89     if (new RegExp('\\b' + set + '\\b', 'i').test(debugEnviron)) {
  90       var pid = process.pid;
  91       debugs[set] = function() {
  92         var msg = exports.format.apply(exports, arguments);
  93         console.error('%s %d: %s', set, pid, msg);
  94       };
  95     } else {
  96       debugs[set] = function() {};
  97     }
  98   }
  99   return debugs[set];
 100 };
 101
 102
 103 /**
 104  * Echos the value of a value. Trys to print the value out
 105  * in the best way possible given the different types.
 106  *
 107  * @param {Object} obj The object to print out.
 108  * @param {Object} opts Optional options object that alters the output.
 109  */
 110 /* legacy: obj, showHidden, depth, colors*/
 111 function inspect(obj, opts) {
 112   // default options
 113   var ctx = {
 114     seen: [],
 115     stylize: stylizeNoColor
 116   };
 117   // legacy...
 118   if (arguments.length >= 3) ctx.depth = arguments[2];
 119   if (arguments.length >= 4) ctx.colors = arguments[3];
 120   if (IS_BOOLEAN(opts)) {
 121     // legacy...
 122     ctx.showHidden = opts;
 123   } else if (opts) {
 124     // got an "options" object
 125     exports._extend(ctx, opts);
 126   }
 127   // set default options
 128   if (IS_UNDEFINED(ctx.showHidden)) ctx.showHidden = false;
 129   if (IS_UNDEFINED(ctx.depth)) ctx.depth = 2;
 130   if (IS_UNDEFINED(ctx.colors)) ctx.colors = false;
 131   if (IS_UNDEFINED(ctx.customInspect)) ctx.customInspect = true;
 132   if (ctx.colors) ctx.stylize = stylizeWithColor;
 133   return formatValue(ctx, obj, ctx.depth);
 134 }
 135 exports.inspect = inspect;
 136
 137
 138 // http://en.wikipedia.org/wiki/ANSI_escape_code#graphics
 139 inspect.colors = {
 140   'bold' : [1, 22],
 141   'italic' : [3, 23],
 142   'underline' : [4, 24],
 143   'inverse' : [7, 27],
 144   'white' : [37, 39],
 145   'grey' : [90, 39],
 146   'black' : [30, 39],
 147   'blue' : [34, 39],
 148   'cyan' : [36, 39],
 149   'green' : [32, 39],
 150   'magenta' : [35, 39],
 151   'red' : [31, 39],
 152   'yellow' : [33, 39]
 153 };
 154
 155 // Don't use 'blue' not visible on cmd.exe
 156 inspect.styles = {
 157   'special': 'cyan',
 158   'number': 'yellow',
 159   'boolean': 'yellow',
 160   'undefined': 'grey',
 161   'null': 'bold',
 162   'string': 'green',
 163   'date': 'magenta',
 164   // "name": intentionally not styling
 165   'regexp': 'red'
 166 };
 167
 168
 169 function stylizeWithColor(str, styleType) {
 170   var style = inspect.styles[styleType];
 171
 172   if (style) {
 173     return '\u001b[' + inspect.colors[style][0] + 'm' + str +
 174            '\u001b[' + inspect.colors[style][1] + 'm';
 175   } else {
 176     return str;
 177   }
 178 }
 179
 180
 181 function stylizeNoColor(str, styleType) {
 182   return str;
 183 }
 184
 185
 186 function arrayToHash(array) {
 187   var hash = {};
 188
 189   array.forEach(function(val, idx) {
 190     hash[val] = true;
 191   });
 192
 193   return hash;
 194 }
 195
 196
 197 function formatValue(ctx, value, recurseTimes) {
 198   // Provide a hook for user-specified inspect functions.
 199   // Check that value is an object with an inspect function on it
 200   if (ctx.customInspect &&
 201       value &&
 202       IS_FUNCTION(value.inspect) &&
 203       // Filter out the util module, it's inspect function is special
 204       value.inspect !== exports.inspect &&
 205       // Also filter out any prototype objects using the circular check.
 206       !(value.constructor && value.constructor.prototype === value)) {
 207     var ret = value.inspect(recurseTimes);
 208     if (!IS_STRING(ret)) {
 209       ret = formatValue(ctx, ret, recurseTimes);
 210     }
 211     return ret;
 212   }
 213
 214   // Primitive types cannot have properties
 215   var primitive = formatPrimitive(ctx, value);
 216   if (primitive) {
 217     return primitive;
 218   }
 219
 220   // Look up the keys of the object.
 221   var keys = Object.keys(value);
 222   var visibleKeys = arrayToHash(keys);
 223
 224   if (ctx.showHidden) {
 225     keys = Object.getOwnPropertyNames(value);
 226   }
 227
 228   // Some type of object without properties can be shortcutted.
 229   if (keys.length === 0) {
 230     if (IS_FUNCTION(value)) {
 231       var name = value.name ? ': ' + value.name : '';
 232       return ctx.stylize('[Function' + name + ']', 'special');
 233     }
 234     if (isRegExp(value)) {
 235       return ctx.stylize(RegExp.prototype.toString.call(value), 'regexp');
 236     }
 237     if (isDate(value)) {
 238       return ctx.stylize(Date.prototype.toString.call(value), 'date');
 239     }
 240     if (isError(value)) {
 241       return formatError(value);
 242     }
 243   }
 244
 245   var base = '', array = false, braces = ['{', '}'];
 246
 247   // Make Array say that they are Array
 248   if (isArray(value)) {
 249     array = true;
 250     braces = ['[', ']'];
 251   }
 252
 253   // Make functions say that they are functions
 254   if (IS_FUNCTION(value)) {
 255     var n = value.name ? ': ' + value.name : '';
 256     base = ' [Function' + n + ']';
 257   }
 258
 259   // Make RegExps say that they are RegExps
 260   if (isRegExp(value)) {
 261     base = ' ' + RegExp.prototype.toString.call(value);
 262   }
 263
 264   // Make dates with properties first say the date
 265   if (isDate(value)) {
 266     base = ' ' + Date.prototype.toUTCString.call(value);
 267   }
 268
 269   // Make error with message first say the error
 270   if (isError(value)) {
 271     base = ' ' + formatError(value);
 272   }
 273
 274   if (keys.length === 0 && (!array || value.length == 0)) {
 275     return braces[0] + base + braces[1];
 276   }
 277
 278   if (recurseTimes < 0) {
 279     if (isRegExp(value)) {
 280       return ctx.stylize(RegExp.prototype.toString.call(value), 'regexp');
 281     } else {
 282       return ctx.stylize('[Object]', 'special');
 283     }
 284   }
 285
 286   ctx.seen.push(value);
 287
 288   var output;
 289   if (array) {
 290     output = formatArray(ctx, value, recurseTimes, visibleKeys, keys);
 291   } else {
 292     output = keys.map(function(key) {
 293       return formatProperty(ctx, value, recurseTimes, visibleKeys, key, array);
 294     });
 295   }
 296
 297   ctx.seen.pop();
 298
 299   return reduceToSingleString(output, base, braces);
 300 }
 301
 302
 303 function formatPrimitive(ctx, value) {
 304   if (IS_UNDEFINED(value))
 305     return ctx.stylize('undefined', 'undefined');
 306   if (IS_STRING(value)) {
 307     var simple = '\'' + JSON.stringify(value).replace(/^"|"$/g, '')
 308                                              .replace(/'/g, "\\'")
 309                                              .replace(/\\"/g, '"') + '\'';
 310     return ctx.stylize(simple, 'string');
 311   }
 312   if (IS_NUMBER(value))
 313     return ctx.stylize('' + value, 'number');
 314   if (IS_BOOLEAN(value))
 315     return ctx.stylize('' + value, 'boolean');
 316   // For some reason typeof null is "object", so special case here.
 317   if (IS_NULL(value))
 318     return ctx.stylize('null', 'null');
 319 }
 320
 321
 322 function formatError(value) {
 323   return '[' + Error.prototype.toString.call(value) + ']';
 324 }
 325
 326
 327 function formatArray(ctx, value, recurseTimes, visibleKeys, keys) {
 328   var output = [];
 329   for (var i = 0, l = value.length; i < l; ++i) {
 330     if (hasOwnProperty(value, String(i))) {
 331       output.push(formatProperty(ctx, value, recurseTimes, visibleKeys,
 332           String(i), true));
 333     } else {
 334       output.push('');
 335     }
 336   }
 337   keys.forEach(function(key) {
 338     if (!key.match(/^\d+$/)) {
 339       output.push(formatProperty(ctx, value, recurseTimes, visibleKeys,
 340           key, true));
 341     }
 342   });
 343   return output;
 344 }
 345
 346
 347 function formatProperty(ctx, value, recurseTimes, visibleKeys, key, array) {
 348   var name, str, desc;
 349   desc = Object.getOwnPropertyDescriptor(value, key) || { value: value[key] };
 350   if (desc.get) {
 351     if (desc.set) {
 352       str = ctx.stylize('[Getter/Setter]', 'special');
 353     } else {
 354       str = ctx.stylize('[Getter]', 'special');
 355     }
 356   } else {
 357     if (desc.set) {
 358       str = ctx.stylize('[Setter]', 'special');
 359     }
 360   }
 361   if (!hasOwnProperty(visibleKeys, key)) {
 362     name = '[' + key + ']';
 363   }
 364   if (!str) {
 365     if (ctx.seen.indexOf(desc.value) < 0) {
 366       if (IS_NULL(recurseTimes)) {
 367         str = formatValue(ctx, desc.value, null);
 368       } else {
 369         str = formatValue(ctx, desc.value, recurseTimes - 1);
 370       }
 371       if (str.indexOf('\n') > -1) {
 372         if (array) {
 373           str = str.split('\n').map(function(line) {
 374             return '  ' + line;
 375           }).join('\n').substr(2);
 376         } else {
 377           str = '\n' + str.split('\n').map(function(line) {
 378             return '   ' + line;
 379           }).join('\n');
 380         }
 381       }
 382     } else {
 383       str = ctx.stylize('[Circular]', 'special');
 384     }
 385   }
 386   if (IS_UNDEFINED(name)) {
 387     if (array && key.match(/^\d+$/)) {
 388       return str;
 389     }
 390     name = JSON.stringify('' + key);
 391     if (name.match(/^"([a-zA-Z_][a-zA-Z_0-9]*)"$/)) {
 392       name = name.substr(1, name.length - 2);
 393       name = ctx.stylize(name, 'name');
 394     } else {
 395       name = name.replace(/'/g, "\\'")
 396                  .replace(/\\"/g, '"')
 397                  .replace(/(^"|"$)/g, "'");
 398       name = ctx.stylize(name, 'string');
 399     }
 400   }
 401
 402   return name + ': ' + str;
 403 }
 404
 405
 406 function reduceToSingleString(output, base, braces) {
 407   var numLinesEst = 0;
 408   var length = output.reduce(function(prev, cur) {
 409     numLinesEst++;
 410     if (cur.indexOf('\n') >= 0) numLinesEst++;
 411     return prev + cur.replace(/\u001b\[\d\d?m/g, '').length + 1;
 412   }, 0);
 413
 414   if (length > 60) {
 415     return braces[0] +
 416            (base === '' ? '' : base + '\n ') +
 417            ' ' +
 418            output.join(',\n  ') +
 419            ' ' +
 420            braces[1];
 421   }
 422
 423   return braces[0] + base + ' ' + output.join(', ') + ' ' + braces[1];
 424 }
 425
 426
 427 // NOTE: These type checking functions intentionally don't use `instanceof`
 428 // because it is fragile and can be easily faked with `Object.create()`.
 429 function isArray(ar) {
 430   return IS_ARRAY(ar);
 431 }
 432 exports.isArray = isArray;
 433
 434
 435 function isRegExp(re) {
 436   return IS_OBJECT(re) && objectToString(re) === '[object RegExp]';
 437 }
 438 exports.isRegExp = isRegExp;
 439
 440
 441 function isDate(d) {
 442   return IS_OBJECT(d) && objectToString(d) === '[object Date]';
 443 }
 444 exports.isDate = isDate;
 445
 446
 447 function isError(e) {
 448   return IS_OBJECT(e) && objectToString(e) === '[object Error]';
 449 }
 450 exports.isError = isError;
 451
 452
 453 function objectToString(o) {
 454   return Object.prototype.toString.call(o);
 455 }
 456
 457
 458 function pad(n) {
 459   return n < 10 ? '0' + n.toString(10) : n.toString(10);
 460 }
 461
 462
 463 var months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep',
 464               'Oct', 'Nov', 'Dec'];
 465
 466 // 26 Feb 16:19:34
 467 function timestamp() {
 468   var d = new Date();
 469   var time = [pad(d.getHours()),
 470               pad(d.getMinutes()),
 471               pad(d.getSeconds())].join(':');
 472   return [d.getDate(), months[d.getMonth()], time].join(' ');
 473 }
 474
 475
 476 // log is just a thin wrapper to console.log that prepends a timestamp
 477 exports.log = function() {
 478   console.log('%s - %s', timestamp(), exports.format.apply(exports, arguments));
 479 };
 480
 481
 482 /**
 483  * Inherit the prototype methods from one constructor into another.
 484  *
 485  * The Function.prototype.inherits from lang.js rewritten as a standalone
 486  * function (not on Function.prototype). NOTE: If this file is to be loaded
 487  * during bootstrapping this function needs to be rewritten using some native
 488  * functions as prototype setup using normal JavaScript does not work as
 489  * expected during bootstrapping (see mirror.js in r114903).
 490  *
 491  * @param {function} ctor Constructor function which needs to inherit the
 492  *     prototype.
 493  * @param {function} superCtor Constructor function to inherit prototype from.
 494  */
 495 exports.inherits = function(ctor, superCtor) {
 496   ctor.super_ = superCtor;
 497   ctor.prototype = Object.create(superCtor.prototype, {
 498     constructor: {
 499       value: ctor,
 500       enumerable: false,
 501       writable: true,
 502       configurable: true
 503     }
 504   });
 505 };
 506
 507 exports._extend = function(origin, add) {
 508   // Don't do anything if add isn't an object
 509   if (!add || !IS_OBJECT(add)) return origin;
 510
 511   var keys = Object.keys(add);
 512   var i = keys.length;
 513   while (i--) {
 514     origin[keys[i]] = add[keys[i]];
 515   }
 516   return origin;
 517 };
 518
 519 function hasOwnProperty(obj, prop) {
 520   return Object.prototype.hasOwnProperty.call(obj, prop);
 521 }
 522
 523
 524 // Deprecated old stuff.
 525
 526 exports.p = exports.deprecate(function() {
 527   for (var i = 0, len = arguments.length; i < len; ++i) {
 528     console.error(exports.inspect(arguments[i]));
 529   }
 530 }, 'util.p: Use console.error() instead');
 531
 532
 533 exports.exec = exports.deprecate(function() {
 534   return require('child_process').exec.apply(this, arguments);
 535 }, 'util.exec is now called `child_process.exec`.');
 536
 537
 538 exports.print = exports.deprecate(function() {
 539   for (var i = 0, len = arguments.length; i < len; ++i) {
 540     process.stdout.write(String(arguments[i]));
 541   }
 542 }, 'util.print: Use console.log instead');
 543
 544
 545 exports.puts = exports.deprecate(function() {
 546   for (var i = 0, len = arguments.length; i < len; ++i) {
 547     process.stdout.write(arguments[i] + '\n');
 548   }
 549 }, 'util.puts: Use console.log instead');
 550
 551
 552 exports.debug = exports.deprecate(function(x) {
 553   process.stderr.write('DEBUG: ' + x + '\n');
 554 }, 'util.debug: Use console.error instead');
 555
 556
 557 exports.error = exports.deprecate(function(x) {
 558   for (var i = 0, len = arguments.length; i < len; ++i) {
 559     process.stderr.write(arguments[i] + '\n');
 560   }
 561 }, 'util.error: Use console.error instead');
 562
 563
 564 exports.pump = exports.deprecate(function(readStream, writeStream, callback) {
 565   var callbackCalled = false;
 566
 567   function call(a, b, c) {
 568     if (callback && !callbackCalled) {
 569       callback(a, b, c);
 570       callbackCalled = true;
 571     }
 572   }
 573
 574   readStream.addListener('data', function(chunk) {
 575     if (writeStream.write(chunk) === false) readStream.pause();
 576   });
 577
 578   writeStream.addListener('drain', function() {
 579     readStream.resume();
 580   });
 581
 582   readStream.addListener('end', function() {
 583     writeStream.end();
 584   });
 585
 586   readStream.addListener('close', function() {
 587     call();
 588   });
 589
 590   readStream.addListener('error', function(err) {
 591     writeStream.end();
 592     call(err);
 593   });
 594
 595   writeStream.addListener('error', function(err) {
 596     readStream.destroy();
 597     call(err);
 598   });
 599 }, 'util.pump(): Use readableStream.pipe() instead');
 600
 601
 602 var uv;
 603 exports._errnoException = function(err, syscall) {
 604   if (IS_UNDEFINED(uv)) uv = process.binding('uv');
 605   var errname = uv.errname(err);
 606   var e = new Error(syscall + ' ' + errname);
 607   e.code = errname;
 608   e.errno = errname;
 609   e.syscall = syscall;
 610   return e;
 611 };