Coverage Summary for Class: HtmlEscapers (com.google.common.html)

1 /*
2  * Copyright (C) 2009 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.html;
16 
17 import com.google.common.annotations.GwtCompatible;
18 import com.google.common.escape.Escaper;
19 import com.google.common.escape.Escapers;
20 
21 /**
22  * {@code Escaper} instances suitable for strings to be included in HTML attribute values and
23  * <em>most</em> elements' text contents. When possible, avoid manual escaping by using templating
24  * systems and high-level APIs that provide autoescaping.
25  * One Google-authored templating system available for external use is <a
26  * href="https://developers.google.com/closure/templates/">Closure Templates</a>.
27  *
28  * <p>HTML escaping is particularly tricky: For example, <a href="http://goo.gl/5TgZb">some
29  * elements' text contents must not be HTML escaped</a>. As a result, it is impossible to escape an
30  * HTML document correctly without domain-specific knowledge beyond what {@code HtmlEscapers}
31  * provides. We strongly encourage the use of HTML templating systems.
32  *
33  * @author Sven Mawson
34  * @author David Beaumont
35  * @since 15.0
36  */
37 @GwtCompatible
38 @ElementTypesAreNonnullByDefault
39 public final class HtmlEscapers {
40   /**
41    * Returns an {@link Escaper} instance that escapes HTML metacharacters as specified by <a
42    * href="http://www.w3.org/TR/html4/">HTML 4.01</a>. The resulting strings can be used both in
43    * attribute values and in <em>most</em> elements' text contents, provided that the HTML
44    * document's character encoding can encode any non-ASCII code points in the input (as UTF-8 and
45    * other Unicode encodings can).
46    *
47    * <p><b>Note:</b> This escaper only performs minimal escaping to make content structurally
48    * compatible with HTML. Specifically, it does not perform entity replacement (symbolic or
49    * numeric), so it does not replace non-ASCII code points with character references. This escaper
50    * escapes only the following five ASCII characters: {@code '"&<>}.
51    */
52   public static Escaper htmlEscaper() {
53     return HTML_ESCAPER;
54   }
55 
56   // For each xxxEscaper() method, please add links to external reference pages
57   // that are considered authoritative for the behavior of that escaper.
58 
59   private static final Escaper HTML_ESCAPER =
60       Escapers.builder()
61           .addEscape('"', "&quot;")
62           // Note: "&apos;" is not defined in HTML 4.01.
63           .addEscape('\'', "&#39;")
64           .addEscape('&', "&amp;")
65           .addEscape('<', "&lt;")
66           .addEscape('>', "&gt;")
67           .build();
68 
69   private HtmlEscapers() {}
70 }