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
029 * href="https://www.w3.org/TR/html4/types.html#h-6.2">some elements' text contents must not be HTML
030 * escaped</a>. As a result, it is impossible to escape an HTML document correctly without
031 * domain-specific knowledge beyond what {@code HtmlEscapers} provides. We strongly encourage the
032 * use of HTML templating systems.
033 *
034 * @author Sven Mawson
035 * @author David Beaumont
036 * @since 15.0
037 */
038@GwtCompatible
039@ElementTypesAreNonnullByDefault
040public final class HtmlEscapers {
041  /**
042   * Returns an {@link Escaper} instance that escapes HTML metacharacters as specified by <a
043   * href="http://www.w3.org/TR/html4/">HTML 4.01</a>. The resulting strings can be used both in
044   * attribute values and in <em>most</em> elements' text contents, provided that the HTML
045   * document's character encoding can encode any non-ASCII code points in the input (as UTF-8 and
046   * other Unicode encodings can).
047   *
048   * <p><b>Note:</b> This escaper only performs minimal escaping to make content structurally
049   * compatible with HTML. Specifically, it does not perform entity replacement (symbolic or
050   * numeric), so it does not replace non-ASCII code points with character references. This escaper
051   * escapes only the following five ASCII characters: {@code '"&<>}.
052   */
053  public static Escaper htmlEscaper() {
054    return HTML_ESCAPER;
055  }
056
057  // For each xxxEscaper() method, please add links to external reference pages
058  // that are considered authoritative for the behavior of that escaper.
059
060  private static final Escaper HTML_ESCAPER =
061      Escapers.builder()
062          .addEscape('"', "&quot;")
063          // Note: "&apos;" is not defined in HTML 4.01.
064          .addEscape('\'', "&#39;")
065          .addEscape('&', "&amp;")
066          .addEscape('<', "&lt;")
067          .addEscape('>', "&gt;")
068          .build();
069
070  private HtmlEscapers() {}
071}