Allowing external plugins

[krasimir]

This PR introduces a small change so we can send an external plugin to Babylon. Right now this is not possible because we have the plugins' registration hard-coded in src/index.js.

I'm suggesting the following plugin addition format:

var plugin = function (Parser) {
  /*
    Here we extend the Parser's prototype with our own methods
    for example:

    Parser.prototype.cssxEntryPoint = function () {
      ...
    }

    so we can use `this.cssxEntryPoint` later.
  */
  return {
    pluginName: 'cssx',
    pluginFunc: function CSSX(instance) {
      /*
        Here we use `instance.extend`. For example:

        instance.extend('parseStatement', function (inner) {
          return function (declaration, topLevel) {
            ...
            return inner.call(this, declaration, topLevel);
          };
        });
      */
    }
  }
}

babylon.parse(code, {
  plugins: [
    'jsx',
    'flow',
    'asyncFunctions',
    ...
    plugin
  ],
  sourceType: opts.sourceType || 'script'
})

Or in other words we may pass a function (not only a string).

While I was working on this changes I realize that we need one more thing - the lib folder. I agree that compiled files should never go into the source control but using only bin/babylon.js is not enough to fully extend the parser. That's because we need lots of internal classes and helpers. The simple example is asserting the current parsed token. Even though we have an access to the current state we can't assert agains token types because we don't have an access to their definitions. Same for the context. What I did as a temporary solution is requiring these files locally and producing a bundle that contains all I need.

What you think @kittens @hzoo ?

[lukehorvat]

Just piggybacking on your PR here...

I fully support the idea of external plugins. But given this may not be merged for quite some time, I've built a tiny wrapper around Babel v6 that supports such plugins, aptly named Babby. Anyone who is interested, feel free to check it out and help me make it better.

[loganfsmyth]

@lukehorvat If you want plugins, I'd be much prefered to make a fork and encourage people to use that. Your module inserts a new line at line 48. Not only is that extremely fragile, but it means if something breaks, the Babel team are the ones who get to field all of the support requests for it, because it's impossible for users to know that something has broken due to their use (or a dependency's use) of babby.

It's already a huge burden for our small team of volunteers to support the Babel ecosystem. I understand, I really do, but having people in the community you're trying to support actively circumventing your wishes with is super demotivating. We're doing our best, but we're just not in a place where it's realistic for us to support plugins right now. Pretending we are by hacking stuff into Babylon helps no-one.

If you want to continue maintaining this, it would be great put a warning at the top of the README saying it could break at any moment, and change your

lines.splice(48, 0, 'exports.Parser = _parser2["default"];');

to

lines.splice(48, 0, 'try {exports.Parser = _parser2["default"]; } catch (e){ throw new Error("Babby has failed to patch Babylon, please file an issue on https://github.com/lukehorvat/babby"} ');

so that if something does go wrong, Babylon isn't stuck handling all your support requests.

[lukehorvat]

I should clarify. Babby is just a small (and, as you rightly said, fragile) experiment I hacked together to show what is possible. A proof-of-concept, basically. I would much prefer to work in collaboration with you guys on an "official" fork that we can eventually merge into Babel one day.

[sebmck]

Parser plugins are a really good idea, they're just going to have to be more sophisticated than method overloading. Method overloading requires all the internal methods to be public API which is extremely fragile and prevents us from changing the core in any meaningful way.

[sebmck]

This seems to just be the same as #5 so I'm closing this.