001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.text;
018
019import java.io.IOException;
020import java.io.Writer;
021import java.util.Collections;
022import java.util.HashMap;
023import java.util.Map;
024
025import org.apache.commons.lang3.StringUtils;
026import org.apache.commons.text.translate.AggregateTranslator;
027import org.apache.commons.text.translate.CharSequenceTranslator;
028import org.apache.commons.text.translate.CsvTranslators;
029import org.apache.commons.text.translate.EntityArrays;
030import org.apache.commons.text.translate.JavaUnicodeEscaper;
031import org.apache.commons.text.translate.LookupTranslator;
032import org.apache.commons.text.translate.NumericEntityEscaper;
033import org.apache.commons.text.translate.NumericEntityUnescaper;
034import org.apache.commons.text.translate.OctalUnescaper;
035import org.apache.commons.text.translate.UnicodeUnescaper;
036import org.apache.commons.text.translate.UnicodeUnpairedSurrogateRemover;
037
038/**
039 * <p>
040 * Escapes and unescapes {@code String}s for Java, Java Script, HTML and XML.
041 * </p>
042 *
043 * <p>
044 * #ThreadSafe#
045 * </p>
046 *
047 * <p>
048 * This code has been adapted from Apache Commons Lang 3.5.
049 * </p>
050 *
051 * @since 1.0
052 */
053public class StringEscapeUtils {
054
055    /* ESCAPE TRANSLATORS */
056
057    /**
058     * Translator object for escaping Java.
059     *
060     * While {@link #escapeJava(String)} is the expected method of use, this
061     * object allows the Java escaping functionality to be used
062     * as the foundation for a custom translator.
063     */
064    public static final CharSequenceTranslator ESCAPE_JAVA;
065    static {
066        final Map<CharSequence, CharSequence> escapeJavaMap = new HashMap<>();
067        escapeJavaMap.put("\"", "\\\"");
068        escapeJavaMap.put("\\", "\\\\");
069        ESCAPE_JAVA = new AggregateTranslator(
070                new LookupTranslator(Collections.unmodifiableMap(escapeJavaMap)),
071                new LookupTranslator(EntityArrays.JAVA_CTRL_CHARS_ESCAPE),
072                JavaUnicodeEscaper.outsideOf(32, 0x7f)
073        );
074    }
075
076    /**
077     * Translator object for escaping EcmaScript/JavaScript.
078     *
079     * While {@link #escapeEcmaScript(String)} is the expected method of use, this
080     * object allows the EcmaScript escaping functionality to be used
081     * as the foundation for a custom translator.
082     */
083    public static final CharSequenceTranslator ESCAPE_ECMASCRIPT;
084    static {
085        final Map<CharSequence, CharSequence> escapeEcmaScriptMap = new HashMap<>();
086        escapeEcmaScriptMap.put("'", "\\'");
087        escapeEcmaScriptMap.put("\"", "\\\"");
088        escapeEcmaScriptMap.put("\\", "\\\\");
089        escapeEcmaScriptMap.put("/", "\\/");
090        ESCAPE_ECMASCRIPT = new AggregateTranslator(
091                new LookupTranslator(Collections.unmodifiableMap(escapeEcmaScriptMap)),
092                new LookupTranslator(EntityArrays.JAVA_CTRL_CHARS_ESCAPE),
093                JavaUnicodeEscaper.outsideOf(32, 0x7f)
094        );
095    }
096
097    /**
098     * Translator object for escaping Json.
099     *
100     * While {@link #escapeJson(String)} is the expected method of use, this
101     * object allows the Json escaping functionality to be used
102     * as the foundation for a custom translator.
103     */
104    public static final CharSequenceTranslator ESCAPE_JSON;
105    static {
106        final Map<CharSequence, CharSequence> escapeJsonMap = new HashMap<>();
107        escapeJsonMap.put("\"", "\\\"");
108        escapeJsonMap.put("\\", "\\\\");
109        escapeJsonMap.put("/", "\\/");
110        ESCAPE_JSON = new AggregateTranslator(
111                new LookupTranslator(Collections.unmodifiableMap(escapeJsonMap)),
112                new LookupTranslator(EntityArrays.JAVA_CTRL_CHARS_ESCAPE),
113                JavaUnicodeEscaper.outsideOf(32, 0x7e)
114        );
115    }
116
117    /**
118     * Translator object for escaping XML 1.0.
119     *
120     * While {@link #escapeXml10(String)} is the expected method of use, this
121     * object allows the XML escaping functionality to be used
122     * as the foundation for a custom translator.
123     */
124    public static final CharSequenceTranslator ESCAPE_XML10;
125    static {
126        final Map<CharSequence, CharSequence> escapeXml10Map = new HashMap<>();
127        escapeXml10Map.put("\u0000", StringUtils.EMPTY);
128        escapeXml10Map.put("\u0001", StringUtils.EMPTY);
129        escapeXml10Map.put("\u0002", StringUtils.EMPTY);
130        escapeXml10Map.put("\u0003", StringUtils.EMPTY);
131        escapeXml10Map.put("\u0004", StringUtils.EMPTY);
132        escapeXml10Map.put("\u0005", StringUtils.EMPTY);
133        escapeXml10Map.put("\u0006", StringUtils.EMPTY);
134        escapeXml10Map.put("\u0007", StringUtils.EMPTY);
135        escapeXml10Map.put("\u0008", StringUtils.EMPTY);
136        escapeXml10Map.put("\u000b", StringUtils.EMPTY);
137        escapeXml10Map.put("\u000c", StringUtils.EMPTY);
138        escapeXml10Map.put("\u000e", StringUtils.EMPTY);
139        escapeXml10Map.put("\u000f", StringUtils.EMPTY);
140        escapeXml10Map.put("\u0010", StringUtils.EMPTY);
141        escapeXml10Map.put("\u0011", StringUtils.EMPTY);
142        escapeXml10Map.put("\u0012", StringUtils.EMPTY);
143        escapeXml10Map.put("\u0013", StringUtils.EMPTY);
144        escapeXml10Map.put("\u0014", StringUtils.EMPTY);
145        escapeXml10Map.put("\u0015", StringUtils.EMPTY);
146        escapeXml10Map.put("\u0016", StringUtils.EMPTY);
147        escapeXml10Map.put("\u0017", StringUtils.EMPTY);
148        escapeXml10Map.put("\u0018", StringUtils.EMPTY);
149        escapeXml10Map.put("\u0019", StringUtils.EMPTY);
150        escapeXml10Map.put("\u001a", StringUtils.EMPTY);
151        escapeXml10Map.put("\u001b", StringUtils.EMPTY);
152        escapeXml10Map.put("\u001c", StringUtils.EMPTY);
153        escapeXml10Map.put("\u001d", StringUtils.EMPTY);
154        escapeXml10Map.put("\u001e", StringUtils.EMPTY);
155        escapeXml10Map.put("\u001f", StringUtils.EMPTY);
156        escapeXml10Map.put("\ufffe", StringUtils.EMPTY);
157        escapeXml10Map.put("\uffff", StringUtils.EMPTY);
158        ESCAPE_XML10 = new AggregateTranslator(
159                new LookupTranslator(EntityArrays.BASIC_ESCAPE),
160                new LookupTranslator(EntityArrays.APOS_ESCAPE),
161                new LookupTranslator(Collections.unmodifiableMap(escapeXml10Map)),
162                NumericEntityEscaper.between(0x7f, 0x84),
163                NumericEntityEscaper.between(0x86, 0x9f),
164                new UnicodeUnpairedSurrogateRemover()
165        );
166    }
167
168    /**
169     * Translator object for escaping XML 1.1.
170     *
171     * While {@link #escapeXml11(String)} is the expected method of use, this
172     * object allows the XML escaping functionality to be used
173     * as the foundation for a custom translator.
174     */
175    public static final CharSequenceTranslator ESCAPE_XML11;
176    static {
177        final Map<CharSequence, CharSequence> escapeXml11Map = new HashMap<>();
178        escapeXml11Map.put("\u0000", StringUtils.EMPTY);
179        escapeXml11Map.put("\u000b", "&#11;");
180        escapeXml11Map.put("\u000c", "&#12;");
181        escapeXml11Map.put("\ufffe", StringUtils.EMPTY);
182        escapeXml11Map.put("\uffff", StringUtils.EMPTY);
183        ESCAPE_XML11 = new AggregateTranslator(
184                new LookupTranslator(EntityArrays.BASIC_ESCAPE),
185                new LookupTranslator(EntityArrays.APOS_ESCAPE),
186                new LookupTranslator(Collections.unmodifiableMap(escapeXml11Map)),
187                NumericEntityEscaper.between(0x1, 0x8),
188                NumericEntityEscaper.between(0xe, 0x1f),
189                NumericEntityEscaper.between(0x7f, 0x84),
190                NumericEntityEscaper.between(0x86, 0x9f),
191                new UnicodeUnpairedSurrogateRemover()
192        );
193    }
194
195    /**
196     * Translator object for escaping HTML version 3.0.
197     *
198     * While {@link #escapeHtml3(String)} is the expected method of use, this
199     * object allows the HTML escaping functionality to be used
200     * as the foundation for a custom translator.
201     */
202    public static final CharSequenceTranslator ESCAPE_HTML3 =
203            new AggregateTranslator(
204                    new LookupTranslator(EntityArrays.BASIC_ESCAPE),
205                    new LookupTranslator(EntityArrays.ISO8859_1_ESCAPE)
206            );
207
208    /**
209     * Translator object for escaping HTML version 4.0.
210     *
211     * While {@link #escapeHtml4(String)} is the expected method of use, this
212     * object allows the HTML escaping functionality to be used
213     * as the foundation for a custom translator.
214     */
215    public static final CharSequenceTranslator ESCAPE_HTML4 =
216            new AggregateTranslator(
217                    new LookupTranslator(EntityArrays.BASIC_ESCAPE),
218                    new LookupTranslator(EntityArrays.ISO8859_1_ESCAPE),
219                    new LookupTranslator(EntityArrays.HTML40_EXTENDED_ESCAPE)
220            );
221
222    /**
223     * Translator object for escaping individual Comma Separated Values.
224     *
225     * While {@link #escapeCsv(String)} is the expected method of use, this
226     * object allows the CSV escaping functionality to be used
227     * as the foundation for a custom translator.
228     */
229    public static final CharSequenceTranslator ESCAPE_CSV = new CsvTranslators.CsvEscaper();
230
231    /**
232     * Translator object for escaping Shell command language.
233     *
234     * @see <a href="http://pubs.opengroup.org/onlinepubs/7908799/xcu/chap2.html">Shell Command Language</a>
235     */
236    public static final CharSequenceTranslator ESCAPE_XSI;
237    static {
238        final Map<CharSequence, CharSequence> escapeXsiMap = new HashMap<>();
239        escapeXsiMap.put("|", "\\|");
240        escapeXsiMap.put("&", "\\&");
241        escapeXsiMap.put(";", "\\;");
242        escapeXsiMap.put("<", "\\<");
243        escapeXsiMap.put(">", "\\>");
244        escapeXsiMap.put("(", "\\(");
245        escapeXsiMap.put(")", "\\)");
246        escapeXsiMap.put("$", "\\$");
247        escapeXsiMap.put("`", "\\`");
248        escapeXsiMap.put("\\", "\\\\");
249        escapeXsiMap.put("\"", "\\\"");
250        escapeXsiMap.put("'", "\\'");
251        escapeXsiMap.put(" ", "\\ ");
252        escapeXsiMap.put("\t", "\\\t");
253        escapeXsiMap.put("\r\n", StringUtils.EMPTY);
254        escapeXsiMap.put("\n", StringUtils.EMPTY);
255        escapeXsiMap.put("*", "\\*");
256        escapeXsiMap.put("?", "\\?");
257        escapeXsiMap.put("[", "\\[");
258        escapeXsiMap.put("#", "\\#");
259        escapeXsiMap.put("~", "\\~");
260        escapeXsiMap.put("=", "\\=");
261        escapeXsiMap.put("%", "\\%");
262        ESCAPE_XSI = new LookupTranslator(
263                Collections.unmodifiableMap(escapeXsiMap)
264        );
265    }
266
267    /* UNESCAPE TRANSLATORS */
268
269    /**
270     * Translator object for unescaping escaped Java.
271     *
272     * While {@link #unescapeJava(String)} is the expected method of use, this
273     * object allows the Java unescaping functionality to be used
274     * as the foundation for a custom translator.
275     */
276    public static final CharSequenceTranslator UNESCAPE_JAVA;
277    static {
278        final Map<CharSequence, CharSequence> unescapeJavaMap = new HashMap<>();
279        unescapeJavaMap.put("\\\\", "\\");
280        unescapeJavaMap.put("\\\"", "\"");
281        unescapeJavaMap.put("\\'", "'");
282        unescapeJavaMap.put("\\", StringUtils.EMPTY);
283        UNESCAPE_JAVA = new AggregateTranslator(
284                new OctalUnescaper(),     // .between('\1', '\377'),
285                new UnicodeUnescaper(),
286                new LookupTranslator(EntityArrays.JAVA_CTRL_CHARS_UNESCAPE),
287                new LookupTranslator(Collections.unmodifiableMap(unescapeJavaMap))
288        );
289    }
290
291    /**
292     * Translator object for unescaping escaped EcmaScript.
293     *
294     * While {@link #unescapeEcmaScript(String)} is the expected method of use, this
295     * object allows the EcmaScript unescaping functionality to be used
296     * as the foundation for a custom translator.
297     */
298    public static final CharSequenceTranslator UNESCAPE_ECMASCRIPT = UNESCAPE_JAVA;
299
300    /**
301     * Translator object for unescaping escaped Json.
302     *
303     * While {@link #unescapeJson(String)} is the expected method of use, this
304     * object allows the Json unescaping functionality to be used
305     * as the foundation for a custom translator.
306     */
307    public static final CharSequenceTranslator UNESCAPE_JSON = UNESCAPE_JAVA;
308
309    /**
310     * Translator object for unescaping escaped HTML 3.0.
311     *
312     * While {@link #unescapeHtml3(String)} is the expected method of use, this
313     * object allows the HTML unescaping functionality to be used
314     * as the foundation for a custom translator.
315     */
316    public static final CharSequenceTranslator UNESCAPE_HTML3 =
317            new AggregateTranslator(
318                    new LookupTranslator(EntityArrays.BASIC_UNESCAPE),
319                    new LookupTranslator(EntityArrays.ISO8859_1_UNESCAPE),
320                    new NumericEntityUnescaper()
321            );
322
323    /**
324     * Translator object for unescaping escaped HTML 4.0.
325     *
326     * While {@link #unescapeHtml4(String)} is the expected method of use, this
327     * object allows the HTML unescaping functionality to be used
328     * as the foundation for a custom translator.
329     */
330    public static final CharSequenceTranslator UNESCAPE_HTML4 =
331            new AggregateTranslator(
332                    new LookupTranslator(EntityArrays.BASIC_UNESCAPE),
333                    new LookupTranslator(EntityArrays.ISO8859_1_UNESCAPE),
334                    new LookupTranslator(EntityArrays.HTML40_EXTENDED_UNESCAPE),
335                    new NumericEntityUnescaper()
336            );
337
338    /**
339     * Translator object for unescaping escaped XML.
340     *
341     * While {@link #unescapeXml(String)} is the expected method of use, this
342     * object allows the XML unescaping functionality to be used
343     * as the foundation for a custom translator.
344     */
345    public static final CharSequenceTranslator UNESCAPE_XML =
346            new AggregateTranslator(
347                    new LookupTranslator(EntityArrays.BASIC_UNESCAPE),
348                    new LookupTranslator(EntityArrays.APOS_UNESCAPE),
349                    new NumericEntityUnescaper()
350            );
351
352    /**
353     * Translator object for unescaping escaped Comma Separated Value entries.
354     *
355     * While {@link #unescapeCsv(String)} is the expected method of use, this
356     * object allows the CSV unescaping functionality to be used
357     * as the foundation for a custom translator.
358     */
359    public static final CharSequenceTranslator UNESCAPE_CSV = new CsvTranslators.CsvUnescaper();
360
361    /**
362     * Translator object for unescaping escaped XSI Value entries.
363     *
364     * While {@link #unescapeXSI(String)}  is the expected method of use, this
365     * object allows the XSI unescaping functionality to be used
366     * as the foundation for a custom translator.
367     */
368    public static final CharSequenceTranslator UNESCAPE_XSI = new XsiUnescaper();
369
370    /**
371     * Translator object for unescaping backslash escaped entries.
372     */
373    static class XsiUnescaper extends CharSequenceTranslator {
374
375        /**
376         * Escaped backslash constant.
377         */
378        private static final char BACKSLASH = '\\';
379
380        @Override
381        public int translate(final CharSequence input, final int index, final Writer out) throws IOException {
382
383            if (index != 0) {
384                throw new IllegalStateException("XsiUnescaper should never reach the [1] index");
385            }
386
387            final String s = input.toString();
388
389            int segmentStart = 0;
390            int searchOffset = 0;
391            while (true) {
392                final int pos = s.indexOf(BACKSLASH, searchOffset);
393                if (pos == -1) {
394                    if (segmentStart < s.length()) {
395                        out.write(s.substring(segmentStart));
396                    }
397                    break;
398                }
399                if (pos > segmentStart) {
400                    out.write(s.substring(segmentStart, pos));
401                }
402                segmentStart = pos + 1;
403                searchOffset = pos + 2;
404            }
405
406            return Character.codePointCount(input, 0, input.length());
407        }
408    }
409
410    /* Helper functions */
411
412    /**
413     * <p>{@code StringEscapeUtils} instances should NOT be constructed in
414     * standard programming.</p>
415     *
416     * <p>Instead, the class should be used as:</p>
417     * <pre>StringEscapeUtils.escapeJava("foo");</pre>
418     *
419     * <p>This constructor is public to permit tools that require a JavaBean
420     * instance to operate.</p>
421     */
422    public StringEscapeUtils() {
423        super();
424    }
425
426    /**
427     * <p>Convenience wrapper for {@link java.lang.StringBuilder} providing escape methods.</p>
428     *
429     * <p>Example:</p>
430     * <pre>
431     * new Builder(ESCAPE_HTML4)
432     *      .append("&lt;p&gt;")
433     *      .escape("This is paragraph 1 and special chars like &amp; get escaped.")
434     *      .append("&lt;/p&gt;&lt;p&gt;")
435     *      .escape("This is paragraph 2 &amp; more...")
436     *      .append("&lt;/p&gt;")
437     *      .toString()
438     * </pre>
439     *
440     */
441    public static final class Builder {
442
443        /**
444         * StringBuilder to be used in the Builder class.
445         */
446        private final StringBuilder sb;
447
448        /**
449         * CharSequenceTranslator to be used in the Builder class.
450         */
451        private final CharSequenceTranslator translator;
452
453        /**
454         * Builder constructor.
455         *
456         * @param translator a CharSequenceTranslator.
457         */
458        private Builder(final CharSequenceTranslator translator) {
459            this.sb = new StringBuilder();
460            this.translator = translator;
461        }
462
463        /**
464         * <p>Escape {@code input} according to the given {@link CharSequenceTranslator}.</p>
465         *
466         * @param input the String to escape
467         * @return {@code this}, to enable chaining
468         */
469        public Builder escape(final String input) {
470            sb.append(translator.translate(input));
471            return this;
472        }
473
474        /**
475         * Literal append, no escaping being done.
476         *
477         * @param input the String to append
478         * @return {@code this}, to enable chaining
479         */
480        public Builder append(final String input) {
481            sb.append(input);
482            return this;
483        }
484
485        /**
486         * <p>Return the escaped string.</p>
487         *
488         * @return The escaped string
489         */
490        @Override
491        public String toString() {
492            return sb.toString();
493        }
494    }
495
496    /**
497     * Get a {@link Builder}.
498     * @param translator the text translator
499     * @return {@link Builder}
500     */
501    public static StringEscapeUtils.Builder builder(final CharSequenceTranslator translator) {
502        return new Builder(translator);
503    }
504
505    // Java and JavaScript
506    //--------------------------------------------------------------------------
507    /**
508     * <p>Escapes the characters in a {@code String} using Java String rules.</p>
509     *
510     * <p>Deals correctly with quotes and control-chars (tab, backslash, cr, ff, etc.) </p>
511     *
512     * <p>So a tab becomes the characters {@code '\\'} and
513     * {@code 't'}.</p>
514     *
515     * <p>The only difference between Java strings and JavaScript strings
516     * is that in JavaScript, a single quote and forward-slash (/) are escaped.</p>
517     *
518     * <p>Example:</p>
519     * <pre>
520     * input string: He didn't say, "Stop!"
521     * output string: He didn't say, \"Stop!\"
522     * </pre>
523     *
524     * @param input  String to escape values in, may be null
525     * @return String with escaped values, {@code null} if null string input
526     */
527    public static final String escapeJava(final String input) {
528        return ESCAPE_JAVA.translate(input);
529    }
530
531    /**
532     * <p>Escapes the characters in a {@code String} using EcmaScript String rules.</p>
533     * <p>Escapes any values it finds into their EcmaScript String form.
534     * Deals correctly with quotes and control-chars (tab, backslash, cr, ff, etc.) </p>
535     *
536     * <p>So a tab becomes the characters {@code '\\'} and
537     * {@code 't'}.</p>
538     *
539     * <p>The only difference between Java strings and EcmaScript strings
540     * is that in EcmaScript, a single quote and forward-slash (/) are escaped.</p>
541     *
542     * <p>Note that EcmaScript is best known by the JavaScript and ActionScript dialects.</p>
543     *
544     * <p>Example:</p>
545     * <pre>
546     * input string: He didn't say, "Stop!"
547     * output string: He didn\'t say, \"Stop!\"
548     * </pre>
549     *
550     * <b>Security Note.</b> We only provide backslash escaping in this method. For example, {@code '\"'} has the output
551     * {@code '\\\"'} which could result in potential issues in the case where the string being escaped is being used
552     * in an HTML tag like {@code <select onmouseover="..." />}. If you wish to have more rigorous string escaping, you
553     * may consider the
554     * <a href="https://www.owasp.org/index.php/Category:OWASP_Enterprise_Security_API_JAVA">ESAPI Libraries</a>.
555     * Further, you can view the <a href="https://github.com/esapi">ESAPI GitHub Org</a>.
556     *
557     * @param input  String to escape values in, may be null
558     * @return String with escaped values, {@code null} if null string input
559     */
560    public static final String escapeEcmaScript(final String input) {
561        return ESCAPE_ECMASCRIPT.translate(input);
562    }
563
564    /**
565     * <p>Escapes the characters in a {@code String} using Json String rules.</p>
566     * <p>Escapes any values it finds into their Json String form.
567     * Deals correctly with quotes and control-chars (tab, backslash, cr, ff, etc.) </p>
568     *
569     * <p>So a tab becomes the characters {@code '\\'} and
570     * {@code 't'}.</p>
571     *
572     * <p>The only difference between Java strings and Json strings
573     * is that in Json, forward-slash (/) is escaped.</p>
574     *
575     * <p>See http://www.ietf.org/rfc/rfc4627.txt for further details.</p>
576     *
577     * <p>Example:</p>
578     * <pre>
579     * input string: He didn't say, "Stop!"
580     * output string: He didn't say, \"Stop!\"
581     * </pre>
582     *
583     * @param input  String to escape values in, may be null
584     * @return String with escaped values, {@code null} if null string input
585     */
586    public static final String escapeJson(final String input) {
587        return ESCAPE_JSON.translate(input);
588    }
589
590    /**
591     * <p>Unescapes any Java literals found in the {@code String}.
592     * For example, it will turn a sequence of {@code '\'} and
593     * {@code 'n'} into a newline character, unless the {@code '\'}
594     * is preceded by another {@code '\'}.</p>
595     *
596     * @param input  the {@code String} to unescape, may be null
597     * @return a new unescaped {@code String}, {@code null} if null string input
598     */
599    public static final String unescapeJava(final String input) {
600        return UNESCAPE_JAVA.translate(input);
601    }
602
603    /**
604     * <p>Unescapes any EcmaScript literals found in the {@code String}.</p>
605     *
606     * <p>For example, it will turn a sequence of {@code '\'} and {@code 'n'}
607     * into a newline character, unless the {@code '\'} is preceded by another
608     * {@code '\'}.</p>
609     *
610     * @see #unescapeJava(String)
611     * @param input  the {@code String} to unescape, may be null
612     * @return A new unescaped {@code String}, {@code null} if null string input
613     */
614    public static final String unescapeEcmaScript(final String input) {
615        return UNESCAPE_ECMASCRIPT.translate(input);
616    }
617
618    /**
619     * <p>Unescapes any Json literals found in the {@code String}.</p>
620     *
621     * <p>For example, it will turn a sequence of {@code '\'} and {@code 'n'}
622     * into a newline character, unless the {@code '\'} is preceded by another
623     * {@code '\'}.</p>
624     *
625     * @see #unescapeJava(String)
626     * @param input  the {@code String} to unescape, may be null
627     * @return A new unescaped {@code String}, {@code null} if null string input
628     */
629    public static final String unescapeJson(final String input) {
630        return UNESCAPE_JSON.translate(input);
631    }
632
633    // HTML and XML
634    //--------------------------------------------------------------------------
635    /**
636     * <p>Escapes the characters in a {@code String} using HTML entities.</p>
637     *
638     * <p>
639     * For example:
640     * </p>
641     * <p>{@code "bread" &amp; "butter"}</p>
642     * becomes:
643     * <p>
644     * {@code &amp;quot;bread&amp;quot; &amp;amp; &amp;quot;butter&amp;quot;}.
645     * </p>
646     *
647     * <p>Supports all known HTML 4.0 entities, including funky accents.
648     * Note that the commonly used apostrophe escape character (&amp;apos;)
649     * is not a legal entity and so is not supported).</p>
650     *
651     * @param input  the {@code String} to escape, may be null
652     * @return a new escaped {@code String}, {@code null} if null string input
653     *
654     * @see <a href="http://hotwired.lycos.com/webmonkey/reference/special_characters/">ISO Entities</a>
655     * @see <a href="http://www.w3.org/TR/REC-html32#latin1">HTML 3.2 Character Entities for ISO Latin-1</a>
656     * @see <a href="http://www.w3.org/TR/REC-html40/sgml/entities.html">HTML 4.0 Character entity references</a>
657     * @see <a href="http://www.w3.org/TR/html401/charset.html#h-5.3">HTML 4.01 Character References</a>
658     * @see <a href="http://www.w3.org/TR/html401/charset.html#code-position">HTML 4.01 Code positions</a>
659     */
660    public static final String escapeHtml4(final String input) {
661        return ESCAPE_HTML4.translate(input);
662    }
663
664    /**
665     * <p>Escapes the characters in a {@code String} using HTML entities.</p>
666     * <p>Supports only the HTML 3.0 entities.</p>
667     *
668     * @param input  the {@code String} to escape, may be null
669     * @return a new escaped {@code String}, {@code null} if null string input
670     */
671    public static final String escapeHtml3(final String input) {
672        return ESCAPE_HTML3.translate(input);
673    }
674
675    //-----------------------------------------------------------------------
676    /**
677     * <p>Unescapes a string containing entity escapes to a string
678     * containing the actual Unicode characters corresponding to the
679     * escapes. Supports HTML 4.0 entities.</p>
680     *
681     * <p>For example, the string {@code "&lt;Fran&ccedil;ais&gt;"}
682     * will become {@code "<Fran´┐Żais>"}</p>
683     *
684     * <p>If an entity is unrecognized, it is left alone, and inserted
685     * verbatim into the result string. e.g. {@code "&gt;&zzzz;x"} will
686     * become {@code ">&zzzz;x"}.</p>
687     *
688     * @param input  the {@code String} to unescape, may be null
689     * @return a new unescaped {@code String}, {@code null} if null string input
690     */
691    public static final String unescapeHtml4(final String input) {
692        return UNESCAPE_HTML4.translate(input);
693    }
694
695    /**
696     * <p>Unescapes a string containing entity escapes to a string
697     * containing the actual Unicode characters corresponding to the
698     * escapes. Supports only HTML 3.0 entities.</p>
699     *
700     * @param input  the {@code String} to unescape, may be null
701     * @return a new unescaped {@code String}, {@code null} if null string input
702     */
703    public static final String unescapeHtml3(final String input) {
704        return UNESCAPE_HTML3.translate(input);
705    }
706
707    /**
708     * <p>Escapes the characters in a {@code String} using XML entities.</p>
709     *
710     * <p>For example: {@code "bread" & "butter"} =&gt;
711     * {@code &quot;bread&quot; &amp; &quot;butter&quot;}.
712     * </p>
713     *
714     * <p>Note that XML 1.0 is a text-only format: it cannot represent control
715     * characters or unpaired Unicode surrogate codepoints, even after escaping.
716     * {@code escapeXml10} will remove characters that do not fit in the
717     * following ranges:</p>
718     *
719     * <p>{@code #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]}</p>
720     *
721     * <p>Though not strictly necessary, {@code escapeXml10} will escape
722     * characters in the following ranges:</p>
723     *
724     * <p>{@code [#x7F-#x84] | [#x86-#x9F]}</p>
725     *
726     * <p>The returned string can be inserted into a valid XML 1.0 or XML 1.1
727     * document. If you want to allow more non-text characters in an XML 1.1
728     * document, use {@link #escapeXml11(String)}.</p>
729     *
730     * @param input  the {@code String} to escape, may be null
731     * @return a new escaped {@code String}, {@code null} if null string input
732     * @see #unescapeXml(java.lang.String)
733     */
734    public static String escapeXml10(final String input) {
735        return ESCAPE_XML10.translate(input);
736    }
737
738    /**
739     * <p>Escapes the characters in a {@code String} using XML entities.</p>
740     *
741     * <p>For example: {@code "bread" & "butter"} =&gt;
742     * {@code &quot;bread&quot; &amp; &quot;butter&quot;}.
743     * </p>
744     *
745     * <p>XML 1.1 can represent certain control characters, but it cannot represent
746     * the null byte or unpaired Unicode surrogate codepoints, even after escaping.
747     * {@code escapeXml11} will remove characters that do not fit in the following
748     * ranges:</p>
749     *
750     * <p>{@code [#x1-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]}</p>
751     *
752     * <p>{@code escapeXml11} will escape characters in the following ranges:</p>
753     *
754     * <p>{@code [#x1-#x8] | [#xB-#xC] | [#xE-#x1F] | [#x7F-#x84] | [#x86-#x9F]}</p>
755     *
756     * <p>The returned string can be inserted into a valid XML 1.1 document. Do not
757     * use it for XML 1.0 documents.</p>
758     *
759     * @param input  the {@code String} to escape, may be null
760     * @return a new escaped {@code String}, {@code null} if null string input
761     * @see #unescapeXml(java.lang.String)
762     */
763    public static String escapeXml11(final String input) {
764        return ESCAPE_XML11.translate(input);
765    }
766
767    //-----------------------------------------------------------------------
768    /**
769     * <p>Unescapes a string containing XML entity escapes to a string
770     * containing the actual Unicode characters corresponding to the
771     * escapes.</p>
772     *
773     * <p>Supports only the five basic XML entities (gt, lt, quot, amp, apos).
774     * Does not support DTDs or external entities.</p>
775     *
776     * <p>Note that numerical \\u Unicode codes are unescaped to their respective
777     *    Unicode characters. This may change in future releases.</p>
778     *
779     * @param input  the {@code String} to unescape, may be null
780     * @return a new unescaped {@code String}, {@code null} if null string input
781     * @see #escapeXml10(String)
782     * @see #escapeXml11(String)
783     */
784    public static final String unescapeXml(final String input) {
785        return UNESCAPE_XML.translate(input);
786    }
787
788    //-----------------------------------------------------------------------
789
790    /**
791     * <p>Returns a {@code String} value for a CSV column enclosed in double quotes,
792     * if required.</p>
793     *
794     * <p>If the value contains a comma, newline or double quote, then the
795     *    String value is returned enclosed in double quotes.</p>
796     *
797     * <p>Any double quote characters in the value are escaped with another double quote.</p>
798     *
799     * <p>If the value does not contain a comma, newline or double quote, then the
800     *    String value is returned unchanged.</p>
801     *
802     * see <a href="http://en.wikipedia.org/wiki/Comma-separated_values">Wikipedia</a> and
803     * <a href="http://tools.ietf.org/html/rfc4180">RFC 4180</a>.
804     *
805     * @param input the input CSV column String, may be null
806     * @return The input String, enclosed in double quotes if the value contains a comma,
807     * newline or double quote, {@code null} if null string input
808     */
809    public static final String escapeCsv(final String input) {
810        return ESCAPE_CSV.translate(input);
811    }
812
813    /**
814     * <p>Returns a {@code String} value for an unescaped CSV column.</p>
815     *
816     * <p>If the value is enclosed in double quotes, and contains a comma, newline
817     *    or double quote, then quotes are removed.
818     * </p>
819     *
820     * <p>Any double quote escaped characters (a pair of double quotes) are unescaped
821     *    to just one double quote.</p>
822     *
823     * <p>If the value is not enclosed in double quotes, or is and does not contain a
824     *    comma, newline or double quote, then the String value is returned unchanged.</p>
825     *
826     * see <a href="http://en.wikipedia.org/wiki/Comma-separated_values">Wikipedia</a> and
827     * <a href="http://tools.ietf.org/html/rfc4180">RFC 4180</a>.
828     *
829     * @param input the input CSV column String, may be null
830     * @return The input String, with enclosing double quotes removed and embedded double
831     * quotes unescaped, {@code null} if null string input
832     */
833    public static final String unescapeCsv(final String input) {
834        return UNESCAPE_CSV.translate(input);
835    }
836
837    /**
838     * <p>Escapes the characters in a {@code String} using XSI rules.</p>
839     *
840     * <p><b>Beware!</b> In most cases you don't want to escape shell commands but use multi-argument
841     * methods provided by {@link java.lang.ProcessBuilder} or {@link java.lang.Runtime#exec(String[])}
842     * instead.</p>
843     *
844     * <p>Example:</p>
845     * <pre>
846     * input string: He didn't say, "Stop!"
847     * output string: He\ didn\'t\ say,\ \"Stop!\"
848     * </pre>
849     *
850     * @see <a href="http://pubs.opengroup.org/onlinepubs/7908799/xcu/chap2.html">Shell Command Language</a>
851     * @param input  String to escape values in, may be null
852     * @return String with escaped values, {@code null} if null string input
853     */
854    public static final String escapeXSI(final String input) {
855        return ESCAPE_XSI.translate(input);
856    }
857
858    /**
859     * <p>Unescapes the characters in a {@code String} using XSI rules.</p>
860     *
861     * @see StringEscapeUtils#escapeXSI(String)
862     * @param input  the {@code String} to unescape, may be null
863     * @return a new unescaped {@code String}, {@code null} if null string input
864     */
865    public static final String unescapeXSI(final String input) {
866        return UNESCAPE_XSI.translate(input);
867    }
868
869}