feat: add options with escapeSpecialCharacters (#65)

Fixes #26. Fixes #63.

As described in #63, this introduces the concept of options with single
option, `escapeSpecialCharacters`. The option defaults to:

* `true` when called for a template literal's string tag
* `false` when called as a function

```js
// "\$hello!"
dedent.options({ escapeSpecialCharacters: false })`
  $hello!
`;
```

I'd played with allowing passing it in as a first argument instead of a
string or template literal strings array, but that got complex. I
suppose we can do that as a followup if people really want.

cc @G-Rath @sirian - what do you think?

Author: JoshuaKGoldberg

README.md

@@ -54,6 +54,62 @@ That's all.
 Wait! I lied. Dedent can also be used as a function.
 ```
 
+## Options
+
+You can customize the options `dedent` runs with by calling its `withOptions` method with an object:
+
+<!-- prettier-ignore -->
+```js
+import dedent from 'dedent';
+
+dedent.withOptions({ /* ... */ })`input`;
+dedent.withOptions({ /* ... */ })(`input`);
+```
+
+`options` returns a new `dedent` function, so if you'd like to reuse the same options, you can create a dedicated `dedent` function:
+
+<!-- prettier-ignore -->
+```js
+import dedent from 'dedent';
+
+const dedenter = dedent.withOptions({ /* ... */ });
+
+dedenter`input`;
+dedenter(`input`);
+```
+
+### `escapeSpecialCharacters`
+
+JavaScript string tags by default add an extra `\` escape in front of some special characters such as `$` dollar signs.
+`dedent` will escape those special characters when called as a string tag.
+
+If you'd like to change the behavior, an `escapeSpecialCharacters` option is available.
+It defaults to:
+
+- `false`: when `dedent` is called as a function
+- `true`: when `dedent` is called as a string tag
+
+```js
+import dedent from "dedent";
+
+// "$hello!"
+dedent`
+  $hello!
+`;
+
+// "\$hello!"
+dedent.withOptions({ escapeSpecialCharacters: false })`
+  $hello!
+`;
+
+// "$hello!"
+dedent.withOptions({ escapeSpecialCharacters: true })`
+  $hello!
+`;
+```
+
+For more context, see [https://github.com/dmnd/dedent/issues/63](🚀 Feature: Add an option to disable special character escaping).
+
 ## License
 
 MIT

__tests__/__snapshots__/dedent-tests.ts.snap

@@ -2,32 +2,100 @@
 
 exports[`dedent can be used as a function 1`] = `"A test argument."`;
 
-exports[`dedent doesn't strip exlicit newlines 1`] = `
+exports[`dedent doesn't strip explicit newlines 1`] = `
 "<p>Hello world!</p>
 "
 `;
 
-exports[`dedent doesn't strip exlicit newlines with mindent 1`] = `
+exports[`dedent doesn't strip explicit newlines with mindent 1`] = `
 "<p>
   Hello world!
 </p>
 "
 `;
 
-exports[`dedent escapes backticks 1`] = `"\`"`;
+exports[`dedent function character escapes default behavior does not escape backticks 1`] = `"\`"`;
 
-exports[`dedent escapes dollar signs 1`] = `"$"`;
+exports[`dedent function character escapes default behavior does not escape dollar signs 1`] = `"$"`;
 
-exports[`dedent escapes opening braces 1`] = `"{"`;
+exports[`dedent function character escapes default behavior does not escape opening braces 1`] = `"{"`;
 
-exports[`dedent ignores closing braces 1`] = `"\\}"`;
+exports[`dedent function character escapes default behavior escapes double-escaped backticks 1`] = `"\\\`"`;
+
+exports[`dedent function character escapes default behavior escapes double-escaped dollar signs 1`] = `"\\$"`;
+
+exports[`dedent function character escapes default behavior escapes double-escaped opening braces 1`] = `"\\{"`;
+
+exports[`dedent function character escapes default behavior ignores closing braces 1`] = `"}"`;
+
+exports[`dedent function character escapes with escapeSpecialCharacters false backticks 1`] = `"\`"`;
+
+exports[`dedent function character escapes with escapeSpecialCharacters false dollar signs 1`] = `"$"`;
+
+exports[`dedent function character escapes with escapeSpecialCharacters false double-escaped backticks 1`] = `"\\\`"`;
+
+exports[`dedent function character escapes with escapeSpecialCharacters false double-escaped dollar signs 1`] = `"\\$"`;
+
+exports[`dedent function character escapes with escapeSpecialCharacters false double-escaped opening braces 1`] = `"\\{"`;
+
+exports[`dedent function character escapes with escapeSpecialCharacters false opening braces 1`] = `"{"`;
+
+exports[`dedent function character escapes with escapeSpecialCharacters true backticks 1`] = `"\`"`;
+
+exports[`dedent function character escapes with escapeSpecialCharacters true dollar signs 1`] = `"$"`;
+
+exports[`dedent function character escapes with escapeSpecialCharacters true double-escaped backticks 1`] = `"\`"`;
+
+exports[`dedent function character escapes with escapeSpecialCharacters true double-escaped dollar signs 1`] = `"$"`;
+
+exports[`dedent function character escapes with escapeSpecialCharacters true double-escaped opening braces 1`] = `"{"`;
+
+exports[`dedent function character escapes with escapeSpecialCharacters true opening braces 1`] = `"{"`;
+
+exports[`dedent function character escapes with escapeSpecialCharacters undefined backticks 1`] = `"\`"`;
+
+exports[`dedent function character escapes with escapeSpecialCharacters undefined dollar signs 1`] = `"$"`;
+
+exports[`dedent function character escapes with escapeSpecialCharacters undefined double-escaped backticks 1`] = `"\\\`"`;
+
+exports[`dedent function character escapes with escapeSpecialCharacters undefined double-escaped dollar signs 1`] = `"\\$"`;
+
+exports[`dedent function character escapes with escapeSpecialCharacters undefined double-escaped opening braces 1`] = `"\\{"`;
+
+exports[`dedent function character escapes with escapeSpecialCharacters undefined opening braces 1`] = `"{"`;
 
 exports[`dedent single line input works with single line and closing backtick on newline 1`] = `"A single line of input."`;
 
 exports[`dedent single line input works with single line and inline closing backtick 1`] = `"A single line of input."`;
 
 exports[`dedent single line input works with single line input 1`] = `"A single line of input."`;
 
+exports[`dedent string tag character escapes default behavior escapes backticks 1`] = `"\`"`;
+
+exports[`dedent string tag character escapes default behavior escapes dollar signs 1`] = `"$"`;
+
+exports[`dedent string tag character escapes default behavior escapes opening braces 1`] = `"{"`;
+
+exports[`dedent string tag character escapes default behavior ignores closing braces 1`] = `"\\}"`;
+
+exports[`dedent string tag character escapes with escapeSpecialCharacters false backticks 1`] = `"\\\`"`;
+
+exports[`dedent string tag character escapes with escapeSpecialCharacters false dollar signs 1`] = `"\\$"`;
+
+exports[`dedent string tag character escapes with escapeSpecialCharacters false opening braces 1`] = `"\\{"`;
+
+exports[`dedent string tag character escapes with escapeSpecialCharacters true backticks 1`] = `"\`"`;
+
+exports[`dedent string tag character escapes with escapeSpecialCharacters true dollar signs 1`] = `"$"`;
+
+exports[`dedent string tag character escapes with escapeSpecialCharacters true opening braces 1`] = `"{"`;
+
+exports[`dedent string tag character escapes with escapeSpecialCharacters undefined backticks 1`] = `"\`"`;
+
+exports[`dedent string tag character escapes with escapeSpecialCharacters undefined dollar signs 1`] = `"$"`;
+
+exports[`dedent string tag character escapes with escapeSpecialCharacters undefined opening braces 1`] = `"{"`;
+
 exports[`dedent works with blank first line 1`] = `
 "Some text that I might want to indent:
   * reasons