add 'colors: boolean' property to Options

Author: rwe

lib/index.js

@@ -7,6 +7,8 @@
  *   Configuration.
  * @property {boolean | null | undefined} [showPositions=true]
  *   Whether to include positional information (default: `true`).
+ * @property {boolean | null | undefined} [colors]
+ *   Whether to include ANSI colors (default: `true` on Node, `false` otherwise).
  *
  * @typedef Style
  *   Styling functions.
@@ -27,42 +29,42 @@
  *   Rendering stylization.
  */
 
-import {color} from '#conditional-color'
+import {color as useColorByDefault} from '#conditional-color'
 
 /**
  * Inspect a node, with color in Node, without color in browsers.
  *
- * @param tree
- *   Tree to inspect.
- * @param options
- *   Configuration (optional).
- * @returns
- *   Pretty printed `tree`.
- */
-/* c8 ignore next */
-export const inspect = color ? inspectColor : inspectNoColor
-
-const own = {}.hasOwnProperty
-
-/**
- * Inspect a node, without color.
- *
  * @param {unknown} tree
  *   Tree to inspect.
  * @param {Options | null | undefined} [options]
  *   Configuration.
  * @returns {string}
  *   Pretty printed `tree`.
  */
-export function inspectNoColor(tree, options) {
+/* c8 ignore next */
+export function inspect(tree, options) {
+  const useColor =
+    !options || options.colors === null || options.colors === undefined
+      ? useColorByDefault
+      : options.colors
+
+  const style = useColor
+    ? {
+        bold: ansiColor(1, 22),
+        dim: ansiColor(2, 22),
+        yellow: ansiColor(33, 39),
+        green: ansiColor(32, 39)
+      }
+    : {
+        bold: noColor,
+        dim: noColor,
+        yellow: noColor,
+        green: noColor
+      }
+
   /** @type {State} */
   const state = {
-    style: {
-      bold: noColor,
-      dim: noColor,
-      yellow: noColor,
-      green: noColor
-    },
+    style,
     showPositions:
       !options ||
       options.showPositions === null ||
@@ -74,34 +76,48 @@ export function inspectNoColor(tree, options) {
   return inspectValue(tree, state)
 }
 
+const own = {}.hasOwnProperty
+
+/**
+ * Inspect a node, without color.
+ *
+ * @deprecated
+ *   Use `inspect` with the option `{colors: false}`.
+ *
+ * @param {unknown} tree
+ *   Tree to inspect.
+ * @param {Omit<Options, 'colors'> | null | undefined} [options]
+ *   Configuration.
+ * @returns {string}
+ *   Pretty printed `tree`.
+ */
+export function inspectNoColor(tree, options) {
+  /* c8 ignore next 3 */
+  const optionsWithNoColor = useColorByDefault
+    ? Object.assign({}, options, {colors: false})
+    : options
+  return inspect(tree, optionsWithNoColor)
+}
+
 /**
  * Inspects a node, using color.
  *
+ * @deprecated
+ *   Use `inspect` with the option `{colors: true}`.
+ *
  * @param {unknown} tree
  *   Tree to inspect.
- * @param {Options | null | undefined} [options]
+ * @param {Omit<Options, 'colors'> | null | undefined} [options]
  *   Configuration (optional).
  * @returns {string}
  *   Pretty printed `tree`.
  */
 export function inspectColor(tree, options) {
-  /** @type {State} */
-  const state = {
-    style: {
-      bold: ansiColor(1, 22),
-      dim: ansiColor(2, 22),
-      yellow: ansiColor(33, 39),
-      green: ansiColor(32, 39)
-    },
-    showPositions:
-      !options ||
-      options.showPositions === null ||
-      options.showPositions === undefined
-        ? true
-        : options.showPositions
-  }
-
-  return inspectValue(tree, state)
+  /* c8 ignore next 3 */
+  const optionsWithColor = useColorByDefault
+    ? options
+    : Object.assign({}, options, {colors: true})
+  return inspect(tree, optionsWithColor)
 }
 
 /**

test.js

@@ -18,6 +18,16 @@ const chalkEnabled = new Chalk({level: 1})
 
 const paragraph = 'Some simple text. Other “sentence”.'
 
+/**
+ * Split `text` on newlines, keeping the first `count`.
+ *
+ * @param {string} text
+ * @param {number} count
+ * @return string
+ *   The first `count` lines of `text`.
+ */
+const lines = (text, count) => text.split('\n').slice(0, count).join('\n')
+
 test('inspect()', async function (t) {
   await t.test('should expose the public api', async function () {
     assert.deepEqual(Object.keys(await import('unist-util-inspect')).sort(), [
@@ -420,6 +430,51 @@ test('inspect()', async function (t) {
       ].join('\n')
     )
   })
+
+  await t.test('inspect(…, {colors: false})', async function () {
+    assert.equal(
+      lines(inspect(retext().parse(paragraph), {colors: false}), 2),
+      [
+        'RootNode[1] (1:1-1:36, 0-35)',
+        '└─0 ParagraphNode[3] (1:1-1:36, 0-35)'
+      ].join('\n')
+    )
+  })
+
+  await t.test(
+    'inspect(…, {colors?: true | null | undefined})',
+    async function () {
+      const expectedOutput = [
+        chalkEnabled.bold('RootNode') +
+          chalkEnabled.dim('[') +
+          chalkEnabled.yellow('1') +
+          chalkEnabled.dim(']') +
+          ' ' +
+          chalkEnabled.dim('(') +
+          '1:1-1:36, 0-35' +
+          chalkEnabled.dim(')'),
+        chalkEnabled.dim('└─0') +
+          ' ' +
+          chalkEnabled.bold('ParagraphNode') +
+          chalkEnabled.dim('[') +
+          chalkEnabled.yellow('3') +
+          chalkEnabled.dim(']') +
+          ' ' +
+          chalkEnabled.dim('(') +
+          '1:1-1:36, 0-35' +
+          chalkEnabled.dim(')')
+      ].join('\n')
+
+      const parsed = retext().parse(paragraph)
+
+      assert.equal(lines(inspect(parsed, {colors: true}), 2), expectedOutput)
+      assert.equal(lines(inspect(parsed, {colors: null}), 2), expectedOutput)
+      assert.equal(
+        lines(inspect(parsed, {colors: undefined}), 2),
+        expectedOutput
+      )
+    }
+  )
 })
 
 test('inspectNoColor()', async function () {