benjamingr/js-restructure

JavaScript matching REs into objects

js-restructure

Based on https://github.com/alexflint/go-restructure

This package allows you to express regular expressions by defining an object, and then capture matched sub-expressions into object's fields.

• Motivation
• API Docs
• Installation
• Contribution

Here is a very simple email address parser:

var parser = matcher({
   _    : "^",
   user : "\\w+", // can also pass a JS RegExp here
   _2   : "@",
   host : "[^@]+",
   _3    : "$"
});
var parts = parser("[email protected]");
console.log(parts.user); // benji
console.log(parts.host); // somewhere.com

Example primitive URL parser:

var m = matcher({
   protocol    : "http|https",
   _1 : "://", // can also pass a RegExp here
   host : "[^/]+",
   _2   : "/",
   path : ".+",
   _3    : "$"
})("http://www.google.com/search?foo=bar");
m.protocol; // http
m.host; // www.google.com
m.path; // search?foo=bar

Note: In "real code" use the built-in parsing capabilities of browsers/node to parse real URLs.

Motivation

Matching nested RegExps is hard to read. The goal of this package is to allow users to match common patterns without having to parse the capturing groups of complex regular expressions and put those in object fields. This "shims" the lack of named capturing groups in JavaScript.

Installation

npm install js-restructure

Or in the browser:

<script src='https://wzrd.in/standalone/js-restructure@latest'></script>

Usage in script tag:

var matcher = window.jsRestructure(...);

Browser Support

Any ES5 capable browser is supported meaning IE9+, Firefox, Chrome, Safari and all modern mobile browsers.

Contribution

Contribution is very welcome and friendliness is a project goal. Feel free to open issues and feature requests. Pull requests are also very welcome.

We indent with two spaces and the code is ES5.

js-restructure's Issues

JavaScript does not gaurantee the order or properties

Does it?

Maybe put them in an array? Or maybe I'm mis-understanding how the RegExp builder keeps the correct order

The library should deal with nested matches

Not as big of a deal as in Go, but would be useful for reuse.

Goals for adding this

• nested objects should work.
• nesting a restructure parser should work and invoke the parser.

Consider returning empty object instead of null

Consider returning empty object instead of null so that if someone tries to access an element of a failed parse they don't hit an error trying to get a key from null.

Or have the parser throw some error if there was a "real" error and return the empty object otherwise.