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 4430442 Javadoc.
4430442 is described below
commit 4430442363b1f545e114878760a0e323678abc90
Author: Gary Gregory <[email protected]>
AuthorDate: Sun Jun 28 10:45:40 2020 -0400
Javadoc.
---
.../commons/text/lookup/StringLookupFactory.java | 70 ++++++++++++++++------
.../apache/commons/text/lookup/package-info.java | 17 +++++-
.../apache/commons/text/matcher/package-info.java | 5 +-
.../text/translate/NumericEntityUnescaper.java | 18 +++++-
4 files changed, 85 insertions(+), 25 deletions(-)
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 05fc77b..8a983a3 100644
--- a/src/main/java/org/apache/commons/text/lookup/StringLookupFactory.java
+++ b/src/main/java/org/apache/commons/text/lookup/StringLookupFactory.java
@@ -26,7 +26,19 @@ import java.util.function.Function;
import org.apache.commons.text.StringSubstitutor;
/**
- * Provides access to lookups defined in this package.
+ * Create instances of string lookups or access singleton string lookups
implemented in this package.
+ * <p>
+ * The "classic" look up is {@link #mapStringLookup(Map)}.
+ * </p>
+ * <p>
+ * The methods for variable interpolation (A.K.A. variable substitution) are:
+ * </p>
+ * <ul>
+ * <li>{@link #interpolatorStringLookup()}.</li>
+ * <li>{@link #interpolatorStringLookup(Map)}.</li>
+ * <li>{@link #interpolatorStringLookup(StringLookup)}.</li>
+ * <li>{@link #interpolatorStringLookup(Map, StringLookup, boolean)}.</li>
+ * </ul>
* <p>
* The default lookups are:
* </p>
@@ -34,113 +46,133 @@ import org.apache.commons.text.StringSubstitutor;
* <caption>Default String Lookups</caption>
* <tr>
* <th>Key</th>
- * <th>Implementation</th>
+ * <th>Interface</th>
* <th>Factory Method</th>
* <th>Since</th>
* </tr>
* <tr>
* <td>{@value #KEY_BASE64_DECODER}</td>
- * <td>{@link FunctionStringLookup}</td>
+ * <td>{@link StringLookup}</td>
* <td>{@link #base64DecoderStringLookup()}</td>
* <td>1.6</td>
* </tr>
* <tr>
* <td>{@value #KEY_BASE64_ENCODER}</td>
- * <td>{@link FunctionStringLookup}</td>
+ * <td>{@link StringLookup}</td>
* <td>{@link #base64EncoderStringLookup()}</td>
* <td>1.6</td>
* </tr>
* <tr>
* <td>{@value #KEY_CONST}</td>
- * <td>{@link ConstantStringLookup}</td>
+ * <td>{@link StringLookup}</td>
* <td>{@link #constantStringLookup()}</td>
* <td>1.5</td>
* </tr>
* <tr>
* <td>{@value #KEY_DATE}</td>
- * <td>{@link DateStringLookup}</td>
+ * <td>{@link StringLookup}</td>
* <td>{@link #dateStringLookup()}</td>
* <td>1.5</td>
* </tr>
* <tr>
* <td>{@value #KEY_DNS}</td>
- * <td>{@link DnsStringLookup}</td>
+ * <td>{@link StringLookup}</td>
* <td>{@link #dnsStringLookup()}</td>
* <td>1.8</td>
* </tr>
* <tr>
* <td>{@value #KEY_ENV}</td>
- * <td>{@link FunctionStringLookup}</td>
+ * <td>{@link StringLookup}</td>
* <td>{@link #environmentVariableStringLookup()}</td>
* <td>1.3</td>
* </tr>
* <tr>
* <td>{@value #KEY_FILE}</td>
- * <td>{@link FileStringLookup}</td>
+ * <td>{@link StringLookup}</td>
* <td>{@link #fileStringLookup()}</td>
* <td>1.5</td>
* </tr>
* <tr>
* <td>{@value #KEY_JAVA}</td>
- * <td>{@link JavaPlatformStringLookup}</td>
+ * <td>{@link StringLookup}</td>
* <td>{@link #javaPlatformStringLookup()}</td>
* <td>1.5</td>
* </tr>
* <tr>
* <td>{@value #KEY_LOCALHOST}</td>
- * <td>{@link LocalHostStringLookup}</td>
+ * <td>{@link StringLookup}</td>
* <td>{@link #localHostStringLookup()}</td>
* <td>1.3</td>
* </tr>
* <tr>
* <td>{@value #KEY_PROPERTIES}</td>
- * <td>{@link PropertiesStringLookup}</td>
+ * <td>{@link StringLookup}</td>
* <td>{@link #propertiesStringLookup()}</td>
* <td>1.5</td>
* </tr>
* <tr>
* <td>{@value #KEY_RESOURCE_BUNDLE}</td>
- * <td>{@link ResourceBundleStringLookup}</td>
+ * <td>{@link StringLookup}</td>
* <td>{@link #resourceBundleStringLookup()}</td>
* <td>1.6</td>
* </tr>
* <tr>
* <td>{@value #KEY_SCRIPT}</td>
- * <td>{@link ScriptStringLookup}</td>
+ * <td>{@link StringLookup}</td>
* <td>{@link #scriptStringLookup()}</td>
* <td>1.5</td>
* </tr>
* <tr>
* <td>{@value #KEY_SYS}</td>
- * <td>{@link FunctionStringLookup}</td>
+ * <td>{@link StringLookup}</td>
* <td>{@link #systemPropertyStringLookup()}</td>
* <td>1.3</td>
* </tr>
* <tr>
* <td>{@value #KEY_URL}</td>
- * <td>{@link UrlStringLookup}</td>
+ * <td>{@link StringLookup}</td>
* <td>{@link #urlStringLookup()}</td>
* <td>1.5</td>
* </tr>
* <tr>
* <td>{@value #KEY_URL_DECODER}</td>
- * <td>{@link UrlDecoderStringLookup}</td>
+ * <td>{@link StringLookup}</td>
* <td>{@link #urlDecoderStringLookup()}</td>
* <td>1.5</td>
* </tr>
* <tr>
* <td>{@value #KEY_URL_ENCODER}</td>
- * <td>{@link UrlEncoderStringLookup}</td>
+ * <td>{@link StringLookup}</td>
* <td>{@link #urlEncoderStringLookup()}</td>
* <td>1.5</td>
* </tr>
* <tr>
* <td>{@value #KEY_XML}</td>
- * <td>{@link XmlStringLookup}</td>
+ * <td>{@link StringLookup}</td>
* <td>{@link #xmlStringLookup()}</td>
* <td>1.5</td>
* </tr>
* </table>
+ * <p>
+ * We also provide functional lookups used as building blocks for other
lookups.
+ * <table>
+ * <caption>Functional String Lookups</caption>
+ * <tr>
+ * <th>Interface</th>
+ * <th>Factory Method</th>
+ * <th>Since</th>
+ * </tr>
+ * <tr>
+ * <td>{@link BiStringLookup}</td>
+ * <td>{@link #biFunctionStringLookup(BiFunction)}</td>
+ * <td>1.9</td>
+ * </tr>
+ * <tr>
+ * <td>{@link StringLookup}</td>
+ * <td>{@link #functionStringLookup(Function)}</td>
+ * <td>1.9</td>
+ * </tr>
+ * </table>
*
* @since 1.3
*/
diff --git a/src/main/java/org/apache/commons/text/lookup/package-info.java
b/src/main/java/org/apache/commons/text/lookup/package-info.java
index 6e20eab..65ea003 100644
--- a/src/main/java/org/apache/commons/text/lookup/package-info.java
+++ b/src/main/java/org/apache/commons/text/lookup/package-info.java
@@ -14,12 +14,23 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
/**
* <p>
- * Provides algorithms for looking up strings for use with a {@link
org.apache.commons.text.StringSubstitutor}. The main
- * class in this package is {@link
org.apache.commons.text.lookup.StringLookupFactory}.
+ * Provides algorithms for looking up strings for use with a {@link
org.apache.commons.text.StringSubstitutor
+ * StringSubstitutor}. The main class in this package is {@link
org.apache.commons.text.lookup.StringLookupFactory
+ * StringLookupFactory}.
+ * </p>
+ * <p>
+ * Use {@link org.apache.commons.text.lookup.StringLookupFactory
StringLookupFactory} to create instances of string
+ * lookups or access singleton string lookups. The main interface is {@link
org.apache.commons.text.lookup.StringLookup
+ * StringLookup} which is implemented here in package private classes.
+ * </p>
+ * <p>
+ * Like {@link java.util.function.BiFunction BiFunction} is a variant of
{@link java.util.function.Function Function},
+ * this {@link org.apache.commons.text.lookup.BiStringLookup BiStringLookup}
is a variant of
+ * {@link org.apache.commons.text.lookup.StringLookup StringLookup}.
* </p>
- *
* <p>
* The initial implementation was adapted from Apache Commons Log4j 2.11.0.
* </p>
diff --git a/src/main/java/org/apache/commons/text/matcher/package-info.java
b/src/main/java/org/apache/commons/text/matcher/package-info.java
index 1ba8f5c..a6b1d7d 100644
--- a/src/main/java/org/apache/commons/text/matcher/package-info.java
+++ b/src/main/java/org/apache/commons/text/matcher/package-info.java
@@ -16,8 +16,9 @@
*/
/**
* <p>
- * Provides algorithms for matching up strings for use with a {@link
org.apache.commons.text.StringSubstitutor}. The
- * main class here is {@link
org.apache.commons.text.matcher.StringMatcherFactory}
+ * Provides algorithms for matching up strings for use with a {@link
org.apache.commons.text.StringSubstitutor
+ * StringSubstitutor}. The main class here is {@link
org.apache.commons.text.matcher.StringMatcherFactory
+ * StringMatcherFactory}.
* </p>
*
* @since 1.3
diff --git
a/src/main/java/org/apache/commons/text/translate/NumericEntityUnescaper.java
b/src/main/java/org/apache/commons/text/translate/NumericEntityUnescaper.java
index 1b8a7ee..6ad9b73 100644
---
a/src/main/java/org/apache/commons/text/translate/NumericEntityUnescaper.java
+++
b/src/main/java/org/apache/commons/text/translate/NumericEntityUnescaper.java
@@ -32,7 +32,23 @@ import java.util.EnumSet;
public class NumericEntityUnescaper extends CharSequenceTranslator {
/** NumericEntityUnescaper option enum. */
- public enum OPTION { semiColonRequired, semiColonOptional,
errorIfNoSemiColon }
+ public enum OPTION {
+
+ /**
+ * Require a semicolon.
+ */
+ semiColonRequired,
+
+ /**
+ * Do not require a semicolon.
+ */
+ semiColonOptional,
+
+ /**
+ * Throw an exception if a semi-colon is missing.
+ */
+ errorIfNoSemiColon
+ }
/** EnumSet of OPTIONS, given from the constructor. */
private final EnumSet<OPTION> options;
