1 // Copyright (c) 2013 The Chromium Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef TOOLS_GN_ESCAPE_H_ 6 #define TOOLS_GN_ESCAPE_H_ 7 8 #include <iosfwd> 9 #include <string_view> 10 11 enum EscapingMode { 12 // No escaping. 13 ESCAPE_NONE, 14 15 // Space only. 16 ESCAPE_SPACE, 17 18 // Ninja string escaping. 19 ESCAPE_NINJA, 20 21 // Ninja/makefile depfile string escaping. 22 ESCAPE_DEPFILE, 23 24 // For writing commands to ninja files. This assumes the output is "one 25 // thing" like a filename, so will escape or quote spaces as necessary for 26 // both Ninja and the shell to keep that thing together. 27 ESCAPE_NINJA_COMMAND, 28 29 // For writing preformatted shell commands to Ninja files. This assumes the 30 // output already has the proper quoting and may include special shell 31 // characters which we want to pass to the shell (like when writing tool 32 // commands). Only Ninja "$" are escaped. 33 ESCAPE_NINJA_PREFORMATTED_COMMAND, 34 35 // Shell escaping as described by JSON Compilation Database spec: 36 // Parameters use shell quoting and shell escaping of quotes, with ‘"’ and ‘\’ 37 // being the only special characters. 38 ESCAPE_COMPILATION_DATABASE, 39 }; 40 41 enum EscapingPlatform { 42 // Do escaping for the current platform. 43 ESCAPE_PLATFORM_CURRENT, 44 45 // Force escaping for the given platform. 46 ESCAPE_PLATFORM_POSIX, 47 ESCAPE_PLATFORM_WIN, 48 }; 49 50 struct EscapeOptions { 51 EscapingMode mode = ESCAPE_NONE; 52 53 // Controls how "fork" escaping is done. You will generally want to keep the 54 // default "current" platform. 55 EscapingPlatform platform = ESCAPE_PLATFORM_CURRENT; 56 57 // When the escaping mode is ESCAPE_SHELL, the escaper will normally put 58 // quotes around things with spaces. If this value is set to true, we'll 59 // disable the quoting feature and just add the spaces. 60 // 61 // This mode is for when quoting is done at some higher-level. Defaults to 62 // false. Note that Windows has strange behavior where the meaning of the 63 // backslashes changes according to if it is followed by a quote. The 64 // escaping rules assume that a double-quote will be appended to the result. 65 bool inhibit_quoting = false; 66 }; 67 68 // Escapes the given input, returnining the result. 69 // 70 // If needed_quoting is non-null, whether the string was or should have been 71 // (if inhibit_quoting was set) quoted will be written to it. This value should 72 // be initialized to false by the caller and will be written to only if it's 73 // true (the common use-case is for chaining calls). 74 std::string EscapeString(std::string_view str, 75 const EscapeOptions& options, 76 bool* needed_quoting); 77 78 // Same as EscapeString but writes the results to the given stream, saving a 79 // copy. 80 void EscapeStringToStream(std::ostream& out, 81 std::string_view str, 82 const EscapeOptions& options); 83 84 // Same as EscapeString but escape JSON string and writes the results to the 85 // given stream, saving a copy. 86 void EscapeJSONStringToStream(std::ostream& out, 87 std::string_view str, 88 const EscapeOptions& options); 89 90 #endif // TOOLS_GN_ESCAPE_H_ 91