Merge pull request #3 from lfbittencourt/feature/escaping

New feature: escaping

Author: lfbittencourt

README.md

@@ -108,6 +108,14 @@ Igroups can also be nested:
 (+a|(+b|c)) => ['a', 'ab', 'abc', 'ac', 'b', 'bc', 'c']
 ```
 
+### Escaping
+
+You can escape special characters by using a backslash (`\`):
+
+```
+\(a\|b\) => ['(a|b)']
+```
+
 ### Complex patterns
 
 Finally, you can mix all of them into complex patterns:

src/parser.ts

@@ -3,17 +3,30 @@ import { EmbeddedActionsParser } from 'chevrotain';
 import { And, LogicalChildren, Or } from './logical';
 
 import tokens, {
-  Text, LeftParenthesis, RightParenthesis, QuestionMark, Pipe, PlusSign,
+  Backslash,
+  escapableTokens,
+  LeftParenthesis,
+  Pipe,
+  PlusSign,
+  QuestionMark,
+  RightParenthesis,
+  Text,
 } from './tokens';
 
 /**
  * GRAMMAR
  *
  * element:
- *   Text | optionalText | optionableGroup
+ *   optionableEscapedToken | optionableText | optionableGroup
  *
- * optionalText:
- *   Text QuestionMark
+ * optionableEscapedToken:
+ *   Backslash
+ *   (Backslash | LeftParenthesis | Pipe | PlusSign | QuestionMark | RightParenthesis)
+ *   (QuestionMark)?
+ *
+ * optionableText:
+ *   Text
+ *   (QuestionMark)?
  *
  * optionableGroup:
  *   LeftParenthesis
@@ -32,14 +45,28 @@ export default class Parser extends EmbeddedActionsParser {
     this.performSelfAnalysis();
   }
 
-  private text = this.RULE('text', () => this.CONSUME(Text).image);
+  private optionableEscapedToken = this.RULE('escapedToken', () => {
+    this.CONSUME1(Backslash);
 
-  private optionalText = this.RULE('optionalText', () => {
-    const text: string = this.SUBRULE(this.text);
+    const token = this.OR(
+      escapableTokens.map((escapableToken) => ({ ALT: () => this.CONSUME2(escapableToken) })),
+    );
+
+    if (this.OPTION(() => this.CONSUME(QuestionMark))) {
+      return new Or(token.image, '');
+    }
 
-    this.CONSUME(QuestionMark);
+    return token.image;
+  });
+
+  private optionableText = this.RULE('optionalText', () => {
+    const text: string = this.CONSUME(Text).image;
+
+    if (this.OPTION(() => this.CONSUME(QuestionMark))) {
+      return new Or(text, text.slice(0, -1));
+    }
 
-    return this.ACTION(() => new Or(text, text.slice(0, -1)));
+    return text;
   });
 
   private optionableGroup = this.RULE('optionableGroup', () => {
@@ -72,8 +99,8 @@ export default class Parser extends EmbeddedActionsParser {
   });
 
   private element = this.RULE('element', () => this.OR([
-    { ALT: () => this.SUBRULE(this.optionalText) },
-    { ALT: () => this.SUBRULE(this.text) },
+    { ALT: () => this.SUBRULE(this.optionableEscapedToken) },
+    { ALT: () => this.SUBRULE(this.optionableText) },
     { ALT: () => this.SUBRULE(this.optionableGroup) },
   ]));
 

src/tokens.ts

@@ -6,5 +6,15 @@ export const RightParenthesis = createToken({ name: 'RightParenthesis', pattern:
 export const QuestionMark = createToken({ name: 'QuestionMark', pattern: '?' });
 export const Pipe = createToken({ name: 'Pipe', pattern: '|' });
 export const PlusSign = createToken({ name: 'PlusSign', pattern: '+' });
+export const Backslash = createToken({ name: 'Backslash', pattern: '\\' });
 
-export default [Text, LeftParenthesis, RightParenthesis, QuestionMark, Pipe, PlusSign];
+export const escapableTokens = [
+  Backslash,
+  LeftParenthesis,
+  Pipe,
+  PlusSign,
+  QuestionMark,
+  RightParenthesis,
+];
+
+export default [...escapableTokens, Text];

tests/escaping.spec.ts

@@ -0,0 +1,41 @@
+import { escapableTokens } from '../src/tokens';
+
+import expand from '../src';
+
+describe('escaping', () => {
+  it('should escape escaped tokens', () => {
+    const result = expand(escapableTokens.map((token) => `\\${token.PATTERN}`).join('')).sort();
+
+    expect(result).toEqual([escapableTokens.map((token) => token.PATTERN).join('')].sort());
+  });
+
+  it('should escape escape parenthesis', () => {
+    const result = expand('(\\(\\))').sort();
+
+    expect(result).toEqual(['()'].sort());
+  });
+
+  it('should escape pipe', () => {
+    const result = expand('(\\||a)').sort();
+
+    expect(result).toEqual(['|', 'a'].sort());
+  });
+
+  it('should escape plus sign', () => {
+    const result = expand('(+\\+|a)').sort();
+
+    expect(result).toEqual(['+', 'a', '+a'].sort());
+  });
+
+  it('should escape question mark', () => {
+    const result = expand('\\??').sort();
+
+    expect(result).toEqual(['?', ''].sort());
+  });
+
+  it('should escape backslash', () => {
+    const result = expand('\\\\').sort();
+
+    expect(result).toEqual(['\\'].sort());
+  });
+});

tests/igroups.spec.ts

@@ -1,25 +1,25 @@
 import expand from '../src';
 
 describe('inclusive groups', () => {
-  it('should expand inclusive groups', () => {
+  it('should expand igroups', () => {
     const result = expand('(+a|b)').sort();
 
     expect(result).toEqual(['a', 'b', 'ab'].sort());
   });
 
-  it('should expand optional inclusive groups', () => {
+  it('should expand optional igroups', () => {
     const result = expand('(+a|b)?').sort();
 
     expect(result).toEqual(['a', 'b', 'ab', ''].sort());
   });
 
-  it('should not expand single-option inclusive groups', () => {
+  it('should not expand single-option igroups', () => {
     const result = expand('(+a)').sort();
 
     expect(result).toEqual(['a'].sort());
   });
 
-  it('should expand nested inclusive groups', () => {
+  it('should expand nested igroups', () => {
     const result = expand('(+a|(+b|c))').sort();
 
     expect(result).toEqual(['a', 'ab', 'abc', 'ac', 'b', 'bc', 'c'].sort());