Code/Engine/Foundation/Utilities/CommandLineUtils.h - dev - redgpu/ezEngine

Code/Engine/Foundation/Utilities/CommandLineUtils.h
186 строк9 KB
Sanakan8472
Cross-platform tracing system (ETW, LTTNG, Perfetto) (#1815)
15 фев 2026, 10:24
15 фев 2026, 10:24fac0c1f
#pragma once

#include <Foundation/Basics.h>
#include <Foundation/Containers/DynamicArray.h>
#include <Foundation/Strings/String.h>
#include <Foundation/Strings/StringBuilder.h>

/// \brief This is a helper class to parse command lines.
///
/// Initialize it using SetCommandLine(). Then query for command line options using GetStringOption(), GetBoolOption(), GetIntOption()
/// or GetFloatOption().
///
/// Command line format:
/// - Options start with a hyphen (-) and can have zero or more arguments
/// - Arguments that don't start with a hyphen are considered values for the preceding option
/// - Boolean options can be specified alone (-verbose) or with a value (-verbose true)
/// - Multiple arguments can follow an option (-input file1.txt file2.txt)
///
/// Examples:
/// - Simple flags: "-verbose -debug"
/// - Options with values: "-input data.txt -output result.bin"
/// - Multiple values: "-files a.txt b.txt c.txt -count 3"
/// - Mixed usage: "-v -input file.dat -threads 4 -optimize"
class EZ_FOUNDATION_DLL ezCommandLineUtils
{
public:
  enum ArgMode
  {
    UseArgcArgv,  ///< Use the passed in argc/argv values as they are passed in. May have limited Unicode support on some platforms.
    PreferOsArgs, ///< On Windows, ignore argc/argv and query arguments directly from GetCommandLineW(). This provides full Unicode
                  ///< support and handles special characters correctly. On non-Windows platforms, falls back to UseArgcArgv behavior.
  };

  /// \brief Returns one global instance of ezCommandLineUtils.
  static ezCommandLineUtils* GetGlobalInstance();

  /// \brief Splits a string into the classic argc/argv string.
  ///
  /// Useful for platforms where command line args come in as a single string.
  /// \param addExecutableDir
  ///   Adds executable path as first parameter (just as it would normally be in 'int main(argc, argv)').
  static void SplitCommandLineString(ezStringView sCommandString, bool bAddExecutableDir, ezDynamicArray<ezString>& out_args, ezDynamicArray<const char*>& out_argsV);

  /// \brief Initializes ezCommandLineUtils from the parameter arguments that were passed to the application.
  void SetCommandLine(ezUInt32 uiArgc, const char** pArgv, ArgMode mode = UseArgcArgv); // [tested]

  /// \brief Overload for non-const argv versions.
  void SetCommandLine(ezUInt32 uiArgc, char** pArgv, ArgMode mode = UseArgcArgv)
  {
    SetCommandLine(uiArgc, const_cast<const char**>(pArgv), mode);
  }

  /// \brief Initializes ezCommandLineUtils from a list of already split up commands.
  void SetCommandLine(ezArrayPtr<ezString> commands);

#if EZ_ENABLED(EZ_PLATFORM_WINDOWS_DESKTOP)
  /// \brief Initializes ezCommandLineUtils by querying the command line parameters directly from the OS.
  ///
  /// This function is not available on all platforms.
  void SetCommandLine();
#endif

  /// \brief Returns the split up command line.
  const ezDynamicArray<ezString>& GetCommandLineArray() const;

  /// \brief Assembles the original command line from the split up string representation.
  ezString GetCommandLineString() const;

  /// \brief Returns the total number of command line parameters (excluding the program path, which is often passed as the first parameter).
  ezUInt32 GetParameterCount() const; // [tested]

  /// \brief Returns the n-th parameter string that was passed to the application.
  const ezString& GetParameter(ezUInt32 uiParam) const; // [tested]

  /// \brief Returns the index at which the given option string can be found in the parameter list.
  ///
  /// \param szOption
  ///   The name of the command line option. Must start with a hyphen (-)
  /// \param bCaseSensitive
  ///   Whether the option name szOption shall be searched case sensitive.
  ///
  /// \return
  ///  -1 When no option with the given name is found.
  ///  Otherwise the index at which the option can be found. This can be passed to GetParameter() or GetStringOptionArguments().
  ezInt32 GetOptionIndex(ezStringView sOption, bool bCaseSensitive = false) const; // [tested]

  /// \brief Returns whether the requested option is specified, at all.
  bool HasOption(ezStringView sOption, bool bCaseSensitive = false) const;

  /// \brief Returns how many arguments follow behind the option with the name \a szOption.
  ///
  /// Everything that does not start with a hyphen is considered to be an additional parameter for the option.
  ezUInt32 GetStringOptionArguments(ezStringView sOption, bool bCaseSensitive = false) const; // [tested]

  /// \brief Returns the n-th parameter to the command line option with the name \a szOption.
  ///
  /// If the option does not exist or does not have that many parameters, \a szDefault is returned.
  ezStringView GetStringOption(ezStringView sOption, ezUInt32 uiArgument = 0, ezStringView sDefault = {},
    bool bCaseSensitive = false) const; // [tested]

  /// \brief Similar to GetStringOption() but assumes that the strings represent paths and concatenates the current working directory if a relative
  /// path is given.
  ///
  /// To check how many arguments are available, use GetStringOptionArguments().
  /// \note This function always returns absolute or rooted paths, never relative ones. If relative paths are supposed to be allowed,
  /// use GetStringOption() instead.
  ///
  /// If szDefault is empty and the user did not provide this option, then the result will also be the empty string.
  /// If szDefault is a relative path, it will be concatenated with the CWD just as any user provided option would.
  const ezString GetAbsolutePathOption(ezStringView sOption, ezUInt32 uiArgument = 0, ezStringView sDefault = {}, bool bCaseSensitive = false) const;

  /// \brief Returns a boolean interpretation of the option \a szOption or bDefault if it cannot be found.
  ///
  /// \param szOption
  ///   The name of the option to search for. All option-names must start with a hyphen.
  ///
  /// \param bDefault
  ///   The default value to use when no other value can be derived.
  ///
  /// \param bCaseSensitive
  ///   Whether it should be searched case-sensitive for the option with name \a szOption.
  ///
  /// \return
  ///   If an option with the name \a szOption can be found, which has no parameters, it is interpreted as 'true'.
  ///   If there is one parameter following, it is interpreted using ezConversionUtils::StringToBool().
  ///   If that conversion fails, bDefault is returned.
  bool GetBoolOption(ezStringView sOption, bool bDefault = false, bool bCaseSensitive = false) const; // [tested]

  /// \brief Returns an integer interpretation of the option \a szOption or iDefault if it cannot be found.
  ///
  /// \param szOption
  ///   The name of the option to search for. All option-names must start with a hyphen.
  ///
  /// \param iDefault
  ///   The default value to use when no other value can be derived.
  ///
  /// \param bCaseSensitive
  ///   Whether it should be searched case-sensitive for the option with name \a szOption.
  ///
  /// \return
  ///   If an option with the name \a szOption can be found, and there is one parameter following,
  ///   it is interpreted using ezConversionUtils::StringToInt().
  ///   If that conversion fails or there is no such option or no parameter follows it, iDefault is returned.
  ezInt32 GetIntOption(ezStringView sOption, ezInt32 iDefault = 0, bool bCaseSensitive = false) const; // [tested]

  /// \brief Same as GetIntOption() but assumes the value is a uint32.
  ezUInt32 GetUIntOption(ezStringView sOption, ezUInt32 uiDefault = 0, bool bCaseSensitive = false) const; // [tested]

  /// \brief Returns a float interpretation of the option \a szOption or fDefault if it cannot be found.
  ///
  /// \param szOption
  ///   The name of the option to search for. All option-names must start with a hyphen.
  ///
  /// \param fDefault
  ///   The default value to use when no other value can be derived.
  ///
  /// \param bCaseSensitive
  ///   Whether it should be searched case-sensitive for the option with name \a szOption.
  ///
  /// \return
  ///   If an option with the name \a szOption can be found, and there is one parameter following,
  ///   it is interpreted using ezConversionUtils::StringToFloat().
  ///   If that conversion fails or there is no such option or no parameter follows it, fDefault is returned.
  double GetFloatOption(ezStringView sOption, double fDefault = 0.0, bool bCaseSensitive = false) const; // [tested]

  /// \brief Appends an argument programmatically, as if it was specified on the command line.
  ///
  /// This can be useful when the command-line is a method to configure something, which might be hidden away in a plugin,
  /// and we have no other easy way to configure it. Also useful for programmatically adding default values or
  /// configuration overrides.
  ///
  /// Each call to this function adds one command line argument. Therefore to add "-arg test", call it two times,
  /// once with "-arg", once with "test". To add a string with spaces, call it once, but do not wrap the string
  /// in artificial quotes - the function handles strings with spaces correctly.
  ///
  /// Example usage:
  /// \code
  ///   cmdLine.InjectCustomArgument("-config");
  ///   cmdLine.InjectCustomArgument("default.cfg");
  ///   cmdLine.InjectCustomArgument("path with spaces");  // Handled correctly without quotes
  /// \endcode
  void InjectCustomArgument(ezStringView sArgument); // [tested]

private:
  ezDynamicArray<ezString> m_Commands;
};