Java tutorial
/* Copyright (c) 2008 Google Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package com.google.common.base; import java.io.*; import static com.google.common.base.Preconditions.*; /** * Utility functions for dealing with {@code CharEscaper}s, and some commonly * used {@code CharEscaper} instances. * * * */ @SuppressWarnings("JavadocReference") public final class CharEscapers { private CharEscapers() { } // For each xxxEscaper method, please add links to external // reference pages that we consider authoritative for what // that escaper should exactly be doing. /** * Performs no escaping. */ private static final CharEscaper NULL_ESCAPER = new CharEscaper() { @Override public String escape(String string) { Preconditions.checkNotNull(string); return string; } @Override public Appendable escape(final Appendable out) { Preconditions.checkNotNull(out); // we can't simply return out because the CharEscaper contract says that // the returned Appendable will throw a NullPointerException if asked to // append null. return new Appendable() { public Appendable append(CharSequence csq) throws IOException { Preconditions.checkNotNull(csq); out.append(csq); return this; } public Appendable append(CharSequence csq, int start, int end) throws IOException { Preconditions.checkNotNull(csq); out.append(csq, start, end); return this; } public Appendable append(char c) throws IOException { out.append(c); return this; } }; } @Override protected char[] escape(char c) { return null; } }; /** * Returns a {@link CharEscaper} that does no escaping. */ public static CharEscaper nullEscaper() { return NULL_ESCAPER; } /** * Returns a {@link CharEscaper} instance that escapes special characters in a * string so it can safely be included in an XML document in either element * content or attribute values. * * <p><b>Note</b></p>: silently removes null-characters and control * characters, as there is no way to represent them in XML. */ public static CharEscaper xmlEscaper() { return XML_ESCAPER; } /** * Escapes special characters from a string so it can safely be included in an * XML document in either element content or attribute values. Also removes * null-characters and control characters, as there is no way to represent * them in XML. */ private static final CharEscaper XML_ESCAPER = newBasicXmlEscapeBuilder().addEscape('"', """) .addEscape('\'', "'").toEscaper(); /** * Returns a {@link CharEscaper} instance that escapes special characters in a * string so it can safely be included in an XML document in element content. * * <p><b>Note</b></p>: double and single quotes are not escaped, so it is not * safe to use this escaper to escape attribute values. Use the * {@link #xmlEscaper()} escaper to escape attribute values or if you are * unsure. Also silently removes non-whitespace control characters, as there * is no way to represent them in XML. */ public static CharEscaper xmlContentEscaper() { return XML_CONTENT_ESCAPER; } /** * Escapes special characters from a string so it can safely be included in an * XML document in element content. Note that quotes are <em>not</em> * escaped, so <em>this is not safe for use in attribute values</em>. Use * {@link #XML_ESCAPER} for attribute values, or if you are unsure. Also * removes non-whitespace control characters, as there is no way to represent * them in XML. */ private static final CharEscaper XML_CONTENT_ESCAPER = newBasicXmlEscapeBuilder().toEscaper(); /** * Returns a {@link CharEscaper} instance that escapes special characters in a * string so it can safely be included in an HTML document in either element * content or attribute values. * * <p><b>Note</b></p>: alters non-ASCII and control characters. * * The entity list was taken from: * <a href="http://www.w3.org/TR/html4/sgml/entities.html">here</a> */ public static CharEscaper htmlEscaper() { return HtmlEscaperHolder.HTML_ESCAPER; } /** * A lazy initialization holder for HTML_ESCAPER. */ private static class HtmlEscaperHolder { private static final CharEscaper HTML_ESCAPER = new HtmlCharEscaper(new CharEscaperBuilder() .addEscape('"', """).addEscape('\'', "'").addEscape('&', "&").addEscape('<', "<") .addEscape('>', ">").addEscape('\u00A0', " ").addEscape('\u00A1', "¡") .addEscape('\u00A2', "¢").addEscape('\u00A3', "£").addEscape('\u00A4', "¤") .addEscape('\u00A5', "¥").addEscape('\u00A6', "¦").addEscape('\u00A7', "§") .addEscape('\u00A8', "¨").addEscape('\u00A9', "©").addEscape('\u00AA', "ª") .addEscape('\u00AB', "«").addEscape('\u00AC', "¬").addEscape('\u00AD', "­") .addEscape('\u00AE', "®").addEscape('\u00AF', "¯").addEscape('\u00B0', "°") .addEscape('\u00B1', "±").addEscape('\u00B2', "²").addEscape('\u00B3', "³") .addEscape('\u00B4', "´").addEscape('\u00B5', "µ").addEscape('\u00B6', "¶") .addEscape('\u00B7', "·").addEscape('\u00B8', "¸").addEscape('\u00B9', "¹") .addEscape('\u00BA', "º").addEscape('\u00BB', "»").addEscape('\u00BC', "¼") .addEscape('\u00BD', "½").addEscape('\u00BE', "¾").addEscape('\u00BF', "¿") .addEscape('\u00C0', "À").addEscape('\u00C1', "Á").addEscape('\u00C2', "Â") .addEscape('\u00C3', "Ã").addEscape('\u00C4', "Ä").addEscape('\u00C5', "Å") .addEscape('\u00C6', "Æ").addEscape('\u00C7', "Ç").addEscape('\u00C8', "È") .addEscape('\u00C9', "É").addEscape('\u00CA', "Ê").addEscape('\u00CB', "Ë") .addEscape('\u00CC', "Ì").addEscape('\u00CD', "Í").addEscape('\u00CE', "Î") .addEscape('\u00CF', "Ï").addEscape('\u00D0', "Ð").addEscape('\u00D1', "Ñ") .addEscape('\u00D2', "Ò").addEscape('\u00D3', "Ó").addEscape('\u00D4', "Ô") .addEscape('\u00D5', "Õ").addEscape('\u00D6', "Ö").addEscape('\u00D7', "×") .addEscape('\u00D8', "Ø").addEscape('\u00D9', "Ù").addEscape('\u00DA', "Ú") .addEscape('\u00DB', "Û").addEscape('\u00DC', "Ü").addEscape('\u00DD', "Ý") .addEscape('\u00DE', "Þ").addEscape('\u00DF', "ß").addEscape('\u00E0', "à") .addEscape('\u00E1', "á").addEscape('\u00E2', "â").addEscape('\u00E3', "ã") .addEscape('\u00E4', "ä").addEscape('\u00E5', "å").addEscape('\u00E6', "æ") .addEscape('\u00E7', "ç").addEscape('\u00E8', "è").addEscape('\u00E9', "é") .addEscape('\u00EA', "ê").addEscape('\u00EB', "ë").addEscape('\u00EC', "ì") .addEscape('\u00ED', "í").addEscape('\u00EE', "î").addEscape('\u00EF', "ï") .addEscape('\u00F0', "ð").addEscape('\u00F1', "ñ").addEscape('\u00F2', "ò") .addEscape('\u00F3', "ó").addEscape('\u00F4', "ô").addEscape('\u00F5', "õ") .addEscape('\u00F6', "ö").addEscape('\u00F7', "÷").addEscape('\u00F8', "ø") .addEscape('\u00F9', "ù").addEscape('\u00FA', "ú").addEscape('\u00FB', "û") .addEscape('\u00FC', "ü").addEscape('\u00FD', "ý").addEscape('\u00FE', "þ") .addEscape('\u00FF', "ÿ").addEscape('\u0152', "Œ").addEscape('\u0153', "œ") .addEscape('\u0160', "Š").addEscape('\u0161', "š").addEscape('\u0178', "Ÿ") .addEscape('\u0192', "ƒ").addEscape('\u02C6', "ˆ").addEscape('\u02DC', "˜") .addEscape('\u0391', "Α").addEscape('\u0392', "Β").addEscape('\u0393', "Γ") .addEscape('\u0394', "Δ").addEscape('\u0395', "Ε").addEscape('\u0396', "Ζ") .addEscape('\u0397', "Η").addEscape('\u0398', "Θ").addEscape('\u0399', "Ι") .addEscape('\u039A', "Κ").addEscape('\u039B', "Λ").addEscape('\u039C', "Μ") .addEscape('\u039D', "Ν").addEscape('\u039E', "Ξ").addEscape('\u039F', "Ο") .addEscape('\u03A0', "Π").addEscape('\u03A1', "Ρ").addEscape('\u03A3', "Σ") .addEscape('\u03A4', "Τ").addEscape('\u03A5', "Υ").addEscape('\u03A6', "Φ") .addEscape('\u03A7', "Χ").addEscape('\u03A8', "Ψ").addEscape('\u03A9', "Ω") .addEscape('\u03B1', "α").addEscape('\u03B2', "β").addEscape('\u03B3', "γ") .addEscape('\u03B4', "δ").addEscape('\u03B5', "ε").addEscape('\u03B6', "ζ") .addEscape('\u03B7', "η").addEscape('\u03B8', "θ").addEscape('\u03B9', "ι") .addEscape('\u03BA', "κ").addEscape('\u03BB', "λ").addEscape('\u03BC', "μ") .addEscape('\u03BD', "ν").addEscape('\u03BE', "ξ").addEscape('\u03BF', "ο") .addEscape('\u03C0', "π").addEscape('\u03C1', "ρ").addEscape('\u03C2', "ς") .addEscape('\u03C3', "σ").addEscape('\u03C4', "τ").addEscape('\u03C5', "υ") .addEscape('\u03C6', "φ").addEscape('\u03C7', "χ").addEscape('\u03C8', "ψ") .addEscape('\u03C9', "ω").addEscape('\u03D1', "ϑ").addEscape('\u03D2', "ϒ") .addEscape('\u03D6', "ϖ").addEscape('\u2002', " ").addEscape('\u2003', " ") .addEscape('\u2009', " ").addEscape('\u200C', "‌").addEscape('\u200D', "‍") .addEscape('\u200E', "‎").addEscape('\u200F', "‏").addEscape('\u2013', "–") .addEscape('\u2014', "—").addEscape('\u2018', "‘").addEscape('\u2019', "’") .addEscape('\u201A', "‚").addEscape('\u201C', "“").addEscape('\u201D', "”") .addEscape('\u201E', "„").addEscape('\u2020', "†").addEscape('\u2021', "‡") .addEscape('\u2022', "•").addEscape('\u2026', "…").addEscape('\u2030', "‰") .addEscape('\u2032', "′").addEscape('\u2033', "″").addEscape('\u2039', "‹") .addEscape('\u203A', "›").addEscape('\u203E', "‾").addEscape('\u2044', "⁄") .addEscape('\u20AC', "€").addEscape('\u2111', "ℑ").addEscape('\u2118', "℘") .addEscape('\u211C', "ℜ").addEscape('\u2122', "™").addEscape('\u2135', "ℵ") .addEscape('\u2190', "←").addEscape('\u2191', "↑").addEscape('\u2192', "→") .addEscape('\u2193', "↓").addEscape('\u2194', "↔").addEscape('\u21B5', "↵") .addEscape('\u21D0', "⇐").addEscape('\u21D1', "⇑").addEscape('\u21D2', "⇒") .addEscape('\u21D3', "⇓").addEscape('\u21D4', "⇔").addEscape('\u2200', "∀") .addEscape('\u2202', "∂").addEscape('\u2203', "∃").addEscape('\u2205', "∅") .addEscape('\u2207', "∇").addEscape('\u2208', "∈").addEscape('\u2209', "∉") .addEscape('\u220B', "∋").addEscape('\u220F', "∏").addEscape('\u2211', "∑") .addEscape('\u2212', "−").addEscape('\u2217', "∗").addEscape('\u221A', "√") .addEscape('\u221D', "∝").addEscape('\u221E', "∞").addEscape('\u2220', "∠") .addEscape('\u2227', "∧").addEscape('\u2228', "∨").addEscape('\u2229', "∩") .addEscape('\u222A', "∪").addEscape('\u222B', "∫").addEscape('\u2234', "∴") .addEscape('\u223C', "∼").addEscape('\u2245', "≅").addEscape('\u2248', "≈") .addEscape('\u2260', "≠").addEscape('\u2261', "≡").addEscape('\u2264', "≤") .addEscape('\u2265', "≥").addEscape('\u2282', "⊂").addEscape('\u2283', "⊃") .addEscape('\u2284', "⊄").addEscape('\u2286', "⊆").addEscape('\u2287', "⊇") .addEscape('\u2295', "⊕").addEscape('\u2297', "⊗").addEscape('\u22A5', "⊥") .addEscape('\u22C5', "⋅").addEscape('\u2308', "⌈").addEscape('\u2309', "⌉") .addEscape('\u230A', "⌊").addEscape('\u230B', "⌋").addEscape('\u2329', "⟨") .addEscape('\u232A', "⟩").addEscape('\u25CA', "◊").addEscape('\u2660', "♠") .addEscape('\u2663', "♣").addEscape('\u2665', "♥").addEscape('\u2666', "♦") .toArray()); } /** * Returns a {@link CharEscaper} instance that escapes special characters in a * string so it can safely be included in an HTML document in either element * content or attribute values. * * <p><b>Note</b></p>: does not alter non-ASCII and control characters. */ public static CharEscaper asciiHtmlEscaper() { return ASCII_HTML_ESCAPER; } /** * Escapes special characters from a string so it can safely be included in an * HTML document in either element content or attribute values. Does * <em>not</em> alter non-ASCII characters or control characters. */ private static final CharEscaper ASCII_HTML_ESCAPER = new CharEscaperBuilder().addEscape('"', """) .addEscape('\'', "'").addEscape('&', "&").addEscape('<', "<").addEscape('>', ">") .toEscaper(); /** * Returns an {@link Escaper} instance that escapes Java chars so they can be * safely included in URIs. For details on escaping URIs, see section 2.4 of * <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a>. * * <p>When encoding a String, the following rules apply: * <ul> * <li>The alphanumeric characters "a" through "z", "A" through "Z" and "0" * through "9" remain the same. * <li>The special characters ".", "-", "*", and "_" remain the same. * <li>The space character " " is converted into a plus sign "+". * <li>All other characters are converted into one or more bytes using UTF-8 * encoding and each byte is then represented by the 3-character string * "%XY", where "XY" is the two-digit, uppercase, hexadecimal * representation of the byte value. * <ul> * * <p><b>Note</b>: Unlike other escapers, URI escapers produce uppercase * hexidecimal sequences. From <a href="http://www.ietf.org/rfc/rfc3986.txt"> * RFC 3986</a>:<br> * <i>"URI producers and normalizers should use uppercase hexadecimal digits * for all percent-encodings."</i> * * <p>This escaper has identical behavior to (but is potentially much faster * than): * <ul> * <li>{@link com.google.gdata.util.httputil.FastURLEncoder#encode(String)} * <li>{@link com.google.gdata.util.httputil.FastURLEncoder#encode(String,String)} * with the encoding name "UTF-8" * <li>{@link com.google.gdata.util.common.net.UriEncoder#encode(String)} * <li>{@link com.google.gdata.util.common.net.UriEncoder#encode(String,java.nio.charset.Charset)} * with the UTF_8 Charset * <li>{@link java.net.URLEncoder#encode(String, String)} * with the encoding name "UTF-8" * </ul> * * <p>This method is equivalent to {@code uriEscaper(true)}. */ public static Escaper uriEscaper() { return uriEscaper(true); } /** * Returns an {@link Escaper} instance that escapes Java chars so they can be * safely included in URI path segments. For details on escaping URIs, see * section 2.4 of <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>. * * <p>When encoding a String, the following rules apply: * <ul> * <li>The alphanumeric characters "a" through "z", "A" through "Z" and "0" * through "9" remain the same. * <li>The unreserved characters ".", "-", "~", and "_" remain the same. * <li>The general delimiters "@" and ":" remain the same. * <li>The subdelimiters "!", "$", "&", "'", "(", ")", "*", ",", ";", * and "=" remain the same. * <li>The space character " " is converted into %20. * <li>All other characters are converted into one or more bytes using UTF-8 * encoding and each byte is then represented by the 3-character string * "%XY", where "XY" is the two-digit, uppercase, hexadecimal * representation of the byte value. * </ul> * * <p><b>Note</b>: Unlike other escapers, URI escapers produce uppercase * hexidecimal sequences. From <a href="http://www.ietf.org/rfc/rfc3986.txt"> * RFC 3986</a>:<br> * <i>"URI producers and normalizers should use uppercase hexadecimal digits * for all percent-encodings."</i> */ public static Escaper uriPathEscaper() { return URI_PATH_ESCAPER; } /** * Returns an {@link Escaper} instance that escapes Java chars so they can be * safely included in URI query string segments. When the query string * consists of a sequence of name=value pairs separated by &, the names * and values should be individually encoded. If you escape an entire query * string in one pass with this escaper, then the "=" and "&" characters * used as separators will also be escaped. * * <p>This escaper is also suitable for escaping fragment identifiers. * * <p>For details on escaping URIs, see * section 2.4 of <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>. * * <p>When encoding a String, the following rules apply: * <ul> * <li>The alphanumeric characters "a" through "z", "A" through "Z" and "0" * through "9" remain the same. * <li>The unreserved characters ".", "-", "~", and "_" remain the same. * <li>The general delimiters "@" and ":" remain the same. * <li>The path delimiters "/" and "?" remain the same. * <li>The subdelimiters "!", "$", "'", "(", ")", "*", ",", and ";", * remain the same. * <li>The space character " " is converted into %20. * <li>The equals sign "=" is converted into %3D. * <li>The ampersand "&" is converted into %26. * <li>All other characters are converted into one or more bytes using UTF-8 * encoding and each byte is then represented by the 3-character string * "%XY", where "XY" is the two-digit, uppercase, hexadecimal * representation of the byte value. * </ul> * * <p><b>Note</b>: Unlike other escapers, URI escapers produce uppercase * hexidecimal sequences. From <a href="http://www.ietf.org/rfc/rfc3986.txt"> * RFC 3986</a>:<br> * <i>"URI producers and normalizers should use uppercase hexadecimal digits * for all percent-encodings."</i> */ public static Escaper uriQueryStringEscaper() { return URI_QUERY_STRING_ESCAPER; } /** * Returns a {@link Escaper} instance that escapes Java characters so they can * be safely included in URIs. For details on escaping URIs, see section 2.4 * of <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a>. * * <p>When encoding a String, the following rules apply: * <ul> * <li>The alphanumeric characters "a" through "z", "A" through "Z" and "0" * through "9" remain the same. * <li>The special characters ".", "-", "*", and "_" remain the same. * <li>If {@code plusForSpace} was specified, the space character " " is * converted into a plus sign "+". Otherwise it is converted into "%20". * <li>All other characters are converted into one or more bytes using UTF-8 * encoding and each byte is then represented by the 3-character string * "%XY", where "XY" is the two-digit, uppercase, hexadecimal * representation of the byte value. * </ul> * * <p><b>Note</b>: Unlike other escapers, URI escapers produce uppercase * hexidecimal sequences. From <a href="http://www.ietf.org/rfc/rfc3986.txt"> * RFC 3986</a>:<br> * <i>"URI producers and normalizers should use uppercase hexadecimal digits * for all percent-encodings."</i> * * @param plusForSpace if {@code true} space is escaped to {@code +} otherwise * it is escaped to {@code %20}. Although common, the escaping of * spaces as plus signs has a very ambiguous status in the relevant * specifications. You should prefer {@code %20} unless you are doing * exact character-by-character comparisons of URLs and backwards * compatibility requires you to use plus signs. * * @see #uriEscaper() */ public static Escaper uriEscaper(boolean plusForSpace) { return plusForSpace ? URI_ESCAPER : URI_ESCAPER_NO_PLUS; } private static final Escaper URI_ESCAPER = new PercentEscaper(PercentEscaper.SAFECHARS_URLENCODER, true); private static final Escaper URI_ESCAPER_NO_PLUS = new PercentEscaper(PercentEscaper.SAFECHARS_URLENCODER, false); private static final Escaper URI_PATH_ESCAPER = new PercentEscaper(PercentEscaper.SAFEPATHCHARS_URLENCODER, false); private static final Escaper URI_QUERY_STRING_ESCAPER = new PercentEscaper( PercentEscaper.SAFEQUERYSTRINGCHARS_URLENCODER, false); /** * Returns a {@link Escaper} instance that escapes Java characters in a manner * compatible with the C++ webutil/url URL class (the {@code kGoogle1Escape} * set). * * <p>When encoding a String, the following rules apply: * <ul> * <li>The alphanumeric characters "a" through "z", "A" through "Z" and "0" * through "9" remain the same. * <li>The special characters "!", "(", ")", "*", "-", ".", "_", "~", ",", "/" * and ":" remain the same. * <li>The space character " " is converted into a plus sign "+". * <li>All other characters are converted into one or more bytes using UTF-8 * encoding and each byte is then represented by the 3-character string * "%XY", where "XY" is the two-digit, uppercase, hexadecimal * representation of the byte value. * </ul> * * <p><b>Note</b>: Unlike other escapers, URI escapers produce uppercase * hexidecimal sequences. From <a href="http://www.ietf.org/rfc/rfc3986.txt"> * RFC 3986</a>:<br> * <i>"URI producers and normalizers should use uppercase hexadecimal digits * for all percent-encodings."</i> * * <p><b>Note</b>: This escaper is a special case and is <em>not * compliant</em> with <a href="http://www.ietf.org/rfc/rfc2396.txt"> * RFC 2396</a>. Specifically it will not escape "/", ":" and ",". This is * only provided for certain limited use cases and you should favor using * {@link #uriEscaper()} whenever possible. */ public static Escaper cppUriEscaper() { return CPP_URI_ESCAPER; } // Based on comments from FastURLEncoder: // These octets mimic the ones escaped by the C++ webutil/url URL class -- // the kGoogle1Escape set. // To produce the same escaping as C++, use this set with the plusForSpace // option. // WARNING: Contrary to RFC 2396 ",", "/" and ":" are listed as safe here. private static final Escaper CPP_URI_ESCAPER = new PercentEscaper("!()*-._~,/:", true); /** * Returns a {@link CharEscaper} instance that escapes special characters in a * string so it can safely be included in a Java string literal. * * <p><b>Note</b></p>: does not escape single quotes, so use the escaper * returned by {@link #javaCharEscaper()} if you are generating char * literals or if you are unsure. */ public static CharEscaper javaStringEscaper() { return JAVA_STRING_ESCAPER; } /** * Escapes special characters from a string so it can safely be included in a * Java string literal. Does <em>not</em> escape single-quotes, so use * JAVA_CHAR_ESCAPE if you are generating char literals, or if you are unsure. * * <p>Note that non-ASCII characters will be octal or Unicode escaped. */ private static final CharEscaper JAVA_STRING_ESCAPER = new JavaCharEscaper(new CharEscaperBuilder() .addEscape('\b', "\\b").addEscape('\f', "\\f").addEscape('\n', "\\n").addEscape('\r', "\\r") .addEscape('\t', "\\t").addEscape('\"', "\\\"").addEscape('\\', "\\\\").toArray()); /** * Returns a {@link CharEscaper} instance that escapes special characters in a * string so it can safely be included in a Java char or string literal. The * behavior of this escaper is the same as that of the * {@link #javaStringEscaper()}, except it also escapes single quotes. */ public static CharEscaper javaCharEscaper() { return JAVA_CHAR_ESCAPER; } /** * Escapes special characters from a string so it can safely be included in a * Java char literal or string literal. * * <p>Note that non-ASCII characters will be octal or Unicode escaped. * * <p>This is the same as {@link #JAVA_STRING_ESCAPER}, except that it escapes * single quotes. */ private static final CharEscaper JAVA_CHAR_ESCAPER = new JavaCharEscaper( new CharEscaperBuilder().addEscape('\b', "\\b").addEscape('\f', "\\f").addEscape('\n', "\\n") .addEscape('\r', "\\r").addEscape('\t', "\\t").addEscape('\'', "\\'").addEscape('\"', "\\\"") .addEscape('\\', "\\\\").toArray()); /** * Returns a {@link CharEscaper} instance that replaces non-ASCII characters * in a string with their Unicode escape sequences ({@code \\uxxxx} where * {@code xxxx} is a hex number). Existing escape sequences won't be affected. */ public static CharEscaper javaStringUnicodeEscaper() { return JAVA_STRING_UNICODE_ESCAPER; } /** * Escapes each non-ASCII character in with its Unicode escape sequence * {@code \\uxxxx} where {@code xxxx} is a hex number. Existing escape * sequences won't be affected. */ private static final CharEscaper JAVA_STRING_UNICODE_ESCAPER = new CharEscaper() { @Override protected char[] escape(char c) { if (c <= 127) { return null; } char[] r = new char[6]; r[5] = HEX_DIGITS[c & 15]; c >>>= 4; r[4] = HEX_DIGITS[c & 15]; c >>>= 4; r[3] = HEX_DIGITS[c & 15]; c >>>= 4; r[2] = HEX_DIGITS[c & 15]; r[1] = 'u'; r[0] = '\\'; return r; } }; /** * Returns a {@link CharEscaper} instance that escapes special characters from * a string so it can safely be included in a Python string literal. Does not * have any special handling for non-ASCII characters. */ public static CharEscaper pythonEscaper() { return PYTHON_ESCAPER; } /** * Escapes special characters in a string so it can safely be included in a * Python string literal. Does not have any special handling for non-ASCII * characters. */ private static final CharEscaper PYTHON_ESCAPER = new CharEscaperBuilder().addEscape('\n', "\\n") .addEscape('\r', "\\r").addEscape('\t', "\\t").addEscape('\\', "\\\\").addEscape('\"', "\\\"") .addEscape('\'', "\\\'").toEscaper(); /** * Returns a {@link CharEscaper} instance that escapes non-ASCII characters in * a string so it can safely be included in a Javascript string literal. * Non-ASCII characters are replaced with their ASCII javascript escape * sequences (e.g., \\uhhhh or \xhh). */ public static CharEscaper javascriptEscaper() { return JAVASCRIPT_ESCAPER; } /** * {@code CharEscaper} to escape javascript strings. Turns all non-ASCII * characters into ASCII javascript escape sequences (e.g., \\uhhhh or \xhh). */ private static final CharEscaper JAVASCRIPT_ESCAPER = new JavascriptCharEscaper( new CharEscaperBuilder().addEscape('\'', "\\x27").addEscape('"', "\\x22").addEscape('<', "\\x3c") .addEscape('=', "\\x3d").addEscape('>', "\\x3e").addEscape('&', "\\x26").addEscape('\b', "\\b") .addEscape('\t', "\\t").addEscape('\n', "\\n").addEscape('\f', "\\f").addEscape('\r', "\\r") .addEscape('\\', "\\\\").toArray()); private static CharEscaperBuilder newBasicXmlEscapeBuilder() { return new CharEscaperBuilder().addEscape('&', "&").addEscape('<', "<").addEscape('>', ">") .addEscapes(new char[] { '\000', '\001', '\002', '\003', '\004', '\005', '\006', '\007', '\010', '\013', '\014', '\016', '\017', '\020', '\021', '\022', '\023', '\024', '\025', '\026', '\027', '\030', '\031', '\032', '\033', '\034', '\035', '\036', '\037' }, ""); } /** * Returns a composite {@link CharEscaper} instance that tries to escape * characters using a primary {@code CharEscaper} first and falls back to a * secondary one if there is no escaping. * * <p>The returned escaper will attempt to escape each character using the * primary escaper, and if the primary escaper has no escaping for that * character, it will use the secondary escaper. If the secondary escaper has * no escaping for a character either, the original character will be used. * If the primary escaper has an escape for a character, the secondary escaper * will not be used at all for that character; the escaped output of the * primary is not run through the secondary. For a case where you would like * to first escape with one escaper, and then with another, it is recommended * that you call each escaper in order. * * @param primary The primary {@code CharEscaper} to use * @param secondary The secondary {@code CharEscaper} to use if the first one * has no escaping rule for a character * @throws NullPointerException if any of the arguments is null */ public static CharEscaper fallThrough(CharEscaper primary, CharEscaper secondary) { checkNotNull(primary); checkNotNull(secondary); return new FallThroughCharEscaper(primary, secondary); } /** * A fast {@link CharEscaper} that uses an array of replacement characters and * a range of safe characters. It overrides {@link #escape(String)} to improve * performance. Rough benchmarking shows that this almost doubles the speed * when processing strings that do not require escaping (providing the escape * test itself is efficient). */ private static abstract class FastCharEscaper extends CharEscaper { protected final char[][] replacements; protected final int replacementLength; protected final char safeMin; protected final char safeMax; public FastCharEscaper(char[][] replacements, char safeMin, char safeMax) { this.replacements = replacements; this.replacementLength = replacements.length; this.safeMin = safeMin; this.safeMax = safeMax; } /** Overridden for performance (see {@link FastCharEscaper}). */ @Override public String escape(String s) { int slen = s.length(); for (int index = 0; index < slen; index++) { char c = s.charAt(index); if ((c < replacementLength && replacements[c] != null) || c < safeMin || c > safeMax) { return escapeSlow(s, index); } } return s; } } /** * Escaper for Java character escaping, contains both an array and a * backup function. We're not overriding the array decorator because we * want to keep this as fast as possible, so no calls to super.escape first. */ private static class JavaCharEscaper extends FastCharEscaper { public JavaCharEscaper(char[][] replacements) { super(replacements, ' ', '~'); } @Override protected char[] escape(char c) { // First check if our array has a valid escaping. if (c < replacementLength) { char[] r = replacements[c]; if (r != null) { return r; } } // This range is un-escaped. if (safeMin <= c && c <= safeMax) { return null; } if (c <= 0xFF) { // Convert c to an octal-escaped string. // Equivalent to String.format("\\%03o", (int)c); char[] r = new char[4]; r[0] = '\\'; r[3] = HEX_DIGITS[c & 7]; c >>>= 3; r[2] = HEX_DIGITS[c & 7]; c >>>= 3; r[1] = HEX_DIGITS[c & 7]; return r; } // Convert c to a hex-escaped string. // Equivalent to String.format("\\u%04x", (int)c); char[] r = new char[6]; r[0] = '\\'; r[1] = 'u'; r[5] = HEX_DIGITS[c & 15]; c >>>= 4; r[4] = HEX_DIGITS[c & 15]; c >>>= 4; r[3] = HEX_DIGITS[c & 15]; c >>>= 4; r[2] = HEX_DIGITS[c & 15]; return r; } } /** * Escaper for javascript character escaping, contains both an array and a * backup function. We're not overriding the array decorator because we * want to keep this as fast as possible, so no calls to super.escape first. */ private static class JavascriptCharEscaper extends FastCharEscaper { public JavascriptCharEscaper(char[][] replacements) { super(replacements, ' ', '~'); } @Override protected char[] escape(char c) { // First check if our array has a valid escaping. if (c < replacementLength) { char[] r = replacements[c]; if (r != null) { return r; } } // This range is unescaped. if (safeMin <= c && c <= safeMax) { return null; } // we can do a 2 digit hex escape for chars less that 0x100 if (c < 0x100) { char[] r = new char[4]; r[3] = HEX_DIGITS[c & 0xf]; c >>>= 4; r[2] = HEX_DIGITS[c & 0xf]; r[1] = 'x'; r[0] = '\\'; return r; } // 4 digit hex escape everything else char[] r = new char[6]; r[5] = HEX_DIGITS[c & 0xf]; c >>>= 4; r[4] = HEX_DIGITS[c & 0xf]; c >>>= 4; r[3] = HEX_DIGITS[c & 0xf]; c >>>= 4; r[2] = HEX_DIGITS[c & 0xf]; r[1] = 'u'; r[0] = '\\'; return r; } } /** * Escaper for HTML character escaping, contains both an array and a * backup function. We're not overriding the array decorator because we * want to keep this as fast as possible, so no calls to super.escape first. */ private static class HtmlCharEscaper extends FastCharEscaper { public HtmlCharEscaper(char[][] replacements) { super(replacements, Character.MIN_VALUE, '~'); } @Override protected char[] escape(char c) { // First check if our array has a valid escaping. if (c < replacementLength) { char[] r = replacements[c]; if (r != null) { return r; } } // ~ is ASCII 126, the highest value char that does not need // to be escaped if (c <= safeMax) { return null; } int index; if (c < 1000) { index = 4; } else if (c < 10000) { index = 5; } else { index = 6; } char[] result = new char[index + 2]; result[0] = '&'; result[1] = '#'; result[index + 1] = ';'; // to avoid the division and modulo operators. int intValue = c; for (; index > 1; index--) { result[index] = HEX_DIGITS[intValue % 10]; intValue /= 10; } return result; } } /** * A composite {@code CharEscaper} object that tries to escape characters * using a primary {@code CharEscaper} first and falls back to a secondary * one if there is no escaping. */ private static class FallThroughCharEscaper extends CharEscaper { private final CharEscaper primary; private final CharEscaper secondary; public FallThroughCharEscaper(CharEscaper primary, CharEscaper secondary) { this.primary = primary; this.secondary = secondary; } @Override protected char[] escape(char c) { char result[] = primary.escape(c); if (result == null) { result = secondary.escape(c); } return result; } } private static final char[] HEX_DIGITS = "0123456789abcdef".toCharArray(); }