folly::NestedCommandLineApp Class Reference

#include <NestedCommandLineApp.h>

Classes
struct	CommandInfo

Public Types
typedef std::function< void(const std::string &command, const boost::program_options::variables_map &options, const std::vector< std::string > &args)>	InitFunction
typedef std::function< void(const boost::program_options::variables_map &options, const std::vector< std::string > &)>	Command

Public Member Functions
	NestedCommandLineApp (std::string programName=std::string(), std::string version=std::string(), std::string programHeading=std::string(), std::string programHelpFooter=std::string(), InitFunction initFunction=InitFunction())
void	addGFlags (ProgramOptionsStyle style=ProgramOptionsStyle::GNU)
boost::program_options::options_description &	globalOptions ()
boost::program_options::options_description &	addCommand (std::string name, std::string argStr, std::string shortHelp, std::string fullHelp, Command command)
void	addAlias (std::string newName, std::string oldName)
int	run (int argc, const char *const argv[])
int	run (const std::vector< std::string > &args)
bool	isBuiltinCommand (const std::string &name) const

Static Public Attributes
static constexpr StringPiece const	kHelpCommand = "help"
static constexpr StringPiece const	kVersionCommand = "version"

Private Member Functions
void	doRun (const std::vector< std::string > &args)
const std::string &	resolveAlias (const std::string &name) const
const std::pair< const std::string, CommandInfo > &	findCommand (const std::string &name) const
void	displayHelp (const boost::program_options::variables_map &options, const std::vector< std::string > &args) const
void	displayVersion () const

Private Attributes
std::string	programName_
std::string	programHeading_
std::string	programHelpFooter_
std::string	version_
InitFunction	initFunction_
boost::program_options::options_description	globalOptions_
std::map< std::string, CommandInfo >	commands_
std::map< std::string, std::string >	aliases_
std::set< folly::StringPiece >	builtinCommands_

Detailed Description

App that uses a nested command line, of the form:

program [–global_options...] command [–command_options...] command_args...

Definition at line 51 of file NestedCommandLineApp.h.

Member Typedef Documentation

typedef std::function<void( const boost::program_options::variables_map& options, const std::vector<std::string>&)> folly::NestedCommandLineApp::Command

Definition at line 62 of file NestedCommandLineApp.h.

typedef std::function<void( const std::string& command, const boost::program_options::variables_map& options, const std::vector<std::string>& args)> folly::NestedCommandLineApp::InitFunction

Definition at line 57 of file NestedCommandLineApp.h.

Constructor & Destructor Documentation

folly::NestedCommandLineApp::NestedCommandLineApp ( std::string  programName = std::string(), std::string  version = std::string(), std::string  programHeading = std::string(), std::string  programHelpFooter = std::string(), InitFunction  initFunction = InitFunction()  )

explicit

Initialize the app.

If programName is not set, we try to guess (readlink("/proc/self/exe")).

version is the version string printed when given the –version flag.

initFunction, if specified, is called after parsing the command line, right before executing the command.

Definition at line 51 of file NestedCommandLineApp.cpp.

References addCommand(), builtinCommands_, displayHelp(), displayVersion(), globalOptions_, kHelpCommand, kVersionCommand, and folly::Range< Iter >::str().

    : programName_(std::move(programName)),
      programHeading_(std::move(programHeading)),
      programHelpFooter_(std::move(programHelpFooter)),
      version_(std::move(version)),
      initFunction_(std::move(initFunction)),
      globalOptions_("Global options") {
  addCommand(
      kHelpCommand.str(),
      "[command]",
      "Display help (globally or for a given command)",
      "Displays help (globally or for a given command).",
      [this](
          const po::variables_map& vm, const std::vector<std::string>& args) {
        displayHelp(vm, args);
      });
  builtinCommands_.insert(kHelpCommand);

  addCommand(
      kVersionCommand.str(),
      "[command]",
      "Display version information",
      "Displays version information.",
      [this](const po::variables_map&, const std::vector<std::string>&) {
        displayVersion();
      });
  builtinCommands_.insert(kVersionCommand);

  globalOptions_.add_options()(
      kHelpCommand.str().c_str(),
      "Display help (globally or for a given command)")(
      kVersionCommand.str().c_str(), "Display version information");
}

Member Function Documentation

void folly::NestedCommandLineApp::addAlias	(	std::string	newName,
		std::string	oldName
	)

Add an alias; running the command newName will have the same effect as running oldName.

Definition at line 109 of file NestedCommandLineApp.cpp.

References aliases_, commands_, and folly::gen::move.

Referenced by main().

                                                                        {
  CHECK(aliases_.count(oldName) || commands_.count(oldName))
      << "Alias old name does not exist";
  CHECK(!aliases_.count(newName) && !commands_.count(newName))
      << "Alias new name already exists";
  aliases_.emplace(std::move(newName), std::move(oldName));
}

po::options_description & folly::NestedCommandLineApp::addCommand	(	std::string	name,
		std::string	argStr,
		std::string	shortHelp,
		std::string	fullHelp,
		Command	command
	)

Add a command.

name: command name argStr: description of arguments in help strings (<filename> <N>) shortHelp: one-line summary help string fullHelp: full help string command: function to run

Returns a reference to the options_description object that you can use to add options for this command.

Definition at line 90 of file NestedCommandLineApp.cpp.

References commands_, deadlock::info(), folly::gen::move, and folly::sformat().

Referenced by main(), and NestedCommandLineApp().

                     {
  CommandInfo info{
      std::move(argStr),
      std::move(shortHelp),
      std::move(fullHelp),
      std::move(command),
      po::options_description(folly::sformat("Options for `{}'", name))};

  auto p = commands_.emplace(std::move(name), std::move(info));
  CHECK(p.second) << "Command already exists";

  return p.first->second.options;
}

void folly::NestedCommandLineApp::addGFlags ( ProgramOptionsStyle  style = ProgramOptionsStyle::GNU )

inline

Add GFlags to the list of supported options with the given style.

Definition at line 86 of file NestedCommandLineApp.h.

References folly::getGFlags().

Referenced by main().

                                                                     {
    globalOptions_.add(getGFlags(style));
  }

void folly::NestedCommandLineApp::displayHelp ( const boost::program_options::variables_map &  options, const std::vector< std::string > &  args  ) const

private

Definition at line 117 of file NestedCommandLineApp.cpp.

References aliases_, commands_, findCommand(), globalOptions_, deadlock::info(), max, programHeading_, programHelpFooter_, programName_, and resolveAlias().

Referenced by doRun(), and NestedCommandLineApp().

                                            {
  if (args.empty()) {
    // General help
    printf(
        "%s\nUsage: %s [global_options...] <command> [command_options...] "
        "[command_args...]\n\n",
        programHeading_.c_str(),
        programName_.c_str());
    std::cout << globalOptions_;
    printf("\nAvailable commands:\n");

    size_t maxLen = 0;
    for (auto& p : commands_) {
      maxLen = std::max(maxLen, p.first.size());
    }
    for (auto& p : aliases_) {
      maxLen = std::max(maxLen, p.first.size());
    }

    for (auto& p : commands_) {
      printf(
          "  %-*s    %s\n",
          int(maxLen),
          p.first.c_str(),
          p.second.shortHelp.c_str());
    }

    if (!aliases_.empty()) {
      printf("\nAvailable aliases:\n");
      for (auto& p : aliases_) {
        printf(
            "  %-*s => %s\n",
            int(maxLen),
            p.first.c_str(),
            resolveAlias(p.second).c_str());
      }
    }
    std::cout << "\n" << programHelpFooter_ << "\n";
  } else {
    // Help for a given command
    auto& p = findCommand(args.front());
    if (p.first != args.front()) {
      printf(
          "`%s' is an alias for `%s'; showing help for `%s'\n",
          args.front().c_str(),
          p.first.c_str(),
          p.first.c_str());
    }
    auto& info = p.second;

    printf(
        "Usage: %s [global_options...] %s%s%s%s\n\n",
        programName_.c_str(),
        p.first.c_str(),
        info.options.options().empty() ? "" : " [command_options...]",
        info.argStr.empty() ? "" : " ",
        info.argStr.c_str());

    printf("%s\n", info.fullHelp.c_str());

    std::cout << globalOptions_;

    if (!info.options.options().empty()) {
      printf("\n");
      std::cout << info.options;
    }
  }
}

void folly::NestedCommandLineApp::displayVersion ( ) const

private

Definition at line 188 of file NestedCommandLineApp.cpp.

References programName_, and version_.

Referenced by doRun(), and NestedCommandLineApp().

                                                {
  printf("%s %s\n", programName_.c_str(), version_.c_str());
}

void folly::NestedCommandLineApp::doRun ( const std::vector< std::string > &  args )

private

Definition at line 266 of file NestedCommandLineApp.cpp.

References cmd, displayHelp(), displayVersion(), findCommand(), globalOptions_, deadlock::info(), initFunction_, kHelpCommand, kVersionCommand, folly::parseNestedCommandLine(), programName_, folly::sformat(), and folly::Range< Iter >::str().

Referenced by run().

                                                                 {
  if (programName_.empty()) {
    programName_ = guessProgramName();
  }

  bool not_clean = false;
  std::vector<std::string> cleanArgs;
  std::vector<std::string> endArgs;

  for (auto& na : args) {
    if (na == "--") {
      not_clean = true;
    } else if (not_clean) {
      endArgs.push_back(na);
    } else {
      cleanArgs.push_back(na);
    }
  }

  auto parsed = parseNestedCommandLine(cleanArgs, globalOptions_);
  po::variables_map vm;
  po::store(parsed.options, vm);
  if (vm.count(kHelpCommand.str())) {
    std::vector<std::string> helpArgs;
    if (parsed.command) {
      helpArgs.push_back(*parsed.command);
    }
    displayHelp(vm, helpArgs);
    return;
  }

  if (vm.count(kVersionCommand.str())) {
    displayVersion();
    return;
  }

  if (!parsed.command) {
    throw ProgramExit(
        1,
        folly::sformat(
            "Command not specified. Run '{} {}' for help.",
            programName_,
            kHelpCommand));
  }

  auto& p = findCommand(*parsed.command);
  auto& cmd = p.first;
  auto& info = p.second;

  auto cmdOptions =
      po::command_line_parser(parsed.rest).options(info.options).run();

  po::store(cmdOptions, vm);
  po::notify(vm);

  auto cmdArgs =
      po::collect_unrecognized(cmdOptions.options, po::include_positional);

  cmdArgs.insert(cmdArgs.end(), endArgs.begin(), endArgs.end());

  if (initFunction_) {
    initFunction_(cmd, vm, cmdArgs);
  }

  info.command(vm, cmdArgs);
}

auto folly::NestedCommandLineApp::findCommand ( const std::string &  name ) const

private

Definition at line 205 of file NestedCommandLineApp.cpp.

References commands_, kHelpCommand, name, programName_, resolveAlias(), and folly::sformat().

Referenced by displayHelp(), and doRun().

                                                    {
  auto pos = commands_.find(resolveAlias(name));
  if (pos == commands_.end()) {
    throw ProgramExit(
        1,
        folly::sformat(
            "Command '{}' not found. Run '{} {}' for help.",
            name,
            programName_,
            kHelpCommand));
  }
  return *pos;
}

boost::program_options::options_description& folly::NestedCommandLineApp::globalOptions ( )

inline

Return the global options object, so you can add options.

Definition at line 93 of file NestedCommandLineApp.h.

References argv, name, folly::run(), and string.

                                                           {
    return globalOptions_;
  }

bool folly::NestedCommandLineApp::isBuiltinCommand

(

const std::string &

name

)

const

Return true if name represent known built-in command (help, version)

Definition at line 333 of file NestedCommandLineApp.cpp.

References builtinCommands_.

Referenced by folly::test::TEST().

                                                                       {
  return builtinCommands_.count(name);
}

const std::string & folly::NestedCommandLineApp::resolveAlias ( const std::string &  name ) const

private

Definition at line 192 of file NestedCommandLineApp.cpp.

References aliases_, upload::dest, and name.

Referenced by displayHelp(), and findCommand().

                                 {
  auto dest = &name;
  for (;;) {
    auto pos = aliases_.find(*dest);
    if (pos == aliases_.end()) {
      break;
    }
    dest = &pos->second;
  }
  return *dest;
}

int folly::NestedCommandLineApp::run	(	int	argc,
		const char *const	argv[]
	)

Run the command and return; the return code is 0 on success or non-zero on error, so it is idiomatic to call this at the end of main(): return app.run(argc, argv);

On successful exit, run() will check for errors on stdout (and flush it) to help command-line applications that need to write to stdout (failing to write to stdout is an error). If there is an error on stdout, we'll print a helpful message on stderr and return an error status (1).

Definition at line 220 of file NestedCommandLineApp.cpp.

References programName_.

Referenced by main().

                                                                {
  if (programName_.empty()) {
    programName_ = fs::path(argv[0]).filename().string();
  }
  return run(std::vector<std::string>(argv + 1, argv + argc));
}

int folly::NestedCommandLineApp::run

(

const std::vector< std::string > &

args

)

Definition at line 227 of file NestedCommandLineApp.cpp.

References doRun(), folly::errnoStr(), folly::pushmi::operators::error(), kHelpCommand, programName_, folly::sformat(), and folly::ProgramExit::status().

                                                              {
  int status;
  try {
    doRun(args);
    status = 0;
  } catch (const ProgramExit& ex) {
    if (ex.what()[0]) { // if not empty
      fprintf(stderr, "%s\n", ex.what());
    }
    status = ex.status();
  } catch (const po::error& ex) {
    fprintf(
        stderr,
        "%s",
        folly::sformat(
            "{}. Run '{} help' for {}.\n",
            ex.what(),
            programName_,
            kHelpCommand)
            .c_str());
    status = 1;
  }

  if (status == 0) {
    if (ferror(stdout)) {
      fprintf(stderr, "error on standard output\n");
      status = 1;
    } else if (fflush(stdout)) {
      fprintf(
          stderr,
          "standard output flush failed: %s\n",
          errnoStr(errno).c_str());
      status = 1;
    }
  }

  return status;
}

Member Data Documentation

std::map<std::string, std::string> folly::NestedCommandLineApp::aliases_

private

Definition at line 169 of file NestedCommandLineApp.h.

Referenced by addAlias(), displayHelp(), and resolveAlias().

std::set<folly::StringPiece> folly::NestedCommandLineApp::builtinCommands_

private

Definition at line 170 of file NestedCommandLineApp.h.

Referenced by isBuiltinCommand(), and NestedCommandLineApp().

std::map<std::string, CommandInfo> folly::NestedCommandLineApp::commands_

private

Definition at line 168 of file NestedCommandLineApp.h.

Referenced by addAlias(), addCommand(), displayHelp(), and findCommand().

boost::program_options::options_description folly::NestedCommandLineApp::globalOptions_

private

Definition at line 167 of file NestedCommandLineApp.h.

Referenced by displayHelp(), doRun(), and NestedCommandLineApp().

InitFunction folly::NestedCommandLineApp::initFunction_

private

Definition at line 166 of file NestedCommandLineApp.h.

Referenced by doRun().

constexpr StringPiece const folly::NestedCommandLineApp::kHelpCommand = "help"

static

Definition at line 64 of file NestedCommandLineApp.h.

Referenced by doRun(), findCommand(), NestedCommandLineApp(), folly::ProgramExit::ProgramExit(), run(), and folly::test::TEST().

constexpr StringPiece const folly::NestedCommandLineApp::kVersionCommand = "version"

static

Definition at line 65 of file NestedCommandLineApp.h.

Referenced by doRun(), NestedCommandLineApp(), folly::ProgramExit::ProgramExit(), and folly::test::TEST().

std::string folly::NestedCommandLineApp::programHeading_

private

Definition at line 163 of file NestedCommandLineApp.h.

Referenced by displayHelp().

std::string folly::NestedCommandLineApp::programHelpFooter_

private

Definition at line 164 of file NestedCommandLineApp.h.

Referenced by displayHelp().

std::string folly::NestedCommandLineApp::programName_

private

Definition at line 162 of file NestedCommandLineApp.h.

Referenced by displayHelp(), displayVersion(), doRun(), findCommand(), and run().

std::string folly::NestedCommandLineApp::version_

private

Definition at line 165 of file NestedCommandLineApp.h.

Referenced by displayVersion().

---

The documentation for this class was generated from the following files:

• proxygen/folly/folly/experimental/NestedCommandLineApp.h
• proxygen/folly/folly/experimental/NestedCommandLineApp.cpp