util: add util.inspect compact option

The current default formatting is not ideal and this improves the situation by formatting the output more intuitiv. 1) All object keys are now indented by 2 characters instead of sometimes 2 and sometimes 3 characters. 2) Each object key will now use an individual line instead of sharing a line potentially with multiple object keys. 3) Long strings will now be split into multiple lines in case they exceed the "lineBreak" option length (including the current indentation). 4) Opening braces are now directly behind a object property instead of using a new line. 5) Switch inspect "base" order. In case the compact option is set to `false`, inspect will now print "[Function: foo]{\n property: 'data'\n}" instead of "{[Function: foo]\n property: 'data'\n}". Backport-PR-URL: #19230 PR-URL: #17576 Reviewed-By: Anna Henningsen <[email protected]>

Author: BridgeAR

doc/api/util.md

@@ -316,6 +316,9 @@ stream.write('With ES6');
 <!-- YAML
 added: v0.3.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/REPLACEME
+ description: The `compact` option is supported now.
  - version: v6.6.0
  pr-url: https://github.com/nodejs/node/pull/8174
  description: Custom inspection functions can now return `this`.
@@ -353,6 +356,13 @@ changes:
 *`breakLength`{number} The length at which an object's keys are split
  across multiple lines. Set to `Infinity` to format an object as a single
  line. Defaults to 60 for legacy compatibility.
+*`compact`{boolean} Setting this to `false` changes the default indentation
+ to use a line break for each object key instead of lining up multiple
+ properties in one line. It will also break text that is above the
+`breakLength` size into smaller and better readable chunks and indents
+ objects the same as arrays. Note that no text will be reduced below 16
+ characters, no matter the `breakLength` size. For more information, see the
+ example below. Defaults to `true`.
 
 The `util.inspect()` method returns a string representation of `object` that is
 primarily useful for debugging. Additional `options` may be passed that alter
@@ -370,6 +380,63 @@ Values may supply their own custom `inspect(depth, opts)` functions, when
 called these receive the current `depth` in the recursive inspection, as well as
 the options object passed to `util.inspect()`.
 
+The following example highlights the difference with the `compact` option:
+
+```js
+constutil=require('util');
+
+consto={
+ a: [1, 2, [[
+'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do '+
+'eiusmod tempor incididunt ut labore et dolore magna aliqua.',
+'test',
+'foo']], 4],
+ b:newMap([['za', 1], ['zb', 'test']])
+};
+console.log(util.inspect(o,{compact:true, depth:5, breakLength:80 }));
+
+// This will print
+
+//{a:
+// [ 1,
+// 2,
+// [ [ 'Lorem ipsum dolor sit amet, consectetur [...]', // A long line
+// 'test',
+// 'foo' ] ],
+// 4 ],
+// b: Map{'za' => 1, 'zb' => 'test'} }
+
+// Setting `compact` to false changes the output to be more reader friendly.
+console.log(util.inspect(o,{compact:false, depth:5, breakLength:80 }));
+
+//{
+// a: [
+// 1,
+// 2,
+// [
+// [
+// 'Lorem ipsum dolor sit amet, consectetur ' +
+// 'adipiscing elit, sed do eiusmod tempor ' +
+// 'incididunt ut labore et dolore magna ' +
+// 'aliqua.,
+// 'test',
+// 'foo'
+// ]
+// ],
+// 4
+// ],
+// b: Map{
+// 'za' => 1,
+// 'zb' => 'test'
+// }
+// }
+
+// Setting `breakLength` to e.g. 150 will print the "Lorem ipsum" text in a
+// single line.
+// Reducing the `breakLength` will split the "Lorem ipsum" text in smaller
+// chunks.
+```
+
 ### Customizing `util.inspect` colors
 
 <!-- type=misc -->

lib/util.js

@@ -68,7 +68,8 @@ const inspectDefaultOptions = Object.seal({
 customInspect: true,
 showProxy: false,
 maxArrayLength: 100,
-breakLength: 60
+breakLength: 60,
+compact: true
 });
 
 constpropertyIsEnumerable=Object.prototype.propertyIsEnumerable;
@@ -86,6 +87,10 @@ const strEscapeSequencesReplacer = /[\x00-\x1f\x27\x5c]/g;
 constkeyStrRegExp=/^[a-zA-Z_][a-zA-Z_0-9]*$/;
 constnumberRegExp=/^(0|[1-9][0-9]*)$/;
 
+constreadableRegExps={};
+
+constMIN_LINE_LENGTH=16;
+
 // Escaped special characters. Use empty strings to fill up unused entries.
 constmeta=[
 '\\u0000','\\u0001','\\u0002','\\u0003','\\u0004',
@@ -276,7 +281,8 @@ function inspect(value, opts){
 showProxy: inspectDefaultOptions.showProxy,
 maxArrayLength: inspectDefaultOptions.maxArrayLength,
 breakLength: inspectDefaultOptions.breakLength,
-indentationLvl: 0
+indentationLvl: 0,
+compact: inspectDefaultOptions.compact
 };
 // Legacy...
 if(arguments.length>2){
@@ -374,7 +380,7 @@ function ensureDebugIsInitialized(){
 functionformatValue(ctx,value,recurseTimes,ln){
 // Primitive types cannot have properties
 if(typeofvalue!=='object'&&typeofvalue!=='function'){
-returnformatPrimitive(ctx.stylize,value);
+returnformatPrimitive(ctx.stylize,value,ctx);
 }
 if(value===null){
 returnctx.stylize('null','null');
@@ -481,10 +487,10 @@ function formatValue(ctx, value, recurseTimes, ln){
 }catch(e){/* ignore */}
 
 if(typeofraw==='string'){
-constformatted=formatPrimitive(stylizeNoColor,raw);
+constformatted=formatPrimitive(stylizeNoColor,raw,ctx);
 if(keyLength===raw.length)
 returnctx.stylize(`[String: ${formatted}]`,'string');
-base=`[String: ${formatted}]`;
+base=`[String: ${formatted}]`;
 // For boxed Strings, we have to remove the 0-n indexed entries,
 // since they just noisy up the output and are redundant
 // Make boxed primitive Strings look like such
@@ -505,25 +511,25 @@ function formatValue(ctx, value, recurseTimes, ln){
 constname=`${constructor.name}${value.name ? `: ${value.name}` : ''}`;
 if(keyLength===0)
 returnctx.stylize(`[${name}]`,'special');
-base=`[${name}]`;
+base=`[${name}]`;
 }elseif(isRegExp(value)){
 // Make RegExps say that they are RegExps
 if(keyLength===0||recurseTimes<0)
 returnctx.stylize(regExpToString.call(value),'regexp');
-base=`${regExpToString.call(value)}`;
+base=`${regExpToString.call(value)}`;
 }elseif(isDate(value)){
 if(keyLength===0){
 if(Number.isNaN(value.getTime()))
 returnctx.stylize(value.toString(),'date');
 returnctx.stylize(dateToISOString.call(value),'date');
 }
 // Make dates with properties first say the date
-base=`${dateToISOString.call(value)}`;
+base=`${dateToISOString.call(value)}`;
 }elseif(isError(value)){
 // Make error with message first say the error
 if(keyLength===0)
 returnformatError(value);
-base=`${formatError(value)}`;
+base=`${formatError(value)}`;
 }elseif(isAnyArrayBuffer(value)){
 // Fast path for ArrayBuffer and SharedArrayBuffer.
 // Can't do the same for DataView because it has a non-primitive
@@ -553,13 +559,13 @@ function formatValue(ctx, value, recurseTimes, ln){
 constformatted=formatPrimitive(stylizeNoColor,raw);
 if(keyLength===0)
 returnctx.stylize(`[Number: ${formatted}]`,'number');
-base=`[Number: ${formatted}]`;
+base=`[Number: ${formatted}]`;
 }elseif(typeofraw==='boolean'){
 // Make boxed primitive Booleans look like such
 constformatted=formatPrimitive(stylizeNoColor,raw);
 if(keyLength===0)
 returnctx.stylize(`[Boolean: ${formatted}]`,'boolean');
-base=`[Boolean: ${formatted}]`;
+base=`[Boolean: ${formatted}]`;
 }elseif(typeofraw==='symbol'){
 constformatted=formatPrimitive(stylizeNoColor,raw);
 returnctx.stylize(`[Symbol: ${formatted}]`,'symbol');
@@ -603,9 +609,42 @@ function formatNumber(fn, value){
 returnfn(`${value}`,'number');
 }
 
-functionformatPrimitive(fn,value){
-if(typeofvalue==='string')
+functionformatPrimitive(fn,value,ctx){
+if(typeofvalue==='string'){
+if(ctx.compact===false&&
+value.length>MIN_LINE_LENGTH&&
+ctx.indentationLvl+value.length>ctx.breakLength){
+// eslint-disable-next-line max-len
+constminLineLength=Math.max(ctx.breakLength-ctx.indentationLvl,MIN_LINE_LENGTH);
+// eslint-disable-next-line max-len
+constaverageLineLength=Math.ceil(value.length/Math.ceil(value.length/minLineLength));
+constdivisor=Math.max(averageLineLength,MIN_LINE_LENGTH);
+varres='';
+if(readableRegExps[divisor]===undefined){
+// Build a new RegExp that naturally breaks text into multiple lines.
+//
+// Rules
+// 1. Greedy match all text up the max line length that ends with a
+// whitespace or the end of the string.
+// 2. If none matches, non-greedy match any text up to a whitespace or
+// the end of the string.
+//
+// eslint-disable-next-line max-len, no-unescaped-regexp-dot
+readableRegExps[divisor]=newRegExp(`(.|\\n){1,${divisor}}(\\s|$)|(\\n|.)+?(\\s|$)`,'gm');
+}
+constindent=' '.repeat(ctx.indentationLvl);
+constmatches=value.match(readableRegExps[divisor]);
+if(matches.length>1){
+res+=`${fn(strEscape(matches[0]),'string')} +\n`;
+for(vari=1;i<matches.length-1;i++){
+res+=`${indent}${fn(strEscape(matches[i]),'string')} +\n`;
+}
+res+=`${indent}${fn(strEscape(matches[i]),'string')}`;
+returnres;
+}
+}
 returnfn(strEscape(value),'string');
+}
 if(typeofvalue==='number')
 returnformatNumber(fn,value);
 if(typeofvalue==='boolean')
@@ -806,7 +845,7 @@ function formatProperty(ctx, value, recurseTimes, key, array){
 constdesc=Object.getOwnPropertyDescriptor(value,key)||
 {value: value[key],enumerable: true};
 if(desc.value!==undefined){
-constdiff=array===0? 3 : 2;
+constdiff=array!==0||ctx.compact===false ? 2 : 3;
 ctx.indentationLvl+=diff;
 str=formatValue(ctx,desc.value,recurseTimes,array===0);
 ctx.indentationLvl-=diff;
@@ -839,25 +878,36 @@ function formatProperty(ctx, value, recurseTimes, key, array){
 
 functionreduceToSingleString(ctx,output,base,braces,addLn){
 constbreakLength=ctx.breakLength;
+vari=0;
+if(ctx.compact===false){
+constindentation=' '.repeat(ctx.indentationLvl);
+varres=`${base ? `${base} ` : ''}${braces[0]}\n${indentation} `;
+for(;i<output.length-1;i++){
+res+=`${output[i]},\n${indentation} `;
+}
+res+=`${output[i]}\n${indentation}${braces[1]}`;
+returnres;
+}
 if(output.length*2<=breakLength){
 varlength=0;
-for(vari=0;i<output.length&&length<=breakLength;i++){
+for(;i<output.length&&length<=breakLength;i++){
 if(ctx.colors){
 length+=removeColors(output[i]).length+1;
 }else{
 length+=output[i].length+1;
 }
 }
 if(length<=breakLength)
-return`${braces[0]}${base}${join(output,', ')}${braces[1]}`;
+return`${braces[0]}${base ? ` ${base}` : ''}${join(output,', ')} `+
+braces[1];
 }
 // If the opening "brace" is too large, like in the case of "Set{",
 // we need to force the first item to be on the next line or the
 // items will not line up correctly.
 constindentation=' '.repeat(ctx.indentationLvl);
 constextraLn=addLn===true ? `\n${indentation}` : '';
 constln=base===''&&braces[0].length===1 ?
-' ' : `${base}\n${indentation} `;
+' ' : `${base ? ` ${base}` : base}\n${indentation} `;
 conststr=join(output,`,\n${indentation} `);
 return`${extraLn}${braces[0]}${ln}${str}${braces[1]}`;
 }