1 // Copyright 2012 The Chromium Authors
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 // This class works with command lines: building and parsing.
6 // Arguments with prefixes ('--', '-', and on Windows, '/') are switches.
7 // Switches will precede all other arguments without switch prefixes.
8 // Switches can optionally have values, delimited by '=', e.g., "-switch=value".
9 // If a switch is specified multiple times, only the last value is used.
10 // An argument of "--" will terminate switch parsing during initialization,
11 // interpreting subsequent tokens as non-switch arguments, regardless of prefix.
13 // There is a singleton read-only CommandLine that represents the command line
14 // that the current process was started with. It must be initialized in main().
16 #ifndef BASE_COMMAND_LINE_H_
17 #define BASE_COMMAND_LINE_H_
26 #include "base/base_export.h"
27 #include "base/containers/span.h"
28 #include "base/debug/debugging_buildflags.h"
29 #include "base/strings/string_piece.h"
30 #include "build/build_config.h"
32 #if BUILDFLAG(ENABLE_COMMANDLINE_SEQUENCE_CHECKS)
33 #include "base/sequence_checker.h"
34 #endif // BUILDFLAG(ENABLE_COMMANDLINE_SEQUENCE_CHECKS)
38 class DuplicateSwitchHandler;
41 class BASE_EXPORT CommandLine {
44 // The native command line string type.
45 using StringType = std::wstring;
46 #elif BUILDFLAG(IS_POSIX) || BUILDFLAG(IS_FUCHSIA)
47 using StringType = std::string;
50 using CharType = StringType::value_type;
51 using StringPieceType = base::BasicStringPiece<CharType>;
52 using StringVector = std::vector<StringType>;
53 using SwitchMap = std::map<std::string, StringType, std::less<>>;
55 // A constructor for CommandLines that only carry switches and arguments.
56 enum NoProgram { NO_PROGRAM };
57 explicit CommandLine(NoProgram no_program);
59 // Construct a new command line with |program| as argv[0].
60 explicit CommandLine(const FilePath& program);
62 // Construct a new command line from an argument list.
63 CommandLine(int argc, const CharType* const* argv);
64 explicit CommandLine(const StringVector& argv);
66 // Allow the copy constructor. A common pattern is to copy of the current
67 // process's command line and then add some flags to it. For example:
68 // CommandLine cl(*CommandLine::ForCurrentProcess());
69 // cl.AppendSwitch(...);
70 CommandLine(const CommandLine& other);
71 CommandLine& operator=(const CommandLine& other);
76 // By default this class will treat command-line arguments beginning with
77 // slashes as switches on Windows, but not other platforms.
79 // If this behavior is inappropriate for your application, you can call this
80 // function BEFORE initializing the current process' global command line
81 // object and the behavior will be the same as Posix systems (only hyphens
82 // begin switches, everything else will be an arg).
83 static void set_slash_is_not_a_switch();
85 // Normally when the CommandLine singleton is initialized it gets the command
86 // line via the GetCommandLineW API and then uses the shell32 API
87 // CommandLineToArgvW to parse the command line and convert it back to
88 // argc and argv. Tests who don't want this dependency on shell32 and need
89 // to honor the arguments passed in should use this function.
90 static void InitUsingArgvForTesting(int argc, const char* const* argv);
93 // Initialize the current process CommandLine singleton. On Windows, ignores
94 // its arguments (we instead parse GetCommandLineW() directly) because we
95 // don't trust the CRT's parsing of the command line, but it still must be
96 // called to set up the command line. Returns false if initialization has
97 // already occurred, and true otherwise. Only the caller receiving a 'true'
98 // return value should take responsibility for calling Reset.
99 static bool Init(int argc, const char* const* argv);
101 // Destroys the current process CommandLine singleton. This is necessary if
102 // you want to reset the base library to its initial state (for example, in an
103 // outer library that needs to be able to terminate, and be re-initialized).
104 // If Init is called only once, as in main(), Reset() is not necessary.
105 // Do not call this in tests. Use base::test::ScopedCommandLine instead.
108 // Get the singleton CommandLine representing the current process's
109 // command line. Note: returned value is mutable, but not thread safe;
110 // only mutate if you know what you're doing!
111 static CommandLine* ForCurrentProcess();
113 // Returns true if the CommandLine has been initialized for the given process.
114 static bool InitializedForCurrentProcess();
116 #if BUILDFLAG(IS_WIN)
117 static CommandLine FromString(StringPieceType command_line);
120 // Initialize from an argv vector.
121 void InitFromArgv(int argc, const CharType* const* argv);
122 void InitFromArgv(const StringVector& argv);
124 // Constructs and returns the represented command line string.
125 // CAUTION! This should be avoided on POSIX because quoting behavior is
127 // CAUTION! If writing a command line to the Windows registry, use
128 // GetCommandLineStringForShell() instead.
129 StringType GetCommandLineString() const;
131 #if BUILDFLAG(IS_WIN)
132 // Quotes and escapes `arg` if necessary so that it will be interpreted as a
133 // single command-line parameter according to the following rules in line with
134 // `::CommandLineToArgvW` and C++ `main`:
135 // * Returns `arg` unchanged if `arg` does not include any characters that may
136 // need encoding, which is spaces, tabs, backslashes, and double-quotes.
137 // * Otherwise, double-quotes `arg` and in addition:
138 // * Escapes any double-quotes in `arg` with backslashes.
139 // * Escapes backslashes in `arg` if:
140 // * `arg` ends with backslashes , or
141 // * the backslashes end in a pre-existing double quote.
143 // https://learn.microsoft.com/en-us/search/?terms=CommandLineToArgvW and
144 // http://msdn.microsoft.com/en-us/library/17w5ykft.aspx#parsing-c-command-line-arguments.
145 static std::wstring QuoteForCommandLineToArgvW(const std::wstring& arg);
147 // Returns the command-line string in the proper format for the Windows shell,
148 // ending with the argument placeholder "--single-argument %1". The single-
149 // argument switch prevents unexpected parsing of arguments from other
150 // software that cannot be trusted to escape double quotes when substituting
151 // into a placeholder (e.g., "%1" insert sequences populated by the Windows
153 // NOTE: this must be used to generate the command-line string for the shell
154 // even if this command line was parsed from a string with the proper syntax,
155 // because the --single-argument switch is not preserved during parsing.
156 StringType GetCommandLineStringForShell() const;
158 // Returns the represented command-line string. Allows the use of unsafe
159 // Windows insert sequences like "%1". Only use this method if
160 // GetCommandLineStringForShell() is not adequate AND the processor inserting
161 // the arguments is known to do so securely (i.e., is not the Windows shell).
162 // If in doubt, do not use.
163 StringType GetCommandLineStringWithUnsafeInsertSequences() const;
166 // Constructs and returns the represented arguments string.
167 // CAUTION! This should be avoided on POSIX because quoting behavior is
169 StringType GetArgumentsString() const;
171 // Returns the original command line string as a vector of strings.
172 const StringVector& argv() const { return argv_; }
174 // Get and Set the program part of the command line string (the first item).
175 FilePath GetProgram() const;
176 void SetProgram(const FilePath& program);
178 // Returns true if this command line contains the given switch.
179 // Switch names must be lowercase.
180 // The second override provides an optimized version to avoid inlining codegen
181 // at every callsite to find the length of the constant and construct a
183 bool HasSwitch(StringPiece switch_string) const;
184 bool HasSwitch(const char switch_constant[]) const;
186 // Returns the value associated with the given switch. If the switch has no
187 // value or isn't present, this method returns the empty string.
188 // Switch names must be lowercase.
189 std::string GetSwitchValueASCII(StringPiece switch_string) const;
190 FilePath GetSwitchValuePath(StringPiece switch_string) const;
191 StringType GetSwitchValueNative(StringPiece switch_string) const;
193 // Get a copy of all switches, along with their values.
194 const SwitchMap& GetSwitches() const { return switches_; }
196 // Append a switch [with optional value] to the command line.
197 // Note: Switches will precede arguments regardless of appending order.
198 void AppendSwitch(StringPiece switch_string);
199 void AppendSwitchPath(StringPiece switch_string, const FilePath& path);
200 void AppendSwitchNative(StringPiece switch_string, StringPieceType value);
201 void AppendSwitchASCII(StringPiece switch_string, StringPiece value);
203 // Removes the switch that matches |switch_key_without_prefix|, regardless of
204 // prefix and value. If no such switch is present, this has no effect.
205 void RemoveSwitch(const base::StringPiece switch_key_without_prefix);
207 // Copies a set of switches (and any values) from another command line.
208 // Commonly used when launching a subprocess.
209 // If an entry in `switches` does not exist in `source`, then it is ignored.
210 void CopySwitchesFrom(const CommandLine& source,
211 span<const char* const> switches);
213 // Get the remaining arguments to the command.
214 StringVector GetArgs() const;
216 // Append an argument to the command line. Note that the argument is quoted
217 // properly such that it is interpreted as one argument to the target command.
218 // AppendArg is primarily for ASCII; non-ASCII input is interpreted as UTF-8.
219 // Note: Switches will precede arguments regardless of appending order.
220 void AppendArg(StringPiece value);
221 void AppendArgPath(const FilePath& value);
222 void AppendArgNative(StringPieceType value);
224 // Append the switches and arguments from another command line to this one.
225 // If |include_program| is true, include |other|'s program as well.
226 void AppendArguments(const CommandLine& other, bool include_program);
228 // Insert a command before the current command.
229 // Common for debuggers, like "gdb --args".
230 void PrependWrapper(StringPieceType wrapper);
232 #if BUILDFLAG(IS_WIN)
233 // Initialize by parsing the given command line string.
234 // The program name is assumed to be the first item in the string.
235 void ParseFromString(StringPieceType command_line);
237 // Returns true if the command line had the --single-argument switch, and
238 // thus likely came from a Windows shell registration. This is only set if the
239 // command line is parsed, and is not changed after it is parsed.
240 bool HasSingleArgumentSwitch() const { return has_single_argument_switch_; }
243 // Detaches this object from the current sequence in preparation for a move to
244 // a different sequence.
245 void DetachFromCurrentSequence();
247 // Sets a delegate that's called when we encounter a duplicate switch
248 static void SetDuplicateSwitchHandler(
249 std::unique_ptr<DuplicateSwitchHandler>);
252 #if BUILDFLAG(ENABLE_COMMANDLINE_SEQUENCE_CHECKS)
253 // A helper class that encapsulates a SEQUENCE_CHECKER but allows copy.
254 // Copying this class will detach the sequence checker from the owning object.
255 class InstanceBoundSequenceChecker {
257 InstanceBoundSequenceChecker() = default;
259 InstanceBoundSequenceChecker(const InstanceBoundSequenceChecker& other) {}
261 InstanceBoundSequenceChecker& operator=(
262 const InstanceBoundSequenceChecker& other) {
267 InstanceBoundSequenceChecker(InstanceBoundSequenceChecker&&) = delete;
268 InstanceBoundSequenceChecker& operator=(InstanceBoundSequenceChecker&&) =
271 void Detach() { DETACH_FROM_SEQUENCE(sequence_checker_); }
272 void Check() { DCHECK_CALLED_ON_VALID_SEQUENCE(sequence_checker_); }
275 SEQUENCE_CHECKER(sequence_checker_);
277 #endif // BUILDFLAG(ENABLE_COMMANDLINE_SEQUENCE_CHECKS)
279 // Disallow default constructor; a program name must be explicitly specified.
280 CommandLine() = delete;
282 // Append switches and arguments, keeping switches before arguments.
283 void AppendSwitchesAndArguments(const StringVector& argv);
285 // Internal version of GetArgumentsString to support allowing unsafe insert
286 // sequences in rare cases (see
287 // GetCommandLineStringWithUnsafeInsertSequences).
288 StringType GetArgumentsStringInternal(
289 bool allow_unsafe_insert_sequences) const;
291 #if BUILDFLAG(IS_WIN)
292 // Initializes by parsing |raw_command_line_string_|, treating everything
293 // after |single_arg_switch_string| + <a single character> as the command
294 // line's single argument, and dropping any arguments previously parsed. The
295 // command line must contain |single_arg_switch_string|, and the argument, if
296 // present, must be separated from |single_arg_switch_string| by one
298 // NOTE: the single-argument switch is not preserved after parsing;
299 // GetCommandLineStringForShell() must be used to reproduce the original
300 // command-line string with single-argument switch.
301 void ParseAsSingleArgument(const StringType& single_arg_switch_string);
303 // The string returned by GetCommandLineW(), to be parsed via
304 // ParseFromString(). Empty if this command line was not parsed from a string,
305 // or if ParseFromString() has finished executing.
306 StringPieceType raw_command_line_string_;
308 // Set to true if the command line had --single-argument when initially
309 // parsed. It does not change if the command line mutates after initial
311 bool has_single_argument_switch_ = false;
314 // The singleton CommandLine representing the current process's command line.
315 static CommandLine* current_process_commandline_;
317 // The argv array: { program, [(--|-|/)switch[=value]]*, [--], [argument]* }
320 // Parsed-out switch keys and values.
323 // The index after the program and switches, any arguments start here.
324 ptrdiff_t begin_args_;
326 #if BUILDFLAG(ENABLE_COMMANDLINE_SEQUENCE_CHECKS)
327 InstanceBoundSequenceChecker sequence_checker_;
331 class BASE_EXPORT DuplicateSwitchHandler {
333 // out_value contains the existing value of the switch
334 virtual void ResolveDuplicate(base::StringPiece key,
335 CommandLine::StringPieceType new_value,
336 CommandLine::StringType& out_value) = 0;
337 virtual ~DuplicateSwitchHandler() = default;
342 #endif // BASE_COMMAND_LINE_H_