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