[go: nahoru, domu]
Google Git
Sign in
chromium / chromium / src / 418597846f9a31e126c68ae4ef64e873e43c4569 / . / base / command_line.h
blob: ad0281283a29b3c3beed6deb5422a0e7dd2aec62 [file] [log] [blame]
erikwright@chromium.org72e2e2422012-02-27 18:38:12[diff] [blame]1// Copyright (c) 2012 The Chromium Authors. All rights reserved.
license.botbf09a502008-08-24 00:55:55[diff] [blame]2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
deanm@chromium.org02c87962008-10-06 10:25:35[diff] [blame]4
evan@chromium.orgbb975362009-01-21 01:00:22[diff] [blame]5// This class works with command lines: building and parsing.
msw@chromium.orga40ca4302011-05-14 01:10:24[diff] [blame]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".
John Rummellb1d5fcb2019-04-27 01:13:33[diff] [blame]9// If a switch is specified multiple times, only the last value is used.
msw@chromium.orga40ca4302011-05-14 01:10:24[diff] [blame]10// An argument of "--" will terminate switch parsing during initialization,
11// interpreting subsequent tokens as non-switch arguments, regardless of prefix.
evan@chromium.orgbb975362009-01-21 01:00:22[diff] [blame]12
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]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().
initial.commitd7cae122008-07-26 21:49:38[diff] [blame]15
deanm@chromium.org02c87962008-10-06 10:25:35[diff] [blame]16#ifndef BASE_COMMAND_LINE_H_
17#define BASE_COMMAND_LINE_H_
initial.commitd7cae122008-07-26 21:49:38[diff] [blame]18
jhawkins@chromium.org2edc2862011-04-04 18:04:37[diff] [blame]19#include <stddef.h>
Sumaid Syed22f60eeb2021-08-26 05:16:26[diff] [blame]20#include <functional>
initial.commitd7cae122008-07-26 21:49:38[diff] [blame]21#include <map>
Stephan Hartmann41859782021-10-12 18:49:23[diff] [blame^]22#include <memory>
initial.commitd7cae122008-07-26 21:49:38[diff] [blame]23#include <string>
24#include <vector>
25
darin@chromium.org0bea7252011-08-05 15:34:00[diff] [blame]26#include "base/base_export.h"
jackhou1bd9da92015-05-21 04:48:00[diff] [blame]27#include "base/strings/string_piece.h"
brettw@chromium.org74e9fa22010-12-29 21:06:43[diff] [blame]28#include "build/build_config.h"
initial.commitd7cae122008-07-26 21:49:38[diff] [blame]29
brettw@chromium.orga3ef4832013-02-02 05:12:33[diff] [blame]30namespace base {
brettw@chromium.org2f3b1cc2014-03-17 23:07:15[diff] [blame]31
erg@google.com5d91c9e2010-07-28 17:25:28[diff] [blame]32class FilePath;
Greg Gutermanfe16560d2021-10-07 19:58:15[diff] [blame]33class DuplicateSwitchHandler;
sky@google.comd4515eb2009-01-30 00:40:43[diff] [blame]34
darin@chromium.org0bea7252011-08-05 15:34:00[diff] [blame]35class BASE_EXPORT CommandLine {
initial.commitd7cae122008-07-26 21:49:38[diff] [blame]36 public:
erg@google.coma502bbe72011-01-07 18:06:45[diff] [blame]37#if defined(OS_WIN)
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]38 // The native command line string type.
Jan Wilken Dörrieda77fd432019-10-24 21:40:34[diff] [blame]39 using StringType = std::wstring;
Fabrice de Gans-Riberi306871de2018-05-16 19:38:39[diff] [blame]40#elif defined(OS_POSIX) || defined(OS_FUCHSIA)
thestigfd085682016-07-15 02:50:16[diff] [blame]41 using StringType = std::string;
erg@google.coma502bbe72011-01-07 18:06:45[diff] [blame]42#endif
43
thestigfd085682016-07-15 02:50:16[diff] [blame]44 using CharType = StringType::value_type;
Jan Wilken Dörrie8ed6fce2021-03-25 23:00:38[diff] [blame]45 using StringPieceType = base::BasicStringPiece<CharType>;
thestigfd085682016-07-15 02:50:16[diff] [blame]46 using StringVector = std::vector<StringType>;
Jeremy Roman863386d2017-10-31 19:25:38[diff] [blame]47 using SwitchMap = std::map<std::string, StringType, std::less<>>;
erg@google.coma502bbe72011-01-07 18:06:45[diff] [blame]48
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]49 // A constructor for CommandLines that only carry switches and arguments.
mattm@chromium.org947446b2010-10-21 03:36:31[diff] [blame]50 enum NoProgram { NO_PROGRAM };
51 explicit CommandLine(NoProgram no_program);
erg@google.coma502bbe72011-01-07 18:06:45[diff] [blame]52
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]53 // Construct a new command line with |program| as argv[0].
brettw@chromium.org2f3b1cc2014-03-17 23:07:15[diff] [blame]54 explicit CommandLine(const FilePath& program);
erg@google.coma502bbe72011-01-07 18:06:45[diff] [blame]55
msw@chromium.orga40ca4302011-05-14 01:10:24[diff] [blame]56 // Construct a new command line from an argument list.
57 CommandLine(int argc, const CharType* const* argv);
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]58 explicit CommandLine(const StringVector& argv);
erg@google.coma502bbe72011-01-07 18:06:45[diff] [blame]59
jackhou1bd9da92015-05-21 04:48:00[diff] [blame]60 CommandLine(const CommandLine& other);
61 CommandLine& operator=(const CommandLine& other);
62
msw@chromium.orgacbeb3d2011-03-01 20:47:58[diff] [blame]63 ~CommandLine();
64
brettw@chromium.orgbf98a0e12013-09-25 23:36:00[diff] [blame]65#if defined(OS_WIN)
66 // By default this class will treat command-line arguments beginning with
67 // slashes as switches on Windows, but not other platforms.
68 //
69 // If this behavior is inappropriate for your application, you can call this
70 // function BEFORE initializing the current process' global command line
71 // object and the behavior will be the same as Posix systems (only hyphens
72 // begin switches, everything else will be an arg).
73 static void set_slash_is_not_a_switch();
anantad936bc12016-06-22 21:40:31[diff] [blame]74
75 // Normally when the CommandLine singleton is initialized it gets the command
76 // line via the GetCommandLineW API and then uses the shell32 API
77 // CommandLineToArgvW to parse the command line and convert it back to
78 // argc and argv. Tests who don't want this dependency on shell32 and need
79 // to honor the arguments passed in should use this function.
80 static void InitUsingArgvForTesting(int argc, const char* const* argv);
brettw@chromium.orgbf98a0e12013-09-25 23:36:00[diff] [blame]81#endif
82
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]83 // Initialize the current process CommandLine singleton. On Windows, ignores
84 // its arguments (we instead parse GetCommandLineW() directly) because we
85 // don't trust the CRT's parsing of the command line, but it still must be
erikwright@chromium.org72e2e2422012-02-27 18:38:12[diff] [blame]86 // called to set up the command line. Returns false if initialization has
87 // already occurred, and true otherwise. Only the caller receiving a 'true'
88 // return value should take responsibility for calling Reset.
89 static bool Init(int argc, const char* const* argv);
evan@chromium.orgbb975362009-01-21 01:00:22[diff] [blame]90
evan@chromium.orga2318cda2009-02-25 21:13:53[diff] [blame]91 // Destroys the current process CommandLine singleton. This is necessary if
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]92 // you want to reset the base library to its initial state (for example, in an
evan@chromium.orga2318cda2009-02-25 21:13:53[diff] [blame]93 // outer library that needs to be able to terminate, and be re-initialized).
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]94 // If Init is called only once, as in main(), Reset() is not necessary.
thestigfd085682016-07-15 02:50:16[diff] [blame]95 // Do not call this in tests. Use base::test::ScopedCommandLine instead.
evan@chromium.org02fb75ab2009-10-12 16:11:40[diff] [blame]96 static void Reset();
evan@chromium.orga2318cda2009-02-25 21:13:53[diff] [blame]97
evan@chromium.orgbb975362009-01-21 01:00:22[diff] [blame]98 // Get the singleton CommandLine representing the current process's
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]99 // command line. Note: returned value is mutable, but not thread safe;
evan@chromium.org0189bbd2009-10-12 22:50:39[diff] [blame]100 // only mutate if you know what you're doing!
erg@google.comdcd869c2010-08-30 20:15:25[diff] [blame]101 static CommandLine* ForCurrentProcess();
evanm@google.com1a48f312008-08-12 01:14:37[diff] [blame]102
vollick@chromium.org2bf64a92013-07-11 23:10:40[diff] [blame]103 // Returns true if the CommandLine has been initialized for the given process.
104 static bool InitializedForCurrentProcess();
105
evan@chromium.orgbb975362009-01-21 01:00:22[diff] [blame]106#if defined(OS_WIN)
Jan Wilken Dörrieda77fd432019-10-24 21:40:34[diff] [blame]107 static CommandLine FromString(StringPieceType command_line);
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]108#endif
109
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]110 // Initialize from an argv vector.
msw@chromium.orga40ca4302011-05-14 01:10:24[diff] [blame]111 void InitFromArgv(int argc, const CharType* const* argv);
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]112 void InitFromArgv(const StringVector& argv);
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]113
msw@chromium.orga40ca4302011-05-14 01:10:24[diff] [blame]114 // Constructs and returns the represented command line string.
gab@chromium.org45f982e2012-10-29 21:31:31[diff] [blame]115 // CAUTION! This should be avoided on POSIX because quoting behavior is
116 // unclear.
Jesse McKenna036150c2020-07-17 21:11:17[diff] [blame]117 // CAUTION! If writing a command line to the Windows registry, use
118 // GetCommandLineStringForShell() instead.
119 StringType GetCommandLineString() const;
mgiucac974d512014-10-01 09:24:51[diff] [blame]120
121#if defined(OS_WIN)
Jesse McKenna036150c2020-07-17 21:11:17[diff] [blame]122 // Returns the command-line string in the proper format for the Windows shell,
123 // ending with the argument placeholder "--single-argument %1". The single-
124 // argument switch prevents unexpected parsing of arguments from other
125 // software that cannot be trusted to escape double quotes when substituting
Jesse McKenna185ceda22021-03-10 06:47:55[diff] [blame]126 // into a placeholder (e.g., "%1" insert sequences populated by the Windows
Jesse McKenna036150c2020-07-17 21:11:17[diff] [blame]127 // shell).
128 // NOTE: this must be used to generate the command-line string for the shell
129 // even if this command line was parsed from a string with the proper syntax,
130 // because the --single-argument switch is not preserved during parsing.
131 StringType GetCommandLineStringForShell() const;
Jesse McKenna185ceda22021-03-10 06:47:55[diff] [blame]132
133 // Returns the represented command-line string. Allows the use of unsafe
134 // Windows insert sequences like "%1". Only use this method if
135 // GetCommandLineStringForShell() is not adequate AND the processor inserting
136 // the arguments is known to do so securely (i.e., is not the Windows shell).
137 // If in doubt, do not use.
138 StringType GetCommandLineStringWithUnsafeInsertSequences() const;
mgiucac974d512014-10-01 09:24:51[diff] [blame]139#endif
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]140
gab@chromium.org45f982e2012-10-29 21:31:31[diff] [blame]141 // Constructs and returns the represented arguments string.
142 // CAUTION! This should be avoided on POSIX because quoting behavior is
143 // unclear.
Jesse McKenna036150c2020-07-17 21:11:17[diff] [blame]144 StringType GetArgumentsString() const;
gab@chromium.org45f982e2012-10-29 21:31:31[diff] [blame]145
estade@chromium.org10e42bf2008-10-15 21:59:08[diff] [blame]146 // Returns the original command line string as a vector of strings.
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]147 const StringVector& argv() const { return argv_; }
estade@chromium.org10e42bf2008-10-15 21:59:08[diff] [blame]148
msw@chromium.orga40ca4302011-05-14 01:10:24[diff] [blame]149 // Get and Set the program part of the command line string (the first item).
brettw@chromium.org2f3b1cc2014-03-17 23:07:15[diff] [blame]150 FilePath GetProgram() const;
151 void SetProgram(const FilePath& program);
evan@chromium.org0189bbd2009-10-12 22:50:39[diff] [blame]152
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]153 // Returns true if this command line contains the given switch.
jackhou1bd9da92015-05-21 04:48:00[diff] [blame]154 // Switch names must be lowercase.
155 // The second override provides an optimized version to avoid inlining codegen
156 // at every callsite to find the length of the constant and construct a
157 // StringPiece.
Wez65018d02021-05-20 15:47:45[diff] [blame]158 bool HasSwitch(StringPiece switch_string) const;
tapted009a1dc82015-03-30 03:57:10[diff] [blame]159 bool HasSwitch(const char switch_constant[]) const;
initial.commitd7cae122008-07-26 21:49:38[diff] [blame]160
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]161 // Returns the value associated with the given switch. If the switch has no
162 // value or isn't present, this method returns the empty string.
jackhou1bd9da92015-05-21 04:48:00[diff] [blame]163 // Switch names must be lowercase.
Wez65018d02021-05-20 15:47:45[diff] [blame]164 std::string GetSwitchValueASCII(StringPiece switch_string) const;
165 FilePath GetSwitchValuePath(StringPiece switch_string) const;
166 StringType GetSwitchValueNative(StringPiece switch_string) const;
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]167
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]168 // Get a copy of all switches, along with their values.
169 const SwitchMap& GetSwitches() const { return switches_; }
170
171 // Append a switch [with optional value] to the command line.
msw@chromium.orga40ca4302011-05-14 01:10:24[diff] [blame]172 // Note: Switches will precede arguments regardless of appending order.
Wez65018d02021-05-20 15:47:45[diff] [blame]173 void AppendSwitch(StringPiece switch_string);
174 void AppendSwitchPath(StringPiece switch_string, const FilePath& path);
175 void AppendSwitchNative(StringPiece switch_string, StringPieceType value);
176 void AppendSwitchASCII(StringPiece switch_string, StringPiece value);
evan@chromium.org4f08c83f2010-07-29 23:02:34[diff] [blame]177
Pavol Markobf16b812019-06-14 00:53:12[diff] [blame]178 // Removes the switch that matches |switch_key_without_prefix|, regardless of
179 // prefix and value. If no such switch is present, this has no effect.
180 void RemoveSwitch(const base::StringPiece switch_key_without_prefix);
Avi Drissman1aa6cb92019-01-23 15:58:38[diff] [blame]181
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]182 // Copy a set of switches (and any values) from another command line.
183 // Commonly used when launching a subprocess.
msw@chromium.orga40ca4302011-05-14 01:10:24[diff] [blame]184 void CopySwitchesFrom(const CommandLine& source,
185 const char* const switches[],
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]186 size_t count);
187
188 // Get the remaining arguments to the command.
msw@chromium.org75f1c782011-07-13 23:41:22[diff] [blame]189 StringVector GetArgs() const;
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]190
191 // Append an argument to the command line. Note that the argument is quoted
192 // properly such that it is interpreted as one argument to the target command.
193 // AppendArg is primarily for ASCII; non-ASCII input is interpreted as UTF-8.
msw@chromium.orga40ca4302011-05-14 01:10:24[diff] [blame]194 // Note: Switches will precede arguments regardless of appending order.
Wez65018d02021-05-20 15:47:45[diff] [blame]195 void AppendArg(StringPiece value);
brettw@chromium.org2f3b1cc2014-03-17 23:07:15[diff] [blame]196 void AppendArgPath(const FilePath& value);
Wez65018d02021-05-20 15:47:45[diff] [blame]197 void AppendArgNative(StringPieceType value);
evan@chromium.orgbb975362009-01-21 01:00:22[diff] [blame]198
msw@chromium.orga40ca4302011-05-14 01:10:24[diff] [blame]199 // Append the switches and arguments from another command line to this one.
evan@chromium.orgbb975362009-01-21 01:00:22[diff] [blame]200 // If |include_program| is true, include |other|'s program as well.
msw@chromium.orga40ca4302011-05-14 01:10:24[diff] [blame]201 void AppendArguments(const CommandLine& other, bool include_program);
initial.commitd7cae122008-07-26 21:49:38[diff] [blame]202
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]203 // Insert a command before the current command.
Mostyn Bramley-Moored0ecd6a2017-12-06 19:13:21[diff] [blame]204 // Common for debuggers, like "gdb --args".
Wez65018d02021-05-20 15:47:45[diff] [blame]205 void PrependWrapper(StringPieceType wrapper);
agl@chromium.org052f1d482009-02-10 00:52:14[diff] [blame]206
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]207#if defined(OS_WIN)
208 // Initialize by parsing the given command line string.
209 // The program name is assumed to be the first item in the string.
Jan Wilken Dörrieda77fd432019-10-24 21:40:34[diff] [blame]210 void ParseFromString(StringPieceType command_line);
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]211#endif
evan@chromium.org4f08c83f2010-07-29 23:02:34[diff] [blame]212
Greg Gutermanfe16560d2021-10-07 19:58:15[diff] [blame]213 // Sets a delegate that's called when we encounter a duplicate switch
214 static void SetDuplicateSwitchHandler(
215 std::unique_ptr<DuplicateSwitchHandler>);
216
initial.commitd7cae122008-07-26 21:49:38[diff] [blame]217 private:
msw@chromium.orga40ca4302011-05-14 01:10:24[diff] [blame]218 // Disallow default constructor; a program name must be explicitly specified.
Chris Watkins091d6292017-12-13 04:25:58[diff] [blame]219 CommandLine() = delete;
msw@chromium.orga40ca4302011-05-14 01:10:24[diff] [blame]220 // Allow the copy constructor. A common pattern is to copy of the current
221 // process's command line and then add some flags to it. For example:
222 // CommandLine cl(*CommandLine::ForCurrentProcess());
223 // cl.AppendSwitch(...);
sky@google.comd4515eb2009-01-30 00:40:43[diff] [blame]224
Jesse McKenna036150c2020-07-17 21:11:17[diff] [blame]225 // Append switches and arguments, keeping switches before arguments.
226 void AppendSwitchesAndArguments(const StringVector& argv);
mgiucac974d512014-10-01 09:24:51[diff] [blame]227
Jesse McKenna185ceda22021-03-10 06:47:55[diff] [blame]228 // Internal version of GetArgumentsString to support allowing unsafe insert
229 // sequences in rare cases (see
230 // GetCommandLineStringWithUnsafeInsertSequences).
231 StringType GetArgumentsStringInternal(
232 bool allow_unsafe_insert_sequences) const;
233
Jesse McKenna036150c2020-07-17 21:11:17[diff] [blame]234#if defined(OS_WIN)
235 // Initializes by parsing |raw_command_line_string_|, treating everything
236 // after |single_arg_switch_string| + <a single character> as the command
237 // line's single argument, and dropping any arguments previously parsed. The
238 // command line must contain |single_arg_switch_string|, and the argument, if
239 // present, must be separated from |single_arg_switch_string| by one
240 // character.
241 // NOTE: the single-argument switch is not preserved after parsing;
242 // GetCommandLineStringForShell() must be used to reproduce the original
243 // command-line string with single-argument switch.
244 void ParseAsSingleArgument(const StringType& single_arg_switch_string);
245
246 // The string returned by GetCommandLineW(), to be parsed via
247 // ParseFromString(). Empty if this command line was not parsed from a string,
248 // or if ParseFromString() has finished executing.
249 StringPieceType raw_command_line_string_;
250#endif
mgiucac974d512014-10-01 09:24:51[diff] [blame]251
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]252 // The singleton CommandLine representing the current process's command line.
evan@chromium.orgbb975362009-01-21 01:00:22[diff] [blame]253 static CommandLine* current_process_commandline_;
initial.commitd7cae122008-07-26 21:49:38[diff] [blame]254
msw@chromium.orga40ca4302011-05-14 01:10:24[diff] [blame]255 // The argv array: { program, [(--|-|/)switch[=value]]*, [--], [argument]* }
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]256 StringVector argv_;
evan@chromium.orgbb975362009-01-21 01:00:22[diff] [blame]257
msw@chromium.org06cc083a2011-03-01 02:28:42[diff] [blame]258 // Parsed-out switch keys and values.
kinuko@chromium.orgf6c34832010-05-24 10:39:59[diff] [blame]259 SwitchMap switches_;
evan@chromium.orgbb975362009-01-21 01:00:22[diff] [blame]260
msw@chromium.orga40ca4302011-05-14 01:10:24[diff] [blame]261 // The index after the program and switches, any arguments start here.
262 size_t begin_args_;
initial.commitd7cae122008-07-26 21:49:38[diff] [blame]263};
264
Greg Gutermanfe16560d2021-10-07 19:58:15[diff] [blame]265class BASE_EXPORT DuplicateSwitchHandler {
266 public:
267 // out_value contains the existing value of the switch
268 virtual void ResolveDuplicate(base::StringPiece key,
269 CommandLine::StringPieceType new_value,
270 CommandLine::StringType& out_value) = 0;
271 virtual ~DuplicateSwitchHandler() = default;
272};
273
brettw@chromium.org2f3b1cc2014-03-17 23:07:15[diff] [blame]274} // namespace base
275
deanm@chromium.org02c87962008-10-06 10:25:35[diff] [blame]276#endif // BASE_COMMAND_LINE_H_