5 minute read

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 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 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.