Merge pull request #1 from lfbittencourt/feature/inclusive-or

Feature: inclusive groups

Author: lfbittencourt

README.md

@@ -32,35 +32,43 @@ console.log(result); // ['a', 'b']
 The syntax is similar to regular expressions and its composed by just a few
 different tokens.
 
+### Literals
+
 Literal strings output themselves:
 
 ```
 a => ['a']
 ```
 
+### Optional characters
+
 Optional characters are followed by a `?`:
 
 ```
 ab? => ['a', 'ab']
 ```
 
+### Groups
+
 Groups are used to group options. The group is defined by parentheses and the
 options are separated by `|`:
 
 ```
 (a|b) => ['a', 'b']
 ```
 
-Optional groups are followed by a `?`:
+Groups can have a single option:
 
 ```
-(a|b)? => ['a', 'b', '']
+(a) => ['a']
 ```
 
-Groups can have a single option:
+### Optional groups
+
+Optional groups are followed by a `?`:
 
 ```
-(a) => ['a']
+(a|b)? => ['a', 'b', '']
 ```
 
 You can use a single-option group combined with the optional character `?` to
@@ -70,27 +78,56 @@ make more than one character optional:
 (ab)? => ['ab', '']
 ```
 
+### Nested groups
+
 Groups can be nested:
 
 ```
 (a(b|c)) => ['ab', 'ac']
 ```
 
+### Inclusive groups
+
+You can also use inclusive groups (or simply igroups) by using a plus sign (`+`)
+before the options. Different from the standard groups, igroups also output an
+option that concatenates all of its options:
+
+```
+(+a|b) => ['a', 'b', 'ab']
+```
+
+As with standard groups, igroups can be optional:
+
+```
+(+a|b)? => ['a', 'b', 'ab', '']
+```
+
+Igroups can also be nested:
+
+```
+(+a|(+b|c)) => ['a', 'ab', 'abc', 'ac', 'b', 'bc', 'c']
+```
+
+### Complex patterns
+
 Finally, you can mix all of them into complex patterns:
 
 ```
 Mary( Eli(z|s)abeth)?( Simmons)? Smith(son)? => [
-  'Mary Elizabeth Simmons Smithson',
-  'Mary Elizabeth Simmons Smith',
-  'Mary Elizabeth Smithson',
-  'Mary Elizabeth Smith',
-  'Mary Elisabeth Simmons Smithson',
+  'Mary Elisabeth Simmons',
   'Mary Elisabeth Simmons Smith',
-  'Mary Elisabeth Smithson',
+  'Mary Elisabeth Simmons Smithson',
   'Mary Elisabeth Smith',
-  'Mary Simmons Smithson',
+  'Mary Elisabeth Smithson',
+  'Mary Elizabeth Simmons',
+  'Mary Elizabeth Simmons Smith',
+  'Mary Elizabeth Simmons Smithson',
+  'Mary Elizabeth Smith',
+  'Mary Elizabeth Smithson',
+  'Mary Simmons',
   'Mary Simmons Smith',
+  'Mary Simmons Smithson',
+  'Mary Smith',
   'Mary Smithson',
-  'Mary Smith'
 ]
 ```

src/logical.ts

@@ -5,8 +5,8 @@ export type LogicalChildren = LogicalChild[];
 class Logical {
   children: LogicalChildren;
 
-  constructor(...args: LogicalChildren) {
-    this.children = args;
+  constructor(...children: LogicalChildren) {
+    this.children = children;
   }
 }
 

src/parser.ts

@@ -3,7 +3,7 @@ import { EmbeddedActionsParser } from 'chevrotain';
 import { And, LogicalChildren, Or } from './logical';
 
 import tokens, {
-  Text, LeftParenthesis, RightParenthesis, QuestionMark, Pipe,
+  Text, LeftParenthesis, RightParenthesis, QuestionMark, Pipe, PlusSign,
 } from './tokens';
 
 /**
@@ -16,7 +16,11 @@ import tokens, {
  *   Text QuestionMark
  *
  * optionableGroup:
- *   LeftParenthesis tree (Pipe tree)* RightParenthesis (QuestionMark)?
+ *   LeftParenthesis
+ *   (PlusSign)?
+ *   tree (Pipe tree)*
+ *   RightParenthesis
+ *   (QuestionMark)?
  *
  * tree:
  *   element+
@@ -39,18 +43,24 @@ export default class Parser extends EmbeddedActionsParser {
   });
 
   private optionableGroup = this.RULE('optionableGroup', () => {
-    const alternatives = [];
+    const alternatives: LogicalChildren = [];
 
     this.CONSUME(LeftParenthesis);
 
+    const isIgroup = this.OPTION1(() => this.CONSUME(PlusSign));
+
     this.AT_LEAST_ONE_SEP({
       SEP: Pipe,
       DEF: () => alternatives.push(this.SUBRULE(this.tree)),
     });
 
     this.CONSUME(RightParenthesis);
 
-    if (this.OPTION(() => this.CONSUME(QuestionMark))) {
+    if (isIgroup && alternatives.length > 1) {
+      alternatives.push(new And(...alternatives));
+    }
+
+    if (this.OPTION2(() => this.CONSUME(QuestionMark))) {
       alternatives.push('');
     }
 
@@ -68,14 +78,14 @@ export default class Parser extends EmbeddedActionsParser {
   ]));
 
   public tree = this.RULE('tree', () => {
-    const variations: LogicalChildren = [];
+    const children: LogicalChildren = [];
 
-    this.AT_LEAST_ONE(() => variations.push(this.SUBRULE(this.element)));
+    this.AT_LEAST_ONE(() => children.push(this.SUBRULE(this.element)));
 
-    if (variations.length === 1) {
-      return variations[0];
+    if (children.length === 1) {
+      return children[0];
     }
 
-    return new And(...variations);
+    return new And(...children);
   });
 }

src/tokens.ts

@@ -5,5 +5,6 @@ export const LeftParenthesis = createToken({ name: 'LeftParenthesis', pattern: '
 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 default [Text, LeftParenthesis, RightParenthesis, QuestionMark, Pipe];
+export default [Text, LeftParenthesis, RightParenthesis, QuestionMark, Pipe, PlusSign];

tests/basic.spec.ts

@@ -0,0 +1,15 @@
+import expand from '../src';
+
+describe('basic', () => {
+  it('should expand literal strings', () => {
+    const result = expand('a');
+
+    expect(result).toEqual(['a']);
+  });
+
+  it('should expand optional characters', () => {
+    const result = expand('ab?').sort();
+
+    expect(result).toEqual(['a', 'ab'].sort());
+  });
+});

tests/expand.spec.ts

@@ -0,0 +1,25 @@
+import expand from '../src';
+
+describe('extra', () => {
+  it('should expand complex patterns', () => {
+    const result = expand('Mary( Eli(z|s)abeth)?(+ Simmons| Smith(son)?)').sort();
+
+    expect(result).toEqual([
+      'Mary Elisabeth Simmons',
+      'Mary Elisabeth Simmons Smith',
+      'Mary Elisabeth Simmons Smithson',
+      'Mary Elisabeth Smith',
+      'Mary Elisabeth Smithson',
+      'Mary Elizabeth Simmons',
+      'Mary Elizabeth Simmons Smith',
+      'Mary Elizabeth Simmons Smithson',
+      'Mary Elizabeth Smith',
+      'Mary Elizabeth Smithson',
+      'Mary Simmons',
+      'Mary Simmons Smith',
+      'Mary Simmons Smithson',
+      'Mary Smith',
+      'Mary Smithson',
+    ].sort());
+  });
+});

tests/extra.spec.ts

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

tests/groups.spec.ts

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