Skip to content

Commit 896b2aa

Browse files
isaacsisaacs
committed
util: Add debuglog, deprecate console lookalikes
1 parent 0fefcc1 commit 896b2aa

16 files changed

+296
-185
lines changed

‎doc/api/util.markdown‎

Lines changed: 75 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,46 @@
22

33
Stability: 5 - Locked
44

5-
These functions are in the module `'util'`. Use `require('util')` to access
6-
them.
5+
These functions are in the module `'util'`. Use `require('util')` to
6+
access them.
77

8+
The `util` module is primarily designed to support the needs of Node's
9+
internal APIs. Many of these utilities are useful for your own
10+
programs. If you find that these functions are lacking for your
11+
purposes, however, you are encouraged to write your own utilities. We
12+
are not interested in any future additions to the `util` module that
13+
are unnecessary for Node's internal functionality.
14+
15+
## util.debuglog(section)
16+
17+
* `section` {String} The section of the program to be debugged
18+
* Returns: {Function} The logging function
19+
20+
This is used to create a function which conditionally writes to stderr
21+
based on the existence of a `NODE_DEBUG` environment variable. If the
22+
`section` name appears in that environment variable, then the returned
23+
function will be similar to `console.error()`. If not, then the
24+
returned function is a no-op.
25+
26+
For example:
27+
28+
```javascript
29+
var debuglog = util.debuglog('foo');
30+
31+
var bar = 123;
32+
debuglog('hello from foo [%d]', bar);
33+
```
34+
35+
If this program is run with `NODE_DEBUG=foo` in the environment, then
36+
it will output something like:
37+
38+
FOO 3245: hello from foo [123]
39+
40+
where `3245` is the process id. If it is not run with that
41+
environment variable set, then it will not print anything.
42+
43+
You may separate multiple `NODE_DEBUG` environment variables with a
44+
comma. For example, `NODE_DEBUG=fs,net,tls`.
845

946
## util.format(format, [...])
1047

@@ -37,35 +74,12 @@ Each argument is converted to a string with `util.inspect()`.
3774
util.format(1, 2, 3); // '1 2 3'
3875

3976

40-
## util.debug(string)
41-
42-
A synchronous output function. Will block the process and
43-
output `string` immediately to `stderr`.
44-
45-
require('util').debug('message on stderr');
46-
47-
## util.error([...])
48-
49-
Same as `util.debug()` except this will output all arguments immediately to
50-
`stderr`.
51-
52-
## util.puts([...])
53-
54-
A synchronous output function. Will block the process and output all arguments
55-
to `stdout` with newlines after each argument.
56-
57-
## util.print([...])
58-
59-
A synchronous output function. Will block the process, cast each argument to a
60-
string then output to `stdout`. Does not place newlines after each argument.
61-
6277
## util.log(string)
6378

6479
Output with timestamp on `stdout`.
6580

6681
require('util').log('Timestamped message.');
6782

68-
6983
## util.inspect(object, [options])
7084

7185
Return a string representation of `object`, which is useful for debugging.
@@ -94,6 +108,8 @@ Example of inspecting all properties of the `util` object:
94108

95109
### Customizing `util.inspect` colors
96110

111+
<!-- type=misc -->
112+
97113
Color output (if enabled) of `util.inspect` is customizable globally
98114
via `util.inspect.styles` and `util.inspect.colors` objects.
99115

@@ -116,6 +132,8 @@ There are also `bold`, `italic`, `underline` and `inverse` codes.
116132

117133
### Custom `inspect()` function on Objects
118134

135+
<!-- type=misc -->
136+
119137
Objects also may define their own `inspect(depth)` function which `util.inspect()`
120138
will invoke and use the result of when inspecting the object:
121139

@@ -198,17 +216,6 @@ Returns `true` if the given "object" is an `Error`. `false` otherwise.
198216
// false
199217

200218

201-
## util.pump(readableStream, writableStream, [callback])
202-
203-
Stability: 0 - Deprecated: Use readableStream.pipe(writableStream)
204-
205-
Read the data from `readableStream` and send it to the `writableStream`.
206-
When `writableStream.write(data)` returns `false` `readableStream` will be
207-
paused until the `drain` event occurs on the `writableStream`. `callback` gets
208-
an error as its only argument and is called when `writableStream` is closed or
209-
when an error occurs.
210-
211-
212219
## util.inherits(constructor, superConstructor)
213220

214221
Inherit the prototype methods from one
@@ -241,3 +248,35 @@ through the `constructor.super_` property.
241248
console.log('Received data: "' + data + '"');
242249
})
243250
stream.write("It works!"); // Received data: "It works!"
251+
252+
253+
## util.debug(string)
254+
255+
Stability: 0 - Deprecated: use console.error() instead.
256+
257+
Deprecated predecessor of `console.error`.
258+
259+
## util.error([...])
260+
261+
Stability: 0 - Deprecated: Use console.error() instead.
262+
263+
Deprecated predecessor of `console.error`.
264+
265+
## util.puts([...])
266+
267+
Stability: 0 - Deprecated: Use console.log() instead.
268+
269+
Deprecated predecessor of `console.log`.
270+
271+
## util.print([...])
272+
273+
Stability: 0 - Deprecated: Use `console.log` instead.
274+
275+
Deprecated predecessor of `console.log`.
276+
277+
278+
## util.pump(readableStream, writableStream, [callback])
279+
280+
Stability: 0 - Deprecated: Use readableStream.pipe(writableStream)
281+
282+
Deprecated predecessor of `stream.pipe()`.

‎lib/_http_client.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -205,7 +205,7 @@ function socketErrorListener(err) {
205205
var socket = this;
206206
var parser = socket.parser;
207207
var req = socket._httpMessage;
208-
debug('HTTP SOCKET ERROR: ' + err.message + '\n' + err.stack);
208+
debug('SOCKET ERROR:', err.message, err.stack);
209209

210210
if (req) {
211211
req.emit('error', err);
@@ -325,7 +325,7 @@ function parserOnIncomingClient(res, shouldKeepAlive) {
325325
// to the content-length of the entity-body had the request
326326
// been a GET.
327327
var isHeadResponse = req.method == 'HEAD';
328-
debug('AGENT isHeadResponse ' + isHeadResponse);
328+
debug('AGENT isHeadResponse', isHeadResponse);
329329

330330
if (res.statusCode == 100) {
331331
// restart the parser, as this is a continue message.

‎lib/_http_common.js‎

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -28,12 +28,7 @@ var readStart = incoming.readStart;
2828
var readStop = incoming.readStop;
2929

3030

31-
var debug;
32-
if (process.env.NODE_DEBUG && /http/.test(process.env.NODE_DEBUG)) {
33-
debug = function(x) { console.error('HTTP: %s', x); };
34-
} else {
35-
debug = function() { };
36-
}
31+
var debug = require('util').debuglog('http');
3732
exports.debug = debug;
3833

3934
exports.CRLF = '\r\n';

‎lib/module.js‎

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -62,12 +62,7 @@ Module.wrap = NativeModule.wrap;
6262

6363
var path = NativeModule.require('path');
6464

65-
Module._debug = function() {};
66-
if (process.env.NODE_DEBUG && /module/.test(process.env.NODE_DEBUG)) {
67-
Module._debug = function(x) {
68-
console.error(x);
69-
};
70-
}
65+
Module._debug = NativeModule.require('util').debuglog('module');
7166

7267

7368
// We use this alias for the preprocessor that filters it out

‎lib/net.js‎

Lines changed: 1 addition & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -51,20 +51,7 @@ function createHandle(fd) {
5151
}
5252

5353

54-
var debug;
55-
if (process.env.NODE_DEBUG && /net/.test(process.env.NODE_DEBUG)) {
56-
var pid = process.pid;
57-
debug = function(x) {
58-
// if console is not set up yet, then skip this.
59-
if (!console.error)
60-
return;
61-
console.error('NET: %d', pid,
62-
util.format.apply(util, arguments).slice(0, 500));
63-
};
64-
} else {
65-
debug = function() { };
66-
}
67-
54+
var debug = util.debuglog('net');
6855

6956
function isPipeName(s) {
7057
return typeof s === 'string' && toNumber(s) === false;

‎lib/timers.js‎

Lines changed: 5 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -26,12 +26,7 @@ var assert = require('assert').ok;
2626
// Timeout values > TIMEOUT_MAX are set to 1.
2727
var TIMEOUT_MAX = 2147483647; // 2^31-1
2828

29-
var debug;
30-
if (process.env.NODE_DEBUG && /timer/.test(process.env.NODE_DEBUG)) {
31-
debug = function() { require('util').error.apply(this, arguments); };
32-
} else {
33-
debug = function() { };
34-
}
29+
var debug = require('util').debuglog('timer');
3530

3631

3732
// IDLE TIMEOUTS
@@ -78,17 +73,17 @@ function listOnTimeout() {
7873
var msecs = this.msecs;
7974
var list = this;
8075

81-
debug('timeout callback ' + msecs);
76+
debug('timeout callback %d', msecs);
8277

8378
var now = Date.now();
84-
debug('now: ' + now);
79+
debug('now: %s', now);
8580

8681
var first;
8782
while (first = L.peek(list)) {
8883
var diff = now - first._idleStart;
8984
if (diff < msecs) {
9085
list.start(msecs - diff, 0);
91-
debug(msecs + ' list wait because diff is ' + diff);
86+
debug('%d list wait because diff is %d', msecs, diff);
9287
return;
9388
} else {
9489
L.remove(first);
@@ -121,7 +116,7 @@ function listOnTimeout() {
121116
}
122117
}
123118

124-
debug(msecs + ' list empty');
119+
debug('%d list empty', msecs);
125120
assert(L.isEmpty(list));
126121
list.close();
127122
delete lists[msecs];

‎lib/tls.js‎

Lines changed: 11 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -52,13 +52,7 @@ exports.getCiphers = function() {
5252
};
5353

5454

55-
var debug;
56-
if (process.env.NODE_DEBUG && /tls/.test(process.env.NODE_DEBUG)) {
57-
debug = function(a) { console.error('TLS:', a); };
58-
} else {
59-
debug = function() { };
60-
}
61-
55+
var debug = util.debuglog('tls');
6256

6357
var Connection = null;
6458
try {
@@ -328,10 +322,10 @@ CryptoStream.prototype._write = function write(data, encoding, cb) {
328322
// Write current buffer now
329323
var written;
330324
if (this === this.pair.cleartext) {
331-
debug('cleartext.write called with ' + data.length + ' bytes');
325+
debug('cleartext.write called with %d bytes', data.length);
332326
written = this.pair.ssl.clearIn(data, 0, data.length);
333327
} else {
334-
debug('encrypted.write called with ' + data.length + ' bytes');
328+
debug('encrypted.write called with %d bytes', data.length);
335329
written = this.pair.ssl.encIn(data, 0, data.length);
336330
}
337331

@@ -354,9 +348,9 @@ CryptoStream.prototype._write = function write(data, encoding, cb) {
354348
// Whole buffer was written
355349
if (written === data.length) {
356350
if (this === this.pair.cleartext) {
357-
debug('cleartext.write succeed with ' + data.length + ' bytes');
351+
debug('cleartext.write succeed with %d bytes', data.length);
358352
} else {
359-
debug('encrypted.write succeed with ' + data.length + ' bytes');
353+
debug('encrypted.write succeed with %d bytes', data.length);
360354
}
361355

362356
return cb(null);
@@ -375,9 +369,9 @@ CryptoStream.prototype._write = function write(data, encoding, cb) {
375369
this._pendingCallback = cb;
376370

377371
if (this === this.pair.cleartext) {
378-
debug('cleartext.write queued with ' + data.length + ' bytes');
372+
debug('cleartext.write queued with %d bytes', data.length);
379373
} else {
380-
debug('encrypted.write queued with ' + data.length + ' bytes');
374+
debug('encrypted.write queued with %d bytes', data.length);
381375
}
382376
};
383377

@@ -404,10 +398,10 @@ CryptoStream.prototype._read = function read(size) {
404398

405399
var out;
406400
if (this === this.pair.cleartext) {
407-
debug('cleartext.read called with ' + size + ' bytes');
401+
debug('cleartext.read called with %d bytes', size);
408402
out = this.pair.ssl.clearOut;
409403
} else {
410-
debug('encrypted.read called with ' + size + ' bytes');
404+
debug('encrypted.read called with %d bytes', size);
411405
out = this.pair.ssl.encOut;
412406
}
413407

@@ -437,9 +431,9 @@ CryptoStream.prototype._read = function read(size) {
437431
assert(bytesRead >= 0);
438432

439433
if (this === this.pair.cleartext) {
440-
debug('cleartext.read succeed with ' + bytesRead + ' bytes');
434+
debug('cleartext.read succeed with %d bytes', bytesRead);
441435
} else {
442-
debug('encrypted.read succeed with ' + bytesRead + ' bytes');
436+
debug('encrypted.read succeed with %d bytes', bytesRead);
443437
}
444438

445439
// Try writing pending data

0 commit comments

Comments
 (0)