Substitutions
Substitutions are used to replace arbitrary text tokens in any text file with static or dynamic contents.
Substitutions are configured with rules where each rule:
- defines the file paths where replacements must occur; file paths are defined as regular paths or globs so you can match multiple files with a single rule
- defines the token to be replaced using regular expressions to give you complete freedom on the selection, which may include dynamic values
- defines the content to use when replacing the content as a static string or a template so you can use static contents or any dynamic attribute from the internal State
A common use case for substitutions is replacing the version attribute into platform-specific files so you can bridge the version detection and generation performed by Nyx with any language-specific artifact. For example, if you're woking on a Node project you can replace the value of the version attribute in the package.json using the version attribute from the State to make sure the Node version is always in synch with Nyx.
Substitutions are configured within the substitutions section. The section allows one sub-section for each substitution and some overall options.
Substitutions are performed by the Make command.
You can have as many substitutions as you want. You can use presets that come bundled with Nyx, override them or define your own from scratch.
Substitutions for a widely used set of technologies and languages is provided as part of the Extended preset. None of them is enabled by default but if you're using the Extended preset all you need to do is to enable the ones you need.
Substitutions overall options
| Name | Type | Command Line Option | Environment Variable | Default |
|---|---|---|---|---|
substitutions/enabled | list | --substitutions-enabled=<NAMES> | NYX_SUBSTITUTIONS_ENABLED=<NAMES> | No substitution |
Enabled
| Name | substitutions/enabled |
| Type | list |
| Default | No substitution |
| Command Line Option | --substitutions-enabled=<NAMES> |
| Environment Variable | NYX_SUBSTITUTIONS_ENABLED=<NAMES> |
| Configuration File Option | substitutions/enabled |
| Related state attributes |
The comma separated list of substitution names that are enabled for the project. Here you can enable or disable the various substitutions, either custom or default.
Each item in the list must correspond to a substitution name attribute. Each named substitution must exist, but not all defined substitutions must be enabled here. Substitutions not listed here will just be ignored by Nyx as if they were not even defined.
The order in which substitution are listed matters. The substitutions listed first are evaluated first, so consider this in case you are defining multiple substitutions that may replace the same secrions of a target file.
Substitution definition
Within the substitutions block you can define as many substitutions as you want, each in its own separate block. The name identifies the substitution so to define a brand new substitution make sure you give it a name that was not already in use. If you use a name that was already defined for a substitution then you are overriding an existing substitution. Depending on the configuration method you use the name property might be defined inside or outside the block that configures a single substitution.
Configuring substitution gives Nyx information about:
- which files to operate the substitutions on
- the text tokens to replace
- the content to use to replace the matching text tokens
Each substitution has the following attributes:
| Name | Type | Command Line Option | Environment Variable | Default |
|---|---|---|---|---|
substitutions/<NAME>/files | string | --substitutions-<NAME>-files=<GLOB> | NYX_SUBSTITUTIONS_<NAME>_FILES=<GLOB> | N/A |
substitutions/<NAME>/match | string | --substitutions-<NAME>-match=<REGEX> | NYX_SUBSTITUTIONS_<NAME>_MATCH=<REGEX> | N/A |
substitutions/<NAME>/replace | string | --substitutions-<NAME>-replace=<TEMPLATE> | NYX_SUBSTITUTIONS_<NAME>_REPLACE=<TEMPLATE> | N/A |
When using multiple configuration methods or customizing presets, these values must be inherited or overridden as a whole. Overriding single values and inheriting others is not supported for this type of configuration option so when they are re-declared at one configuration level, all inherited values from those configuration methods with lower precedence are suppressed.
Files
| Name | substitutions/<NAME>/files |
| Type | string |
| Default | N/A |
| Command Line Option | --substitutions-<NAME>-files=<GLOB> |
| Environment Variable | NYX_SUBSTITUTIONS_<NAME>_FILES=<GLOB> |
| Configuration File Option | substitutions/items/<NAME>/files |
| Related state attributes |
The files is a regular file path or glob that matches zero, one or multiple files to evaluate for substitutions. When relative paths are used they are interpreted as relative to the current working directory.
Match
| Name | substitutions/<NAME>/match |
| Type | string |
| Default | N/A |
| Command Line Option | --substitutions-<NAME>-match=<REGEX> |
| Environment Variable | NYX_SUBSTITUTIONS_<NAME>_MATCH=<REGEX> |
| Configuration File Option | substitutions/items/<NAME>/match |
| Related state attributes |
The match regular expression defines the tokens to be replaced as a whole using the replace value configured for the rule. This expression can match zero, one or more text tokens. When multiple tokens are matched they are all replaced.
Please note that the token is matched as a whole so, for example, if this expression matches version: 1.2.3, the replace option must contain version: {{version}}, not just {{version}}, or the version: part will disappear and subsequent substitutions won't work.
Use tools like regular expressions 101 to write and test your regular expressions.
Replace
| Name | substitutions/<NAME>/replace |
| Type | string |
| Default | N/A |
| Command Line Option | --substitutions-<NAME>-replace=<TEMPLATE> |
| Environment Variable | NYX_SUBSTITUTIONS_<NAME>_REPLACE=<TEMPLATE> |
| Configuration File Option | substitutions/items/<NAME>/replace |
| Related state attributes | any |
The text to replace the matched tokens, if any.
Here you can pass a template to generate this attribute dynamically at runtime.
Name
| Name | substitutions/<NAME> |
| Type | string |
| Default | N/A |
| Command Line Option | --substitutions-<NAME>=<NAME> |
| Environment Variable | NYX_SUBSTITUTIONS_<NAME>=<NAME> |
| Configuration File Option | substitutions/items/<NAME> |
| Related state attributes |
The short name that identifies this substitution. This is also the value you can use in the enabled substitutions. This is actually not a field to be set within a substitution section but instead the key of the map element.
This option is mandatory.