Better documentation of escape characters to avoid: throw new Error('Found extraneous } in Chalk template literal');

[zmorris]

Hi I hit this error while using template literals for a long string. I'm coming at this from a backend PHP and shell programming perspective where heredoc syntax (EOF, 'EOF') is often used when working with multiline text verbatim.

Anyway, the closest thing to that in Javascript is template literals using backticks. But since they're interpolated before Chalk receives them, it can be difficult to find the right escape sequence that provides proper formatting without triggering parsing errors. Also, some packages apply multiple levels of template parsing and character escaping, which makes it difficult to derive the exact incantation.

The project's readme.md barely mentions curly braces or escape characters. And so far even project issues don't reveal much:

chalk/chalk#498
chalk/chalk#349

I usually try every permutation of {{, \{, \\{, \{{, \\{{, etc. But sometimes things refuse to cooperate, and once programming becomes a random walk like that, it's better to reference a pre-built table of working examples. Which is why I'd like to see more open source projects adopt a third person view of themselves and understand that the smallest breadcrumbs can save their users many hours or sometimes even days of work. So I'm going to list some working examples here, and hopefully other people can add more permutations as they discover what works for other packages that use Chalk:

const chalk = require('chalk');

console.log(chalk`Hello, ${'world'}!`);

const chalk = require('chalk');

console.log(chalk`puppeteer.launch(\{ headless: false \}`);

const commandLineUsage = require('command-line-usage'); // uses chalk internally

const sections = [{
  content: `puppeteer.launch(\\{ headless: false \\}`
}];

console.log(commandLineUsage(sections));

[Qix-]

The first example uses template literal escapes, which are a Javascript feature.

The second example uses escapes as we parse raw strings from the template string. I don't see how that required a bunch of effort to test, honestly. But you're right, it would be beneficial to mention in the readme.

The third example is a third-party library, I don't see how it's relevant. If you don't like that you need \\ then use String.raw:

String.raw`this\{should\}work`

Which, again, is a Javascript feature. It's not dictated by Chalk.

---

However, I want to address one other thing in your post:

Which is why I'd like to see more open source projects adopt a third person view of themselves and understand that the smallest breadcrumbs can save their users many hours or sometimes even days of work.

I'm sorry, but claiming this caused you hours or days of work when it's something trivially tested in the console is a bit unfair. To imply that we're not doing enough as maintainers is a bit rude given that we do this on our free time, for free, and make it available to you to use as you please - including commercially. Please consider that when making future comments on Github.

We are also users of our own libraries, and since Chalk has millions of downloads a day and has had template support for a long time now, it's pretty safe to assume problems like this come up rarely enough.

---

Feel free to open a PR to add a mention of the bracket escapes.