1. DNF5 Command Template

This page focuses on how to write a command with two options in dnf5.

Note

This code is thought to be self explanatory. You should be able to copy the snippets, following the directory structure and naming shown above each one.

dnf5/command/template.hpp

#define DNF5_COMMANDS_TEMPLATE_TEMPLATE_HPP
#include "arguments.hpp"

#include <dnf5/context.hpp>
#include <libdnf5/conf/option_bool.hpp>

#include <memory>
#include <vector>


namespace dnf5 {

// This template aims to explain how to add a new command to dnf5.
// This is the definition of a command called `template` with two options:
// --foo and --bar.
class TemplateCommand : public Command {
public:
    // The command name is set directly in the constructor.
    explicit TemplateCommand(Command & parent) : Command(parent, "template") {}

    // This method needs to be overridden to define the structure of the
    // command such as description, options or sub-commands.
    void set_argument_parser() override;

    // This method needs to be overridden to run the command.
    void run() override;

private:
    // There are two ways to specify options for a command.

    // Option 1: C++ Pointer.
    // Create a OptionBool pointer for the option you need.
    //
    // Using a pure C++ pointer is safe here since the OptionBool class
    // will take care of moving the pointer ownership to the parser, which will
    // be in charge of handling the memory deallocation.
    libdnf5::OptionBool * foo_option{nullptr};

    // Option 2: STL Unique Pointer
    // Create a unique_ptr<BarOption>
    //
    // This might be needed in case you need full control over the options and
    // do not want dnf5's parser to handle it.
    // To use a unique_ptr, BarOption has to be defined (see the file
    // dnf5/commands/arguments.hpp)
    std::unique_ptr<BarOption> bar_option{nullptr};
};


}  // namespace dnf5


#endif  // DNF5_COMMANDS_TEMPLATE_TEMPLATE_HPP

dnf5/command/template.cpp

namespace dnf5 {

using namespace libdnf5::cli;

void TemplateCommand::set_argument_parser() {
    // Context is the main object in dnf5.
    // It contains useful functions and pieces of information necessary to run
    // and interact with dnf5 capabilities.
    //
    // For example, here we need the parser object which is necessary to define
    // commands and options.
    auto & ctx = get_context();
    auto & parser = ctx.get_argument_parser();

    auto & cmd = *get_argument_parser_command();

    // Add template command to the Parser
    //
    // Set a description that would be displayed in the second column of the
    // help message would also add the command to the parser
    cmd.set_short_description("A command that prints its name and arguments' name");

    // Add foo and bar options
    //
    // Option 1: as said in the header file here you should handle the pointer
    // by giving up the ownership to dnf5's parser.
    // Set the default value here.
    foo_option = dynamic_cast<libdnf5::OptionBool *>(
        parser.add_init_value(std::unique_ptr<libdnf5::OptionBool>(new libdnf5::OptionBool(false))));

    // Create an option by giving it a name. It will be shown in the help message.
    // Set long name, description and constant value.
    // Link the option to the TemplateCommand's class member.
    auto foo = parser.add_new_named_arg("foo");
    foo->set_long_name("foo");
    foo->set_short_description("print foo");
    foo->set_const_value("true");
    foo->link_value(foo_option);

    // Register the argument to the command template.
    cmd.register_named_arg(foo);

    // Option 2: create a unique_ptr of type BarOption.
    // The long name, description, and other values were set in
    // dnf5/command/arguments.hpp
    bar_option = std::make_unique<BarOption>(*this);
}

void TemplateCommand::run() {
    // The behavior of the command is a simple hello world.
    std::cout << "Template Command" << std::endl;

    if (foo_option->get_value()) {
        std::cout << "foo" << std::endl;
    }
    if (bar_option->get_value()) {
        std::cout << "bar" << std::endl;
    }
}

}  // namespace dnf5

dnf5/command/arguments.hpp

#define DNF5_COMMANDS_TEMPLATE_ARGUMENTS_HPP

#include <libdnf5-cli/session.hpp>
#include <libdnf5/utils/bgettext/bgettext-lib.h>


namespace dnf5 {

// This implementation is needed only if you are using unique_ptr as the type
// for the option of your command.
// You will have to initialize the Option yourself.
class BarOption : public libdnf5::cli::session::BoolOption {
public:
    // Initialize the constructor passing command, long name, short name,
    // description and default value.
    explicit BarOption(libdnf5::cli::session::Command & command)
        : BoolOption(command, "bar", '\0', _("print bar"), false) {}
};

}  // namespace dnf5


#endif  // DNF_COMMANDS_DOWNLOAD_TEMPLATE_ARGUMENTS_HPP

The command must be included and registered in dnf5/main.cpp

// new commands must be included in main.cpp
#include "commands/template/template.hpp"

// commands must be registered like this
register_subcommand(std::make_unique<TemplateCommand>(*this), software_management_commands_group);

Following this example you should have an output like this.

$ dnf5 --help
...
Software Management Commands:
  install                                Install software
  upgrade                                Upgrade software
  ...
  template                               A command that prints its name and arguments' name

$ dnf5 template --help
Usage:
  dnf5 template [GLOBAL OPTIONS] [OPTIONS] [ARGUMENTS]

Options:
  --bar                         print bar
  --foo                         print foo