Installing

Using yarn:

$ yarn add exceptional-expressions

Using npm:

$ npm install exceptional-expressions

Using bower:

$ bower install exceptional-expressions

Hello World

import { ExpBuilder, or, Constants, anythingBut } from 'exceptional-expressions;

const builder = new ExpBuilder('ig');

builder
  .beginsWith(or(['hello', 'goodbye']))
  .followedBy(Constants.whitespace)
  .endsWith(anythingBut('world'));

builder.matchesString('Hello World'); // false
builder.matchesString('Goodbye Earth'); // true
builder.matchesString('hello world'); // false
builder.matchesString('helloearth'); // false

Examples

The exceptional expressions builder class exposes many methods for chaining expressions in various combinations. These methods, combined with the various utility functions provide extensive functionality such as named grouping, or and optional chaining, exclusions and many more.

// Optional chaining
import { ExpBuilder, or, Constants, Sequences } from 'exceptional-expressions;

const builder = new ExpBuilder('g');

builder
  .beginsWith('(a)')
  .orBeginsWith('(b)')
  .followedBy(Constants.whitespace)
  .followedBy(or([Constants.word, Sequences.numbers(3)]));

builder.matchesString('(a) Test');  // true
builder.matchesString('(b) word');  // true
builder.matchesString('(a)string'); // false
builder.matchesString('(a) 123');  // true

builder.getMatches('(a) first extra test string (b) second');
// ['(a) first']

builder.toRegex(); // /^(?:(?:\(a\))|(?:\(b\)))\s(?:(?:[A-Za-z']+\b)|(?:[\d]{3}))/g

Named groups allow you to group chunks of your expression and then extract that chunk by the name that you gave it. This functionality seeks to improve on the regex.exec(string) method, which requires you to keep careful track on the ordering of your regex capture groups in order to determine which array index your group will be extracted into.

// Named groups
import { ExpBuilder, group, Constants } from 'exceptional-expressions;

const builder = new ExpBuilder('g');

builder
  .contains(group([Constants.word, '.', Constants.word], 'username'))
  .followedBy('@')
  .followedBy(
    group([
      group(Constants.word, 'company'), '.', group(Constants.word, 'tld')
    ], 'domain')
  );

builder.getCaptureGroups();
// ['username', 'domain', 'company', 'tld']

builder.matchesString('[email protected]');
// true

builder.getMatchesWithGroups('[email protected], [email protected]')
/* [{
      match: '[email protected]',
      groups:
         {
           username: 'test.person',
           domain: 'example.com',
           company: 'example',
           tld: 'com'
         }
     },
     {
       match: '[email protected]',
       groups:
         {
           username: 'another.guy',
           domain: 'test.io',
           company: 'test',
           tld: 'io'
         }
    }]
*/

builder.getMatchesByGroup('[email protected], [email protected]', 'company')
// ['example', 'test']

License

MIT