.verb.md

Usage

var matchFile = require('{%= name %}');

API

matchFile

Returns true if the given string matches one of the path properties on the file object (does not match agains file.extname only)

var File = require('vinyl');
var matchFile = require('{%= name %}');

var file = new File({path: 'a/b/c.txt', base: 'a'});
var isMatch = matchFile('c.txt', file);
//=> true (since `c.txt` matches file.basename)

Examples

Continuing with the above setup code, all of the following would return true:

// file.path
matchFile('a/b/c.txt', file);
// file.relative
matchFile('b/c.txt', file);
// file.basename
matchFile('c.txt', file);
// file.stem
matchFile('c', file);

.isMatch

Similar to matchFile, but also supports glob patterns for matching. [micromatch][] is used for matching, visit that project to see all available features and options.

var file = new File({path: 'a/b/c.txt'});
console.log(matcher.isMatch('*.js', file));
//=> false

var file = new File({path: 'a/b/c.js'});
console.log(matcher.isMatch('*.js', file));
//=> true

Examples

var File = require('vinyl');
var matchFile = require('{%= name %}');

var file = new File({path: 'a/b/c/d/e.txt', base: 'a/b/c'});
file.key = 'zzz/a.txt'; // arbitrary key (for caching)

// file.path
console.log(matchFile.isMatch('a/b/c/d/e.txt', file));
// file.relative
console.log(matchFile.isMatch('d/e.txt', file));
// file.basename
console.log(matchFile.isMatch('e.txt', file));
// file.stem
console.log(matchFile.isMatch('e', file));
// file.key
console.log(matchFile.isMatch('zzz/a.txt', file));
// glob pattern for `file.path`
console.log(matchFile.isMatch('**/*.txt', file));
// glob pattern for `file.relative`
console.log(matchFile.isMatch('d/*.txt', file));
// glob pattern for `file.stem`
console.log(matchFile.isMatch('*', file));
// glob pattern for `file.basename`
console.log(matchFile.isMatch('*.txt', file));

.matcher

Returns a matcher function bound to the given glob patterns and options. [micromatch][] is used for matching, visit that project to see all available features and options.

var isMatch = matchFile.matcher('*.js');
console.log(isMatch);
//=> [function]

var file = new File({path: 'a/b/c.txt'});
console.log(isMatch(file));
//=> false

var file = new File({path: 'a/b/c.js'});
console.log(isMatch(file));
//=> true

Examples

Given this setup code:

var File = require('vinyl');
var matchFile = require('{%= name %}');

var file = new File({path: 'a/b/c/d/e.txt', base: 'a/b/c'});
file.key = 'zzz/a.txt'; // arbitrary key (for caching)

All of the following examples would return true:

// file.path
var isMatch = matchFile.matcher('a/b/c/d/e.txt');
console.log(isMatch(file));
// file.relative
var isMatch = matchFile.matcher('d/e.txt');
console.log(isMatch(file));
// file.basename
var isMatch = matchFile.matcher('e.txt');
console.log(isMatch(file));
// file.stem
var isMatch = matchFile.matcher('e');
console.log(isMatch(file));
// file.key
var isMatch = matchFile.matcher('zzz/a.txt');
console.log(isMatch(file));
// glob pattern for `file.path`
var isMatch = matchFile.matcher('**/*.txt');
console.log(isMatch(file));
// glob pattern for `file.relative`
var isMatch = matchFile.matcher('d/*.txt');
console.log(isMatch(file));
// glob pattern for `file.stem`
var isMatch = matchFile.matcher('*');
console.log(isMatch(file));
// glob pattern for `file.basename`
var isMatch = matchFile.matcher('*.txt');
console.log(isMatch(file));

Gulp usage

Use in your [gulp][] plugin:

var though = require('though2');
var gulp = require('gulp');

gulp.task('example', function() {
  return gulp.src('src/**/*')
    .pipe(filter('*.js'));
});

function filter(pattern, options) {
  // define a matcher function outside of the plugin function
  var isMatch = matchFile.matcher(pattern, options);

  return through.obj(function(file, enc, next) {
    // use the matcher function
    if (isMatch(file)) {
      next(null, file);
      return;
    }
    next();
  });
}