@plugin directive is not documented

[AndyOGo]

Less version 2.5 introduced the @plugin directive, but it is not documented anywhere.

[matthew-dean]

It's been on my todo list since then. Contributions always welcome!

[AndyOGo]

I see.
I would like to help. But I could only tell what you told me in the other issue.

IMHO this should include much more than just this. Like how to get a reference to the less instance, less.tree, context property of this, how to access less @variables of the current scope inside less and stuff like that.

[matthew-dean]

@AndyOGo That's pretty much all the work I'm doing for the 3.x branch. Basically NPM-based plugins and these small scripting plugins are unified under the same scoping system via @plugin. Meaning: if you take a look at: http://lesscss.org/usage/#plugins-for-plugin-authors

The 3.x branch (now published in NPM under the "next" tag) allows you to return an object with certain function signatures. So, in your JS file, you might have something like:

functions.add(name, function() {
  /* "this" will be bound to an instance of "FunctionCaller",
     with this.context set to where the function was called */
});

return {  // you can also use module.exports = 
  install: function(less, pluginManager) {
    // can get a reference to less here; this function is now optional
  }
}

@plugin calls have their own function registry, which is available / returned to the local scope when called. Which is just a fancy way of saying that plugin functions are scoped.

.scope {
  @plugin "my-plugin";
  my-special-func();
}
.another-scope {
  my-special-func();  // throws an error (I hope... 3.0 is still a pre-release)
}

[matthew-dean]

I'm maintaining a list of 3.0 changes here: less/less-meta#20

The list itself may change a bit, but should be pretty close. It would be great if you want to try out different uses for @plugin and give some feedback.

[matthew-dean]

I've been testing @plugin changes with a fairly advanced use case, mostly just to see if there were any pieces missing. For instance, I wanted to see if I could add visitors from an inline plugin, which revealed that the plugin visitor code needed to be re-written.

Here's a sample of the code I've used so far in my testing: https://gist.github.com/matthew-dean/708f180b9de7a79e2349b07d58dfafe5

[matthew-dean]

Documented now.