This is an automated email from the ASF dual-hosted git repository. ggregory pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/commons-text.git
The following commit(s) were added to refs/heads/master by this push: new 95f2c20 Javadoc. 95f2c20 is described below commit 95f2c20cd92a64332c6dbd86add1a788d5ca48a8 Author: Gary Gregory <garydgreg...@gmail.com> AuthorDate: Sun Jun 28 11:19:19 2020 -0400 Javadoc. --- .../org/apache/commons/text/StringSubstitutor.java | 68 +++++++++++++--------- 1 file changed, 41 insertions(+), 27 deletions(-) diff --git a/src/main/java/org/apache/commons/text/StringSubstitutor.java b/src/main/java/org/apache/commons/text/StringSubstitutor.java index 64824b6..7c98bb0 100644 --- a/src/main/java/org/apache/commons/text/StringSubstitutor.java +++ b/src/main/java/org/apache/commons/text/StringSubstitutor.java @@ -83,25 +83,34 @@ import org.apache.commons.text.matcher.StringMatcherFactory; * </p> * * <pre> - * The quick brown fox jumped over the lazy dog. + * "The quick brown fox jumped over the lazy dog." * </pre> * * <h2>Providing Default Values</h2> * <p> - * This class lets you set a default value for unresolved variables. The default value for a variable can be appended to - * the variable name after the variable default value delimiter. The default value of the variable default value - * delimiter is ':-', as in bash and other *nix shells, as those are arguably where the default ${} delimiter set - * originated. The variable default value delimiter can be manually set by calling - * {@link #setValueDelimiterMatcher(StringMatcher)}, {@link #setValueDelimiter(char)} or - * {@link #setValueDelimiter(String)}. The following shows an example with variable default value settings: + * 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. * </p> - * + * <p> + * You can set the variable value delimiter with {@link #setValueDelimiterMatcher(StringMatcher)}, + * {@link #setValueDelimiter(char)} or {@link #setValueDelimiter(String)}. + * </p> + * <p> + * For example: + * </p> + * * <pre> + * // 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}."; + * + * // Build StringSubstitutor * StringSubstitutor sub = new StringSubstitutor(valuesMap); + * + * // Replace * String resolvedString = sub.replace(templateString); * </pre> * @@ -110,7 +119,7 @@ import org.apache.commons.text.matcher.StringMatcherFactory; * </p> * * <pre> - * The quick brown fox jumped over the lazy dog. 1234567890. + * "The quick brown fox jumped over the lazy dog. 1234567890." * </pre> * * <p> @@ -120,12 +129,8 @@ import org.apache.commons.text.matcher.StringMatcherFactory; * * <h2>Reusing Instances</h2> * <p> - * In addition to this usage pattern there are some static convenience methods that cover the most common use cases. - * These methods can be used without the need of manually creating an instance. However if multiple replace operations - * are to be performed, creating and reusing an instance of this class will be more efficient. - * </p> - * <p> - * This class is <b>not</b> thread safe. + * 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. * </p> * * <h2>Using Interpolation</h2> @@ -136,16 +141,20 @@ import org.apache.commons.text.matcher.StringMatcherFactory; * <pre> * final StringSubstitutor interpolator = StringSubstitutor.createInterpolator(); * interpolator.setEnableSubstitutionInVariables(true); // Allows for nested $'s. - * final String text = interpolator.replace("Base64 Decoder: ${base64Decoder:SGVsbG9Xb3JsZCE=}\n" + * 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" + "DNS: ${dns:address|apache.org}\n" + * + "Date: ${date:yyyy-MM-dd}\n" + * + "DNS: ${dns:address|apache.org}\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" + * + "Java: ${java:version}\n" + * + "Localhost: ${localhost:canonical-name}\n" * + "Properties File: ${properties:src/test/resources/document.properties::mykey}\n" * + "Resource Bundle: ${resourceBundle:org.example.testResourceBundleLookup:mykey}\n" - * + "Script: ${script:javascript:3 + 4}\n" + "System Property: ${sys:user.dir}\n" + * + "Script: ${script:javascript:3 + 4}\n" + * + "System Property: ${sys:user.dir}\n" * + "URL Decoder: ${urlDecoder:Hello%20World%21}\n" * + "URL Encoder: ${urlEncoder:Hello World!}\n" * + "URL Content (HTTP): ${url:UTF-8:http://www.apache.org}\n" @@ -159,24 +168,24 @@ import org.apache.commons.text.matcher.StringMatcherFactory; * * <h2>Using Recursive Variable Replacement</h2> * <p> - * Variable replacement works in a recursive way. Thus, if a variable value contains a variable then that variable will - * also be replaced. Cyclic replacements are detected and will cause an exception to be thrown. + * Variable replacement can work recursively by calling {@link #setEnableSubstitutionInVariables(boolean)} + * with {@code true}. If a variable value contains a variable then that variable will + * also be replaced. Cyclic replacements are detected and will throw an exception. * </p> * <p> - * Sometimes the interpolation's result must contain a variable prefix. As an example take the following source text: + * You can get the replace result to contain a variable prefix. For example: * </p> * * <pre> - * The variable ${${name}} must be used. + * "The variable ${${name}} must be used." * </pre> * * <p> - * Here only the variable's name referred to in the text should be replaced resulting in the text (assuming that the - * value of the {@code name} variable is {@code x}): + * If the value of the "name" variable is "x", then only the variable "name" is replaced resulting in: * </p> * * <pre> - * The variable ${x} must be used. + * "The variable ${x} must be used." * </pre> * * <p> @@ -187,7 +196,7 @@ import org.apache.commons.text.matcher.StringMatcherFactory; * </p> * * <pre> - * The variable $${${name}} must be used. + * "The variable $${${name}} must be used." * </pre> * <p> * In some complex scenarios you might even want to perform substitution in the names of variables, for instance @@ -202,6 +211,11 @@ import org.apache.commons.text.matcher.StringMatcherFactory; * by calling {@link #setEnableSubstitutionInVariables(boolean)} with {@code true}. * </p> * + * <h2>Thread Safety</h2> + * <p> + * This class is <b>not</b> thread safe. + * </p> + * * @since 1.3 */ public class StringSubstitutor {