osquery-1/include/osquery/flags.h

/*
 *  Copyright (c) 2014, Facebook, Inc.
 *  All rights reserved.
 *
 *  This source code is licensed under the BSD-style license found in the
 *  LICENSE file in the root directory of this source tree. An additional grant 
 *  of patent rights can be found in the PATENTS file in the same directory.
 *
 */

#pragma once

#define STRIP_FLAG_HELP 1
#include <gflags/gflags.h>

#include <osquery/registry.h>
#include <osquery/status.h>

#define __GFLAGS_NAMESPACE google

namespace osquery {

/// Type, Value, Description.
typedef std::tuple<std::string, std::string, std::string> FlagDetail;

/**
 * @brief A small tracking wrapper for options, binary flags.
 *
 * The osquery-specific gflags-like options define macro `DEFINE_osquery_flag`
 * uses a Flag instance to track the options data.
 */
class Flag {
 public:
  /*
   * @brief the instance accessor, but also can register flag data.
   *
   * The accessor is mostly needless. The static instance and registration of
   * flag data requires the accessor wrapper.
   *
   * @param name The 'name' or the options switch data.
   * @param type The lexical type of the flag.
   * @param value The default value for this flag.
   * @param desc The description printed to the screen during help.
   * @param shell_only Only print flag help when using `OSQUERY_TOOL_SHELL`.
   *
   * @return A mostly needless flag instance.
   */
  static Flag& get(const std::string& name = "",
                   const std::string& type = "",
                   const std::string& value = "",
                   const std::string& desc = "",
                   bool shell_only = false);

  /*
   * @brief Wrapper by the Flag::get.
   *
   * @param name The 'name' or the options switch data.
   * @parma type The lexical type of the flag.
   * @param value The default value for this flag.
   * @param desc The description printed to the screen during help.
   * @param shell_only Restrict this flag to the shell help output.
   */
  void add(const std::string& name,
           const std::string& type,
           const std::string& value,
           const std::string& desc,
           bool shell_only);

 private:
  /// Keep the ctor private, for accessing through `add` wrapper.
  Flag() {}

 public:
  /// The public flags instance, usable when parsing `--help`.
  std::map<std::string, FlagDetail> flags() { return flags_; }
  /// The public flags instance, usable when parsing `--help` for the shell.
  std::map<std::string, FlagDetail> shellFlags() { return shell_flags_; }

  /*
   * @brief Access value for a flag name.
   *
   * @param name the flag name.
   * @param value output parameter filled with the flag value on success.
   * @return status of the flag did exist.
   */
  static Status getDefaultValue(const std::string& name, std::string& value);

  /*
   * @brief Check if flag value has been overridden.
   *
   * @param name the flag name.
   * @return is the flag set to its default value.
   */
  static bool isDefault(const std::string& name);

  /*
   * @brief Update the flag value by string name,
   *
   * @param name the flag name.
   * @parma value the new value.
   * @return if the value was updated.
   */
  static Status updateValue(const std::string& name, const std::string& value);

  /*
   * @brief Get the value of an osquery flag.
   *
   * @param name the flag name.
   */
  std::string getValue(const std::string& name);

  /*
   * @brief Print help-style output to stdout for a given flag set.
   *
   * @param flags A flag set (usually generated from Flag::flags).
   */
  static void printFlags(const std::map<std::string, FlagDetail> flags);

 private:
  /// The private simple map of name to value/desc flag data.
  std::map<std::string, FlagDetail> flags_;
  /// The private simple map of name to value/desc shell-only flag data.
  std::map<std::string, FlagDetail> shell_flags_;
};
}

/*
 * @brief Replace gflags' `DEFINE_type` macros to track osquery flags.
 *
 * @param type The `_type` symbol portion of the gflags define.
 * @param name The name symbol passed to gflags' `DEFINE_type`.
 * @param value The default value, use a C++ literal.
 * @param desc A string literal used for help display.
 */
#define DEFINE_osquery_flag(type, name, value, desc) \
  DEFINE_##type(name, value, desc);                  \
  namespace flag_##name {                            \
    Flag flag = Flag::get(#name, #type, #value, desc);      \
  }

/*
 * @brief A duplicate of DEFINE_osquery_flag except the help output will only
 * show when using OSQUERY_TOOL_SHELL (osqueryi).
 *
 * @param type The `_type` symbol portion of the gflags define.
 * @param name The name symbol passed to gflags' `DEFINE_type`.
 * @param value The default value, use a C++ literal.
 * @param desc A string literal used for help display.
 */
#define DEFINE_shell_flag(type, name, value, desc)    \
  DEFINE_##type(name, value, desc);                   \
  namespace flag_##name {                             \
    Flag flag = Flag::get(#name, #type, #value, desc, true); \
  }