001/* 002 * Copyright (C) 2009 The Guava Authors 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except 005 * in compliance with the License. You may obtain a copy of the License at 006 * 007 * http://www.apache.org/licenses/LICENSE-2.0 008 * 009 * Unless required by applicable law or agreed to in writing, software distributed under the License 010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 011 * or implied. See the License for the specific language governing permissions and limitations under 012 * the License. 013 */ 014 015package com.google.common.html; 016 017import com.google.common.annotations.GwtCompatible; 018import com.google.common.escape.Escaper; 019import com.google.common.escape.Escapers; 020 021/** 022 * {@code Escaper} instances suitable for strings to be included in HTML attribute values and 023 * <em>most</em> elements' text contents. When possible, avoid manual escaping by using templating 024 * systems and high-level APIs that provide autoescaping. 025 * One Google-authored templating system available for external use is <a 026 * href="https://developers.google.com/closure/templates/">Closure Templates</a>. 027 * 028 * <p>HTML escaping is particularly tricky: For example, <a href="http://goo.gl/5TgZb">some 029 * elements' text contents must not be HTML escaped</a>. As a result, it is impossible to escape an 030 * HTML document correctly without domain-specific knowledge beyond what {@code HtmlEscapers} 031 * provides. We strongly encourage the use of HTML templating systems. 032 * 033 * @author Sven Mawson 034 * @author David Beaumont 035 * @since 15.0 036 */ 037@GwtCompatible 038@ElementTypesAreNonnullByDefault 039public final class HtmlEscapers { 040 /** 041 * Returns an {@link Escaper} instance that escapes HTML metacharacters as specified by <a 042 * href="http://www.w3.org/TR/html4/">HTML 4.01</a>. The resulting strings can be used both in 043 * attribute values and in <em>most</em> elements' text contents, provided that the HTML 044 * document's character encoding can encode any non-ASCII code points in the input (as UTF-8 and 045 * other Unicode encodings can). 046 * 047 * <p><b>Note:</b> This escaper only performs minimal escaping to make content structurally 048 * compatible with HTML. Specifically, it does not perform entity replacement (symbolic or 049 * numeric), so it does not replace non-ASCII code points with character references. This escaper 050 * escapes only the following five ASCII characters: {@code '"&<>}. 051 */ 052 public static Escaper htmlEscaper() { 053 return HTML_ESCAPER; 054 } 055 056 // For each xxxEscaper() method, please add links to external reference pages 057 // that are considered authoritative for the behavior of that escaper. 058 059 private static final Escaper HTML_ESCAPER = 060 Escapers.builder() 061 .addEscape('"', """) 062 // Note: "'" is not defined in HTML 4.01. 063 .addEscape('\'', "'") 064 .addEscape('&', "&") 065 .addEscape('<', "<") 066 .addEscape('>', ">") 067 .build(); 068 069 private HtmlEscapers() {} 070}