Substitutes variables within a string by values.

This class takes a piece of text and substitutes all the variables within it. The default definition of a variable is ${variableName}. The prefix and suffix can be changed via constructors and set methods.

Variable values are typically resolved from a map, but could also be resolved from system properties, or by supplying a custom variable resolver.

Using System Properties

The simplest example is to use this class to replace Java System properties. For example:

StringSubstitutor
    .replaceSystemProperties("You are running with java.version = ${java.version} and os.name = ${os.name}.");

Using a Custom Map

Typical usage of this class follows the following pattern:

• Create and initialize a StringSubstitutor with the map that contains the values for the variables you want to make available.
• Optionally set attributes like variable prefix, variable suffix, default value delimiter, and so on.
• Call the replace() method with in the source text for interpolation.
• The returned text contains all variable references (as long as their values are known) as resolved.

For example:

// Build map
Map<String, String> valuesMap = new HashMap<>();
valuesMap.put("animal", "quick brown fox");
valuesMap.put("target", "lazy dog");
String templateString = "The ${animal} jumped over the ${target}.";

// Build StringSubstitutor
StringSubstitutor sub = new StringSubstitutor(valuesMap);

// Replace
String resolvedString = sub.replace(templateString);

yielding:

"The quick brown fox jumped over the lazy dog."

Providing Default Values

You can set a default value for unresolved variables. The default value for a variable can be appended to the variable name after the variable default value delimiter. The default value of the variable default value delimiter is ":-", as in bash and other *nix shells.

You can set the variable value delimiter with setValueDelimiterMatcher(StringMatcher), setValueDelimiter(char) or setValueDelimiter(String).

For example:

// Build map
Map<String, String> valuesMap = new HashMap<>();
valuesMap.put("animal", "quick brown fox");
valuesMap.put("target", "lazy dog");
String templateString = "The ${animal} jumped over the ${target} ${undefined.number:-1234567890} times.";

// Build StringSubstitutor
StringSubstitutor sub = new StringSubstitutor(valuesMap);

// Replace
String resolvedString = sub.replace(templateString);

yielding:

"The quick brown fox jumped over the lazy dog 1234567890 times."

StringSubstitutor supports throwing exceptions for unresolved variables, you enable this by setting calling setEnableUndefinedVariableException(boolean) with true.

Reusing Instances

Static shortcut methods cover the most common use cases. If multiple replace operations are to be performed, creating and reusing an instance of this class will be more efficient.

Using Interpolation

The default interpolator lets you use string lookups like:

final StringSubstitutor interpolator = StringSubstitutor.createInterpolator();
final String text = interpolator.replace(
      "Base64 Decoder:        ${base64Decoder:SGVsbG9Xb3JsZCE=}\n"
    + "Base64 Encoder:        ${base64Encoder:HelloWorld!}\n"
    + "Java Constant:         ${const:java.awt.event.KeyEvent.VK_ESCAPE}\n"
    + "Date:                  ${date:yyyy-MM-dd}\n"
    + "Environment Variable:  ${env:USERNAME}\n"
    + "File Content:          ${file:UTF-8:src/test/resources/document.properties}\n"
    + "Java:                  ${java:version}\n"
    + "Localhost:             ${localhost:canonical-name}\n"
    + "Properties File:       ${properties:src/test/resources/document.properties::mykey}\n"
    + "Resource Bundle:       ${resourceBundle:org.apache.commons.text.example.testResourceBundleLookup:mykey}\n"
    + "System Property:       ${sys:user.dir}\n"
    + "URL Decoder:           ${urlDecoder:Hello%20World%21}\n"
    + "URL Encoder:           ${urlEncoder:Hello World!}\n"
    + "XML XPath:             ${xml:src/test/resources/document.xml:/root/path/to/node}\n");

For documentation and a full list of available lookups, see StringLookupFactory.

Using Recursive Variable Replacement

Variable replacement can work recursively by calling setEnableSubstitutionInVariables(boolean) with true. If a variable value contains a variable then that variable will also be replaced. Cyclic replacements are detected and will throw an exception.

You can get the replace result to contain a variable prefix. For example:

"The variable ${${name}} must be used."

If the value of the "name" variable is "x", then only the variable "name" is replaced resulting in:

"The variable ${x} must be used."

To achieve this effect there are two possibilities: Either set a different prefix and suffix for variables which do not conflict with the result text you want to produce. The other possibility is to use the escape character, by default '$'. If this character is placed before a variable reference, this reference is ignored and won't be replaced. For example:

"The variable $${${name}} must be used."

In some complex scenarios you might even want to perform substitution in the names of variables, for instance

${jre-${java.specification.version}}

StringSubstitutor supports this recursive substitution in variable names, but it has to be enabled explicitly by calling setEnableSubstitutionInVariables(boolean) with true.

Thread Safety

This class is not thread safe.

Map<String, String> valuesMap = new HashMap<>();
valuesMap.put("name", "Douglas ${surname}");
valuesMap.put("surname", "Crockford");
String templateString = "Hi ${name}";
StrSubstitutor sub = new StrSubstitutor(valuesMap);
String resolvedString = sub.replace(templateString);