Allow registering custom formatter

Author: SimenB

README.md

@@ -61,9 +61,7 @@ Adds the following properties to the file object:
 
 ```js
 file.csslint.success = true; // or false
-file.csslint.errorCount = 0; // number of errors returned by CSSLint
-file.csslint.results = []; // CSSLint errors
-file.csslint.opt = {}; // The options you passed to CSSLint
+file.csslint.report = {}; // The report from CSSLint after linting the file
 ```
 
 ## Using formatters
@@ -81,27 +79,45 @@ gulp.task('lint', function() {
 
 ### Custom formatters
 
-Custom formatter functions can be passed as `csslint.formatter(formatterFunc)`. The formatter function will be called for each linted file and passed the file object as described above.
+Custom formatters can be provided by first adding a valid CSSLint-formatter, such as `csslint-stylish`, then using it:
 
 ```js
 var csslint = require('gulp-csslint');
-var gutil = require('gulp-util');
 
-var customFormatter = function(file) {
-  gutil.log(gutil.colors.cyan(file.csslint.errorCount)+' errors in '+gutil.colors.magenta(file.path));
+csslint.addFormatter('csslint-stylish');
 
-  file.csslint.results.forEach(function(result) {
-    gutil.log(result.error.message+' on line '+result.error.line);
-  });
-};
+gulp.task('lint', function() {
+  gulp.src('lib/*.css')
+    .pipe(csslint())
+    .pipe(csslint.formatter('stylish'))
+});
+```
+
+You can provide the formatter by requiring it directly as well:
+
+```js
+var csslint = require('gulp-csslint');
 
 gulp.task('lint', function() {
   gulp.src('lib/*.css')
     .pipe(csslint())
-    .pipe(csslint.formatter(customFormatter));
+    .pipe(csslint.formatter(require('csslint-stylish')))
 });
 ```
 
+You can also provide an object with the following contract to implement your own formatter:
+
+```js
+{
+  id: 'string', // Name passed to csslint.formatter
+  startFormat: function() {}, // Called before parsing any files, should return a string
+  startFormat: function() {}, // Called after parsing all files, should return a string
+  formatResult: function (results, filename, options) {} // Called with a results-object per file linted. Optionally called with a filename, and options passed to csslint.formatter(*formatter*, *options*)
+}
+```
+
+You can also provide a function, which is called for each file linted with the same arguments as `formatResults`.
+
 ### Formatter options
 You can also pass options to the built-in formatter, by passing a second option to `formatter`.
 
@@ -153,7 +169,7 @@ gulp.task('lint', function(cb) {
 });
 ```
 
-This functionality is only available when not using custom formatters.
+This functionality is only available when not using a custom formatting function.
 
 ## Custom rules
 

index.js

@@ -5,31 +5,11 @@ var through = require('through2');
 var csslint = require('csslint').CSSLint;
 var RcLoader = require('rcloader');
 
-var formatOutput = function(report, file, options) {
-  if (!report.messages.length) {
-    return {
-      success: true
-    };
+function validateFormatter(formatter) {
+  if (typeof formatter !== 'object' || !formatter.id || !formatter.startFormat || !formatter.endFormat || !formatter.endFormat || !formatter.formatResults) {
+    throw new Error('Invalid formatter: formatters need to be objects, and contain "id", "name", "startFormat", "endFormat" and "formatResults"');
   }
-
-  var filePath = (file.path || 'stdin');
-
-  // Handle errors
-  var results = report.messages.map(function(err) {
-    if (!err) return;
-    return { file: filePath, error: err };
-  }).filter(function(err) {
-    return err;
-  });
-
-  return {
-    originalReport: report,
-    errorCount: results.length,
-    success: false,
-    results: results,
-    options: options
-  };
-};
+}
 
 var cssLintPlugin = function(options) {
   options = options || {};
@@ -64,7 +44,7 @@ var cssLintPlugin = function(options) {
       var report = csslint.verify(content, ruleset);
 
       // send status down-stream
-      file.csslint = formatOutput(report, file, ruleset);
+      file.csslint = { report: report, success: !report.messages.length };
 
       cb(null, file);
     });
@@ -79,21 +59,29 @@ cssLintPlugin.formatter = function(customFormatter, options) {
   options = options || {};
 
   var logger = options.logger || process.stdout.write.bind(process.stdout);
-
-  if (typeof customFormatter === 'function') {
-    formatter = customFormatter;
-    builtInFormatter = false;
-  }
-  else if (typeof customFormatter === 'string') {
-    if (customFormatter === 'fail') {
-      return cssLintPlugin.failFormatter();
+  if (customFormatter) {
+    if (typeof customFormatter === 'function') {
+      formatter = customFormatter;
+      builtInFormatter = false;
     }
+    else if (typeof customFormatter === 'string') {
+      if (customFormatter === 'fail') {
+        return cssLintPlugin.failFormatter();
+      }
 
-    formatter = csslint.getFormatter(customFormatter);
-  }
+      formatter = csslint.getFormatter(customFormatter);
 
-  if (typeof formatter === 'undefined') {
-    throw new Error('Invalid formatter');
+      if (typeof formatter === 'undefined') {
+        throw new Error('Invalid reporter: ' + customFormatter);
+      }
+    }
+    else if (typeof customFormatter === 'object') {
+      validateFormatter(customFormatter);
+      formatter = customFormatter;
+    }
+    else {
+      throw new Error('Invalid custom formatter passed, please pass `null` or `undefined` if you want to pass options while using default formatter.');
+    }
   }
 
   if (builtInFormatter) {
@@ -105,10 +93,10 @@ cssLintPlugin.formatter = function(customFormatter, options) {
       // Only report if CSSLint was ran and errors were found
       if (file.csslint && !file.csslint.success) {
         if (builtInFormatter) {
-          output.push(formatter.formatResults(file.csslint.originalReport, file.path, options));
+          output.push(formatter.formatResults(file.csslint.report, file.path, options));
         }
         else {
-          formatter(file);
+          formatter(file.csslint.report, file.path, options);
         }
       }
 
@@ -137,6 +125,13 @@ cssLintPlugin.addRule = function(rule) {
   csslint.addRule(rule);
 };
 
+cssLintPlugin.addFormatter = function(formatter) {
+  formatter = typeof formatter === 'string' ? require(formatter) : formatter;
+  validateFormatter(formatter);
+
+  csslint.addFormatter(formatter);
+};
+
 cssLintPlugin.failFormatter = function() {
   return through.obj(function(file, enc, cb) {
     // Nothing to report or no errors

package.json

@@ -14,6 +14,7 @@
   },
   "devDependencies": {
     "coveralls": "^2.11.2",
+    "csslint-stylish": "0.0.4",
     "eslint": "^1.1.0",
     "eslint-config-semistandard": "^5.0.0",
     "eslint-config-standard": "^4.1.0",

test/expected/text.txt

@@ -0,0 +1,11 @@
+csslint: There are 2 problems in test/fixtures/usingImportant.css.
+
+usingImportant.css
+1: warning at line 2, col 1
+Bad naming: .mybox
+.mybox {
+
+usingImportant.css
+2: warning at line 3, col 3
+Use of !important
+  border: 1px solid black !important;