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 df619a4 - Add missing documentation. - Fix incorrect examples in Javadocs. - Expand Javadocs. - Add test. df619a4 is described below commit df619a47f69dd073ef82921aacdedc604e470a9c Author: Gary Gregory <gardgreg...@gmail.com> AuthorDate: Sat Aug 3 19:51:03 2019 -0400 - Add missing documentation. - Fix incorrect examples in Javadocs. - Expand Javadocs. - Add test. --- .../text/lookup/Base64DecoderStringLookup.java | 12 ++++- .../commons/text/lookup/ScriptStringLookup.java | 11 ++++- .../commons/text/lookup/StringLookupFactory.java | 2 +- src/site/site.xml | 4 +- src/site/xdoc/userguide.xml | 52 ++++++++++++++++++---- ...ubstitutorWithInterpolatorStringLookupTest.java | 8 ++++ 6 files changed, 75 insertions(+), 14 deletions(-) diff --git a/src/main/java/org/apache/commons/text/lookup/Base64DecoderStringLookup.java b/src/main/java/org/apache/commons/text/lookup/Base64DecoderStringLookup.java index a003e82..515d841 100644 --- a/src/main/java/org/apache/commons/text/lookup/Base64DecoderStringLookup.java +++ b/src/main/java/org/apache/commons/text/lookup/Base64DecoderStringLookup.java @@ -20,9 +20,19 @@ package org.apache.commons.text.lookup; import java.nio.charset.StandardCharsets; import java.util.Base64; +import org.apache.commons.text.StringSubstitutor; + /** * Decodes Base64 Strings. - * + * <p> + * For example: {@code "SGVsbG9Xb3JsZCE="} -> {@code "HelloWorld!"}. + * </p> + * <p> + * Using a {@link StringSubstitutor}: + * </p> + * <pre> + * StringSubstitutor.createInterpolator().replace("${base64Decoder:SGVsbG9Xb3JsZCE=}")); + * </pre> * @since 1.5 */ final class Base64DecoderStringLookup extends AbstractStringLookup { diff --git a/src/main/java/org/apache/commons/text/lookup/ScriptStringLookup.java b/src/main/java/org/apache/commons/text/lookup/ScriptStringLookup.java index a6b1bf6..f471c84 100644 --- a/src/main/java/org/apache/commons/text/lookup/ScriptStringLookup.java +++ b/src/main/java/org/apache/commons/text/lookup/ScriptStringLookup.java @@ -22,15 +22,22 @@ import java.util.Objects; import javax.script.ScriptEngine; import javax.script.ScriptEngineManager; +import org.apache.commons.text.StringSubstitutor; + /** * Looks up keys from an XML document. * <p> * Looks up the value for a given key in the format "Document:Key". * </p> * <p> - * For example: "com/domain/document.properties:key". + * For example: {@code "javascript:\"Hello World!\""}. * </p> - * + * <p> + * Using a {@link StringSubstitutor}: + * </p> + * <pre> + * StringSubstitutor.createInterpolator().replace("${script:javascript:3 + 4}")); + * </pre> * @since 1.5 */ final class ScriptStringLookup extends AbstractStringLookup { diff --git a/src/main/java/org/apache/commons/text/lookup/StringLookupFactory.java b/src/main/java/org/apache/commons/text/lookup/StringLookupFactory.java index a1c80c6..da61c6f 100644 --- a/src/main/java/org/apache/commons/text/lookup/StringLookupFactory.java +++ b/src/main/java/org/apache/commons/text/lookup/StringLookupFactory.java @@ -531,7 +531,7 @@ public final class StringLookupFactory { * Looks up the value for the key in the format "ScriptEngineName:Script". * </p> * <p> - * For example: "javascript:\"HelloWorld\"". + * For example: "javascript:3+4". * </p> * * @return the ScriptStringLookup singleton instance. diff --git a/src/site/site.xml b/src/site/site.xml index 8a0d5a3..2b012fd 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -26,7 +26,7 @@ <menu name="Text"> <item name="Overview" href="/index.html"/> <item name="Download" href="/download_text.cgi"/> - <item name="User guide" href="/userguide.html" /> + <item name="User Guide" href="/userguide.html" /> <item name="Release History" href="/release-history.html"/> <item name="Javadoc (Latest release)" href="javadocs/api-release/index.html"/> </menu> @@ -35,7 +35,7 @@ <item name="Mailing Lists" href="/mail-lists.html"/> <item name="Issue Tracking" href="/issue-tracking.html"/> <item name="Proposal" href="/proposal.html"/> - <item name="Developer guide" href="/developerguide.html"/> + <item name="Developer Guide" href="/developerguide.html"/> <item name="Source Repository" href="/scm.html"/> <item name="Javadoc (latest)" href="apidocs/index.html"/> </menu> diff --git a/src/site/xdoc/userguide.xml b/src/site/xdoc/userguide.xml index 8017ee0..9784950 100644 --- a/src/site/xdoc/userguide.xml +++ b/src/site/xdoc/userguide.xml @@ -24,17 +24,18 @@ limitations under the License. <body> <!-- $Id$ --> - <section name='User guide for Commons "Text"'> + <section name='User Guide for Commons "Text"'> <div align="center"> <h1>The Commons <em>Text</em> Package </h1> <h2>Users Guide</h2> <br/> <a href="#Description">[Description]</a> - <a href="#text.">[text.*]</a> - <a href="#text.diff.">[text.diff.*]</a> - <a href="#text.similarity.">[text.similarity.*]</a> - <a href="#text.translate.">[text.translate.*]</a> + <a href="#text">[text]</a> + <a href="#text.diff">[text.diff]</a> + <a href="#text.lookup">[text.lookup]</a> + <a href="#text.similarity">[text.similarity]</a> + <a href="#text.translate">[text.translate]</a> <br/> <br/> </div> @@ -48,7 +49,7 @@ limitations under the License. </p> </section> - <section name="text.*"> + <section name="text"> <p>Originally the text package was added in Commons Lang 2.2. However, its new home is here. It provides, amongst other @@ -79,6 +80,32 @@ limitations under the License. </p> </subsection> + <subsection name="StringSubstitutor"> + <p> + The simplest example is to use this class to replace Java System properties. For example: + <pre> + StringSubstitutor.replaceSystemProperties( + "You are running with java.version = ${java.version} and os.name = ${os.name}."); + </pre> + </p> + <p> + For details see <a href="http://commons.apache.org/proper/commons-text/apidocs/org/apache/commons/text/StringSubstitutor.html">StringSubstitutor</a>. + </p> + <p> + To build a default full-featured substitutor, use: + </p> + <ul> + <li>Commons Text >= 1.8: + <a href="http://commons.apache.org/proper/commons-text/apidocs/org/apache/commons/text/StringSubstitutor.html">org.apache.commons.text.StringSubstitutor.createInterpolator()</a></li> + <li>Commons Text < 1.8: + <a href="http://commons.apache.org/proper/commons-text/apidocs/org/apache/commons/text/StringSubstitutor.html">new StringSubstitutor(StringLookupFactory.INSTANCE.interpolatorStringLookup())</a></li> + </ul> + <p> + The available substitutions are defined in + <a href="http://commons.apache.org/proper/commons-text/apidocs/org/apache/commons/text/lookup/StringLookupFactory.html">org.apache.commons.text.lookup.StringLookupFactory</a>: + </p> + </subsection> + <subsection name="Similarity and Distance"> <p>The <code>org.apache.commons.text.similarity</code> packages contains various different mechanisms of calculating "similarity scores" as well as "edit distances between Strings. Note, @@ -130,7 +157,7 @@ limitations under the License. </section> - <section name="text.diff.*"> + <section name="text.diff"> <!-- CommandVisitor DeleteCommand @@ -148,7 +175,16 @@ limitations under the License. </p> </section> - <section name="text.similarity.*"> + <section name="text.lookup"> + <p>Provides algorithms for looking up strings used by a + <a href="http://commons.apache.org/proper/commons-text/apidocs/org/apache/commons/text/StringSubstitutor.html">StringSubstitutor</a>. + where you can select which lookup are used from + <a href="http://commons.apache.org/proper/commons-text/apidocs/org/apache/commons/text/lookup/StringLookupFactory.html">StringLookupFactory</a>.</p> + <p> + </p> + </section> + + <section name="text.similarity"> <!-- Enum EnumUtils diff --git a/src/test/java/org/apache/commons/text/StringSubstitutorWithInterpolatorStringLookupTest.java b/src/test/java/org/apache/commons/text/StringSubstitutorWithInterpolatorStringLookupTest.java index e002f22..6d52816 100644 --- a/src/test/java/org/apache/commons/text/StringSubstitutorWithInterpolatorStringLookupTest.java +++ b/src/test/java/org/apache/commons/text/StringSubstitutorWithInterpolatorStringLookupTest.java @@ -101,6 +101,14 @@ public class StringSubstitutorWithInterpolatorStringLookupTest { } @Test + void testJavaScript() { + Assertions.assertEquals("Hello World!", + StringSubstitutor.createInterpolator().replace("${script:javascript:\"Hello World!\"}")); + Assertions.assertEquals("7", + StringSubstitutor.createInterpolator().replace("${script:javascript:3 + 4}")); + } + + @Test public void testSystemProperty() { final StringSubstitutor strSubst = StringSubstitutor.createInterpolator(); final String spKey = "user.name";