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.

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

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

Typical usage of this class follows the following pattern: First an instance is created and initialized with the map that contains the values for the available variables. If a prefix and/or suffix for variables should be used other than the default ones, the appropriate settings can be performed. After that the replace() method can be called passing in the source text for interpolation. In the returned text all variable references (as long as their values are known) will be resolved. The following example demonstrates this:

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}.";
StrSubstitutor sub = new StrSubstitutor(valuesMap);
String resolvedString = sub.replace(templateString);

yielding:

     The quick brown fox jumped over the lazy dog.

Also, this class allows to 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, as those are arguably where the default ${} delimiter set originated. The variable default value delimiter can be manually set by calling setValueDelimiterMatcher(StrMatcher), setValueDelimiter(char) or setValueDelimiter(String). The following shows an example with variable default value settings:

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}.";
StrSubstitutor sub = new StrSubstitutor(valuesMap);
String resolvedString = sub.replace(templateString);

yielding:

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

In addition to this usage pattern there are some static convenience methods that cover the most common use cases. These methods can be used without the need of manually creating an instance. However if multiple replace operations are to be performed, creating and reusing an instance of this class will be more efficient.

Variable replacement works in a recursive way. Thus, if a variable value contains a variable then that variable will also be replaced. Cyclic replacements are detected and will cause an exception to be thrown.

Sometimes the interpolation's result must contain a variable prefix. As an example take the following source text:

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

Here only the variable's name referred to in the text should be replaced resulting in the text (assuming that the value of the name variable is x):

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

StrSubstitutor supports this recursive substitution in variable names, but it has to be enabled explicitly by setting the enableSubstitutionInVariables property to true.

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);