Merge pull request #29 from SimenB/custom-formatter

Custom formatter

Author: lazd

README.md

@@ -17,7 +17,7 @@ var csslint = require('gulp-csslint');
 gulp.task('css', function() {
   gulp.src('client/css/*.css')
     .pipe(csslint())
-    .pipe(csslint.reporter());
+    .pipe(csslint.formatter());
 });
 ```
 
@@ -39,7 +39,7 @@ gulp.src('client/css/*.css')
   .pipe(csslint({
     'shorthand': false
   }))
-  .pipe(csslint.reporter());
+  .pipe(csslint.formatter());
 ```
 
 ### csslint(csslintrc)
@@ -52,7 +52,7 @@ You can also pass the path to your csslintrc file instead of a rule configuratio
 ```js
 gulp.src('client/css/*.css')
   .pipe(csslint('csslintrc.json'))
-  .pipe(csslint.reporter());
+  .pipe(csslint.formatter());
 ```
 
 ## Results
@@ -61,55 +61,71 @@ 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 reporters
+## Using formatters
 
-Several reporters come built-in to css-lint. To use one of these reporters, pass the name to `csslint.reporter`.
+Several formatters come built-in to CSSLint. To use one of these formatters, pass the name to `csslint.formatter`.
 
-For a list of all reporters supported by `csslint`, see the [csslint wiki](https://github.com/CSSLint/csslint/wiki/Command-line-interface#--format).
+For a list of all formatters supported by `csslint`, see the [csslint wiki](https://github.com/CSSLint/csslint/wiki/Command-line-interface#--format).
 
 ```js
 gulp.task('lint', function() {
   gulp.src('lib/*.css')
     .pipe(csslint())
-    .pipe(csslint.reporter('junit-xml'));
+    .pipe(csslint.formatter('junit-xml'));
 ```
 
-### Custom reporters
+### Custom formatters
 
-Custom reporter functions can be passed as `csslint.reporter(reporterFunc)`. The reporter 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 customReporter = 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.reporter(customReporter));
+    .pipe(csslint.formatter(require('csslint-stylish')))
 });
 ```
 
-### Reporter options
-You can also pass options to the built-in formatter, by passing a second option to `reporter`.
+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`.
 
 ```js
 gulp.task('lint', function() {
   gulp.src('lib/*.css')
     .pipe(csslint())
-    .pipe(csslint.reporter('junit-xml', options));
+    .pipe(csslint.formatter('junit-xml', options));
 });
 ```
 
@@ -122,19 +138,19 @@ Default is using `process.stdout.write`, but you can use e.g. `console.log`, or
 gulp.task('lint', function() {
   gulp.src('lib/*.css')
     .pipe(csslint())
-    .pipe(csslint.reporter('junit-xml', {logger: console.log.bind(console)}));
+    .pipe(csslint.formatter('junit-xml', {logger: console.log.bind(console)}));
 });
 ```
 
 ```js
 gulp.task('lint', function() {
   gulp.src('lib/*.css')
     .pipe(csslint())
-    .pipe(csslint.reporter('junit-xml', {logger: gutil.log.bind(null, 'gulp-csslint:')}));
+    .pipe(csslint.formatter('junit-xml', {logger: gutil.log.bind(null, 'gulp-csslint:')}));
 });
 ```
 
-`logger` is called once for the starting format of the reporter, then once for each file containing violations, then
+`logger` is called once for the starting format of the formatter, then once for each file containing violations, then
 lastly once for the ending format. Instead of writing to `stdout`, you can write to file using this option.
 
 ```js
@@ -144,7 +160,7 @@ gulp.task('lint', function(cb) {
 
   gulp.src('lib/*.css')
     .pipe(csslint())
-    .pipe(csslint.reporter('junit-xml', {logger: function(str) { output += str; }}))
+    .pipe(csslint.formatter('junit-xml', {logger: function(str) { output += str; }}))
     .on('end', function(err) {
       if (err) return cb(err);
 
@@ -153,7 +169,7 @@ gulp.task('lint', function(cb) {
 });
 ```
 
-This functionality is only available when not using custom reporters.
+This functionality is only available when not using a custom formatting function.
 
 ## Custom rules
 
@@ -169,22 +185,22 @@ csslint.addRule({
 gulp.task('lint', function() {
   gulp.src('lib/*.css')
     .pipe(csslint())
-    .pipe(csslint.reporter())
+    .pipe(csslint.formatter())
 });
 ```
 
 ## Fail on errors
 
-Pipe the file stream to `csslint.failReporter()` to fail on errors.
+Pipe the file stream to `csslint.failFormatter()` to fail on errors.
 
 ```js
 var csslint = require('gulp-csslint');
 
 gulp.task('lint', function() {
   gulp.src('lib/*.css')
     .pipe(csslint())
-    .pipe(csslint.reporter()) // Display errors
-    .pipe(csslint.reporter('fail')); // Fail on error (or csslint.failReporter())
+    .pipe(csslint.formatter()) // Display errors
+    .pipe(csslint.formatter('fail')); // Fail on error (or csslint.failFormatter())
 });
 ```
 

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,59 +44,67 @@ 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);
     });
   });
 };
 
-cssLintPlugin.reporter = function(customReporter, options) {
-  var reporter = csslint.getFormatter('text');
-  var builtInReporter = true;
+cssLintPlugin.formatter = function(customFormatter, options) {
+  var formatter = csslint.getFormatter('text');
+  var builtInFormatter = true;
   var output;
 
   options = options || {};
 
   var logger = options.logger || process.stdout.write.bind(process.stdout);
-
-  if (typeof customReporter === 'function') {
-    reporter = customReporter;
-    builtInReporter = false;
-  }
-  else if (typeof customReporter === 'string') {
-    if (customReporter === 'fail') {
-      return cssLintPlugin.failReporter();
+  if (customFormatter) {
+    if (typeof customFormatter === 'function') {
+      formatter = customFormatter;
+      builtInFormatter = false;
     }
+    else if (typeof customFormatter === 'string') {
+      if (customFormatter === 'fail') {
+        return cssLintPlugin.failFormatter();
+      }
 
-    reporter = csslint.getFormatter(customReporter);
-  }
+      formatter = csslint.getFormatter(customFormatter);
 
-  if (typeof reporter === 'undefined') {
-    throw new Error('Invalid reporter');
+      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 (builtInReporter) {
-    output = [reporter.startFormat()];
+  if (builtInFormatter) {
+    output = [formatter.startFormat()];
   }
 
   return through.obj(
     function(file, enc, cb) {
       // Only report if CSSLint was ran and errors were found
       if (file.csslint && !file.csslint.success) {
-        if (builtInReporter) {
-          output.push(reporter.formatResults(file.csslint.originalReport, file.path, options));
+        if (builtInFormatter) {
+          output.push(formatter.formatResults(file.csslint.report, file.path, options));
         }
         else {
-          reporter(file);
+          formatter(file.csslint.report, file.path, options);
         }
       }
 
       return cb(null, file);
     },
     function(cb) {
-      if (builtInReporter) {
-        output.push(reporter.endFormat());
+      if (builtInFormatter) {
+        output.push(formatter.endFormat());
 
         output
           .filter(function(str) {
@@ -137,7 +125,14 @@ cssLintPlugin.addRule = function(rule) {
   csslint.addRule(rule);
 };
 
-cssLintPlugin.failReporter = function() {
+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
     if (!file.csslint || file.csslint.success) {

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;