StringLookupFactory (Apache Commons Text 1.13.0 API)
Description: declaration: package: org.apache.commons.text.lookup, class: StringLookupFactory

Package org.apache.commons.text.lookup

# Class StringLookupFactory

java.lang.Object
org.apache.commons.text.lookup.StringLookupFactory

public final class StringLookupFactory extends Object
Create instances of string lookups or access singleton string lookups implemented in this package.

The "classic" look up is `mapStringLookup(Map)`.

The methods for variable interpolation (A.K.A. variable substitution) are:

- `interpolatorStringLookup()`.
- `interpolatorStringLookup(Map)`.
- `interpolatorStringLookup(StringLookup)`.
- `interpolatorStringLookup(Map, StringLookup, boolean)`.

Unless explicitly requested otherwise, a set of default lookups are included for convenience with these variable interpolation methods. These defaults are listed in the table below. However, the exact lookups included can be configured through the use of the "org.apache.commons.text.lookup.StringLookupFactory.defaultStringLookups" system property. If present, this system property will be parsed as a comma-separated list of lookup names, with the names being those defined by the `DefaultStringLookup` enum. For example, setting this system property to `"BASE64_ENCODER,ENVIRONMENT"` will only include the `BASE64_ENCODER` and `ENVIRONMENT` lookups. Setting the property to the empty string will cause no defaults to be configured. Note that not all lookups defined here and in `DefaultStringLookup` are included by default. Specifically, lookups that can execute code (e.g., `SCRIPT`) and those that can result in contact with remote servers (e.g., `URL` and `DNS`) are not included by default. The current set of default lookups can be accessed directly with `addDefaultStringLookups(Map)`.

Default String Lookups
Key | Interface | Factory Method | Since
--- | --- | --- | ---
"base64Decoder" | `StringLookup` | `base64DecoderStringLookup()` | 1.6
"base64Encoder" | `StringLookup` | `base64EncoderStringLookup()` | 1.6
"const" | `StringLookup` | `constantStringLookup()` | 1.5
"date" | `StringLookup` | `dateStringLookup()` | 1.5
"env" | `StringLookup` | `environmentVariableStringLookup()` | 1.3
"file" | `StringLookup` | `fileStringLookup(Path...)` | 1.5
"java" | `StringLookup` | `javaPlatformStringLookup()` | 1.5
"localhost" | `StringLookup` | `localHostStringLookup()` | 1.3
"loobackAddress" | `StringLookup` | `loopbackAddressStringLookup()` | 1.13.0
"properties" | `StringLookup` | `propertiesStringLookup(Path...)` | 1.5
"resourceBundle" | `StringLookup` | `resourceBundleStringLookup()` | 1.6
"sys" | `StringLookup` | `systemPropertyStringLookup()` | 1.3
"urlDecoder" | `StringLookup` | `urlDecoderStringLookup()` | 1.5
"urlEncoder" | `StringLookup` | `urlEncoderStringLookup()` | 1.5
"xml" | `StringLookup` | `xmlStringLookup(Map, Path...)` | 1.5
"xmlDecoder" | `StringLookup` | `xmlDecoderStringLookup()` | 1.11.0
"xmlEncoder" | `StringLookup` | `xmlEncoderStringLookup()` | 1.11.0

Additional String Lookups (not included by default)
Key | Interface | Factory Method | Since
--- | --- | --- | ---
"dns" | `StringLookup` | `dnsStringLookup()` | 1.8
"url" | `StringLookup` | `urlStringLookup()` | 1.5
"script" | `StringLookup` | `scriptStringLookup()` | 1.5

This class also provides functional lookups used as building blocks for other lookups.

Functional String Lookups
Interface | Factory Method | Since
--- | --- | ---
`BiStringLookup` | `biFunctionStringLookup(BiFunction)` | 1.9
`StringLookup` | `functionStringLookup(Function)` | 1.9

Since:
  1.3

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `StringLookupFactory.Builder`
  Builds instance of `StringLookupFactory`.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `DEFAULT_STRING_LOOKUPS_PROPERTY`
  Name of the system property used to determine the string lookups added by the `addDefaultStringLookups(Map)` method.
  `static final StringLookupFactory`
  `INSTANCE`
  Defines the singleton for this class.
  `static final String`
  `KEY_BASE64_DECODER`
  Default lookup key for interpolation "base64Decoder".
  `static final String`
  `KEY_BASE64_ENCODER`
  Default lookup key for interpolation "base64Encoder".
  `static final String`
  `KEY_CONST`
  Default lookup key for interpolation "const".
  `static final String`
  `KEY_DATE`
  Default lookup key for interpolation "date".
  `static final String`
  `KEY_DNS`
  Default lookup key for interpolation "dns".
  `static final String`
  `KEY_ENV`
  Default lookup key for interpolation "env".
  `static final String`
  `KEY_FILE`
  Default lookup key for interpolation "file".
  `static final String`
  `KEY_JAVA`
  Default lookup key for interpolation "java".
  `static final String`
  `KEY_LOCALHOST`
  Default lookup key for interpolation "localhost".
  `static final String`
  `KEY_LOOPBACK_ADDRESS`
  Default lookup key for interpolation "loobackAddress".
  `static final String`
  `KEY_PROPERTIES`
  Default lookup key for interpolation "properties".
  `static final String`
  `KEY_RESOURCE_BUNDLE`
  Default lookup key for interpolation "resourceBundle".
  `static final String`
  `KEY_SCRIPT`
  Default lookup key for interpolation "script".
  `static final String`
  `KEY_SYS`
  Default lookup key for interpolation "sys".
  `static final String`
  `KEY_URL`
  Default lookup key for interpolation "url".
  `static final String`
  `KEY_URL_DECODER`
  Default lookup key for interpolation "urlDecoder".
  `static final String`
  `KEY_URL_ENCODER`
  Default lookup key for interpolation "urlEncoder".
  `static final String`
  `KEY_XML`
  Default lookup key for interpolation "xml".
  `static final String`
  `KEY_XML_DECODER`
  Default lookup key for interpolation "xmlDecoder".
  `static final String`
  `KEY_XML_ENCODER`
  Default lookup key for interpolation "xmlEncoder".

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addDefaultStringLookups(Map<String,StringLookup> stringLookupMap)`
  Adds the default string lookups for this class to `stringLookupMap`.
  `StringLookup`
  `base64DecoderStringLookup()`
  Returns the Base64DecoderStringLookup singleton instance to decode Base64 strings.
  `StringLookup`
  `base64EncoderStringLookup()`
  Returns the Base64EncoderStringLookup singleton instance to encode strings to Base64.
  `StringLookup`
  `base64StringLookup()`
  Deprecated.
  Use `base64DecoderStringLookup()`.
  `<R, U> BiStringLookup<U>`
  `biFunctionStringLookup(BiFunction<String,U,R> biFunction)`
  Returns a new function-based lookup where the request for a lookup is answered by applying the function with a lookup key.
  `static StringLookupFactory.Builder`
  `builder()`
  Constructs a new `StringLookupFactory.Builder`.
  `static void`
  `clear()`
  Clears any static resources.
  `StringLookup`
  `constantStringLookup()`
  Returns the ConstantStringLookup singleton instance to look up the value of a fully-qualified static final value.
  `StringLookup`
  `dateStringLookup()`
  Returns the DateStringLookup singleton instance to format the current date with the format given in the key in a format compatible with `SimpleDateFormat`.
  `StringLookup`
  `dnsStringLookup()`
  Returns the DnsStringLookup singleton instance where the lookup key is one of: name: for the local host name, for example `EXAMPLE` but also `EXAMPLE.apache.org`. canonical-name: for the local canonical host name, for example `EXAMPLE.apache.org`. address: for the local host address, for example `192.168.56.1`.
  `StringLookup`
  `environmentVariableStringLookup()`
  Returns the EnvironmentVariableStringLookup singleton instance where the lookup key is an environment variable name.
  `StringLookup`
  `fileStringLookup()`
  Returns a file StringLookup instance.
  `StringLookup`
  `fileStringLookup(Path... fences)`
  Returns a fenced file StringLookup instance.
  `<R> StringLookup`
  `functionStringLookup(Function<String,R> function)`
  Returns a new function-based lookup where the request for a lookup is answered by applying the function with a lookup key.
  `StringLookup`
  `interpolatorStringLookup()`
  Returns a `InterpolatorStringLookup` containing the configured `default lookups`.
  `StringLookup`
  `interpolatorStringLookup(Map<String,StringLookup> stringLookupMap, StringLookup defaultStringLookup, boolean addDefaultLookups)`
  Returns a new InterpolatorStringLookup.
  `<V> StringLookup`
  `interpolatorStringLookup(Map<String,V> map)`
  Returns a new InterpolatorStringLookup using the given key-value pairs and the configured `default lookups` to resolve variables.
  `StringLookup`
  `interpolatorStringLookup(StringLookup defaultStringLookup)`
  Returns a new InterpolatorStringLookup using the given lookup and the configured `default lookups` to resolve variables.
  `StringLookup`
  `javaPlatformStringLookup()`
  Returns the JavaPlatformStringLookup singleton instance.
  `StringLookup`
  `localHostStringLookup()`
  Returns the InetAddressStringLookup instance where the lookup key for `InetAddress.getLocalHost()` is one of: name: for the local host name, for example `EXAMPLE`. canonical-name: for the local canonical host name, for example `EXAMPLE.apache.org`. address: for the local host address, for example `192.168.56.1`.
  `StringLookup`
  `loopbackAddressStringLookup()`
  Returns the InetAddressStringLookup instance where the lookup key for `InetAddress.getLoopbackAddress()` is one of: name: for the local host name, for example `EXAMPLE`. canonical-name: for the local canonical host name, for example `EXAMPLE.apache.org`. address: for the local host address, for example `192.168.56.1`.
  `<V> StringLookup`
  `mapStringLookup(Map<String,V> map)`
  Returns a new map-based lookup where the request for a lookup is answered with the value for that key.
  `StringLookup`
  `nullStringLookup()`
  Returns the NullStringLookup singleton instance which always returns null.
  `StringLookup`
  `propertiesStringLookup()`
  Returns a Properties StringLookup instance.
  `StringLookup`
  `propertiesStringLookup(Path... fences)`
  Returns a fenced Properties StringLookup instance.
  `StringLookup`
  `resourceBundleStringLookup()`
  Returns the ResourceBundleStringLookup singleton instance.
  `StringLookup`
  `resourceBundleStringLookup(String bundleName)`
  Returns a ResourceBundleStringLookup instance for the given bundle name.
  `StringLookup`
  `scriptStringLookup()`
  Returns the ScriptStringLookup singleton instance.
  `StringLookup`
  `systemPropertyStringLookup()`
  Returns the SystemPropertyStringLookup singleton instance where the lookup key is a system property name.
  `StringLookup`
  `urlDecoderStringLookup()`
  Returns the UrlDecoderStringLookup singleton instance.
  `StringLookup`
  `urlEncoderStringLookup()`
  Returns the UrlDecoderStringLookup singleton instance.
  `StringLookup`
  `urlStringLookup()`
  Returns the UrlStringLookup singleton instance.
  `StringLookup`
  `xmlDecoderStringLookup()`
  Returns the XmlDecoderStringLookup singleton instance.
  `StringLookup`
  `xmlEncoderStringLookup()`
  Returns the XmlEncoderStringLookup singleton instance.
  `StringLookup`
  `xmlStringLookup()`
  Returns an XML StringLookup instance.
  `StringLookup`
  `xmlStringLookup(Map<String,Boolean> xPathFactoryFeatures)`
  Returns an XML StringLookup instance.
  `StringLookup`
  `xmlStringLookup(Map<String,Boolean> xPathFactoryFeatures, Path... fences)`
  Returns a fenced XML StringLookup instance.

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### DEFAULT_STRING_LOOKUPS_PROPERTY

    public static final String DEFAULT_STRING_LOOKUPS_PROPERTY
    Name of the system property used to determine the string lookups added by the `addDefaultStringLookups(Map)` method. Use of this property is only required in cases where the set of default lookups must be modified. (See the class documentation for details.)
    Since:
      1.10.0
    See Also:
      - Constant Field Values

  - ### INSTANCE

    public static final StringLookupFactory INSTANCE
    Defines the singleton for this class.

  - ### KEY_BASE64_DECODER

    public static final String KEY_BASE64_DECODER
    Default lookup key for interpolation "base64Decoder".
    Since:
      1.6
    See Also:
      - Constant Field Values

  - ### KEY_BASE64_ENCODER

    public static final String KEY_BASE64_ENCODER
    Default lookup key for interpolation "base64Encoder".
    Since:
      1.6
    See Also:
      - Constant Field Values

  - ### KEY_CONST

    public static final String KEY_CONST
    Default lookup key for interpolation "const".
    Since:
      1.6
    See Also:
      - Constant Field Values

  - ### KEY_DATE

    public static final String KEY_DATE
    Default lookup key for interpolation "date".
    Since:
      1.6
    See Also:
      - Constant Field Values

  - ### KEY_DNS

    public static final String KEY_DNS
    Default lookup key for interpolation "dns".
    Since:
      1.8
    See Also:
      - Constant Field Values

  - ### KEY_ENV

    public static final String KEY_ENV
    Default lookup key for interpolation "env".
    Since:
      1.6
    See Also:
      - Constant Field Values

  - ### KEY_FILE

    public static final String KEY_FILE
    Default lookup key for interpolation "file".
    Since:
      1.6
    See Also:
      - Constant Field Values

  - ### KEY_JAVA

    public static final String KEY_JAVA
    Default lookup key for interpolation "java".
    Since:
      1.6
    See Also:
      - Constant Field Values

  - ### KEY_LOCALHOST

    public static final String KEY_LOCALHOST
    Default lookup key for interpolation "localhost".
    Since:
      1.6
    See Also:
      - Constant Field Values

  - ### KEY_LOOPBACK_ADDRESS

    public static final String KEY_LOOPBACK_ADDRESS
    Default lookup key for interpolation "loobackAddress".
    Since:
      1.13.0
    See Also:
      - Constant Field Values

  - ### KEY_PROPERTIES

    public static final String KEY_PROPERTIES
    Default lookup key for interpolation "properties".
    Since:
      1.6
    See Also:
      - Constant Field Values

  - ### KEY_RESOURCE_BUNDLE

    public static final String KEY_RESOURCE_BUNDLE
    Default lookup key for interpolation "resourceBundle".
    Since:
      1.6
    See Also:
      - Constant Field Values

  - ### KEY_SCRIPT

    public static final String KEY_SCRIPT
    Default lookup key for interpolation "script".
    Since:
      1.6
    See Also:
      - Constant Field Values

  - ### KEY_SYS

    public static final String KEY_SYS
    Default lookup key for interpolation "sys".
    Since:
      1.6
    See Also:
      - Constant Field Values

  - ### KEY_URL

    public static final String KEY_URL
    Default lookup key for interpolation "url".
    Since:
      1.6
    See Also:
      - Constant Field Values

  - ### KEY_URL_DECODER

    public static final String KEY_URL_DECODER
    Default lookup key for interpolation "urlDecoder".
    Since:
      1.6
    See Also:
      - Constant Field Values

  - ### KEY_URL_ENCODER

    public static final String KEY_URL_ENCODER
    Default lookup key for interpolation "urlEncoder".
    Since:
      1.6
    See Also:
      - Constant Field Values

  - ### KEY_XML

    public static final String KEY_XML
    Default lookup key for interpolation "xml".
    Since:
      1.6
    See Also:
      - Constant Field Values

  - ### KEY_XML_DECODER

    public static final String KEY_XML_DECODER
    Default lookup key for interpolation "xmlDecoder".
    Since:
      1.11.0
    See Also:
      - Constant Field Values

  - ### KEY_XML_ENCODER

    public static final String KEY_XML_ENCODER
    Default lookup key for interpolation "xmlEncoder".
    Since:
      1.11.0
    See Also:
      - Constant Field Values

- ## Method Details

  - ### builder

    public static StringLookupFactory.Builder builder()
    Constructs a new `StringLookupFactory.Builder`.
    Returns:
      a new `StringLookupFactory.Builder`
    Since:
      1.12.0

  - ### clear

    public static void clear()
    Clears any static resources.
    Since:
      1.5

  - ### addDefaultStringLookups

    public void addDefaultStringLookups(Map<String,StringLookup> stringLookupMap)
    Adds the default string lookups for this class to `stringLookupMap`. The default string lookups are a set of built-in lookups added for convenience during string interpolation. The defaults may be configured using the "org.apache.commons.text.lookup.StringLookupFactory.defaultStringLookups" system property. See the class documentation for details and a list of lookups.
    Parameters:
      `stringLookupMap` - the map of string lookups to edit.
    Since:
      1.5

  - ### base64DecoderStringLookup

    public StringLookup base64DecoderStringLookup()
    Returns the Base64DecoderStringLookup singleton instance to decode Base64 strings.

    Using a `StringLookup` from the `StringLookupFactory`:

         StringLookupFactory.INSTANCE.base64DecoderStringLookup().lookup("SGVsbG9Xb3JsZCE=");

    Using a `StringSubstitutor`:

         StringSubstitutor.createInterpolator().replace("... ${base64Decoder:SGVsbG9Xb3JsZCE=} ..."));

    The above examples convert `"SGVsbG9Xb3JsZCE="` to `"HelloWorld!"`.

    Returns:
      The Base64DecoderStringLookup singleton instance.
    Since:
      1.5

  - ### base64EncoderStringLookup

    public StringLookup base64EncoderStringLookup()
    Returns the Base64EncoderStringLookup singleton instance to encode strings to Base64.

    Using a `StringLookup` from the `StringLookupFactory`:

         StringLookupFactory.INSTANCE.base64EncoderStringLookup().lookup("HelloWorld!");

    Using a `StringSubstitutor`:

         StringSubstitutor.createInterpolator().replace("... ${base64Encoder:HelloWorld!} ..."));

    The above examples convert to `"SGVsbG9Xb3JsZCE="`.

    Returns:
      The Base64EncoderStringLookup singleton instance.
    Since:
      1.6

  - ### base64StringLookup

    @Deprecated public StringLookup base64StringLookup()
    Deprecated.
    Use `base64DecoderStringLookup()`.
    Returns the Base64DecoderStringLookup singleton instance to decode Base64 strings.

    Using a `StringLookup` from the `StringLookupFactory`:

         StringLookupFactory.INSTANCE.base64DecoderStringLookup().lookup("SGVsbG9Xb3JsZCE=");

    Using a `StringSubstitutor`:

         StringSubstitutor.createInterpolator().replace("... ${base64Decoder:SGVsbG9Xb3JsZCE=} ..."));

    The above examples convert `"SGVsbG9Xb3JsZCE="` to `"HelloWorld!"`.

    Returns:
      The Base64DecoderStringLookup singleton instance.
    Since:
      1.5

  - ### biFunctionStringLookup

    public <R, U> BiStringLookup<U> biFunctionStringLookup(BiFunction<String,U,R> biFunction)
    Returns a new function-based lookup where the request for a lookup is answered by applying the function with a lookup key.
    Type Parameters:
      `R` - the function return type.
      `U` - the function's second parameter type.
    Parameters:
      `biFunction` - the function.
    Returns:
      a new MapStringLookup.
    Since:
      1.9

  - ### constantStringLookup

    public StringLookup constantStringLookup()
    Returns the ConstantStringLookup singleton instance to look up the value of a fully-qualified static final value.

    Sometimes it is necessary in a configuration file to refer to a constant defined in a class. This can be done with this lookup implementation. Variable names must be in the format `apackage.AClass.AFIELD`. The `lookup(String)` method will split the passed in string at the last dot, separating the fully qualified class name and the name of the constant (i.e. static final) member field. Then the class is loaded and the field's value is obtained using reflection.

    Once retrieved values are cached for fast access. This class is thread-safe. It can be used as a standard (i.e. global) lookup object and serve multiple clients concurrently.

    Using a `StringLookup` from the `StringLookupFactory`:

         StringLookupFactory.INSTANCE.constantStringLookup().lookup("java.awt.event.KeyEvent.VK_ESCAPE");

    Using a `StringSubstitutor`:

         StringSubstitutor.createInterpolator().replace("... ${const:java.awt.event.KeyEvent.VK_ESCAPE} ..."));

    The above examples convert `java.awt.event.KeyEvent.VK_ESCAPE` to `"27"`.

    Returns:
      The ConstantStringLookup singleton instance.
    Since:
      1.5

  - ### dateStringLookup

    public StringLookup dateStringLookup()
    Returns the DateStringLookup singleton instance to format the current date with the format given in the key in a format compatible with `SimpleDateFormat`.

    Using a `StringLookup` from the `StringLookupFactory`:

         StringLookupFactory.INSTANCE.dateStringLookup().lookup("yyyy-MM-dd");

    Using a `StringSubstitutor`:

         StringSubstitutor.createInterpolator().replace("... ${date:yyyy-MM-dd} ..."));

    The above examples convert `"yyyy-MM-dd"` to todays's date, for example, `"2019-08-04"`.

    Returns:
      The DateStringLookup singleton instance.

  - ### dnsStringLookup

    public StringLookup dnsStringLookup()
    Returns the DnsStringLookup singleton instance where the lookup key is one of:
    - name: for the local host name, for example `EXAMPLE` but also `EXAMPLE.apache.org`.
    - canonical-name: for the local canonical host name, for example `EXAMPLE.apache.org`.
    - address: for the local host address, for example `192.168.56.1`.

    Using a `StringLookup` from the `StringLookupFactory`:

         StringLookupFactory.INSTANCE.dnsStringLookup().lookup("address|apache.org");

    When used through a `StringSubstitutor`, this lookup must either be added programmatically (as below) or enabled as a default lookup using the "org.apache.commons.text.lookup.StringLookupFactory.defaultStringLookups" system property (see class documentation).

         Map<String, StringLookup> lookupMap = new HashMap<>();
         lookupMap.put("dns", StringLookupFactory.INSTANCE.dnsStringLookup());

         StringLookup variableResolver = StringLookupFactory.INSTANCE.interpolatorStringLookup(lookupMap, null, false);

         new StringSubstitutor(variableResolver).replace("... ${dns:address|apache.org} ...");

    The above examples convert `"address|apache.org"` to the IP address of `apache.org`.

    Returns:
      the DnsStringLookup singleton instance.
    Since:
      1.8

  - ### environmentVariableStringLookup

    public StringLookup environmentVariableStringLookup()
    Returns the EnvironmentVariableStringLookup singleton instance where the lookup key is an environment variable name.

    Using a `StringLookup` from the `StringLookupFactory`:

         StringLookupFactory.INSTANCE.environmentVariableStringLookup().lookup("USER");

    Using a `StringSubstitutor`:

         StringSubstitutor.createInterpolator().replace("... ${env:USER} ..."));

    The above examples convert (on Linux) `"USER"` to the current user name. On Windows 10, you would use `"USERNAME"` to the same effect.

    Returns:
      The EnvironmentVariableStringLookup singleton instance.

  - ### fileStringLookup

    public StringLookup fileStringLookup()
    Returns a file StringLookup instance.

    If this factory was built using `StringLookupFactory.Builder.setFences(Path...)`, then the string lookup is fenced and will throw an `IllegalArgumentException` if a lookup causes causes a path to resolve outside of these fences. Otherwise, the result is unfenced to preserved behavior from previous versions.

    Using a fenced StringLookup

    To use a fenced `StringLookup`, use `builder()`:

         // Make the fence the current directory
         StringLookupFactory factory = StringLookupFactory.builder().setFences(Paths.get("")).get();
         factory.fileStringLookup().lookup("UTF-8:com/domain/document.txt");

         // throws IllegalArgumentException
         factory.fileStringLookup().lookup("UTF-8:/rootdir/foo/document.txt");

         // throws IllegalArgumentException
         factory.fileStringLookup().lookup("UTF-8:../document.txt");

    Using an unfenced StringLookup

    To use an unfenced `StringLookup`, use `INSTANCE`:

         StringLookupFactory.INSTANCE.fileStringLookup().lookup("UTF-8:com/domain/document.properties");

    Using a StringLookup with StringSubstitutor

    To build a fenced StringSubstitutor, use:

         // Make the fence the current directory
         final StringLookupFactory factory = StringLookupFactory.builder().setFences(Paths.get("")).get();
         final StringSubstitutor stringSubstitutor = new StringSubstitutor(factory.interpolatorStringLookup());
         stringSubstitutor.replace("... ${file:UTF-8:com/domain/document.txt} ..."));

         // throws IllegalArgumentException
         stringSubstitutor.replace("... ${file:UTF-8:/rootdir/foo/document.txt} ..."));

    Using an unfenced `StringSubstitutor`:

         StringSubstitutor.createInterpolator().replace("... ${file:UTF-8:com/domain/document.txt} ..."));

    The above examples convert `"UTF-8:com/domain/document.txt"` to the contents of the file.

    Returns:
      a file StringLookup instance.
    Since:
      1.5

  - ### fileStringLookup

    public StringLookup fileStringLookup(Path... fences)
    Returns a fenced file StringLookup instance.

    To use a `StringLookup` fenced by the current directory, use:

         StringLookupFactory.INSTANCE.fileStringLookup(Paths.get("")).lookup("UTF-8:com/domain/document.txt");

         // throws IllegalArgumentException
         StringLookupFactory.INSTANCE.fileStringLookup(Paths.get("")).lookup("UTF-8:/rootdir/foo/document.txt");

         // throws IllegalArgumentException
         StringLookupFactory.INSTANCE.fileStringLookup(Paths.get("")).lookup("UTF-8:../com/domain/document.txt");

    The above example converts `"UTF-8:com/domain/document.txt"` to the contents of the file.

    `StringSubstitutor` methods like `StringSubstitutor.replace(String)` will throw a `IllegalArgumentException` when a file doesn't resolves in a fence.

    Parameters:
      `fences` - The fences guarding Path resolution.
    Returns:
      a file StringLookup instance.
    Since:
      1.12.0

  - ### functionStringLookup

    public <R> StringLookup functionStringLookup(Function<String,R> function)
    Returns a new function-based lookup where the request for a lookup is answered by applying the function with a lookup key.
    Type Parameters:
      `R` - the function return type.
    Parameters:
      `function` - the function.
    Returns:
      a new MapStringLookup.
    Since:
      1.9

  - ### interpolatorStringLookup

    public StringLookup interpolatorStringLookup()
    Returns a `InterpolatorStringLookup` containing the configured `default lookups`. See the class documentation for details on how these defaults are configured.

    Using a `StringLookup` from the `StringLookupFactory`:

         StringLookupFactory.INSTANCE.interpolatorStringLookup().lookup("${sys:os.name}, ${env:USER}");

    Using a `StringSubstitutor`:

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

    The above examples convert `"${sys:os.name}, ${env:USER}"` to the OS name and Linux user name.

    Returns:
      the default `InterpolatorStringLookup`.

  - ### interpolatorStringLookup

    public StringLookup interpolatorStringLookup(Map<String,StringLookup> stringLookupMap, StringLookup defaultStringLookup, boolean addDefaultLookups)
    Returns a new InterpolatorStringLookup. If `addDefaultLookups` is `true`, the configured `default lookups` are included in addition to the ones provided in `stringLookupMap`. (See the class documentation for details on how default lookups are configured.)
    Parameters:
      `stringLookupMap` - the map of string lookups.
      `defaultStringLookup` - the default string lookup; this lookup is used when a variable cannot be resolved using the lookups in `stringLookupMap` or the configured default lookups (if enabled)
      `addDefaultLookups` - whether to use default lookups as described above.
    Returns:
      a new InterpolatorStringLookup.
    Since:
      1.4

  - ### interpolatorStringLookup

    public <V> StringLookup interpolatorStringLookup(Map<String,V> map)
    Returns a new InterpolatorStringLookup using the given key-value pairs and the configured `default lookups` to resolve variables. (See the class documentation for details on how default lookups are configured.)
    Type Parameters:
      `V` - the value type the default string lookup's map.
    Parameters:
      `map` - the default map for string lookups.
    Returns:
      a new InterpolatorStringLookup.

  - ### interpolatorStringLookup

    public StringLookup interpolatorStringLookup(StringLookup defaultStringLookup)
    Returns a new InterpolatorStringLookup using the given lookup and the configured `default lookups` to resolve variables. (See the class documentation for details on how default lookups are configured.)
    Parameters:
      `defaultStringLookup` - the default string lookup.
    Returns:
      a new InterpolatorStringLookup.

  - ### javaPlatformStringLookup

    public StringLookup javaPlatformStringLookup()
    Returns the JavaPlatformStringLookup singleton instance. Looks up keys related to Java: Java version, JRE version, VM version, and so on.

    The lookup keys with examples are:

    - version: "Java version 1.8.0_181"
    - runtime: "Java(TM) SE Runtime Environment (build 1.8.0_181-b13) from Oracle Corporation"
    - vm: "Java HotSpot(TM) 64-Bit Server VM (build 25.181-b13, mixed mode)"
    - os: "Windows 10 10.0, architecture: amd64-64"
    - hardware: "processors: 4, architecture: amd64-64, instruction sets: amd64"
    - locale: "default locale: en_US, platform encoding: iso-8859-1"

    Using a `StringLookup` from the `StringLookupFactory`:

         StringLookupFactory.INSTANCE.javaPlatformStringLookup().lookup("version");

    Using a `StringSubstitutor`:

         StringSubstitutor.createInterpolator().replace("... ${java:version} ..."));

    The above examples convert `"version"` to the current VM version, for example, `"Java version 1.8.0_181"`.

    Returns:
      The JavaPlatformStringLookup singleton instance.

  - ### localHostStringLookup

    public StringLookup localHostStringLookup()
    Returns the InetAddressStringLookup instance where the lookup key for `InetAddress.getLocalHost()` is one of:
    - name: for the local host name, for example `EXAMPLE`.
    - canonical-name: for the local canonical host name, for example `EXAMPLE.apache.org`.
    - address: for the local host address, for example `192.168.56.1`.

    Using a `StringLookup` from the `StringLookupFactory`:

         StringLookupFactory.INSTANCE.localHostStringLookup().lookup("canonical-name");

    Using a `StringSubstitutor`:

         StringSubstitutor.createInterpolator().replace("... ${localhost:canonical-name} ..."));

    The above examples convert `"canonical-name"` to the current host name, for example, `"EXAMPLE.apache.org"`.

    Returns:
      The InetAddressStringLookup singleton instance.

  - ### loopbackAddressStringLookup

    public StringLookup loopbackAddressStringLookup()
    Returns the InetAddressStringLookup instance where the lookup key for `InetAddress.getLoopbackAddress()` is one of:
    - name: for the local host name, for example `EXAMPLE`.
    - canonical-name: for the local canonical host name, for example `EXAMPLE.apache.org`.
    - address: for the local host address, for example `192.168.56.1`.

    Using a `StringLookup` from the `StringLookupFactory`:

         StringLookupFactory.INSTANCE.loopbackAddressStringLookup().lookup("canonical-name");

    Using a `StringSubstitutor`:

         StringSubstitutor.createInterpolator().replace("... ${loopbackAddress:canonical-name} ..."));

    The above examples convert `"canonical-name"` to the current host name, for example, `"EXAMPLE.apache.org"`.

    Returns:
      The InetAddressStringLookup singleton instance.

  - ### mapStringLookup

    public <V> StringLookup mapStringLookup(Map<String,V> map)
    Returns a new map-based lookup where the request for a lookup is answered with the value for that key.
    Type Parameters:
      `V` - the map value type.
    Parameters:
      `map` - the map.
    Returns:
      a new MapStringLookup.

  - ### nullStringLookup

    public StringLookup nullStringLookup()
    Returns the NullStringLookup singleton instance which always returns null.
    Returns:
      The NullStringLookup singleton instance.

  - ### propertiesStringLookup

    public StringLookup propertiesStringLookup()
    Returns a Properties StringLookup instance.

    If this factory was built using `StringLookupFactory.Builder.setFences(Path...)`, then the string lookup is fenced and will throw an `IllegalArgumentException` if a lookup causes causes a path to resolve outside of these fences. Otherwise, the result is unfenced to preserved behavior from previous versions.

    We looks up a value for the key in the format "DocumentPath::MyKey".

    Note the use of "::" instead of ":" to allow for "C:" drive letters in paths.

    For example: "com/domain/document.properties::MyKey".

    Using a fenced StringLookup

    To use a fenced `StringLookup`, use `builder()`:

         // Make the fence the current directory
         StringLookupFactory factory = StringLookupFactory.builder().setFences(Paths.get("")).get();
         factory.propertiesStringLookup().lookup("com/domain/document.properties::MyKey");

         // throws IllegalArgumentException
         factory.propertiesStringLookup().lookup("/com/domain/document.properties::MyKey");

         // throws IllegalArgumentException
         factory.propertiesStringLookup().lookup("../com/domain/document.properties::MyKey");

    Using an unfenced StringLookup

    To use an unfenced `StringLookup`, use `INSTANCE`:

         StringLookupFactory.INSTANCE.propertiesStringLookup().lookup("com/domain/document.properties::MyKey");

    Using a StringLookup with StringSubstitutor

    To build a fenced StringSubstitutor, use:

         // Make the fence the current directory
         final StringLookupFactory factory = StringLookupFactory.builder().setFences(Paths.get("")).get();
         final StringSubstitutor stringSubstitutor = new StringSubstitutor(factory.interpolatorStringLookup());
         stringSubstitutor.replace("... ${properties:com/domain/document.properties::MyKey} ..."));

         // throws IllegalArgumentException
         stringSubstitutor.replace("... ${properties:/rootdir/foo/document.properties::MyKey} ..."));

    Using an unfenced `StringSubstitutor`:

         StringSubstitutor.createInterpolator().replace("... ${properties:com/domain/document.properties::MyKey} ..."));

    The above examples convert `"com/domain/document.properties::MyKey"` to the key value in the properties file at the path "com/domain/document.properties".

    Returns:
      a Properties StringLookup instance.
    Since:
      1.5

  - ### propertiesStringLookup

    public StringLookup propertiesStringLookup(Path... fences)
    Returns a fenced Properties StringLookup instance.

    Looks up the value for the key in the format "DocumentPath::MyKey":.

    Note the use of "::" instead of ":" to allow for "C:" drive letters in paths.

    For example: "com/domain/document.properties::MyKey".

    To use a `StringLookup` fenced by the current directory, use:

         StringLookupFactory.INSTANCE.fileStringLookup(Paths.get("")).lookup("com/domain/document.properties::MyKey");

         // throws IllegalArgumentException
         StringLookupFactory.INSTANCE.fileStringLookup(Paths.get("")).lookup("com/domain/document.properties::MyKey");

         // throws IllegalArgumentException
         StringLookupFactory.INSTANCE.fileStringLookup(Paths.get("")).lookup("com/domain/document.properties::MyKey");

    The above example converts `"com/domain/document.properties::MyKey"` to the key value in the properties file at the path "com/domain/document.properties".

    `StringSubstitutor` methods like `StringSubstitutor.replace(String)` will throw a `IllegalArgumentException` when a file doesn't resolves in a fence.

    Parameters:
      `fences` - The fences guarding Path resolution.
    Returns:
      a Properties StringLookup instance.
    Since:
      1.12.0

  - ### resourceBundleStringLookup

    public StringLookup resourceBundleStringLookup()
    Returns the ResourceBundleStringLookup singleton instance.

    Looks up the value for a given key in the format "BundleName:BundleKey".

    For example: "com.domain.messages:MyKey".

    Using a `StringLookup` from the `StringLookupFactory`:

         StringLookupFactory.INSTANCE.resourceBundleStringLookup().lookup("com.domain.messages:MyKey");

    Using a `StringSubstitutor`:

         StringSubstitutor.createInterpolator().replace("... ${resourceBundle:com.domain.messages:MyKey} ..."));

    The above examples convert `"com.domain.messages:MyKey"` to the key value in the resource bundle at `"com.domain.messages"`.

    Returns:
      The ResourceBundleStringLookup singleton instance.

  - ### resourceBundleStringLookup

    public StringLookup resourceBundleStringLookup(String bundleName)
    Returns a ResourceBundleStringLookup instance for the given bundle name.

    Looks up the value for a given key in the format "MyKey".

    For example: "MyKey".

    Using a `StringLookup` from the `StringLookupFactory`:

         StringLookupFactory.INSTANCE.resourceBundleStringLookup("com.domain.messages").lookup("MyKey");

    The above example converts `"MyKey"` to the key value in the resource bundle at `"com.domain.messages"`.

    Parameters:
      `bundleName` - Only lookup in this bundle.
    Returns:
      a ResourceBundleStringLookup instance for the given bundle name.
    Since:
      1.5

  - ### scriptStringLookup

    public StringLookup scriptStringLookup()
    Returns the ScriptStringLookup singleton instance. NOTE: This lookup is not included as a `default lookup` unless explicitly enabled. See the class level documentation for details.

    Looks up the value for the key in the format "ScriptEngineName:Script".

    For example: "javascript:3 + 4".

    Using a `StringLookup` from the `StringLookupFactory`:

         StringLookupFactory.INSTANCE.scriptStringLookup().lookup("javascript:3 + 4");

    When used through a `StringSubstitutor`, this lookup must either be added programmatically (as below) or enabled as a default lookup using the "org.apache.commons.text.lookup.StringLookupFactory.defaultStringLookups" system property (see class documentation).

         Map<String, StringLookup> lookupMap = new HashMap<>();
         lookupMap.put("script", StringLookupFactory.INSTANCE.scriptStringLookup());

         StringLookup variableResolver = StringLookupFactory.INSTANCE.interpolatorStringLookup(lookupMap, null, false);

         String value = new StringSubstitutor(variableResolver).replace("${script:javascript:3 + 4}");

    The above examples convert `"javascript:3 + 4"` to `"7"`.

    Returns:
      The ScriptStringLookup singleton instance.
    Since:
      1.5

  - ### systemPropertyStringLookup

    public StringLookup systemPropertyStringLookup()
    Returns the SystemPropertyStringLookup singleton instance where the lookup key is a system property name.

    Using a `StringLookup` from the `StringLookupFactory`:

         StringLookupFactory.INSTANCE.systemPropertyStringLookup().lookup("os.name");

    Using a `StringSubstitutor`:

         StringSubstitutor.createInterpolator().replace("... ${sys:os.name} ..."));

    The above examples convert `"os.name"` to the operating system name.

    Returns:
      The SystemPropertyStringLookup singleton instance.

  - ### urlDecoderStringLookup

    public StringLookup urlDecoderStringLookup()
    Returns the UrlDecoderStringLookup singleton instance.

    Decodes URL Strings using the UTF-8 encoding.

    For example: "Hello%20World%21" becomes "Hello World!".

    Using a `StringLookup` from the `StringLookupFactory`:

         StringLookupFactory.INSTANCE.urlDecoderStringLookup().lookup("Hello%20World%21");

    Using a `StringSubstitutor`:

         StringSubstitutor.createInterpolator().replace("... ${urlDecoder:Hello%20World%21} ..."));

    The above examples convert `"Hello%20World%21"` to `"Hello World!"`.

    Returns:
      The UrlStringLookup singleton instance.
    Since:
      1.6

  - ### urlEncoderStringLookup

    public StringLookup urlEncoderStringLookup()
    Returns the UrlDecoderStringLookup singleton instance.

    Decodes URL Strings using the UTF-8 encoding.

    For example: "Hello World!" becomes "Hello+World%21".

    Using a `StringLookup` from the `StringLookupFactory`:

         StringLookupFactory.INSTANCE.urlEncoderStringLookup().lookup("Hello World!");

    Using a `StringSubstitutor`:

         StringSubstitutor.createInterpolator().replace("... ${urlEncoder:Hello World!} ..."));

    The above examples convert `"Hello World!"` to `"Hello%20World%21"`.

    Returns:
      The UrlStringLookup singleton instance.
    Since:
      1.6

  - ### urlStringLookup

    public StringLookup urlStringLookup()
    Returns the UrlStringLookup singleton instance. This lookup is not included as a `default lookup` unless explicitly enabled. See the class level documentation for details.

    Looks up the value for the key in the format "CharsetName:URL".

    For example, using the HTTP scheme: "UTF-8:http://www.google.com"

    For example, using the file scheme: "UTF-8:file:///C:/somehome/commons/commons-text/src/test/resources/document.properties"

    Using a `StringLookup` from the `StringLookupFactory`:

         StringLookupFactory.INSTANCE.urlStringLookup().lookup("UTF-8:https://www.apache.org");

    When used through a `StringSubstitutor`, this lookup must either be added programmatically (as below) or enabled as a default lookup using the "org.apache.commons.text.lookup.StringLookupFactory.defaultStringLookups" system property (see class documentation).

         Map<String, StringLookup> lookupMap = new HashMap<>();
         lookupMap.put("url", StringLookupFactory.INSTANCE.urlStringLookup());

         StringLookup variableResolver = StringLookupFactory.INSTANCE.interpolatorStringLookup(lookupMap, null, false);

         String value = new StringSubstitutor(variableResolver).replace("${url:UTF-8:https://www.apache.org}");

    The above examples convert `"UTF-8:https://www.apache.org"` to the contents of that page.

    Returns:
      The UrlStringLookup singleton instance.
    Since:
      1.5

  - ### xmlDecoderStringLookup

    public StringLookup xmlDecoderStringLookup()
    Returns the XmlDecoderStringLookup singleton instance.

    Decodes strings according to the XML 1.0 specification.

    For example: "&lt;element&gt;" becomes "<element>".

    Using a `StringLookup` from the `StringLookupFactory`:

         StringLookupFactory.INSTANCE.xmlDecoderStringLookup().lookup("&lt;element&gt;");

    Using a `StringSubstitutor`:

         StringSubstitutor.createInterpolator().replace("... ${xmlDecoder:&lt;element&gt;} ..."));

    The above examples convert `"&lt;element&gt;"` to `"<element>"`.

    Returns:
      The XmlDecoderStringLookup singleton instance.
    Since:
      1.11.0

  - ### xmlEncoderStringLookup

    public StringLookup xmlEncoderStringLookup()
    Returns the XmlEncoderStringLookup singleton instance.

    Encodes strings according to the XML 1.0 specification.

    For example: "<element>" becomes "&lt;element&gt;".

    Using a `StringLookup` from the `StringLookupFactory`:

         StringLookupFactory.INSTANCE.xmlEncoderStringLookup().lookup("<element>");

    Using a `StringSubstitutor`:

         StringSubstitutor.createInterpolator().replace("... ${xmlEncoder:<element>} ..."));

    The above examples convert `"<element>"` to `"&lt;element&gt;"`.

    Returns:
      The XmlEncoderStringLookup singleton instance.
    Since:
      1.11.0

  - ### xmlStringLookup

    public StringLookup xmlStringLookup()
    Returns an XML StringLookup instance.

    If this factory was built using `StringLookupFactory.Builder.setFences(Path...)`, then the string lookup is fenced and will throw an `IllegalArgumentException` if a lookup causes causes a path to resolve outside of these fences. Otherwise, the result is unfenced to preserved behavior from previous versions.

    We look up the value for the key in the format "DocumentPath:XPath".

    For example: "com/domain/document.xml:/path/to/node".

    Using a `StringLookup` from the `StringLookupFactory`:

         StringLookupFactory.INSTANCE.xmlStringLookup().lookup("com/domain/document.xml:/path/to/node");

    Using a `StringSubstitutor`:

         StringSubstitutor.createInterpolator().replace("... ${xml:com/domain/document.xml:/path/to/node} ..."));

    The above examples convert `"com/domain/document.xml:/path/to/node"` to the value of the XPath in the XML document.

    Returns:
      An XML StringLookup instance.
    Since:
      1.5

  - ### xmlStringLookup

    public StringLookup xmlStringLookup(Map<String,Boolean> xPathFactoryFeatures)
    Returns an XML StringLookup instance.

    If this factory was built using `StringLookupFactory.Builder.setFences(Path...)`, then the string lookup is fenced and will throw an `IllegalArgumentException` if a lookup causes causes a path to resolve outside of these fences. Otherwise, the result is unfenced to preserved behavior from previous versions.

    We look up the value for the key in the format "DocumentPath:XPath".

    For example: "com/domain/document.xml:/path/to/node".

    Using a `StringLookup` from the `StringLookupFactory`:

         StringLookupFactory.INSTANCE.xmlStringLookup().lookup("com/domain/document.xml:/path/to/node");

    Using a `StringSubstitutor`:

         StringSubstitutor.createInterpolator().replace("... ${xml:com/domain/document.xml:/path/to/node} ..."));

    The above examples convert `"com/domain/document.xml:/path/to/node"` to the value of the XPath in the XML document.

    Parameters:
      `xPathFactoryFeatures` - XPathFactory features to set.
    Returns:
      An XML StringLookup instance.
    Since:
      1.11.0
    See Also:
      - `XPathFactory.setFeature(String, boolean)`

  - ### xmlStringLookup

    public StringLookup xmlStringLookup(Map<String,Boolean> xPathFactoryFeatures, Path... fences)
    Returns a fenced XML StringLookup instance.

    If this factory was built using `StringLookupFactory.Builder.setFences(Path...)`, then the string lookup is fenced and will throw an `IllegalArgumentException` if a lookup causes causes a path to resolve outside of these fences. Otherwise, the result is unfenced to preserved behavior from previous versions.

    We look up the value for the key in the format "DocumentPath:XPath".

    For example: "com/domain/document.xml:/path/to/node".

    Using a `StringLookup` from the `StringLookupFactory` fenced by the current directory (`Paths.get("")`):

         StringLookupFactory.INSTANCE.xmlStringLookup(map, Pathe.get("")).lookup("com/domain/document.xml:/path/to/node");

    To use a `StringLookup` fenced by the current directory, use:

         StringLookupFactory.INSTANCE.xmlStringLookup(Paths.get("")).lookup("com/domain/document.xml:/path/to/node");

         // throws IllegalArgumentException
         StringLookupFactory.INSTANCE.xmlStringLookup(Paths.get("")).lookup("/rootdir/foo/document.xml:/path/to/node");

         // throws IllegalArgumentException
         StringLookupFactory.INSTANCE.xmlStringLookup(Paths.get("")).lookup("../com/domain/document.xml:/path/to/node");

    The above examples convert `"com/domain/document.xml:/path/to/node"` to the value of the XPath in the XML document.

    `StringSubstitutor` methods like `StringSubstitutor.replace(String)` will throw a `IllegalArgumentException` when a file doesn't resolves in a fence.

    Parameters:
      `xPathFactoryFeatures` - XPathFactory features to set.
      `fences` - The fences guarding Path resolution.
    Returns:
      An XML StringLookup instance.
    Since:
      1.12.0