Add support for custom output (#119)

README.md

@@ -4,27 +4,49 @@
 Visual Studio Team Services Build and Release extension that replace tokens in files with variable values.
 
 ## Usage
-Add a new task, select **Replace Tokens** from the **Utility** category and configure it as needed.
+If you are using the UI, add a new task, select **Replace Tokens** from the **Utility** category and configure it as needed:
 
 ![Replace Tokens parameters](images/task-parameters.png)
 
-Parameters include:
-- **Root directory**: the base directory for searching files. If not specified the default working directory will be used.
-- **Target files**: the absolute or relative newline-separated paths to the files to replace tokens. Wildcards can be used (eg: `**\*.config` for all config files in all sub folders).
-- **Files encoding**: the files encoding used for reading and writing. The 'auto' value will determine the encoding based on the Byte Order Mark (BOM) if present; otherwise it will use ascii.
-- **Write unicode BOM**: if checked writes an unicode Byte Order Mark (BOM).
-- **Escape type**: specify how to escape variable values. Value `auto` uses the file extension (`.json` and `.xml`) to determine the escaping and `none` as fallback.
-- **Escape character**: when using `custom` escape type, the escape character to use when escaping characters in the variable values.
-- **Characters to escape**: when using `custom` escape type, characters in variable values to escape before replacing tokens.
-- **Verbosity**: specify the level of log verbosity. (note: error and system debug are always on)
-- **Action**: specify the action to take on a missing variable.
+If your are using a YAML file, add a task with the following syntax:
+```yaml
+- task: qetza.replacetokens.replacetokens-task.replacetokens@3
+  displayName: 'Replace tokens'
+  inputs:
+    targetFiles: |
+      **/*.config
+      **/*.json => outputs/*.json
+```
+
+Parameters include (in parenthesis the yaml name):
+- **Root directory** (rootDirectory): the base directory for searching files. If not specified the default working directory will be used.
+- **Target files** (targetFiles): the absolute or relative newline-separated paths to the files to replace tokens. Wildcards can be used (eg: `**\*.config` for all .config files in all sub folders).
+> **Syntax**: {file path}[ => {output path}]  
+>
+> - `web.config` will replace tokens in _web.config_ and update the file.
+> - `web.tokenized.config => web.config` will replace tokens in _web.tokenized.config_ and save the result in _web.config_.
+> - `config\web.tokenized.config => c:\config\web.config` will replace tokens in _config\web.tokenized.config_ and save the result in _c:\\config\web.config_.
+>
+> **Wildcard support**
+> - `*.tokenized.config => *.config` will replace tokens in all _{filename}.tokenized.config_ target files and save the result in _{filename}.config_.
+> - `**\*.tokenized.config => c:\tmp\*.config` will replace tokens in all _{filename}.tokenized.config_ target files and save the result in _c:\tmp\\{filename}.config_.
+>
+> Only the wildcard _*_ in the target file name will be used for replacement in the output.  
+> Relative paths in the output pattern are relative to the target file path.
+- **Files encoding** (encoding): the files encoding used for reading and writing. The 'auto' value will determine the encoding based on the Byte Order Mark (BOM) if present; otherwise it will use ascii.
+- **Write unicode BOM** (writeBOM): if checked writes an unicode Byte Order Mark (BOM).
+- **Escape type** (escapeType): specify how to escape variable values. Value `auto` uses the file extension (`.json` and `.xml`) to determine the escaping and `none` as fallback.
+- **Escape character** (escapeChar): when using `custom` escape type, the escape character to use when escaping characters in the variable values.
+- **Characters to escape** (charsToEscape): when using `custom` escape type, characters in variable values to escape before replacing tokens.
+- **Verbosity** (verbosity): specify the level of log verbosity. (note: error and system debug are always on)
+- **Action** (actionOnMissing): specify the action to take on a missing variable.
   - _silently continue_: the task will continue without displaying any message.
   - _log warning_: the task will continue but log a warning with the missing variable name.
   - _fail_: the task will fail and log the missing variable name.
-- **Keep token**: if checked tokens with missing variables will not be replaced by empty string.
-- **Token prefix**: the prefix of the tokens to search in the target files.
-- **Token suffix**: the suffix of the tokens to search in the target files.
-- **Empty value**: the variable value that will be replaced with an empty string.
+- **Keep token** (keepToken): if checked tokens with missing variables will not be replaced by empty string.
+- **Token prefix** (tokenPrefix): the prefix of the tokens to search in the target files.
+- **Token suffix** (tokenSuffix): the suffix of the tokens to search in the target files.
+- **Empty value** (emptyValue): the variable value that will be replaced with an empty string.
 
 ## Tips
 If you want to use tokens in XML based configuration files to be replaced during deployment and also have those files usable for local development you can combine the [Replace Tokens task](https://marketplace.visualstudio.com/items?itemName=qetza.replacetokens) with the [XDT tranform task](https://marketplace.visualstudio.com/items?itemName=qetza.xdttransform):
@@ -35,11 +57,14 @@ If you want to use tokens in XML based configuration files to be replaced during
   - replace tokens in your updated configuration file
 
 ## Release notes
+**New in 3.3.0**
+- Add support for custom output file and wildcard support ([#114](https://github.com/qetza/vsts-replacetokens-task/issues/114)).
+
 **New in 3.2.2**
-- Fix matching issue with directory
+- Fix matching issue with directory ([#122](https://github.com/qetza/vsts-replacetokens-task/issues/122)).
 
 **New in 3.2.1**
-- Fix log issue with escaped secret values
+- Fix log issue with escaped secret values.
 
 **New in 3.2.0**
 - Switch to [jschardet](https://github.com/aadsm/jschardet) for encoding detection when selecting `auto` in _File encoding_ ([#99](https://github.com/qetza/vsts-replacetokens-task/issues/99)).