Merge pull request #199 from jacksteamdev/master

Add documentation for skip and transform

README.md

@@ -274,9 +274,12 @@ Property | Type | Default | Description
 **force** | *Boolean* | `false` | performs the action [forcefully](#running-a-generator-forcefully) (means different things depending on the action)
 **data** | *Object / Function* | `{}` | specifies data that should be mixed with user prompt answers when running this action
 **abortOnFail** | *Boolean* | `true` | if this action fails for any reason abort all future actions
+**skip** | *Function* | | an optional function that specifies if the action should run
 
 > The `data` property on any `ActionConfig` can also be a `Function` that returns an `Object` or a `Function` that returns a `Promise` that resolves with an `Object`.
 
+> The `skip` function on any `ActionConfig` is optional and should return a string if the action should be skipped. The return value is the reason to skip the action. 
+
 > Instead of an Action Object, a [function can also be used](#custom-action-function-)
 
 ## Other Methods
@@ -301,6 +304,8 @@ Method | Parameters | Returns | Description
 # Built-In Actions
 There are several types of built-in actions you can use in your [GeneratorConfig](#interface-generatorconfig). You specify which `type` of action  (all paths are based on the location of the plopfile), and a template to use.
 
+> The `Add`, `AddMany` and `Modify` actions have an optional `transform` method that can be used to transform the template result before it is written to disk. The `transform` function receives the template result or file contents as a `string` and the action data as arguments. It must return a `string` or a `Promise` that resolves to a `string`.
+
 ## Add
 The `add` action is used to (you guessed it) add a file to your project. The path property is a handlebars template that will be used to create the file by name. The file contents will be determined by the `template` or `templateFile` property.
 
@@ -310,6 +315,8 @@ Property | Type | Default | Description
 **template** | *String* | | a handlebars template that should be used to build the new file
 **templateFile** | *String* | | a path a file containing the `template`
 **skipIfExists** | *Boolean* | `false` | skips a file if it already exists (instead of failing)
+**transform** | *Function* | | [an optional function](#built-in-actions) that can be used to transform the template result before writing the file to disk
+**skip** | *Function* | | *inherited from [ActionConfig](#interface-actionconfig)*
 **force** | *Boolean* | `false` | *inherited from [ActionConfig](#interface-actionconfig)* (overwrites files if they exist)
 **data** | *Object* | `{}` | *inherited from [ActionConfig](#interface-actionconfig)*
 **abortOnFail** | *Boolean* | `true` | *inherited from [ActionConfig](#interface-actionconfig)*
@@ -325,20 +332,24 @@ Property | Type | Default | Description
 **stripExtensions** | *[String]* | `['hbs']` | file extensions that should be stripped from `templateFiles` files names while being added to the `destination`
 **globOptions** | *[Object](https://github.com/sindresorhus/globby#options)* | | glob options that change how to match to the template files to be added
 **verbose** | *Boolean* | `true` | print each successfully added file path
+**transform** | *Function* | | [an optional function](#built-in-actions) that can be used to transform the template result before writing each file to disk
+**skip** | *Function* | | *inherited from [ActionConfig](#interface-actionconfig)*
 **skipIfExists** | *Boolean* | `false` | *inherited from [Add](#add)* (skips a file if it already exists)
 **force** | *Boolean* | `false` | *inherited from [ActionConfig](#interface-actionconfig)* (overwrites files if they exist)
 **data** | *Object* | `{}` | *inherited from [ActionConfig](#interface-actionconfig)*
 **abortOnFail** | *Boolean* | `true` | *inherited from [ActionConfig](#interface-actionconfig)*
 
 ## Modify
-The `modify` action will use a `pattern` property to find/replace text in the file located at the `path` specified. More details on modify can be found in the example folder.
+The `modify` action can be used two ways. You can use a `pattern` property to find/replace text in the file located at the `path` specified, or you can use a `transform` function to transform the file contents. Both `pattern` and `transform` can be used at the same time (`transform` will happen last). More details on modify can be found in the example folder.
 
 Property | Type | Default | Description
 -------- | ---- | ------- | -----------
 **path** | *String* | | handlebars template that (when rendered) is the path of the file to be modified
 **pattern** | *RegExp* | _end‑of‑file_ | regular expression used to match text that should be replaced
 **template** | *String* | | handlebars template that should replace what was matched by the `pattern`. capture groups are available as $1, $2, etc
 **templateFile** | *String* | | path a file containing the `template`
+**transform** | *Function* | | [an optional function](#built-in-actions) that can be used to transform the file before writing it to disk
+**skip** | *Function* | | *inherited from [ActionConfig](#interface-actionconfig)*
 **data** | *Object* | `{}` | *inherited from [ActionConfig](#interface-actionconfig)*
 **abortOnFail** | *Boolean* | `true` | *inherited from [ActionConfig](#interface-actionconfig)*
 

example/plopfile.js

@@ -122,7 +122,22 @@ module.exports = function (plop) {
 				path: 'folder/change-me.txt',
 				pattern: /## replace name here ##/gi,
 				template: 'replaced => {{dashCase name}}'
-			}
+			},{
+				type: 'modify',
+				path: 'folder/change-me.txt',
+				skip(data) {
+					if (!data.toppings.includes('mushroom')) {
+						// Skip this action
+						return 'Skipped replacing mushrooms';
+					} else {
+						// Continue with this action
+						return;
+					}
+				},
+				transform(fileContents, data) {
+					return fileContents.replace(/mushrooms/g, 'pepperoni');
+				}
+			},
 		]
 	});