diff --git a/README.md b/README.md index 92b3c176..6e1bb6f3 100644 --- a/README.md +++ b/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,13 +332,15 @@ 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 -------- | ---- | ------- | ----------- @@ -339,6 +348,8 @@ Property | Type | Default | Description **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)* diff --git a/example/plopfile.js b/example/plopfile.js index 05b514fd..d2f06bb1 100644 --- a/example/plopfile.js +++ b/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'); + } + }, ] });