View Javadoc
1   /*
2    * Copyright (C) 2008 The Guava Authors
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5    * in compliance with the License. You may obtain a copy of the License at
6    *
7    * http://www.apache.org/licenses/LICENSE-2.0
8    *
9    * Unless required by applicable law or agreed to in writing, software distributed under the License
10   * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11   * or implied. See the License for the specific language governing permissions and limitations under
12   * the License.
13   */
14  
15  package com.google.common.escape;
16  
17  import static com.google.common.base.Preconditions.checkNotNull;
18  
19  import com.google.common.annotations.Beta;
20  import com.google.common.annotations.GwtCompatible;
21  
22  /**
23   * An {@link Escaper} that converts literal text into a format safe for inclusion in a particular
24   * context (such as an XML document). Typically (but not always), the inverse process of
25   * "unescaping" the text is performed automatically by the relevant parser.
26   *
27   * <p>For example, an XML escaper would convert the literal string {@code
28   * "Foo<Bar>"} into {@code "Foo&lt;Bar&gt;"} to prevent {@code "<Bar>"} from being confused with an
29   * XML tag. When the resulting XML document is parsed, the parser API will return this text as the
30   * original literal string {@code
31   * "Foo<Bar>"}.
32   *
33   * <p><b>Note:</b> This class is similar to {@link CharEscaper} but with one very important
34   * difference. A CharEscaper can only process Java
35   * <a href="http://en.wikipedia.org/wiki/UTF-16">UTF16</a> characters in isolation and may not cope
36   * when it encounters surrogate pairs. This class facilitates the correct escaping of all Unicode
37   * characters.
38   *
39   * <p>As there are important reasons, including potential security issues, to handle Unicode
40   * correctly if you are considering implementing a new escaper you should favor using UnicodeEscaper
41   * wherever possible.
42   *
43   * <p>A {@code UnicodeEscaper} instance is required to be stateless, and safe when used concurrently
44   * by multiple threads.
45   *
46   * <p>Popular escapers are defined as constants in classes like
47   * {@link com.google.common.html.HtmlEscapers} and {@link com.google.common.xml.XmlEscapers}. To
48   * create your own escapers extend this class and implement the {@link #escape(int)} method.
49   *
50   * @author David Beaumont
51   * @since 15.0
52   */
53  @Beta
54  @GwtCompatible
55  public abstract class UnicodeEscaper extends Escaper {
56    /** The amount of padding (chars) to use when growing the escape buffer. */
57    private static final int DEST_PAD = 32;
58  
59    /** Constructor for use by subclasses. */
60    protected UnicodeEscaper() {}
61  
62    /**
63     * Returns the escaped form of the given Unicode code point, or {@code null} if this code point
64     * does not need to be escaped. When called as part of an escaping operation, the given code point
65     * is guaranteed to be in the range {@code 0 <= cp <= Character#MAX_CODE_POINT}.
66     *
67     * <p>If an empty array is returned, this effectively strips the input character from the
68     * resulting text.
69     *
70     * <p>If the character does not need to be escaped, this method should return {@code null}, rather
71     * than an array containing the character representation of the code point. This enables the
72     * escaping algorithm to perform more efficiently.
73     *
74     * <p>If the implementation of this method cannot correctly handle a particular code point then it
75     * should either throw an appropriate runtime exception or return a suitable replacement
76     * character. It must never silently discard invalid input as this may constitute a security risk.
77     *
78     * @param cp the Unicode code point to escape if necessary
79     * @return the replacement characters, or {@code null} if no escaping was needed
80     */
81    protected abstract char[] escape(int cp);
82  
83    /**
84     * Scans a sub-sequence of characters from a given {@link CharSequence}, returning the index of
85     * the next character that requires escaping.
86     *
87     * <p><b>Note:</b> When implementing an escaper, it is a good idea to override this method for
88     * efficiency. The base class implementation determines successive Unicode code points and invokes
89     * {@link #escape(int)} for each of them. If the semantics of your escaper are such that code
90     * points in the supplementary range are either all escaped or all unescaped, this method can be
91     * implemented more efficiently using {@link CharSequence#charAt(int)}.
92     *
93     * <p>Note however that if your escaper does not escape characters in the supplementary range, you
94     * should either continue to validate the correctness of any surrogate characters encountered or
95     * provide a clear warning to users that your escaper does not validate its input.
96     *
97     * <p>See {@link com.google.common.net.PercentEscaper} for an example.
98     *
99     * @param csq a sequence of characters
100    * @param start the index of the first character to be scanned
101    * @param end the index immediately after the last character to be scanned
102    * @throws IllegalArgumentException if the scanned sub-sequence of {@code csq} contains invalid
103    *     surrogate pairs
104    */
105   protected int nextEscapeIndex(CharSequence csq, int start, int end) {
106     int index = start;
107     while (index < end) {
108       int cp = codePointAt(csq, index, end);
109       if (cp < 0 || escape(cp) != null) {
110         break;
111       }
112       index += Character.isSupplementaryCodePoint(cp) ? 2 : 1;
113     }
114     return index;
115   }
116 
117   /**
118    * Returns the escaped form of a given literal string.
119    *
120    * <p>If you are escaping input in arbitrary successive chunks, then it is not generally safe to
121    * use this method. If an input string ends with an unmatched high surrogate character, then this
122    * method will throw {@link IllegalArgumentException}. You should ensure your input is valid
123    * <a href="http://en.wikipedia.org/wiki/UTF-16">UTF-16</a> before calling this method.
124    *
125    * <p><b>Note:</b> When implementing an escaper it is a good idea to override this method for
126    * efficiency by inlining the implementation of {@link #nextEscapeIndex(CharSequence, int, int)}
127    * directly. Doing this for {@link com.google.common.net.PercentEscaper} more than doubled the
128    * performance for unescaped strings (as measured by {@link CharEscapersBenchmark}).
129    *
130    * @param string the literal string to be escaped
131    * @return the escaped form of {@code string}
132    * @throws NullPointerException if {@code string} is null
133    * @throws IllegalArgumentException if invalid surrogate characters are encountered
134    */
135   @Override
136   public String escape(String string) {
137     checkNotNull(string);
138     int end = string.length();
139     int index = nextEscapeIndex(string, 0, end);
140     return index == end ? string : escapeSlow(string, index);
141   }
142 
143   /**
144    * Returns the escaped form of a given literal string, starting at the given index. This method is
145    * called by the {@link #escape(String)} method when it discovers that escaping is required. It is
146    * protected to allow subclasses to override the fastpath escaping function to inline their
147    * escaping test. See {@link CharEscaperBuilder} for an example usage.
148    *
149    * <p>This method is not reentrant and may only be invoked by the top level
150    * {@link #escape(String)} method.
151    *
152    * @param s the literal string to be escaped
153    * @param index the index to start escaping from
154    * @return the escaped form of {@code string}
155    * @throws NullPointerException if {@code string} is null
156    * @throws IllegalArgumentException if invalid surrogate characters are encountered
157    */
158   protected final String escapeSlow(String s, int index) {
159     int end = s.length();
160 
161     // Get a destination buffer and setup some loop variables.
162     char[] dest = Platform.charBufferFromThreadLocal();
163     int destIndex = 0;
164     int unescapedChunkStart = 0;
165 
166     while (index < end) {
167       int cp = codePointAt(s, index, end);
168       if (cp < 0) {
169         throw new IllegalArgumentException("Trailing high surrogate at end of input");
170       }
171       // It is possible for this to return null because nextEscapeIndex() may
172       // (for performance reasons) yield some false positives but it must never
173       // give false negatives.
174       char[] escaped = escape(cp);
175       int nextIndex = index + (Character.isSupplementaryCodePoint(cp) ? 2 : 1);
176       if (escaped != null) {
177         int charsSkipped = index - unescapedChunkStart;
178 
179         // This is the size needed to add the replacement, not the full
180         // size needed by the string. We only regrow when we absolutely must.
181         int sizeNeeded = destIndex + charsSkipped + escaped.length;
182         if (dest.length < sizeNeeded) {
183           int destLength = sizeNeeded + (end - index) + DEST_PAD;
184           dest = growBuffer(dest, destIndex, destLength);
185         }
186         // If we have skipped any characters, we need to copy them now.
187         if (charsSkipped > 0) {
188           s.getChars(unescapedChunkStart, index, dest, destIndex);
189           destIndex += charsSkipped;
190         }
191         if (escaped.length > 0) {
192           System.arraycopy(escaped, 0, dest, destIndex, escaped.length);
193           destIndex += escaped.length;
194         }
195         // If we dealt with an escaped character, reset the unescaped range.
196         unescapedChunkStart = nextIndex;
197       }
198       index = nextEscapeIndex(s, nextIndex, end);
199     }
200 
201     // Process trailing unescaped characters - no need to account for escaped
202     // length or padding the allocation.
203     int charsSkipped = end - unescapedChunkStart;
204     if (charsSkipped > 0) {
205       int endIndex = destIndex + charsSkipped;
206       if (dest.length < endIndex) {
207         dest = growBuffer(dest, destIndex, endIndex);
208       }
209       s.getChars(unescapedChunkStart, end, dest, destIndex);
210       destIndex = endIndex;
211     }
212     return new String(dest, 0, destIndex);
213   }
214 
215   /**
216    * Returns the Unicode code point of the character at the given index.
217    *
218    * <p>Unlike {@link Character#codePointAt(CharSequence, int)} or {@link String#codePointAt(int)}
219    * this method will never fail silently when encountering an invalid surrogate pair.
220    *
221    * <p>The behaviour of this method is as follows:
222    * <ol>
223    * <li>If {@code index >= end}, {@link IndexOutOfBoundsException} is thrown.
224    * <li><b>If the character at the specified index is not a surrogate, it is returned.</b>
225    * <li>If the first character was a high surrogate value, then an attempt is made to read the next
226    *     character.
227    *     <ol>
228    *     <li><b>If the end of the sequence was reached, the negated value of the trailing high
229    *         surrogate is returned.</b>
230    *     <li><b>If the next character was a valid low surrogate, the code point value of the
231    *         high/low surrogate pair is returned.</b>
232    *     <li>If the next character was not a low surrogate value, then {@link
233    *         IllegalArgumentException} is thrown.
234    *     </ol>
235    * <li>If the first character was a low surrogate value, {@link IllegalArgumentException} is
236    *     thrown.
237    * </ol>
238    *
239    * @param seq the sequence of characters from which to decode the code point
240    * @param index the index of the first character to decode
241    * @param end the index beyond the last valid character to decode
242    * @return the Unicode code point for the given index or the negated value of the trailing high
243    *     surrogate character at the end of the sequence
244    */
245   protected static int codePointAt(CharSequence seq, int index, int end) {
246     checkNotNull(seq);
247     if (index < end) {
248       char c1 = seq.charAt(index++);
249       if (c1 < Character.MIN_HIGH_SURROGATE || c1 > Character.MAX_LOW_SURROGATE) {
250         // Fast path (first test is probably all we need to do)
251         return c1;
252       } else if (c1 <= Character.MAX_HIGH_SURROGATE) {
253         // If the high surrogate was the last character, return its inverse
254         if (index == end) {
255           return -c1;
256         }
257         // Otherwise look for the low surrogate following it
258         char c2 = seq.charAt(index);
259         if (Character.isLowSurrogate(c2)) {
260           return Character.toCodePoint(c1, c2);
261         }
262         throw new IllegalArgumentException(
263             "Expected low surrogate but got char '"
264                 + c2
265                 + "' with value "
266                 + (int) c2
267                 + " at index "
268                 + index
269                 + " in '"
270                 + seq
271                 + "'");
272       } else {
273         throw new IllegalArgumentException(
274             "Unexpected low surrogate character '"
275                 + c1
276                 + "' with value "
277                 + (int) c1
278                 + " at index "
279                 + (index - 1)
280                 + " in '"
281                 + seq
282                 + "'");
283       }
284     }
285     throw new IndexOutOfBoundsException("Index exceeds specified range");
286   }
287 
288   /**
289    * Helper method to grow the character buffer as needed, this only happens once in a while so it's
290    * ok if it's in a method call. If the index passed in is 0 then no copying will be done.
291    */
292   private static char[] growBuffer(char[] dest, int index, int size) {
293     if (size < 0) { // overflow - should be OutOfMemoryError but GWT/j2cl don't support it
294       throw new AssertionError("Cannot increase internal buffer any further");
295     }
296     char[] copy = new char[size];
297     if (index > 0) {
298       System.arraycopy(dest, 0, copy, 0, index);
299     }
300     return copy;
301   }
302 }