braces

JavaScript で実装された Bash ライクなブレース展開。他のブレース展開ライブラリよりも安全で、速度を犠牲にすることなく Bash 4.3 のブレース仕様を完全にサポートします。

このプロジェクトの作者 Jon Schlinkert をフォローし、プロジェクトにスターを付けて ❤️ とサポートを示すことをご検討ください。

インストール

npm でインストールします:

$ npm install --save braces

v3.0.0 リリース!!

詳細は変更履歴を参照してください。

なぜ braces を使うのか?

ブレースパターンは、特定の範囲や文字シーケンスにマッチする機能を追加することで、glob をより強力にします。

• 正確 - Bash 4.3 Brace Expansion 仕様を完全にサポートしています (Bash のブレースに関するすべてのテストに合格)
• 高速で高性能 - 起動が速く、実行も速く、パターンが複雑になってもスケールします。
• 整理されたコードベース - エッジケースが発生した際に、パーサーとコンパイラーを簡単に保守・更新できます。
• 十分にテスト済み - 数千のテストアサーションがあり、Bash、minimatch、および brace-expansion のすべてのユニットテストに合格しています (この文書の執筆時点)。
• より安全 - アプリケーションを壊す可能性のある攻撃的または悪意のあるブレースパターンをユーザーが定義することを心配する必要はありません。Braces は、DDoS 攻撃に使用される可能性のある悪意のある正規表現を防ぐための対策を講じています (壊滅的なバックトラッキングを参照)。
• リストをサポート - (別名「セット」) a/{b,c}/d => ['a/b/d', 'a/c/d']
• シーケンスをサポート - (別名「範囲」) {01..03} => ['01', '02', '03']
• ステップをサポート - (別名「インクリメント」) {2..10..2} => ['2', '4', '6', '8', '10']
• エスケープをサポート - 特殊文字の評価を防ぐため。

使用方法

メインのエクスポートは、1 つ以上のブレース patterns と options を受け取る関数です。

const braces = require('braces');
// braces(patterns[, options]);

console.log(braces(['{01..05}', '{a..e}']));
//=> ['(0[1-5])', '([a-e])']

console.log(braces(['{01..05}', '{a..e}'], { expand: true }));
//=> ['01', '02', '03', '04', '05', 'a', 'b', 'c', 'd', 'e']

ブレース展開とコンパイルの比較

デフォルトでは、ブレースパターンは正規表現の作成とマッチングに最適化された文字列にコンパイルされます。

コンパイル済み

console.log(braces('a/{x,y,z}/b'));
//=> ['a/(x|y|z)/b']
console.log(braces(['a/{01..20}/b', 'a/{1..5}/b']));
//=> [ 'a/(0[1-9]|1[0-9]|20)/b', 'a/([1-5])/b' ]

展開

expand オプションを true に設定するか、braces.expand() を使用することでブレース展開を有効にします（Bash や echo {1..5}、または minimatch から期待されるものと同様の配列を返します）：

console.log(braces('a/{x,y,z}/b', { expand: true }));
//=> ['a/x/b', 'a/y/b', 'a/z/b']

console.log(braces.expand('{01..10}'));
//=> ['01','02','03','04','05','06','07','08','09','10']

リスト

リストを展開します（Bash の「セット」と同様）:

console.log(braces('a/{foo,bar,baz}/*.js'));
//=> ['a/(foo|bar|baz)/*.js']

console.log(braces.expand('a/{foo,bar,baz}/*.js'));
//=> ['a/foo/*.js', 'a/bar/*.js', 'a/baz/*.js']

シーケンス

文字の範囲を展開します（Bashの「シーケンス」のように）:

console.log(braces.expand('{1..3}')); // ['1', '2', '3']
console.log(braces.expand('a/{1..3}/b')); // ['a/1/b', 'a/2/b', 'a/3/b']
console.log(braces('{a..c}', { expand: true })); // ['a', 'b', 'c']
console.log(braces('foo/{a..c}', { expand: true })); // ['foo/a', 'foo/b', 'foo/c']

// supports zero-padded ranges
console.log(braces('a/{01..03}/b')); //=> ['a/(0[1-3])/b']
console.log(braces('a/{001..300}/b')); //=> ['a/(0{2}[1-9]|0[1-9][0-9]|[12][0-9]{2}|300)/b']

範囲展開の全オプションについては fill-range を参照してください。

ステップ付き範囲

ステップ（増分）は範囲とともに使用できます:

console.log(braces.expand('{2..10..2}'));
//=> ['2', '4', '6', '8', '10']

console.log(braces('{2..10..2}'));
//=> ['(2|4|6|8|10)']

.optimize メソッドが使用される場合、または options.optimize が true に設定されている場合、シーケンスは展開のために to-regex-range に渡されます。

ネスト

ブレースパターンはネストできます。展開された各文字列の結果はソートされず、左から右への順序が保持されます。

「展開された」ブレース

console.log(braces.expand('a{b,c,/{x,y}}/e'));
//=> ['ab/e', 'ac/e', 'a/x/e', 'a/y/e']

console.log(braces.expand('a/{x,{1..5},y}/c'));
//=> ['a/x/c', 'a/1/c', 'a/2/c', 'a/3/c', 'a/4/c', 'a/5/c', 'a/y/c']

「最適化された」波括弧

console.log(braces('a{b,c,/{x,y}}/e'));
//=> ['a(b|c|/(x|y))/e']

console.log(braces('a/{x,{1..5},y}/c'));
//=> ['a/(x|([1-5])|y)/c']

エスケープ

波括弧のエスケープ

開き波括弧または閉じ波括弧のいずれかがエスケープされている 場合、波括弧パターンは展開も評価もされません:

console.log(braces.expand('a\\{d,c,b}e'));
//=> ['a{d,c,b}e']

console.log(braces.expand('a{d,c,b\\}e'));
//=> ['a{d,c,b}e']

カンマのエスケープ

波括弧内のカンマもエスケープできます:

console.log(braces.expand('a{b\\,c}d'));
//=> ['a{b,c}d']

console.log(braces.expand('a{d\\,c,b}e'));
//=> ['ad,ce', 'abe']

単一項目

bash の慣例に従い、波括弧パターンは単一文字を含む場合も展開されません:

console.log(braces.expand('a{b}c'));
//=> ['a{b}c']

オプション

options.maxLength

型: Number

デフォルト: 10,000

説明: 入力文字列の長さを制限します。入力文字列が生成される場合や、アプリケーションがユーザーに文字列を渡すことを許可している場合などに便利です。

console.log(braces('a/{b,c}/d', { maxLength: 3 })); //=> throws an error

options.expand

型: Boolean

デフォルト: undefined

説明: 「展開された」ブレースパターンを生成します（代わりに、同じことを行う braces.expand() メソッドを使用することもできます）。

console.log(braces('a/{b,c}/d', { expand: true }));
//=> [ 'a/b/d', 'a/c/d' ]

options.nodupes

型: Boolean

デフォルト: undefined

説明: 返される配列から重複を削除します。

options.rangeLimit

型: Number

デフォルト: 1000

説明: ユーザーによって悪意のあるパターンが渡されるのを防ぐため、braces.expand() が使用された場合、または options.expand が true で生成される範囲が rangeLimit を超える場合にエラーがスローされます。

options.rangeLimit をカスタマイズするか、Inifinity に設定してこれを完全に無効にすることができます。

例

// pattern exceeds the "rangeLimit", so it's optimized automatically
console.log(braces.expand('{1..1000}'));
//=> ['([1-9]|[1-9][0-9]{1,2}|1000)']

// pattern does not exceed "rangeLimit", so it's NOT optimized
console.log(braces.expand('{1..100}'));
//=> ['1', '2', '3', '4', '5', '6', '7', '8', '9', '10', '11', '12', '13', '14', '15', '16', '17', '18', '19', '20', '21', '22', '23', '24', '25', '26', '27', '28', '29', '30', '31', '32', '33', '34', '35', '36', '37', '38', '39', '40', '41', '42', '43', '44', '45', '46', '47', '48', '49', '50', '51', '52', '53', '54', '55', '56', '57', '58', '59', '60', '61', '62', '63', '64', '65', '66', '67', '68', '69', '70', '71', '72', '73', '74', '75', '76', '77', '78', '79', '80', '81', '82', '83', '84', '85', '86', '87', '88', '89', '90', '91', '92', '93', '94', '95', '96', '97', '98', '99', '100']

options.transform

型: Function

デフォルト: undefined

説明: 範囲展開をカスタマイズします。

例: 非数値を変換する

const alpha = braces.expand('x/{a..e}/y', {
  transform(value, index) {
    // When non-numeric values are passed, "value" is a character code.
    return 'foo/' + String.fromCharCode(value) + '-' + index;
  },
});
console.log(alpha);
//=> [ 'x/foo/a-0/y', 'x/foo/b-1/y', 'x/foo/c-2/y', 'x/foo/d-3/y', 'x/foo/e-4/y' ]

例: 数値の変換

const numeric = braces.expand('{1..5}', {
  transform(value) {
    // when numeric values are passed, "value" is a number
    return 'foo/' + value * 2;
  },
});
console.log(numeric);
//=> [ 'foo/2', 'foo/4', 'foo/6', 'foo/8', 'foo/10' ]

options.quantifiers

型: Boolean

デフォルト: undefined

説明: 正規表現では、量指定子を使用してトークンを繰り返せる回数を指定できます。たとえば、a{1,3} は文字 a に1回から3回マッチします。

残念ながら、正規表現の量指定子は Bash リスト と同じ構文を共有しています。