From 66280de133a56964641a08291b06fc0e5ca2b4e1 Mon Sep 17 00:00:00 2001
From: Nathan Rajlich <nathan@tootallnate.net>
Date: Tue, 29 Jan 2013 19:06:32 -0800
Subject: [PATCH] util: custom `inspect()` method may return an Object

This is more like how `JSON.stringify()` works.
Closes #2711.
---
 doc/api/util.markdown            | 14 ++++++++++++++
 lib/util.js                      |  6 +++++-
 test/simple/test-util-inspect.js |  5 +++++
 3 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/doc/api/util.markdown b/doc/api/util.markdown
index f9fa728d64c..8d6a41c6c66 100644
--- a/doc/api/util.markdown
+++ b/doc/api/util.markdown
@@ -114,6 +114,8 @@ Predefined color codes are: `white`, `grey`, `black`, `blue`, `cyan`,
 `green`, `magenta`, `red` and `yellow`.
 There are also `bold`, `italic`, `underline` and `inverse` codes.
 
+### Custom `inpect()` function on Objects
+
 Objects also may define their own `inspect(depth)` function which `util.inspect()`
 will invoke and use the result of when inspecting the object:
 
@@ -127,6 +129,18 @@ will invoke and use the result of when inspecting the object:
     util.inspect(obj);
       // "{nate}"
 
+You may also return another Object entirely, and the returned String will be
+formatted according to the returned Object. This is similar to how
+`JSON.stringify()` works:
+
+    var obj = { foo: 'this will not show up in the inspect() output' };
+    obj.inspect = function(depth) {
+      return { bar: 'baz' };
+    };
+
+    util.inspect(obj);
+      // "{ bar: 'baz' }"
+
 
 ## util.isArray(object)
 
diff --git a/lib/util.js b/lib/util.js
index 40b0680b37f..af9deb8a1d3 100644
--- a/lib/util.js
+++ b/lib/util.js
@@ -209,7 +209,11 @@ function formatValue(ctx, value, recurseTimes) {
       value.inspect !== exports.inspect &&
       // Also filter out any prototype objects using the circular check.
       !(value.constructor && value.constructor.prototype === value)) {
-    return String(value.inspect(recurseTimes));
+    var ret = value.inspect(recurseTimes);
+    if ('string' !== typeof ret) {
+      ret = formatValue(ctx, ret, recurseTimes);
+    }
+    return ret;
   }
 
   // Primitive types cannot have properties
diff --git a/test/simple/test-util-inspect.js b/test/simple/test-util-inspect.js
index 0b04c93c73d..9265f13f0b5 100644
--- a/test/simple/test-util-inspect.js
+++ b/test/simple/test-util-inspect.js
@@ -155,3 +155,8 @@ assert(util.inspect(subject, { customInspect: true }).indexOf('123') !== -1);
 assert(util.inspect(subject, { customInspect: true }).indexOf('inspect') === -1);
 assert(util.inspect(subject, { customInspect: false }).indexOf('123') === -1);
 assert(util.inspect(subject, { customInspect: false }).indexOf('inspect') !== -1);
+
+// custom inspect() functions should be able to return other Objects
+subject.inspect = function() { return { foo: 'bar' }; };
+
+assert.equal(util.inspect(subject), '{ foo: \'bar\' }');