1 | # Dedent
|
2 |
|
3 | An ES6 string tag that strips indentation from multi-line strings.
|
4 |
|
5 | ## Usage
|
6 |
|
7 | ```js
|
8 | import dedent from "dedent";
|
9 |
|
10 | function usageExample() {
|
11 | const first = dedent`A string that gets so long you need to break it over
|
12 | multiple lines. Luckily dedent is here to keep it
|
13 | readable without lots of spaces ending up in the string
|
14 | itself.`;
|
15 |
|
16 | const second = dedent`
|
17 | Leading and trailing lines will be trimmed, so you can write something like
|
18 | this and have it work as you expect:
|
19 |
|
20 | * how convenient it is
|
21 | * that I can use an indented list
|
22 | - and still have it do the right thing
|
23 |
|
24 | That's all.
|
25 | `;
|
26 |
|
27 | const third = dedent(`
|
28 | Wait! I lied. Dedent can also be used as a function.
|
29 | `);
|
30 |
|
31 | return first + "\n\n" + second + "\n\n" + third;
|
32 | }
|
33 | ```
|
34 |
|
35 | ```js
|
36 | > console.log(usageExample());
|
37 | ```
|
38 |
|
39 | ```
|
40 | A string that gets so long you need to break it over
|
41 | multiple lines. Luckily dedent is here to keep it
|
42 | readable without lots of spaces ending up in the string
|
43 | itself.
|
44 |
|
45 | Leading and trailing lines will be trimmed, so you can write something like
|
46 | this and have it work as you expect:
|
47 |
|
48 | * how convenient it is
|
49 | * that I can use an indented list
|
50 | - and still have it do the right thing
|
51 |
|
52 | That's all.
|
53 |
|
54 | Wait! I lied. Dedent can also be used as a function.
|
55 | ```
|
56 |
|
57 | ## Options
|
58 |
|
59 | You can customize the options `dedent` runs with by calling its `withOptions` method with an object:
|
60 |
|
61 |
|
62 | ```js
|
63 | import dedent from 'dedent';
|
64 |
|
65 | dedent.withOptions({ /* ... */ })`input`;
|
66 | dedent.withOptions({ /* ... */ })(`input`);
|
67 | ```
|
68 |
|
69 | `options` returns a new `dedent` function, so if you'd like to reuse the same options, you can create a dedicated `dedent` function:
|
70 |
|
71 |
|
72 | ```js
|
73 | import dedent from 'dedent';
|
74 |
|
75 | const dedenter = dedent.withOptions({ /* ... */ });
|
76 |
|
77 | dedenter`input`;
|
78 | dedenter(`input`);
|
79 | ```
|
80 |
|
81 | ### `escapeSpecialCharacters`
|
82 |
|
83 | JavaScript string tags by default add an extra `\` escape in front of some special characters such as `$` dollar signs.
|
84 | `dedent` will escape those special characters when called as a string tag.
|
85 |
|
86 | If you'd like to change the behavior, an `escapeSpecialCharacters` option is available.
|
87 | It defaults to:
|
88 |
|
89 | - `false`: when `dedent` is called as a function
|
90 | - `true`: when `dedent` is called as a string tag
|
91 |
|
92 | ```js
|
93 | import dedent from "dedent";
|
94 |
|
95 | // "$hello!"
|
96 | dedent`
|
97 | $hello!
|
98 | `;
|
99 |
|
100 | // "\$hello!"
|
101 | dedent.withOptions({ escapeSpecialCharacters: false })`
|
102 | $hello!
|
103 | `;
|
104 |
|
105 | // "$hello!"
|
106 | dedent.withOptions({ escapeSpecialCharacters: true })`
|
107 | $hello!
|
108 | `;
|
109 | ```
|
110 |
|
111 | For more context, see [https://github.com/dmnd/dedent/issues/63](🚀 Feature: Add an option to disable special character escaping).
|
112 |
|
113 | ## License
|
114 |
|
115 | MIT
|