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 ?

[jamiebuilds]

We've been against the idea of allowing external extensions to Babylon in the past. It would be much more difficult to support custom parsing than it is to support custom transformations. Babel already has a lot it has to support, so we haven't wanted to open this up.

I talked to @disnet about this just earlier this week, because others were interested in seeing sweet.js be built on top of Babylon (which would be extremely difficult or impossible due to the nature of how you must parse macros). I would be open to an internal whitelist of external parsing plugins that we could allow for a small subset of users that will be good citizens and we can communicate changes directly with.

[jmm]

@thejameskyle have you read the comments on that babel/babel issue? @kittens seems pretty favorable to the idea.

I would be open to an internal whitelist of external parsing plugins that we could allow for a small subset of users that will be good citizens and we can communicate changes directly with.

My gut reaction is I don't like this idea :( unless it's a preliminary thing to work out details of how to make it generally available. If it's necessary you can curate a list of plugins that get some sort of stamp of approval or something. Presumably there would be some objective criteria published for what constitutes a "good" plugin? What is an example of being a good or bad citizen in this context?

[krasimir]

@thejameskyle @jmm Thanks for the feedback. I do see your points. However, I don't think that you'll increase the support range if you allow external plugins. Simply because the core or Babylon will stay stable and untouched. You can always say "X is an unofficial plugin, so you should know that it may break once we update Babylon".

Isn't it better to polish the API so you allow extending? There are tons of stuff that could be done with custom parsing but right now it is only possible if we clone the project.

[MCluck90]

👍 to this. The main reason I got interested in this project is because I thought I would be able to write my own plugins for it.

[loganfsmyth]

This was auto-closed because this repo has been updated to include the Git history from the main Babel repo. I can't speak to the validity of this PR, but it appears you'll need to rebase and open a new one.

The new force-pused master branch should be identical to the old one, so you should be able to use rebase --onto or cherry-pick to move your commit over.

[krasimir]

Reopened here #11