com.facebook.buck.util

Class Escaper

java.lang.Object

com.facebook.buck.util.Escaper

public final class Escaper
extends Object

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Escaper.Quoter The quoting style to use when escaping.

Field Summary

Fields

Modifier and Type	Field and Description
static java.util.function.Function<String,String>	ARGFILE_ESCAPER Escaper for argfiles for clang and gcc.
static java.util.function.Function<String,String>	BASH_ESCAPER Bash quoting Function which can be passed to Iterables.transform().
static java.util.function.Function<String,String>	CREATE_PROCESS_ESCAPER CreateProcess (Windows) quoting Function which can be passed to Iterables.transform().
static java.util.function.Function<String,String>	SHELL_ESCAPER Platform-aware shell quoting Function which can be passed to Iterables.transform() TODO(sdwilsh): get proper cmd.EXE escaping implemented on Windows

Method Summary

Modifier and Type	Method and Description
static int	decodeNumericEscape(StringBuilder out, String escaped, int pos, int maxCodeLength, int base) Call decodeNumericEscape(StringBuilder, String, int, int, int, int) to parse at most one escaped character; i.e.
static int	decodeNumericEscape(StringBuilder out, String escaped, int pos, int maxCodeLength, int base, int maxCodes) Decode a numeric escape as explained in this page: http://en.cppreference.com/w/cpp/language/escape .
static String	escape(Escaper.Quoter quoter, com.google.common.base.CharMatcher matcher, String str) Escapes the special characters identified the CharMatcher, using single quotes.
static String	escapeAsBashString(Path path)
static String	escapeAsBashString(String str) Quotes a string to be passed to Bash, if necessary.
static String	escapeAsMakefileValueString(String str)
static String	escapeAsPythonString(String str)
static String	escapeAsShellString(String str) Quotes a string to be passed to the shell, if necessary.
static String	escapePathForCIncludeString(Path path) Escapes forward slashes in a Path as a String that is safe to consume with other tools (such as gcc).
static java.util.function.Function<String,String>	escaper(Escaper.Quoter quoter, com.google.common.base.CharMatcher matcher)
static String	escapeWithQuotesAsMakefileValueString(String str)
static java.util.function.Function<String,String>	javacEscaper()
static String	unescapeLineMarkerPath(String escaped) Unescape a path string obtained from preprocessor output, as in: https://gcc.gnu.org/onlinedocs/cpp/Preprocessor-Output.html .

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

BASH_ESCAPER

public static final java.util.function.Function<String,String> BASH_ESCAPER

Bash quoting Function which can be passed to Iterables.transform().

CREATE_PROCESS_ESCAPER

public static final java.util.function.Function<String,String> CREATE_PROCESS_ESCAPER

CreateProcess (Windows) quoting Function which can be passed to Iterables.transform().

SHELL_ESCAPER

public static final java.util.function.Function<String,String> SHELL_ESCAPER

Platform-aware shell quoting Function which can be passed to Iterables.transform() TODO(sdwilsh): get proper cmd.EXE escaping implemented on Windows

ARGFILE_ESCAPER

public static final java.util.function.Function<String,String> ARGFILE_ESCAPER

Escaper for argfiles for clang and gcc.

Based on the following docs in the gcc manual:

@file Read command-line options from file. The options read are inserted in place of the original @file option. If file does not exist, or cannot be read, then the option will be treated literally, and not removed.

Options in file are separated by whitespace. A whitespace character may be included in an option by surrounding the entire option in either single or double quotes. Any character (including a backslash) may be included by prefixing the character to be included with a backslash. The file may itself contain additional @file options; any such options will be processed recursively.

Method Detail

escape

public static String escape(Escaper.Quoter quoter,
                            com.google.common.base.CharMatcher matcher,
                            String str)

Escapes the special characters identified the CharMatcher, using single quotes.

Parameters:

matcher - identifies characters to be escaped

str - string to quote

Returns:

possibly quoted string

escaper

public static java.util.function.Function<String,String> escaper(Escaper.Quoter quoter,
                                                                 com.google.common.base.CharMatcher matcher)

Returns:

a escaper function using the given quote style and escaping characters determined by the given matcher.

javacEscaper

public static java.util.function.Function<String,String> javacEscaper()

escapeAsShellString

public static String escapeAsShellString(String str)

Quotes a string to be passed to the shell, if necessary. This works for the appropriate shell regardless of the platform it is run on.

Parameters:

str - string to escape

Returns:

possibly escaped string

escapeAsBashString

public static String escapeAsBashString(String str)

Quotes a string to be passed to Bash, if necessary. Uses single quotes to prevent variable expansion, `...` evaluation etc.

Parameters:

str - string to quote

Returns:

possibly quoted string

escapeAsBashString

public static String escapeAsBashString(Path path)

escapeAsPythonString

public static String escapeAsPythonString(String str)

Returns:

a double-quoted string with metacharacters and quotes escaped with a backslash; non-ASCII characters escaped as \u

escapeAsMakefileValueString

public static String escapeAsMakefileValueString(String str)

Returns:

an escaped string suitable for use in a GNU makefile on the right side of a variable assignment.

escapeWithQuotesAsMakefileValueString

public static String escapeWithQuotesAsMakefileValueString(String str)

Returns:

quoted string if it contains at least one character that needs to be escaped

escapePathForCIncludeString

public static String escapePathForCIncludeString(Path path)

Escapes forward slashes in a Path as a String that is safe to consume with other tools (such as gcc). On Unix systems, this is equivalent to Path.toString().

Parameters:

path - the Path to escape

Returns:

the escaped Path

unescapeLineMarkerPath

public static String unescapeLineMarkerPath(String escaped)

Unescape a path string obtained from preprocessor output, as in: https://gcc.gnu.org/onlinedocs/cpp/Preprocessor-Output.html .

See Also:

decodeNumericEscape(StringBuilder, String, int, int, int, int)

decodeNumericEscape

public static int decodeNumericEscape(StringBuilder out,
                                      String escaped,
                                      int pos,
                                      int maxCodeLength,
                                      int base,
                                      int maxCodes)

Decode a numeric escape as explained in this page: http://en.cppreference.com/w/cpp/language/escape . The pointed-to substring shouldn't contain the leading backslash + optional 'x' or 'u'.

Parameters:

out - receives decoded characters

escaped - the string containing the escape sequence

pos - starting index of escape (but after the backslash)

base - number base, e.g. 8 for octal, or 16 for hex or unicode.

maxCodes - maximum number of sequences of escape numbers to decode. This is mainly to support unicode escape sequences which might represent one or two characters.

Returns:

position to first character just after the consumed numeric code. Is number of consumed code bytes + pos argument.

decodeNumericEscape

public static int decodeNumericEscape(StringBuilder out,
                                      String escaped,
                                      int pos,
                                      int maxCodeLength,
                                      int base)

Call decodeNumericEscape(StringBuilder, String, int, int, int, int) to parse at most one escaped character; i.e. calls that method with maxCodes = 1.