src/base/command_line.h

   1 // Copyright (c) 2012 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 // 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 // An argument of "--" will terminate switch parsing during initialization,
  10 // interpreting subsequent tokens as non-switch arguments, regardless of prefix.
  11
  12 // There is a singleton read-only CommandLine that represents the command line
  13 // that the current process was started with.  It must be initialized in main().
  14
  15 #ifndef BASE_COMMAND_LINE_H_
  16 #define BASE_COMMAND_LINE_H_
  17
  18 #include <stddef.h>
  19 #include <map>
  20 #include <string>
  21 #include <vector>
  22
  23 #include "base/base_export.h"
  24 #include "base/strings/string16.h"
  25 #include "build/build_config.h"
  26
  27 namespace base {
  28
  29 class FilePath;
  30
  31 class BASE_EXPORT CommandLine {
  32  public:
  33 #if defined(OS_WIN)
  34   // The native command line string type.
  35   typedef base::string16 StringType;
  36 #elif defined(OS_POSIX)
  37   typedef std::string StringType;
  38 #endif
  39
  40   typedef StringType::value_type CharType;
  41   typedef std::vector<StringType> StringVector;
  42   typedef std::map<std::string, StringType> SwitchMap;
  43
  44   // A constructor for CommandLines that only carry switches and arguments.
  45   enum NoProgram { NO_PROGRAM };
  46   explicit CommandLine(NoProgram no_program);
  47
  48   // Construct a new command line with |program| as argv[0].
  49   explicit CommandLine(const FilePath& program);
  50
  51   // Construct a new command line from an argument list.
  52   CommandLine(int argc, const CharType* const* argv);
  53   explicit CommandLine(const StringVector& argv);
  54
  55   ~CommandLine();
  56
  57 #if defined(OS_WIN)
  58   // By default this class will treat command-line arguments beginning with
  59   // slashes as switches on Windows, but not other platforms.
  60   //
  61   // If this behavior is inappropriate for your application, you can call this
  62   // function BEFORE initializing the current process' global command line
  63   // object and the behavior will be the same as Posix systems (only hyphens
  64   // begin switches, everything else will be an arg).
  65   static void set_slash_is_not_a_switch();
  66 #endif
  67
  68   // Initialize the current process CommandLine singleton. On Windows, ignores
  69   // its arguments (we instead parse GetCommandLineW() directly) because we
  70   // don't trust the CRT's parsing of the command line, but it still must be
  71   // called to set up the command line. Returns false if initialization has
  72   // already occurred, and true otherwise. Only the caller receiving a 'true'
  73   // return value should take responsibility for calling Reset.
  74   static bool Init(int argc, const char* const* argv);
  75
  76   // Destroys the current process CommandLine singleton. This is necessary if
  77   // you want to reset the base library to its initial state (for example, in an
  78   // outer library that needs to be able to terminate, and be re-initialized).
  79   // If Init is called only once, as in main(), Reset() is not necessary.
  80   static void Reset();
  81
  82   // Get the singleton CommandLine representing the current process's
  83   // command line. Note: returned value is mutable, but not thread safe;
  84   // only mutate if you know what you're doing!
  85   static CommandLine* ForCurrentProcess();
  86
  87   // Returns true if the CommandLine has been initialized for the given process.
  88   static bool InitializedForCurrentProcess();
  89
  90 #if defined(OS_WIN)
  91   static CommandLine FromString(const base::string16& command_line);
  92 #endif
  93
  94   // Initialize from an argv vector.
  95   void InitFromArgv(int argc, const CharType* const* argv);
  96   void InitFromArgv(const StringVector& argv);
  97
  98   // Constructs and returns the represented command line string.
  99   // CAUTION! This should be avoided on POSIX because quoting behavior is
 100   // unclear.
 101   StringType GetCommandLineString() const {
 102     return GetCommandLineStringInternal(false);
 103   }
 104
 105 #if defined(OS_WIN)
 106   // Constructs and returns the represented command line string. Assumes the
 107   // command line contains placeholders (eg, %1) and quotes any program or
 108   // argument with a '%' in it. This should be avoided unless the placeholder is
 109   // required by an external interface (eg, the Windows registry), because it is
 110   // not generally safe to replace it with an arbitrary string. If possible,
 111   // placeholders should be replaced *before* converting the command line to a
 112   // string.
 113   StringType GetCommandLineStringWithPlaceholders() const {
 114     return GetCommandLineStringInternal(true);
 115   }
 116 #endif
 117
 118   // Constructs and returns the represented arguments string.
 119   // CAUTION! This should be avoided on POSIX because quoting behavior is
 120   // unclear.
 121   StringType GetArgumentsString() const {
 122     return GetArgumentsStringInternal(false);
 123   }
 124
 125 #if defined(OS_WIN)
 126   // Constructs and returns the represented arguments string. Assumes the
 127   // command line contains placeholders (eg, %1) and quotes any argument with a
 128   // '%' in it. This should be avoided unless the placeholder is required by an
 129   // external interface (eg, the Windows registry), because it is not generally
 130   // safe to replace it with an arbitrary string. If possible, placeholders
 131   // should be replaced *before* converting the arguments to a string.
 132   StringType GetArgumentsStringWithPlaceholders() const {
 133     return GetArgumentsStringInternal(true);
 134   }
 135 #endif
 136
 137   // Returns the original command line string as a vector of strings.
 138   const StringVector& argv() const { return argv_; }
 139
 140   // Get and Set the program part of the command line string (the first item).
 141   FilePath GetProgram() const;
 142   void SetProgram(const FilePath& program);
 143
 144   // Returns true if this command line contains the given switch.
 145   // (Switch names are case-insensitive).
 146   bool HasSwitch(const std::string& switch_string) const;
 147
 148   // Returns the value associated with the given switch. If the switch has no
 149   // value or isn't present, this method returns the empty string.
 150   std::string GetSwitchValueASCII(const std::string& switch_string) const;
 151   FilePath GetSwitchValuePath(const std::string& switch_string) const;
 152   StringType GetSwitchValueNative(const std::string& switch_string) const;
 153
 154   // Get a copy of all switches, along with their values.
 155   const SwitchMap& GetSwitches() const { return switches_; }
 156
 157   // Append a switch [with optional value] to the command line.
 158   // Note: Switches will precede arguments regardless of appending order.
 159   void AppendSwitch(const std::string& switch_string);
 160   void AppendSwitchPath(const std::string& switch_string,
 161                         const FilePath& path);
 162   void AppendSwitchNative(const std::string& switch_string,
 163                           const StringType& value);
 164   void AppendSwitchASCII(const std::string& switch_string,
 165                          const std::string& value);
 166
 167   // Copy a set of switches (and any values) from another command line.
 168   // Commonly used when launching a subprocess.
 169   void CopySwitchesFrom(const CommandLine& source,
 170                         const char* const switches[],
 171                         size_t count);
 172
 173   // Get the remaining arguments to the command.
 174   StringVector GetArgs() const;
 175
 176   // Append an argument to the command line. Note that the argument is quoted
 177   // properly such that it is interpreted as one argument to the target command.
 178   // AppendArg is primarily for ASCII; non-ASCII input is interpreted as UTF-8.
 179   // Note: Switches will precede arguments regardless of appending order.
 180   void AppendArg(const std::string& value);
 181   void AppendArgPath(const FilePath& value);
 182   void AppendArgNative(const StringType& value);
 183
 184   // Append the switches and arguments from another command line to this one.
 185   // If |include_program| is true, include |other|'s program as well.
 186   void AppendArguments(const CommandLine& other, bool include_program);
 187
 188   // Insert a command before the current command.
 189   // Common for debuggers, like "valgrind" or "gdb --args".
 190   void PrependWrapper(const StringType& wrapper);
 191
 192 #if defined(OS_WIN)
 193   // Initialize by parsing the given command line string.
 194   // The program name is assumed to be the first item in the string.
 195   void ParseFromString(const base::string16& command_line);
 196 #endif
 197
 198  private:
 199   // Disallow default constructor; a program name must be explicitly specified.
 200   CommandLine();
 201   // Allow the copy constructor. A common pattern is to copy of the current
 202   // process's command line and then add some flags to it. For example:
 203   //   CommandLine cl(*CommandLine::ForCurrentProcess());
 204   //   cl.AppendSwitch(...);
 205
 206   // Internal version of GetCommandLineString. If |quote_placeholders| is true,
 207   // also quotes parts with '%' in them.
 208   StringType GetCommandLineStringInternal(bool quote_placeholders) const;
 209
 210   // Internal version of GetArgumentsString. If |quote_placeholders| is true,
 211   // also quotes parts with '%' in them.
 212   StringType GetArgumentsStringInternal(bool quote_placeholders) const;
 213
 214   // The singleton CommandLine representing the current process's command line.
 215   static CommandLine* current_process_commandline_;
 216
 217   // The argv array: { program, [(--|-|/)switch[=value]]*, [--], [argument]* }
 218   StringVector argv_;
 219
 220   // Parsed-out switch keys and values.
 221   SwitchMap switches_;
 222
 223   // The index after the program and switches, any arguments start here.
 224   size_t begin_args_;
 225 };
 226
 227 }  // namespace base
 228
 229 // TODO(brettw) remove once all callers specify the namespace properly.
 230 using base::CommandLine;
 231
 232 #endif  // BASE_COMMAND_LINE_H_