# Class StringSubstitutor

java.lang.Object
org.apache.commons.text.StringSubstitutor

public class StringSubstitutor extends Object
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`.

NOTE: The list of lookups available by default in `createInterpolator()` changed in version `1.10.0`. See the `StringLookupFactory` documentation for details and an explanation on how to reproduce the previous functionality.

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

Since:
  1.3

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final char`
  `DEFAULT_ESCAPE`
  Constant for the default escape character.
  `static final StringMatcher`
  `DEFAULT_PREFIX`
  Constant for the default variable prefix.
  `static final StringMatcher`
  `DEFAULT_SUFFIX`
  Constant for the default variable suffix.
  `static final StringMatcher`
  `DEFAULT_VALUE_DELIMITER`
  Constant for the default value delimiter of a variable.
  `static final String`
  `DEFAULT_VAR_DEFAULT`
  The default variable default separator.
  `static final String`
  `DEFAULT_VAR_END`
  The default variable end separator.
  `static final String`
  `DEFAULT_VAR_START`
  The default variable start separator.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  ``
  `StringSubstitutor()`
  Constructs a new instance with defaults for variable prefix and suffix and the escaping character.
  `<V>`
  `StringSubstitutor(Map<String,V> valueMap)`
  Constructs a new initialized instance.
  `<V>`
  `StringSubstitutor(Map<String,V> valueMap, String prefix, String suffix)`
  Constructs a new initialized instance.
  `<V>`
  `StringSubstitutor(Map<String,V> valueMap, String prefix, String suffix, char escape)`
  Constructs a new initialized instance.
  `<V>`
  `StringSubstitutor(Map<String,V> valueMap, String prefix, String suffix, char escape, String valueDelimiter)`
  Constructs a new initialized instance.
  ``
  `StringSubstitutor(StringLookup variableResolver)`
  Constructs a new initialized instance.
  ``
  `StringSubstitutor(StringLookup variableResolver, String prefix, String suffix, char escape)`
  Constructs a new initialized instance.
  ``
  `StringSubstitutor(StringLookup variableResolver, String prefix, String suffix, char escape, String valueDelimiter)`
  Constructs a new initialized instance.
  ``
  `StringSubstitutor(StringLookup variableResolver, StringMatcher prefixMatcher, StringMatcher suffixMatcher, char escape)`
  Constructs a new initialized instance.
  ``
  `StringSubstitutor(StringLookup variableResolver, StringMatcher prefixMatcher, StringMatcher suffixMatcher, char escape, StringMatcher valueDelimiterMatcher)`
  Constructs a new initialized instance.
  ``
  `StringSubstitutor(StringSubstitutor other)`
  Creates a new instance based on the given.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static StringSubstitutor`
  `createInterpolator()`
  Creates a new instance using the interpolator string lookup `StringLookupFactory.interpolatorStringLookup()`.
  `char`
  `getEscapeChar()`
  Returns the escape character.
  `StringLookup`
  `getStringLookup()`
  Gets the StringLookup that is used to lookup variables.
  `StringMatcher`
  `getValueDelimiterMatcher()`
  Gets the variable default value delimiter matcher currently in use.
  `StringMatcher`
  `getVariablePrefixMatcher()`
  Gets the variable prefix matcher currently in use.
  `StringMatcher`
  `getVariableSuffixMatcher()`
  Gets the variable suffix matcher currently in use.
  `boolean`
  `isDisableSubstitutionInValues()`
  Returns a flag whether substitution is disabled in variable values.If set to true, the values of variables can contain other variables will not be processed and substituted original variable is evaluated, e.g.
  `boolean`
  `isEnableSubstitutionInVariables()`
  Returns a flag whether substitution is done in variable names.
  `boolean`
  `isEnableUndefinedVariableException()`
  Returns a flag whether exception can be thrown upon undefined variable.
  `boolean`
  `isPreserveEscapes()`
  Returns the flag controlling whether escapes are preserved during substitution.
  `String`
  `replace(char[] source)`
  Replaces all the occurrences of variables with their matching values from the resolver using the given source array as a template.
  `String`
  `replace(char[] source, int offset, int length)`
  Replaces all the occurrences of variables with their matching values from the resolver using the given source array as a template.
  `String`
  `replace(CharSequence source)`
  Replaces all the occurrences of variables with their matching values from the resolver using the given source as a template.
  `String`
  `replace(CharSequence source, int offset, int length)`
  Replaces all the occurrences of variables with their matching values from the resolver using the given source as a template.
  `String`
  `replace(Object source)`
  Replaces all the occurrences of variables in the given source object with their matching values from the resolver.
  `static <V> String`
  `replace(Object source, Map<String,V> valueMap)`
  Replaces all the occurrences of variables in the given source object with their matching values from the map.
  `static <V> String`
  `replace(Object source, Map<String,V> valueMap, String prefix, String suffix)`
  Replaces all the occurrences of variables in the given source object with their matching values from the map.
  `static String`
  `replace(Object source, Properties valueProperties)`
  Replaces all the occurrences of variables in the given source object with their matching values from the properties.
  `String`
  `replace(String source)`
  Replaces all the occurrences of variables with their matching values from the resolver using the given source string as a template.
  `String`
  `replace(StringBuffer source)`
  Replaces all the occurrences of variables with their matching values from the resolver using the given source buffer as a template.
  `String`
  `replace(StringBuffer source, int offset, int length)`
  Replaces all the occurrences of variables with their matching values from the resolver using the given source buffer as a template.
  `String`
  `replace(String source, int offset, int length)`
  Replaces all the occurrences of variables with their matching values from the resolver using the given source string as a template.
  `String`
  `replace(TextStringBuilder source)`
  Replaces all the occurrences of variables with their matching values from the resolver using the given source builder as a template.
  `String`
  `replace(TextStringBuilder source, int offset, int length)`
  Replaces all the occurrences of variables with their matching values from the resolver using the given source builder as a template.
  `boolean`
  `replaceIn(StringBuffer source)`
  Replaces all the occurrences of variables within the given source buffer with their matching values from the resolver.
  `boolean`
  `replaceIn(StringBuffer source, int offset, int length)`
  Replaces all the occurrences of variables within the given source buffer with their matching values from the resolver.
  `boolean`
  `replaceIn(StringBuilder source)`
  Replaces all the occurrences of variables within the given source buffer with their matching values from the resolver.
  `boolean`
  `replaceIn(StringBuilder source, int offset, int length)`
  Replaces all the occurrences of variables within the given source builder with their matching values from the resolver.
  `boolean`
  `replaceIn(TextStringBuilder source)`
  Replaces all the occurrences of variables within the given source builder with their matching values from the resolver.
  `boolean`
  `replaceIn(TextStringBuilder source, int offset, int length)`
  Replaces all the occurrences of variables within the given source builder with their matching values from the resolver.
  `static String`
  `replaceSystemProperties(Object source)`
  Replaces all the occurrences of variables in the given source object with their matching values from the system properties.
  `protected String`
  `resolveVariable(String variableName, TextStringBuilder buf, int startPos, int endPos)`
  Internal method that resolves the value of a variable.
  `StringSubstitutor`
  `setDisableSubstitutionInValues(boolean disableSubstitutionInValues)`
  Sets a flag whether substitution is done in variable values (recursive).
  `StringSubstitutor`
  `setEnableSubstitutionInVariables(boolean enableSubstitutionInVariables)`
  Sets a flag whether substitution is done in variable names.
  `StringSubstitutor`
  `setEnableUndefinedVariableException(boolean failOnUndefinedVariable)`
  Sets a flag whether exception should be thrown if any variable is undefined.
  `StringSubstitutor`
  `setEscapeChar(char escapeChar)`
  Sets the escape character.
  `StringSubstitutor`
  `setPreserveEscapes(boolean preserveEscapes)`
  Sets a flag controlling whether escapes are preserved during substitution.
  `StringSubstitutor`
  `setValueDelimiter(char valueDelimiter)`
  Sets the variable default value delimiter to use.
  `StringSubstitutor`
  `setValueDelimiter(String valueDelimiter)`
  Sets the variable default value delimiter to use.
  `StringSubstitutor`
  `setValueDelimiterMatcher(StringMatcher valueDelimiterMatcher)`
  Sets the variable default value delimiter matcher to use.
  `StringSubstitutor`
  `setVariablePrefix(char prefix)`
  Sets the variable prefix to use.
  `StringSubstitutor`
  `setVariablePrefix(String prefix)`
  Sets the variable prefix to use.
  `StringSubstitutor`
  `setVariablePrefixMatcher(StringMatcher prefixMatcher)`
  Sets the variable prefix matcher currently in use.
  `StringSubstitutor`
  `setVariableResolver(StringLookup variableResolver)`
  Sets the VariableResolver that is used to lookup variables.
  `StringSubstitutor`
  `setVariableSuffix(char suffix)`
  Sets the variable suffix to use.
  `StringSubstitutor`
  `setVariableSuffix(String suffix)`
  Sets the variable suffix to use.
  `StringSubstitutor`
  `setVariableSuffixMatcher(StringMatcher suffixMatcher)`
  Sets the variable suffix matcher currently in use.
  `protected boolean`
  `substitute(TextStringBuilder builder, int offset, int length)`
  Internal method that substitutes the variables.
  `String`
  `toString()`
  Returns a string representation of the object.

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### DEFAULT_ESCAPE

    public static final char DEFAULT_ESCAPE
    Constant for the default escape character.
    See Also:
      - Constant Field Values

  - ### DEFAULT_VAR_DEFAULT

    public static final String DEFAULT_VAR_DEFAULT
    The default variable default separator.
    Since:
      1.5.
    See Also:
      - Constant Field Values

  - ### DEFAULT_VAR_END

    public static final String DEFAULT_VAR_END
    The default variable end separator.
    Since:
      1.5.
    See Also:
      - Constant Field Values

  - ### DEFAULT_VAR_START

    public static final String DEFAULT_VAR_START
    The default variable start separator.
    Since:
      1.5.
    See Also:
      - Constant Field Values

  - ### DEFAULT_PREFIX

    public static final StringMatcher DEFAULT_PREFIX
    Constant for the default variable prefix.

  - ### DEFAULT_SUFFIX

    public static final StringMatcher DEFAULT_SUFFIX
    Constant for the default variable suffix.

  - ### DEFAULT_VALUE_DELIMITER

    public static final StringMatcher DEFAULT_VALUE_DELIMITER
    Constant for the default value delimiter of a variable.

- ## Constructor Details

  - ### StringSubstitutor

    public StringSubstitutor()
    Constructs a new instance with defaults for variable prefix and suffix and the escaping character.

  - ### StringSubstitutor

    public <V> StringSubstitutor(Map<String,V> valueMap)
    Constructs a new initialized instance. Uses defaults for variable prefix and suffix and the escaping character.
    Type Parameters:
      `V` - the type of the values in the map.
    Parameters:
      `valueMap` - the map with the variables' values, may be null.

  - ### StringSubstitutor

    public <V> StringSubstitutor(Map<String,V> valueMap, String prefix, String suffix)
    Constructs a new initialized instance. Uses a default escaping character.
    Type Parameters:
      `V` - the type of the values in the map.
    Parameters:
      `valueMap` - the map with the variables' values, may be null.
      `prefix` - the prefix for variables, not null.
      `suffix` - the suffix for variables, not null.
    Throws:
      `IllegalArgumentException` - if the prefix or suffix is null.

  - ### StringSubstitutor

    public <V> StringSubstitutor(Map<String,V> valueMap, String prefix, String suffix, char escape)
    Constructs a new initialized instance.
    Type Parameters:
      `V` - the type of the values in the map.
    Parameters:
      `valueMap` - the map with the variables' values, may be null.
      `prefix` - the prefix for variables, not null.
      `suffix` - the suffix for variables, not null.
      `escape` - the escape character.
    Throws:
      `IllegalArgumentException` - if the prefix or suffix is null.

  - ### StringSubstitutor

    public <V> StringSubstitutor(Map<String,V> valueMap, String prefix, String suffix, char escape, String valueDelimiter)
    Constructs a new initialized instance.
    Type Parameters:
      `V` - the type of the values in the map.
    Parameters:
      `valueMap` - the map with the variables' values, may be null.
      `prefix` - the prefix for variables, not null.
      `suffix` - the suffix for variables, not null.
      `escape` - the escape character.
      `valueDelimiter` - the variable default value delimiter, may be null.
    Throws:
      `IllegalArgumentException` - if the prefix or suffix is null.

  - ### StringSubstitutor

    public StringSubstitutor(StringLookup variableResolver)
    Constructs a new initialized instance.
    Parameters:
      `variableResolver` - the variable resolver, may be null

  - ### StringSubstitutor

    public StringSubstitutor(StringLookup variableResolver, String prefix, String suffix, char escape)
    Constructs a new initialized instance.
    Parameters:
      `variableResolver` - the variable resolver, may be null.
      `prefix` - the prefix for variables, not null.
      `suffix` - the suffix for variables, not null.
      `escape` - the escape character.
    Throws:
      `IllegalArgumentException` - if the prefix or suffix is null.

  - ### StringSubstitutor

    public StringSubstitutor(StringLookup variableResolver, String prefix, String suffix, char escape, String valueDelimiter)
    Constructs a new initialized instance.
    Parameters:
      `variableResolver` - the variable resolver, may be null.
      `prefix` - the prefix for variables, not null.
      `suffix` - the suffix for variables, not null.
      `escape` - the escape character.
      `valueDelimiter` - the variable default value delimiter string, may be null.
    Throws:
      `IllegalArgumentException` - if the prefix or suffix is null.

  - ### StringSubstitutor

    public StringSubstitutor(StringLookup variableResolver, StringMatcher prefixMatcher, StringMatcher suffixMatcher, char escape)
    Constructs a new initialized instance.
    Parameters:
      `variableResolver` - the variable resolver, may be null
      `prefixMatcher` - the prefix for variables, not null.
      `suffixMatcher` - the suffix for variables, not null.
      `escape` - the escape character.
    Throws:
      `IllegalArgumentException` - if the prefix or suffix is null.

  - ### StringSubstitutor

    public StringSubstitutor(StringLookup variableResolver, StringMatcher prefixMatcher, StringMatcher suffixMatcher, char escape, StringMatcher valueDelimiterMatcher)
    Constructs a new initialized instance.
    Parameters:
      `variableResolver` - the variable resolver, may be null
      `prefixMatcher` - the prefix for variables, not null
      `suffixMatcher` - the suffix for variables, not null
      `escape` - the escape character
      `valueDelimiterMatcher` - the variable default value delimiter matcher, may be null
    Throws:
      `IllegalArgumentException` - if the prefix or suffix is null

  - ### StringSubstitutor

    public StringSubstitutor(StringSubstitutor other)
    Creates a new instance based on the given.
    Parameters:
      `other` - The StringSubstitutor used as the source.
    Since:
      1.9

- ## Method Details

  - ### createInterpolator

    public static StringSubstitutor createInterpolator()
    Creates a new instance using the interpolator string lookup `StringLookupFactory.interpolatorStringLookup()`.

    This StringSubstitutor lets you perform substitutions like:

        StringSubstitutor.createInterpolator().replace(
          "OS name: ${sys:os.name}, user: ${env:USER}");

    The table below lists the lookups available by default in the returned instance. These may be modified through the use of the "org.apache.commons.text.lookup.StringLookupFactory.defaultStringLookups" system property, as described in the `StringLookupFactory` documentation.

    NOTE: The list of lookups available by default changed in version `1.10.0`. Configuration via system property (as mentioned above) may be necessary to reproduce previous functionality.

    Default Lookups
    Key | Lookup
    --- | ---
    "base64Decoder" | `StringLookupFactory.base64DecoderStringLookup()`
    "base64Encoder" | `StringLookupFactory.base64EncoderStringLookup()`
    "const" | `StringLookupFactory.constantStringLookup()`
    "date" | `StringLookupFactory.dateStringLookup()`
    "env" | `StringLookupFactory.environmentVariableStringLookup()`
    "file" | `StringLookupFactory.fileStringLookup()`
    "java" | `StringLookupFactory.javaPlatformStringLookup()`
    "localhost" | `StringLookupFactory.localHostStringLookup()`
    "loobackAddress" | `StringLookupFactory.loopbackAddressStringLookup()`
    "properties" | `StringLookupFactory.propertiesStringLookup()`
    "resourceBundle" | `StringLookupFactory.resourceBundleStringLookup()`
    "sys" | `StringLookupFactory.systemPropertyStringLookup()`
    "urlDecoder" | `StringLookupFactory.urlDecoderStringLookup()`
    "urlEncoder" | `StringLookupFactory.urlEncoderStringLookup()`
    "xml" | `StringLookupFactory.xmlStringLookup()`
    "xmlDecoder" | `StringLookupFactory.xmlDecoderStringLookup()`
    "xmlEncoder" | `StringLookupFactory.xmlEncoderStringLookup()`

    Returns:
      a new instance using the interpolator string lookup.
    Since:
      1.8
    See Also:
      - `StringLookupFactory.interpolatorStringLookup()`

  - ### replace

    public static <V> String replace(Object source, Map<String,V> valueMap)
    Replaces all the occurrences of variables in the given source object with their matching values from the map.
    Type Parameters:
      `V` - the type of the values in the map
    Parameters:
      `source` - the source text containing the variables to substitute, null returns null
      `valueMap` - the map with the values, may be null
    Returns:
      The result of the replace operation
    Throws:
      `IllegalArgumentException` - if a variable is not found and enableUndefinedVariableException is true

  - ### replace

    public static <V> String replace(Object source, Map<String,V> valueMap, String prefix, String suffix)
    Replaces all the occurrences of variables in the given source object with their matching values from the map. This method allows to specify a custom variable prefix and suffix
    Type Parameters:
      `V` - the type of the values in the map
    Parameters:
      `source` - the source text containing the variables to substitute, null returns null
      `valueMap` - the map with the values, may be null
      `prefix` - the prefix of variables, not null
      `suffix` - the suffix of variables, not null
    Returns:
      The result of the replace operation
    Throws:
      `IllegalArgumentException` - if the prefix or suffix is null
      `IllegalArgumentException` - if a variable is not found and enableUndefinedVariableException is true

  - ### replace

    public static String replace(Object source, Properties valueProperties)
    Replaces all the occurrences of variables in the given source object with their matching values from the properties.
    Parameters:
      `source` - the source text containing the variables to substitute, null returns null
      `valueProperties` - the properties with values, may be null
    Returns:
      The result of the replace operation
    Throws:
      `IllegalArgumentException` - if a variable is not found and enableUndefinedVariableException is true

  - ### replaceSystemProperties

    public static String replaceSystemProperties(Object source)
    Replaces all the occurrences of variables in the given source object with their matching values from the system properties.
    Parameters:
      `source` - the source text containing the variables to substitute, null returns null
    Returns:
      The result of the replace operation
    Throws:
      `IllegalArgumentException` - if a variable is not found and enableUndefinedVariableException is true

  - ### getEscapeChar

    public char getEscapeChar()
    Returns the escape character.
    Returns:
      The character used for escaping variable references.

  - ### getStringLookup

    public StringLookup getStringLookup()
    Gets the StringLookup that is used to lookup variables.
    Returns:
      The StringLookup.

  - ### getValueDelimiterMatcher

    public StringMatcher getValueDelimiterMatcher()
    Gets the variable default value delimiter matcher currently in use.

    The variable default value delimiter is the character or characters that delimit the variable name and the variable default value. This delimiter is expressed in terms of a matcher allowing advanced variable default value delimiter matches.

    If it returns null, then the variable default value resolution is disabled.

    Returns:
      The variable default value delimiter matcher in use, may be null.

  - ### getVariablePrefixMatcher

    public StringMatcher getVariablePrefixMatcher()
    Gets the variable prefix matcher currently in use.

    The variable prefix is the character or characters that identify the start of a variable. This prefix is expressed in terms of a matcher allowing advanced prefix matches.

    Returns:
      The prefix matcher in use

  - ### getVariableSuffixMatcher

    public StringMatcher getVariableSuffixMatcher()
    Gets the variable suffix matcher currently in use.

    The variable suffix is the character or characters that identify the end of a variable. This suffix is expressed in terms of a matcher allowing advanced suffix matches.

    Returns:
      The suffix matcher in use

  - ### isDisableSubstitutionInValues

    public boolean isDisableSubstitutionInValues()
    Returns a flag whether substitution is disabled in variable values.If set to true, the values of variables can contain other variables will not be processed and substituted original variable is evaluated, e.g.

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

    yielding:

             Hi Douglas ${surname}

    Returns:
      The substitution in variable values flag.

  - ### isEnableSubstitutionInVariables

    public boolean isEnableSubstitutionInVariables()
    Returns a flag whether substitution is done in variable names.
    Returns:
      The substitution in variable names flag.

  - ### isEnableUndefinedVariableException

    public boolean isEnableUndefinedVariableException()
    Returns a flag whether exception can be thrown upon undefined variable.
    Returns:
      The fail on undefined variable flag.

  - ### isPreserveEscapes

    public boolean isPreserveEscapes()
    Returns the flag controlling whether escapes are preserved during substitution.
    Returns:
      The preserve escape flag.

  - ### replace

    public String replace(char[] source)
    Replaces all the occurrences of variables with their matching values from the resolver using the given source array as a template. The array is not altered by this method.
    Parameters:
      `source` - the character array to replace in, not altered, null returns null.
    Returns:
      The result of the replace operation.
    Throws:
      `IllegalArgumentException` - if variable is not found when its allowed to throw exception.

  - ### replace

    public String replace(char[] source, int offset, int length)
    Replaces all the occurrences of variables with their matching values from the resolver using the given source array as a template. The array is not altered by this method.

    Only the specified portion of the array will be processed. The rest of the array is not processed, and is not returned.

    Parameters:
      `source` - the character array to replace in, not altered, null returns null.
      `offset` - the start offset within the array, must be valid.
      `length` - the length within the array to be processed, must be valid.
    Returns:
      The result of the replace operation.
    Throws:
      `IllegalArgumentException` - if variable is not found when its allowed to throw exception.
      `StringIndexOutOfBoundsException` - if `offset` is not in the range `0 <= offset <= chars.length`.
      `StringIndexOutOfBoundsException` - if `length < 0`.
      `StringIndexOutOfBoundsException` - if `offset + length > chars.length`.

  - ### replace

    public String replace(CharSequence source)
    Replaces all the occurrences of variables with their matching values from the resolver using the given source as a template. The source is not altered by this method.
    Parameters:
      `source` - the buffer to use as a template, not changed, null returns null.
    Returns:
      The result of the replace operation.
    Throws:
      `IllegalArgumentException` - if variable is not found when its allowed to throw exception.

  - ### replace

    public String replace(CharSequence source, int offset, int length)
    Replaces all the occurrences of variables with their matching values from the resolver using the given source as a template. The source is not altered by this method.

    Only the specified portion of the buffer will be processed. The rest of the buffer is not processed, and is not returned.

    Parameters:
      `source` - the buffer to use as a template, not changed, null returns null.
      `offset` - the start offset within the array, must be valid.
      `length` - the length within the array to be processed, must be valid.
    Returns:
      The result of the replace operation.
    Throws:
      `IllegalArgumentException` - if variable is not found when its allowed to throw exception.

  - ### replace

    public String replace(Object source)
    Replaces all the occurrences of variables in the given source object with their matching values from the resolver. The input source object is converted to a string using `toString` and is not altered.
    Parameters:
      `source` - the source to replace in, null returns null.
    Returns:
      The result of the replace operation.
    Throws:
      `IllegalArgumentException` - if a variable is not found and enableUndefinedVariableException is true.

  - ### replace

    public String replace(String source)
    Replaces all the occurrences of variables with their matching values from the resolver using the given source string as a template.
    Parameters:
      `source` - the string to replace in, null returns null.
    Returns:
      The result of the replace operation.
    Throws:
      `IllegalArgumentException` - if variable is not found when its allowed to throw exception.

  - ### replace

    public String replace(String source, int offset, int length)
    Replaces all the occurrences of variables with their matching values from the resolver using the given source string as a template.

    Only the specified portion of the string will be processed. The rest of the string is not processed, and is not returned.

    Parameters:
      `source` - the string to replace in, null returns null.
      `offset` - the start offset within the source, must be valid.
      `length` - the length within the source to be processed, must be valid.
    Returns:
      The result of the replace operation.
    Throws:
      `IllegalArgumentException` - if variable is not found when its allowed to throw exception.
      `StringIndexOutOfBoundsException` - if `offset` is not in the range `0 <= offset <= source.length()`.
      `StringIndexOutOfBoundsException` - if `length < 0`.
      `StringIndexOutOfBoundsException` - if `offset + length > source.length()`.

  - ### replace

    public String replace(StringBuffer source)
    Replaces all the occurrences of variables with their matching values from the resolver using the given source buffer as a template. The buffer is not altered by this method.
    Parameters:
      `source` - the buffer to use as a template, not changed, null returns null.
    Returns:
      The result of the replace operation.
    Throws:
      `IllegalArgumentException` - if variable is not found when its allowed to throw exception.

  - ### replace

    public String replace(StringBuffer source, int offset, int length)
    Replaces all the occurrences of variables with their matching values from the resolver using the given source buffer as a template. The buffer is not altered by this method.

    Only the specified portion of the buffer will be processed. The rest of the buffer is not processed, and is not returned.

    Parameters:
      `source` - the buffer to use as a template, not changed, null returns null.
      `offset` - the start offset within the source, must be valid.
      `length` - the length within the source to be processed, must be valid.
    Returns:
      The result of the replace operation.
    Throws:
      `IllegalArgumentException` - if variable is not found when its allowed to throw exception.

  - ### replace

    public String replace(TextStringBuilder source)
    Replaces all the occurrences of variables with their matching values from the resolver using the given source builder as a template. The builder is not altered by this method.
    Parameters:
      `source` - the builder to use as a template, not changed, null returns null.
    Returns:
      The result of the replace operation.
    Throws:
      `IllegalArgumentException` - if variable is not found when its allowed to throw exception.

  - ### replace

    public String replace(TextStringBuilder source, int offset, int length)
    Replaces all the occurrences of variables with their matching values from the resolver using the given source builder as a template. The builder is not altered by this method.

    Only the specified portion of the builder will be processed. The rest of the builder is not processed, and is not returned.

    Parameters:
      `source` - the builder to use as a template, not changed, null returns null.
      `offset` - the start offset within the source, must be valid.
      `length` - the length within the source to be processed, must be valid.
    Returns:
      The result of the replace operation.
    Throws:
      `IllegalArgumentException` - if variable is not found when its allowed to throw exception.

  - ### replaceIn

    public boolean replaceIn(StringBuffer source)
    Replaces all the occurrences of variables within the given source buffer with their matching values from the resolver. The buffer is updated with the result.
    Parameters:
      `source` - the buffer to replace in, updated, null returns zero.
    Returns:
      true if altered

  - ### replaceIn

    public boolean replaceIn(StringBuffer source, int offset, int length)
    Replaces all the occurrences of variables within the given source buffer with their matching values from the resolver. The buffer is updated with the result.

    Only the specified portion of the buffer will be processed. The rest of the buffer is not processed, but it is not deleted.

    Parameters:
      `source` - the buffer to replace in, updated, null returns zero.
      `offset` - the start offset within the source, must be valid.
      `length` - the length within the source to be processed, must be valid.
    Returns:
      true if altered.
    Throws:
      `IllegalArgumentException` - if variable is not found when its allowed to throw exception.

  - ### replaceIn

    public boolean replaceIn(StringBuilder source)
    Replaces all the occurrences of variables within the given source buffer with their matching values from the resolver. The buffer is updated with the result.
    Parameters:
      `source` - the buffer to replace in, updated, null returns zero.
    Returns:
      true if altered.

  - ### replaceIn

    public boolean replaceIn(StringBuilder source, int offset, int length)
    Replaces all the occurrences of variables within the given source builder with their matching values from the resolver. The builder is updated with the result.

    Only the specified portion of the buffer will be processed. The rest of the buffer is not processed, but it is not deleted.

    Parameters:
      `source` - the buffer to replace in, updated, null returns zero.
      `offset` - the start offset within the source, must be valid.
      `length` - the length within the source to be processed, must be valid.
    Returns:
      true if altered.
    Throws:
      `IllegalArgumentException` - if variable is not found when its allowed to throw exception.

  - ### replaceIn

    public boolean replaceIn(TextStringBuilder source)
    Replaces all the occurrences of variables within the given source builder with their matching values from the resolver.
    Parameters:
      `source` - the builder to replace in, updated, null returns zero.
    Returns:
      true if altered.
    Throws:
      `IllegalArgumentException` - if variable is not found when its allowed to throw exception.

  - ### replaceIn

    public boolean replaceIn(TextStringBuilder source, int offset, int length)
    Replaces all the occurrences of variables within the given source builder with their matching values from the resolver.

    Only the specified portion of the builder will be processed. The rest of the builder is not processed, but it is not deleted.

    Parameters:
      `source` - the builder to replace in, null returns zero.
      `offset` - the start offset within the source, must be valid.
      `length` - the length within the source to be processed, must be valid.
    Returns:
      true if altered.
    Throws:
      `IllegalArgumentException` - if variable is not found when its allowed to throw exception.

  - ### resolveVariable

    protected String resolveVariable(String variableName, TextStringBuilder buf, int startPos, int endPos)
    Internal method that resolves the value of a variable.

    Most users of this class do not need to call this method. This method is called automatically by the substitution process.

    Writers of subclasses can override this method if they need to alter how each substitution occurs. The method is passed the variable's name and must return the corresponding value. This implementation uses the `getStringLookup()` with the variable's name as the key.

    Parameters:
      `variableName` - the name of the variable, not null.
      `buf` - the buffer where the substitution is occurring, not null.
      `startPos` - the start position of the variable including the prefix, valid.
      `endPos` - the end position of the variable including the suffix, valid.
    Returns:
      The variable's value or null if the variable is unknown.

  - ### setDisableSubstitutionInValues

    public StringSubstitutor setDisableSubstitutionInValues(boolean disableSubstitutionInValues)
    Sets a flag whether substitution is done in variable values (recursive).
    Parameters:
      `disableSubstitutionInValues` - true if substitution in variable value are disabled.
    Returns:
      `this` instance.

  - ### setEnableSubstitutionInVariables

    public StringSubstitutor setEnableSubstitutionInVariables(boolean enableSubstitutionInVariables)
    Sets a flag whether substitution is done in variable names. If set to true, the names of variables can contain other variables which are processed first before the original variable is evaluated, e.g. `${jre-${java.version}}`. The default value is false.
    Parameters:
      `enableSubstitutionInVariables` - the new value of the flag.
    Returns:
      `this` instance.

  - ### setEnableUndefinedVariableException

    public StringSubstitutor setEnableUndefinedVariableException(boolean failOnUndefinedVariable)
    Sets a flag whether exception should be thrown if any variable is undefined.
    Parameters:
      `failOnUndefinedVariable` - true if exception should be thrown on undefined variable.
    Returns:
      `this` instance.

  - ### setEscapeChar

    public StringSubstitutor setEscapeChar(char escapeChar)
    Sets the escape character. If this character is placed before a variable reference in the source text, this variable will be ignored.
    Parameters:
      `escapeChar` - the escape character (0 for disabling escaping).
    Returns:
      `this` instance.

  - ### setPreserveEscapes

    public StringSubstitutor setPreserveEscapes(boolean preserveEscapes)
    Sets a flag controlling whether escapes are preserved during substitution. If set to true, the escape character is retained during substitution (e.g. `$${this-is-escaped}` remains `$${this-is-escaped}`). If set to false, the escape character is removed during substitution (e.g. `$${this-is-escaped}` becomes `${this-is-escaped}`). The default value is false
    Parameters:
      `preserveEscapes` - true if escapes are to be preserved.
    Returns:
      `this` instance.

  - ### setValueDelimiter

    public StringSubstitutor setValueDelimiter(char valueDelimiter)
    Sets the variable default value delimiter to use.

    The variable default value delimiter is the character or characters that delimit the variable name and the variable default value. This method allows a single character variable default value delimiter to be easily set.

    Parameters:
      `valueDelimiter` - the variable default value delimiter character to use.
    Returns:
      `this` instance.

  - ### setValueDelimiter

    public StringSubstitutor setValueDelimiter(String valueDelimiter)
    Sets the variable default value delimiter to use.

    The variable default value delimiter is the character or characters that delimit the variable name and the variable default value. This method allows a string variable default value delimiter to be easily set.

    If the `valueDelimiter` is null or empty string, then the variable default value resolution becomes disabled.

    Parameters:
      `valueDelimiter` - the variable default value delimiter string to use, may be null or empty.
    Returns:
      `this` instance.

  - ### setValueDelimiterMatcher

    public StringSubstitutor setValueDelimiterMatcher(StringMatcher valueDelimiterMatcher)
    Sets the variable default value delimiter matcher to use.

    The variable default value delimiter is the character or characters that delimit the variable name and the variable default value. This delimiter is expressed in terms of a matcher allowing advanced variable default value delimiter matches.

    If the `valueDelimiterMatcher` is null, then the variable default value resolution becomes disabled.

    Parameters:
      `valueDelimiterMatcher` - variable default value delimiter matcher to use, may be null.
    Returns:
      `this` instance.

  - ### setVariablePrefix

    public StringSubstitutor setVariablePrefix(char prefix)
    Sets the variable prefix to use.

    The variable prefix is the character or characters that identify the start of a variable. This method allows a single character prefix to be easily set.

    Parameters:
      `prefix` - the prefix character to use.
    Returns:
      `this` instance.

  - ### setVariablePrefix

    public StringSubstitutor setVariablePrefix(String prefix)
    Sets the variable prefix to use.

    The variable prefix is the character or characters that identify the start of a variable. This method allows a string prefix to be easily set.

    Parameters:
      `prefix` - the prefix for variables, not null.
    Returns:
      `this` instance.
    Throws:
      `IllegalArgumentException` - if the prefix is null.

  - ### setVariablePrefixMatcher

    public StringSubstitutor setVariablePrefixMatcher(StringMatcher prefixMatcher)
    Sets the variable prefix matcher currently in use.

    The variable prefix is the character or characters that identify the start of a variable. This prefix is expressed in terms of a matcher allowing advanced prefix matches.

    Parameters:
      `prefixMatcher` - the prefix matcher to use, null ignored.
    Returns:
      `this` instance.
    Throws:
      `IllegalArgumentException` - if the prefix matcher is null.

  - ### setVariableResolver

    public StringSubstitutor setVariableResolver(StringLookup variableResolver)
    Sets the VariableResolver that is used to lookup variables.
    Parameters:
      `variableResolver` - the VariableResolver.
    Returns:
      `this` instance.

  - ### setVariableSuffix

    public StringSubstitutor setVariableSuffix(char suffix)
    Sets the variable suffix to use.

    The variable suffix is the character or characters that identify the end of a variable. This method allows a single character suffix to be easily set.

    Parameters:
      `suffix` - the suffix character to use.
    Returns:
      `this` instance.

  - ### setVariableSuffix

    public StringSubstitutor setVariableSuffix(String suffix)
    Sets the variable suffix to use.

    The variable suffix is the character or characters that identify the end of a variable. This method allows a string suffix to be easily set.

    Parameters:
      `suffix` - the suffix for variables, not null.
    Returns:
      `this` instance.
    Throws:
      `IllegalArgumentException` - if the suffix is null.

  - ### setVariableSuffixMatcher

    public StringSubstitutor setVariableSuffixMatcher(StringMatcher suffixMatcher)
    Sets the variable suffix matcher currently in use.

    The variable suffix is the character or characters that identify the end of a variable. This suffix is expressed in terms of a matcher allowing advanced suffix matches.

    Parameters:
      `suffixMatcher` - the suffix matcher to use, null ignored.
    Returns:
      `this` instance.
    Throws:
      `IllegalArgumentException` - if the suffix matcher is null.

  - ### substitute

    protected boolean substitute(TextStringBuilder builder, int offset, int length)
    Internal method that substitutes the variables.

    Most users of this class do not need to call this method. This method will be called automatically by another (public) method.

    Writers of subclasses can override this method if they need access to the substitution process at the start or end.

    Parameters:
      `builder` - the string builder to substitute into, not null.
      `offset` - the start offset within the builder, must be valid.
      `length` - the length within the builder to be processed, must be valid.
    Returns:
      true if altered.

  - ### toString

    public String toString()
    Returns a string representation of the object.
    Overrides:
      `toString` in class `Object`
    Returns:
      a string representation of the object.
    Since:
      1.11.0