|
| 1 | +/* |
| 2 | + MIT License |
| 3 | +
|
| 4 | + Copyright (c) Microsoft Corporation. |
| 5 | +
|
| 6 | + Permission is hereby granted, free of charge, to any person obtaining a copy |
| 7 | + of this software and associated documentation files (the "Software"), to deal |
| 8 | + in the Software without restriction, including without limitation the rights |
| 9 | + to use, copy, modify, merge, publish, distribute, sublicense, and/or sell |
| 10 | + copies of the Software, and to permit persons to whom the Software is |
| 11 | + furnished to do so, subject to the following conditions: |
| 12 | +
|
| 13 | + The above copyright notice and this permission notice shall be included in all |
| 14 | + copies or substantial portions of the Software. |
| 15 | +
|
| 16 | + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
| 17 | + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
| 18 | + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
| 19 | + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
| 20 | + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, |
| 21 | + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE |
| 22 | + SOFTWARE |
| 23 | + */ |
| 24 | + |
| 25 | +type Transform = (str: string) => string; |
| 26 | + |
| 27 | +interface Options { |
| 28 | + /** |
| 29 | + * Limit the length of the input string. Useful when the input string is generated or your application allows |
| 30 | + * users to pass a string, et cetera. |
| 31 | + * |
| 32 | + * @default 65536 |
| 33 | + * @example |
| 34 | + * console.log(braces('a/{b,c}/d', { maxLength: 3 })); |
| 35 | + * //=> throws an error |
| 36 | + */ |
| 37 | + maxLength?: number | undefined; |
| 38 | + /** |
| 39 | + * Generate an "expanded" brace pattern (alternatively you can use the `braces.expand()` method). |
| 40 | + * |
| 41 | + * @default undefined |
| 42 | + * @example |
| 43 | + * console.log(braces('a/{b,c}/d', { expand: true })); |
| 44 | + * //=> [ 'a/b/d', 'a/c/d' ] |
| 45 | + */ |
| 46 | + expand?: boolean | undefined; |
| 47 | + /** |
| 48 | + * Remove duplicates from the returned array. |
| 49 | + * |
| 50 | + * @default undefined |
| 51 | + */ |
| 52 | + nodupes?: boolean | undefined; |
| 53 | + /** |
| 54 | + * To prevent malicious patterns from being passed by users, an error is thrown when `braces.expand()` |
| 55 | + * is used or `options.expand` is true and the generated range will exceed the `rangeLimit`. |
| 56 | + * |
| 57 | + * You can customize `options.rangeLimit` or set it to `Infinity` to disable this altogether. |
| 58 | + * |
| 59 | + * @default 1000 |
| 60 | + * @example |
| 61 | + * // pattern exceeds the "rangeLimit", so it's optimized automatically |
| 62 | + * console.log(braces.expand('{1..1000}')); |
| 63 | + * //=> ['([1-9]|[1-9][0-9]{1,2}|1000)'] |
| 64 | + * |
| 65 | + * // pattern does not exceed "rangeLimit", so it's NOT optimized |
| 66 | + * console.log(braces.expand('{1..100}')); |
| 67 | + * //=> ['1', '2', '3', '4', '5', …, '100'] |
| 68 | + */ |
| 69 | + rangeLimit?: number | undefined; |
| 70 | + /** |
| 71 | + * Customize range expansion. |
| 72 | + * |
| 73 | + * @default undefined |
| 74 | + * @example |
| 75 | + * const range = braces.expand('x{a..e}y', { |
| 76 | + * transform: (str) => `foo/${str}` |
| 77 | + * }); |
| 78 | + * |
| 79 | + * console.log(range); |
| 80 | + * //=> [ 'xfooay', 'xfooby', 'xfoocy', 'xfoody', 'xfooey' ] |
| 81 | + */ |
| 82 | + transform?: Transform | undefined; |
| 83 | + /** |
| 84 | + * In regular expressions, quanitifiers can be used to specify how many times a token can be repeated. |
| 85 | + * For example, `a{1,3}` will match the letter `a` one to three times. |
| 86 | + * |
| 87 | + * Unfortunately, regex quantifiers happen to share the same syntax as [Bash lists](#lists) |
| 88 | + * |
| 89 | + * The `quantifiers` option tells braces to detect when [regex quantifiers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#quantifiers) |
| 90 | + * are defined in the given pattern, and not to try to expand them as lists. |
| 91 | + * |
| 92 | + * @default undefined |
| 93 | + * @example |
| 94 | + * const braces = require('braces'); |
| 95 | + * console.log(braces('a/b{1,3}/{x,y,z}')); |
| 96 | + * //=> [ 'a/b(1|3)/(x|y|z)' ] |
| 97 | + * console.log(braces('a/b{1,3}/{x,y,z}', {quantifiers: true})); |
| 98 | + * //=> [ 'a/b{1,3}/(x|y|z)' ] |
| 99 | + * console.log(braces('a/b{1,3}/{x,y,z}', {quantifiers: true, expand: true})); |
| 100 | + * //=> [ 'a/b{1,3}/x', 'a/b{1,3}/y', 'a/b{1,3}/z' ] |
| 101 | + */ |
| 102 | + quantifiers?: boolean | undefined; |
| 103 | + /** |
| 104 | + * Do not strip backslashes that were used for escaping from the result. |
| 105 | + * |
| 106 | + * @default undefined |
| 107 | + */ |
| 108 | + keepEscaping?: boolean | undefined; |
| 109 | + /** |
| 110 | + * Do not strip quotes from the result. |
| 111 | + * |
| 112 | + * @default undefined |
| 113 | + */ |
| 114 | + keepQuotes?: boolean | undefined; |
| 115 | +} |
| 116 | + |
| 117 | +// Ambient type override for braces to allow string or string[] as pattern |
| 118 | +declare module "braces" { |
| 119 | + function braces(pattern: string | string[], options?: Options): string[]; |
| 120 | + |
| 121 | + namespace braces { |
| 122 | + function expand(pattern: string | string[], options?: Omit<Options, "expand">): string[]; |
| 123 | + } |
| 124 | + |
| 125 | + export default braces; |
| 126 | +} |
0 commit comments