groovy.json.StringEscapeUtils Maven / Gradle / Ivy
Show all versions of groovy-all Show documentation
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package groovy.json;
import java.io.IOException;
import java.io.StringWriter;
import java.io.Writer;
import java.util.Locale;
/**
* Escapes and unescapes Strings for
* Java, Java Script, HTML, XML, and SQL.
*
* #ThreadSafe#
*
* Note that this version is a stripped down version from Commons Lang 2.6 with only necessary methods for
* JSON builder
* @author Apache Software Foundation
* @author Apache Jakarta Turbine
* @author Purple Technology
* @author Alexander Day Chaffee
* @author Antony Riley
* @author Helge Tesgaard
* @author Sean Brown
* @author Gary Gregory
* @author Phil Steitz
* @author Pete Gieser
* @since 2.0
*/
public class StringEscapeUtils {
/**
*
StringEscapeUtils instances should NOT be constructed in
* standard programming.
*
*
Instead, the class should be used as:
*
StringEscapeUtils.escapeJava("foo");
*
* This constructor is public to permit tools that require a JavaBean
* instance to operate.
*/
public StringEscapeUtils() {
super();
}
// Java and JavaScript
//--------------------------------------------------------------------------
/**
* Escapes the characters in a String using Java String rules.
*
* Deals correctly with quotes and control-chars (tab, backslash, cr, ff, etc.)
*
* So a tab becomes the characters '\\' and 't'.
*
* The only difference between Java strings and JavaScript strings
* is that in JavaScript, a single quote must be escaped.
*
* Example:
*
* input string: He didn't say, "Stop!"
* output string: He didn't say, \"Stop!\"
*
*
* @param str String to escape values in, may be null
* @return String with escaped values, null if null string input
*/
public static String escapeJava(String str) {
return escapeJavaStyleString(str, false, false);
}
/**
* Escapes the characters in a String using Java String rules to
* a Writer.
*
* A null string input has no effect.
*
* @see #escapeJava(java.lang.String)
* @param out Writer to write escaped string into
* @param str String to escape values in, may be null
* @throws IllegalArgumentException if the Writer is null
* @throws IOException if error occurs on underlying Writer
*/
public static void escapeJava(Writer out, String str) throws IOException {
escapeJavaStyleString(out, str, false, false);
}
/**
* Escapes the characters in a String using JavaScript String rules.
*
* Escapes any values it finds into their JavaScript String form.
* Deals correctly with quotes and control-chars (tab, backslash, cr, ff, etc.)
*
* So a tab becomes the characters '\\' and 't'.
*
* The only difference between Java strings and JavaScript strings
* is that in JavaScript, a single quote must be escaped.
*
* Example:
*
* input string: He didn't say, "Stop!"
* output string: He didn\'t say, \"Stop!\"
*
*
* @param str String to escape values in, may be null
* @return String with escaped values, null if null string input
*/
public static String escapeJavaScript(String str) {
return escapeJavaStyleString(str, true, true);
}
/**
* Escapes the characters in a String using JavaScript String rules
* to a Writer.
*
* A null string input has no effect.
*
* @see #escapeJavaScript(java.lang.String)
* @param out Writer to write escaped string into
* @param str String to escape values in, may be null
* @throws IllegalArgumentException if the Writer is null
* @throws IOException if error occurs on underlying Writer
**/
public static void escapeJavaScript(Writer out, String str) throws IOException {
escapeJavaStyleString(out, str, true, true);
}
/**
* Worker method for the {@link #escapeJavaScript(String)} method.
*
* @param str String to escape values in, may be null
* @param escapeSingleQuotes escapes single quotes if true
* @param escapeForwardSlash TODO
* @return the escaped string
*/
private static String escapeJavaStyleString(String str, boolean escapeSingleQuotes, boolean escapeForwardSlash) {
if (str == null) {
return null;
}
try {
StringWriter writer = new StringWriter(str.length() * 2);
escapeJavaStyleString(writer, str, escapeSingleQuotes, escapeForwardSlash);
return writer.toString();
} catch (IOException ioe) {
// this should never ever happen while writing to a StringWriter
throw new RuntimeException(ioe);
}
}
/**
* Worker method for the {@link #escapeJavaScript(String)} method.
*
* @param out write to receieve the escaped string
* @param str String to escape values in, may be null
* @param escapeSingleQuote escapes single quotes if true
* @param escapeForwardSlash TODO
* @throws IOException if an IOException occurs
*/
private static void escapeJavaStyleString(Writer out, String str, boolean escapeSingleQuote,
boolean escapeForwardSlash) throws IOException {
if (out == null) {
throw new IllegalArgumentException("The Writer must not be null");
}
if (str == null) {
return;
}
int sz;
sz = str.length();
for (int i = 0; i < sz; i++) {
char ch = str.charAt(i);
// handle unicode
if (ch > 0xfff) {
out.write("\\u" + hex(ch));
} else if (ch > 0xff) {
out.write("\\u0" + hex(ch));
} else if (ch > 0x7f) {
out.write("\\u00" + hex(ch));
} else if (ch < 32) {
switch (ch) {
case '\b':
out.write('\\');
out.write('b');
break;
case '\n':
out.write('\\');
out.write('n');
break;
case '\t':
out.write('\\');
out.write('t');
break;
case '\f':
out.write('\\');
out.write('f');
break;
case '\r':
out.write('\\');
out.write('r');
break;
default:
if (ch > 0xf) {
out.write("\\u00" + hex(ch));
} else {
out.write("\\u000" + hex(ch));
}
break;
}
} else {
switch (ch) {
case '\'':
if (escapeSingleQuote) {
out.write('\\');
}
out.write('\'');
break;
case '"':
out.write('\\');
out.write('"');
break;
case '\\':
out.write('\\');
out.write('\\');
break;
case '/':
if (escapeForwardSlash) {
out.write('\\');
}
out.write('/');
break;
default:
out.write(ch);
break;
}
}
}
}
/**
* Returns an upper case hexadecimal String for the given
* character.
*
* @param ch The character to convert.
* @return An upper case hexadecimal String
*/
private static String hex(char ch) {
return Integer.toHexString(ch).toUpperCase(Locale.ENGLISH);
}
/**
* Unescapes any Java literals found in the String.
* For example, it will turn a sequence of '\' and
* 'n' into a newline character, unless the '\'
* is preceded by another '\'.
*
* @param str the String to unescape, may be null
* @return a new unescaped String, null if null string input
*/
public static String unescapeJava(String str) {
if (str == null) {
return null;
}
try {
StringWriter writer = new StringWriter(str.length());
unescapeJava(writer, str);
return writer.toString();
} catch (IOException ioe) {
// this should never ever happen while writing to a StringWriter
throw new RuntimeException(ioe);
}
}
/**
*
Unescapes any Java literals found in the String to a
* Writer.
*
* For example, it will turn a sequence of '\' and
* 'n' into a newline character, unless the '\'
* is preceded by another '\'.
*
* A null string input has no effect.
*
* @param out the Writer used to output unescaped characters
* @param str the String to unescape, may be null
* @throws IllegalArgumentException if the Writer is null
* @throws IOException if error occurs on underlying Writer
*/
public static void unescapeJava(Writer out, String str) throws IOException {
if (out == null) {
throw new IllegalArgumentException("The Writer must not be null");
}
if (str == null) {
return;
}
int sz = str.length();
StringBuilder unicode = new StringBuilder(4);
boolean hadSlash = false;
boolean inUnicode = false;
for (int i = 0; i < sz; i++) {
char ch = str.charAt(i);
if (inUnicode) {
// if in unicode, then we're reading unicode
// values in somehow
unicode.append(ch);
if (unicode.length() == 4) {
// unicode now contains the four hex digits
// which represents our unicode character
try {
int value = Integer.parseInt(unicode.toString(), 16);
out.write((char) value);
unicode.setLength(0);
inUnicode = false;
hadSlash = false;
} catch (NumberFormatException nfe) {
throw new RuntimeException("Unable to parse unicode value: " + unicode, nfe);
}
}
continue;
}
if (hadSlash) {
// handle an escaped value
hadSlash = false;
switch (ch) {
case '\\':
out.write('\\');
break;
case '\'':
out.write('\'');
break;
case '\"':
out.write('"');
break;
case 'r':
out.write('\r');
break;
case 'f':
out.write('\f');
break;
case 't':
out.write('\t');
break;
case 'n':
out.write('\n');
break;
case 'b':
out.write('\b');
break;
case 'u':
{
// uh-oh, we're in unicode country....
inUnicode = true;
break;
}
default :
out.write(ch);
break;
}
continue;
} else if (ch == '\\') {
hadSlash = true;
continue;
}
out.write(ch);
}
if (hadSlash) {
// then we're in the weird case of a \ at the end of the
// string, let's output it anyway.
out.write('\\');
}
}
/**
* Unescapes any JavaScript literals found in the String.
*
* For example, it will turn a sequence of '\' and 'n'
* into a newline character, unless the '\' is preceded by another
* '\'.
*
* @see #unescapeJava(String)
* @param str the String to unescape, may be null
* @return A new unescaped String, null if null string input
*/
public static String unescapeJavaScript(String str) {
return unescapeJava(str);
}
/**
* Unescapes any JavaScript literals found in the String to a
* Writer.
*
* For example, it will turn a sequence of '\' and 'n'
* into a newline character, unless the '\' is preceded by another
* '\'.
*
* A null string input has no effect.
*
* @see #unescapeJava(Writer,String)
* @param out the Writer used to output unescaped characters
* @param str the String to unescape, may be null
* @throws IllegalArgumentException if the Writer is null
* @throws IOException if error occurs on underlying Writer
*/
public static void unescapeJavaScript(Writer out, String str) throws IOException {
unescapeJava(out, str);
}
}