001package io.jstach.jstachio.escapers;
002
003import java.nio.charset.StandardCharsets;
004
005import io.jstach.jstache.JStacheConfig;
006import io.jstach.jstache.JStacheContentType;
007import io.jstach.jstachio.Escaper;
008
009/**
010 * Provides a mustache spec based HTML escaper which is the default in normal mustache.
011 * <p>
012 * The escaper simply escapes:
013 * <table border="1">
014 * <caption><strong>Escape table</strong></caption>
015 * <tr>
016 * <th>Character</th>
017 * <th>Escaped String</th>
018 * </tr>
019 * <tr>
020 * <td>'<code>&quot;</code>'</td>
021 * <td>{@value HtmlEscaper#QUOT}</td>
022 * </tr>
023 * <tr>
024 * <td>'<code>&amp;</code>'</td>
025 * <td>{@value HtmlEscaper#AMP}</td>
026 * </tr>
027 * <tr>
028 * <td>'<code>&#x27;</code>'</td>
029 * <td>{@value HtmlEscaper#APOS}</td>
030 * </tr>
031 * <tr>
032 * <td>'<code>&lt;</code>'</td>
033 * <td>{@value HtmlEscaper#LT}</td>
034 * </tr>
035 * <tr>
036 * <td>'<code>=</code>'</td>
037 * <td>{@value HtmlEscaper#EQUAL}</td>
038 * </tr>
039 * <tr>
040 * <td>'<code>&gt;</code>'</td>
041 * <td>{@value HtmlEscaper#GT}</td>
042 * </tr>
043 * <tr>
044 * <td>'<code>&#x60;</code>'</td>
045 * <td>{@value HtmlEscaper#BACK_TICK}</td>
046 * </tr>
047 * </table>
048 * <br />
049 * <em>N.B. Unlike many XML escapers this escaper does not differentiate attribute and
050 * element content. Furthermore Mustache unlike many other templating languages is content
051 * agnostic. If more flexibile attribute escaping is needed a custom lambda could be used
052 * to preserve the whitespace in attributes. </em>
053 * <p>
054 * <strong>This escaper assumes UTF-8 which is the predominate encoding of HTML these days
055 * and thus will not encode characters other then the ones mentioned above. </strong> Thus
056 * if you intend escape for example {@link StandardCharsets#US_ASCII} a different HTML
057 * escaper should be used to properly escape non ascii characters as HTML entities.
058 *
059 * @author agentgt
060 * @author Victor Nazarov
061 * @see JStacheConfig#contentType()
062 */
063@JStacheContentType(mediaType = "text/html", charsets = { "UTF-8" })
064public final class Html {
065
066        private Html() {
067        }
068
069        /**
070         * Provides the escaper.
071         * @return HTML escaper.
072         */
073        public static Escaper provider() {
074                return HtmlEscaper.HTML5;
075        }
076
077        /**
078         * Provides the escaper.
079         * @return HTML escaper.
080         */
081        public static Escaper of() {
082                return HtmlEscaper.HTML5;
083        }
084
085}