Add docs for #50 and add function replace examples, closes #77

README.md

@@ -11,24 +11,72 @@ npm install --save-dev gulp-replace
 
 Then, add it to your `gulpfile.js`:
 
-### Regex Replace
+### Simple string replace
 ```javascript
 var replace = require('gulp-replace');
 
 gulp.task('templates', function(){
   gulp.src(['file.txt'])
+    .pipe(replace('bar', 'foo'))
+    .pipe(gulp.dest('build/'));
+});
+```
+
+### Simple regex replace
+```javascript
+var replace = require('gulp-replace');
+
+gulp.task('templates', function(){
+  gulp.src(['file.txt'])
+    // See http://mdn.io/string.replace#Specifying_a_string_as_a_parameter
     .pipe(replace(/foo(.{3})/g, '$1foo'))
-    .pipe(gulp.dest('build/file.txt'));
+    .pipe(gulp.dest('build/'));
 });
 ```
-### String Replace
+
+### String replace with function callback
 ```javascript
 var replace = require('gulp-replace');
 
 gulp.task('templates', function(){
   gulp.src(['file.txt'])
-    .pipe(replace('bar', 'foo'))
-    .pipe(gulp.dest('build/file.txt'));
+    .pipe(replace('foo', function(match) {
+      // Replaces instances of "foo" with "oof"
+      return match.reverse();
+    }))
+    .pipe(gulp.dest('build/'));
+});
+```
+
+### Regex replace with function callback
+```javascript
+var replace = require('gulp-replace');
+
+gulp.task('templates', function(){
+  gulp.src(['file.txt'])
+    .pipe(replace(/foo(.{3})/g, function(match, p1, offset, string) {
+      // Replace foobaz with barbaz and log a ton of information
+      // See http://mdn.io/string.replace#Specifying_a_function_as_a_parameter
+      console.log('Found ' + match + ' with param ' + p1 + ' at ' + offset + ' inside of ' + string);
+      return 'bar' + p1;
+    }))
+    .pipe(gulp.dest('build/'));
+});
+```
+
+### Function callback with file object
+```javascript
+var replace = require('gulp-replace');
+
+gulp.task('templates', function(){
+  gulp.src(['file.txt'])
+    .pipe(replace('filename', function() {
+      // Replaces instances of "filename" with "file.txt"
+      // this.file is also available for regex replace
+      // See https://github.com/gulpjs/vinyl#instance-properties for details on available properties
+      return this.file.relative;
+    }))
+    .pipe(gulp.dest('build/'));
 });
 ```
 
@@ -49,6 +97,8 @@ Type: `String` or `Function`
 
 The replacement string or function. If `replacement` is a function, it will be called once for each match and will be passed the string that is to be replaced.
 
+The value of `this.file` will be equal to the [vinyl instance](https://github.com/gulpjs/vinyl#instance-properties) for the file being processed.
+
 ### replace(regex, replacement[, options])
 
 #### regex
@@ -59,7 +109,9 @@ The regex pattern to search for. See the [MDN documentation for RegExp] for deta
 #### replacement
 Type: `String` or `Function`
 
-The replacement string or function. See the [MDN documentation for String.replace] for details.
+The replacement string or function. See the [MDN documentation for String.replace] for details on special replacement string patterns and arguments to the replacement function.
+
+The value of `this.file` will be equal to the [vinyl instance](https://github.com/gulpjs/vinyl#instance-properties) for the file being processed.
 
 ### gulp-replace options