dynamic fillers for large apps

[idefy]

This pull request is made in regards of issue #80 which is also something that we needed and which should resolves all cases.

It allows to set a dynamic filler such as name:'module::'
and in the page have injections like : <!-- module:main:js --><!-- module:other:js -->
the transforms methods now gets the tag name as found in the html page, giving freedom to apply specific injection rules based on the current tag.

I have added some tests and updated also the documentation.
Hopes this helps and can be integrated soon.

[joakimbeng]

Actually I don't see the real benefit of this.
The provided example in the readme could already be solved in a much more readable and concise way IMO:

gulp.src('./index.html')
  .pipe(inject(gulp.src('./app/main/**/*.js', {read: false}), {name: 'main'}))
  .pipe(inject(gulp.src('./app/messaging/**/*.js', {read: false}), {name: 'messaging'}))
  .pipe(inject(gulp.src('./app/somethingelse/**/*.js', {read: false}), {name: 'somethingelse'}))
  .pipe(gulp.dest('./'));

So please come up with a better scenario which really makes this feature shine ;)

[idefy]

@joakimbeng
Alas, this solution can't be called concise as soon as you have a large projects with a hundred artefacts you need to load on a per page basis.
Also it goes against the Gulp principle : code over configuration. Here you are adding too much manual configuration.

The scenarios we are trying to resolve is that the HTML provides the file dependencies needed and gulp builds based on that. Adding new artefacts should not force someone to alter the gulp file every single time, which your solution does unfortunately :(

Also, it allows someone to catch the filter and apply some special business rules as needed.

I think #80 is self explanatory.

If you see any ways I could improve the example to make this clearer, let me know I will change it.

[vladimir-djokic]

Why can't we just add support for {{filename}}? The code changes are rather simple (from the looks of it):

index.js:

var filesPerTags = groupBy(collection, function (file) {
    var ext = extname(file.path);
    var filename = path.basename(file.path); // Added

    var startTag = opt.tags.start(targetExt, ext, filename, opt.starttag); // Modified
    var endTag = opt.tags.end(targetExt, ext, opt.endtag);
    var tag = startTag + endTag;
    if (!tags[tag]) {
      tags[tag] = {start: startTag, end: endTag};
    }
    return tag;
  });

function getTag (defaults, targetExt, sourceExt, sourceFilename, defaultValue) { // Modified
  var tag = defaultValue;
  if (!tag) {
    tag = defaults[targetExt] || defaults[DEFAULT_TARGET];
  } else if (typeof tag === 'function') {
    tag = tag(targetExt, sourceExt, sourceFilename); // Modified
  }
  if (!tag) {
    return;
  }
  tag = tag.replace(new RegExp(escapeForRegExp('{{ext}}'), 'g'), sourceExt);
  tag = tag.replace(new RegExp(escapeForRegExp('{{filename}}'), 'g'), sourceFilename); // Added
  return tag.replace(new RegExp(escapeForRegExp('{{name}}'), 'g'), this.name);
}

The reason I personally need this functionality is for automated injection of .schema.json files into my .md technical specification files.

I use something like:

<!-- inject:foo.schema.json -->
<!-- endinject -->

<!-- inject:bar.schema.json -->
<!-- endinject -->

<!-- inject:baz.schema.json -->
<!-- endinject -->

per my single .md file. Different .md files might need to be injected with one or more .schema.json files, depends on the requirements of specification that I'm trying to describe in .md file.

[joakimbeng]

@vladeck see #175 which implements that feature.

@idefy I think the API gets weird with this PR. What do you think about if starttag/endtag could be functions to dynamically return the tag name instead? E.g:

gulp.src('./index.html')
    .pipe(inject(gulp.src('./app/**/*.js', {read: false}), {
        starttag: function (/* anything, maybe the same parameters as the `transform` function? */) {
            return '<!-- whateva -->';
        }
    }))
    .pipe(gulp.dest('./'))