Add postcss.plugin method

API.md

@@ -38,6 +38,28 @@ Arguments:
 You can also set plugins with the [`Processor#use`] method.
 See its description below for details about plugin formats.
 
+### `postcss.plugin(name, initializer)`
+
+Creates PostCSS plugin.
+
+```js
+module.exports = postcss.plugin('postcss-remove', function (opts) {
+    var filter = opts.prop;
+    return function (css, processor) {
+        css.eachDecl(filter, function (decl) {
+            decl.removeSelf();
+        });
+    };
+});
+```
+
+Arguments:
+
+* `name (string)`: PostCSS plugin name. Same as in `name` property
+  in `package.json`. It will be saved in `plugin.postcssPlugin` property.
+* `initializer  (function)`: will receive plugin options and should return
+  functions to modify nodes in input CSS.
+
 ### `postcss.parse(css, opts)`
 
 Parses source `css` and returns a new `Root` node, which contains
@@ -164,11 +186,11 @@ Arguments:
 * `plugin (function|#postcss|Processor)`: PostCSS plugin. I can be in three
   formats:
   * A function. PostCSS will pass the function a [`Root` node]
-     as the first argument.
+    as the first argument and current [`Processor`] instance as second.
   * An object with a `postcss` method. PostCSS will use that method
-     as described in #1.
+    as described in #1.
   * Another `Processor` instance. PostCSS will copy plugins
-     from that instance to this one.
+    from that instance to this one.
 
 Plugins can also be added by passing them as arguments when creating
 a `postcss` instance (cf. [`postcss(plugins)`]).

lib/postcss.js

@@ -30,6 +30,18 @@ postcss.parse = parse;
 // Parse lists by spaces or comma
 postcss.list = list;
 
+// Create PostCSS plugin
+postcss.plugin = function (name, initializer) {
+    var result = function () {
+        return initializer.apply(this, arguments);
+    };
+    result.postcssPlugin = name;
+    result.postcss = function (css, processor) {
+        return result().apply(this, arguments);
+    };
+    return result;
+};
+
 // Nodes shortcuts
 postcss.comment = function (defaults) {
     return new Comment(defaults);

test/postcss.js

@@ -23,6 +23,35 @@ describe('postcss()', () => {
         expect(postcss([a, b]).plugins).to.eql([a, b]);
     });
 
+    describe('.plugin()', () => {
+
+        it('creates plugin', () => {
+            var plugin = postcss.plugin('test', (filter) => {
+                return function (css, processor) {
+                    css.eachDecl(filter || 'two', function (decl) {
+                        decl.removeSelf();
+                    });
+                };
+            });
+
+            expect(plugin.postcssPlugin).to.eql('test');
+
+            var result1 = postcss(plugin('one')).process('a{ one: 1; two: 2 }');
+            expect(result1.css).to.eql('a{ two: 2 }');
+            var result2 = postcss(plugin).process('a{ one: 1; two: 2 }');
+            expect(result2.css).to.eql('a{ one: 1 }');
+        });
+
+    });
+
+    describe('.parse()', () => {
+
+        it('contains parser', () => {
+            expect(postcss.parse('').type).to.eql('root');
+        });
+
+    });
+
     describe('.root()', () => {
 
         it('allows to build own CSS', () => {
@@ -44,14 +73,6 @@ describe('postcss()', () => {
 
     });
 
-    describe('.parse', () => {
-
-        it('contains parser', () => {
-            expect(postcss.parse('').type).to.eql('root');
-        });
-
-    });
-
     describe('.list', () => {
 
         it('contains list module', () => {