2016-02-09 20:07:48 +00:00
|
|
|
|
#pragma once
|
2023-04-01 03:18:41 +00:00
|
|
|
|
///@file
|
2016-02-09 20:07:48 +00:00
|
|
|
|
|
|
|
|
|
#include <iostream>
|
|
|
|
|
#include <map>
|
|
|
|
|
#include <memory>
|
|
|
|
|
|
2020-08-17 15:44:52 +00:00
|
|
|
|
#include <nlohmann/json_fwd.hpp>
|
|
|
|
|
|
2016-02-09 20:07:48 +00:00
|
|
|
|
#include "util.hh"
|
|
|
|
|
|
|
|
|
|
namespace nix {
|
|
|
|
|
|
|
|
|
|
enum HashType : char;
|
|
|
|
|
|
2021-09-13 12:41:28 +00:00
|
|
|
|
class MultiCommand;
|
|
|
|
|
|
2016-02-09 20:07:48 +00:00
|
|
|
|
class Args
|
|
|
|
|
{
|
|
|
|
|
public:
|
|
|
|
|
|
2023-03-27 01:12:25 +00:00
|
|
|
|
/**
|
|
|
|
|
* Parse the command line, throwing a UsageError if something goes
|
|
|
|
|
* wrong.
|
|
|
|
|
*/
|
2016-02-09 20:07:48 +00:00
|
|
|
|
void parseCmdline(const Strings & cmdline);
|
|
|
|
|
|
2023-03-27 01:12:25 +00:00
|
|
|
|
/**
|
|
|
|
|
* Return a short one-line description of the command.
|
|
|
|
|
*/
|
2016-02-09 20:07:48 +00:00
|
|
|
|
virtual std::string description() { return ""; }
|
|
|
|
|
|
2022-01-31 17:03:24 +00:00
|
|
|
|
virtual bool forceImpureByDefault() { return false; }
|
|
|
|
|
|
2023-03-27 01:12:25 +00:00
|
|
|
|
/**
|
|
|
|
|
* Return documentation about this command, in Markdown format.
|
|
|
|
|
*/
|
2020-12-07 12:04:24 +00:00
|
|
|
|
virtual std::string doc() { return ""; }
|
|
|
|
|
|
2016-02-09 20:07:48 +00:00
|
|
|
|
protected:
|
|
|
|
|
|
2024-03-04 03:38:33 +00:00
|
|
|
|
/**
|
|
|
|
|
* The largest `size_t` is used to indicate the "any" arity, for
|
|
|
|
|
* handlers/flags/arguments that accept an arbitrary number of
|
|
|
|
|
* arguments.
|
|
|
|
|
*/
|
2017-08-29 12:28:57 +00:00
|
|
|
|
static const size_t ArityAny = std::numeric_limits<size_t>::max();
|
|
|
|
|
|
2024-03-04 03:38:33 +00:00
|
|
|
|
/**
|
|
|
|
|
* Arguments (flags/options and positional) have a "handler" which is
|
|
|
|
|
* caused when the argument is parsed. The handler has an arbitrary side
|
|
|
|
|
* effect, including possible affect further command-line parsing.
|
|
|
|
|
*
|
|
|
|
|
* There are many constructors in order to support many shorthand
|
|
|
|
|
* initializations, and this is used a lot.
|
|
|
|
|
*/
|
2020-05-11 13:46:18 +00:00
|
|
|
|
struct Handler
|
|
|
|
|
{
|
|
|
|
|
std::function<void(std::vector<std::string>)> fun;
|
|
|
|
|
size_t arity;
|
|
|
|
|
|
|
|
|
|
Handler() {}
|
|
|
|
|
|
|
|
|
|
Handler(std::function<void(std::vector<std::string>)> && fun)
|
|
|
|
|
: fun(std::move(fun))
|
|
|
|
|
, arity(ArityAny)
|
|
|
|
|
{ }
|
|
|
|
|
|
|
|
|
|
Handler(std::function<void()> && handler)
|
|
|
|
|
: fun([handler{std::move(handler)}](std::vector<std::string>) { handler(); })
|
|
|
|
|
, arity(0)
|
|
|
|
|
{ }
|
|
|
|
|
|
|
|
|
|
Handler(std::function<void(std::string)> && handler)
|
|
|
|
|
: fun([handler{std::move(handler)}](std::vector<std::string> ss) {
|
|
|
|
|
handler(std::move(ss[0]));
|
|
|
|
|
})
|
|
|
|
|
, arity(1)
|
|
|
|
|
{ }
|
|
|
|
|
|
|
|
|
|
Handler(std::function<void(std::string, std::string)> && handler)
|
|
|
|
|
: fun([handler{std::move(handler)}](std::vector<std::string> ss) {
|
|
|
|
|
handler(std::move(ss[0]), std::move(ss[1]));
|
|
|
|
|
})
|
|
|
|
|
, arity(2)
|
|
|
|
|
{ }
|
|
|
|
|
|
|
|
|
|
Handler(std::vector<std::string> * dest)
|
|
|
|
|
: fun([=](std::vector<std::string> ss) { *dest = ss; })
|
|
|
|
|
, arity(ArityAny)
|
|
|
|
|
{ }
|
|
|
|
|
|
2021-01-08 09:44:55 +00:00
|
|
|
|
Handler(std::string * dest)
|
|
|
|
|
: fun([=](std::vector<std::string> ss) { *dest = ss[0]; })
|
|
|
|
|
, arity(1)
|
|
|
|
|
{ }
|
|
|
|
|
|
|
|
|
|
Handler(std::optional<std::string> * dest)
|
2020-05-11 13:46:18 +00:00
|
|
|
|
: fun([=](std::vector<std::string> ss) { *dest = ss[0]; })
|
|
|
|
|
, arity(1)
|
|
|
|
|
{ }
|
|
|
|
|
|
|
|
|
|
template<class T>
|
|
|
|
|
Handler(T * dest, const T & val)
|
|
|
|
|
: fun([=](std::vector<std::string> ss) { *dest = val; })
|
|
|
|
|
, arity(0)
|
|
|
|
|
{ }
|
2021-01-08 09:44:55 +00:00
|
|
|
|
|
|
|
|
|
template<class I>
|
|
|
|
|
Handler(I * dest)
|
|
|
|
|
: fun([=](std::vector<std::string> ss) {
|
2021-01-08 11:51:19 +00:00
|
|
|
|
*dest = string2IntWithUnitPrefix<I>(ss[0]);
|
2021-01-08 09:44:55 +00:00
|
|
|
|
})
|
|
|
|
|
, arity(1)
|
|
|
|
|
{ }
|
2021-09-14 17:05:28 +00:00
|
|
|
|
|
|
|
|
|
template<class I>
|
|
|
|
|
Handler(std::optional<I> * dest)
|
|
|
|
|
: fun([=](std::vector<std::string> ss) {
|
|
|
|
|
*dest = string2IntWithUnitPrefix<I>(ss[0]);
|
|
|
|
|
})
|
|
|
|
|
, arity(1)
|
|
|
|
|
{ }
|
2020-05-11 13:46:18 +00:00
|
|
|
|
};
|
|
|
|
|
|
2024-03-04 03:38:33 +00:00
|
|
|
|
/**
|
|
|
|
|
* Description of flags / options
|
|
|
|
|
*
|
|
|
|
|
* These are arguments like `-s` or `--long` that can (mostly)
|
|
|
|
|
* appear in any order.
|
|
|
|
|
*/
|
2016-02-09 20:07:48 +00:00
|
|
|
|
struct Flag
|
|
|
|
|
{
|
2017-06-07 16:41:20 +00:00
|
|
|
|
typedef std::shared_ptr<Flag> ptr;
|
2020-05-04 20:40:19 +00:00
|
|
|
|
|
2017-06-07 16:41:20 +00:00
|
|
|
|
std::string longName;
|
2021-02-07 19:44:56 +00:00
|
|
|
|
std::set<std::string> aliases;
|
2017-06-07 16:41:20 +00:00
|
|
|
|
char shortName = 0;
|
2016-02-09 20:07:48 +00:00
|
|
|
|
std::string description;
|
2017-06-07 16:41:20 +00:00
|
|
|
|
std::string category;
|
2020-05-04 20:40:19 +00:00
|
|
|
|
Strings labels;
|
|
|
|
|
Handler handler;
|
2020-05-10 19:35:07 +00:00
|
|
|
|
std::function<void(size_t, std::string_view)> completer;
|
2020-05-04 20:40:19 +00:00
|
|
|
|
|
2023-01-17 00:13:31 +00:00
|
|
|
|
std::optional<ExperimentalFeature> experimentalFeature;
|
|
|
|
|
|
2020-05-04 20:40:19 +00:00
|
|
|
|
static Flag mkHashTypeFlag(std::string && longName, HashType * ht);
|
2020-06-02 18:25:32 +00:00
|
|
|
|
static Flag mkHashTypeOptFlag(std::string && longName, std::optional<HashType> * oht);
|
2016-02-09 20:07:48 +00:00
|
|
|
|
};
|
|
|
|
|
|
2024-03-04 03:38:33 +00:00
|
|
|
|
/**
|
|
|
|
|
* Index of all registered "long" flag descriptions (flags like
|
|
|
|
|
* `--long`).
|
|
|
|
|
*/
|
2017-06-07 16:41:20 +00:00
|
|
|
|
std::map<std::string, Flag::ptr> longFlags;
|
2024-03-04 03:38:33 +00:00
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Index of all registered "short" flag descriptions (flags like
|
|
|
|
|
* `-s`).
|
|
|
|
|
*/
|
2017-06-07 16:41:20 +00:00
|
|
|
|
std::map<char, Flag::ptr> shortFlags;
|
2016-02-09 20:07:48 +00:00
|
|
|
|
|
2024-03-04 03:38:33 +00:00
|
|
|
|
/**
|
|
|
|
|
* Process a single flag and its arguments, pulling from an iterator
|
|
|
|
|
* of raw CLI args as needed.
|
|
|
|
|
*/
|
2016-02-09 20:07:48 +00:00
|
|
|
|
virtual bool processFlag(Strings::iterator & pos, Strings::iterator end);
|
|
|
|
|
|
2024-03-04 03:38:33 +00:00
|
|
|
|
/**
|
|
|
|
|
* Description of positional arguments
|
|
|
|
|
*
|
|
|
|
|
* These are arguments that do not start with a `-`, and for which
|
|
|
|
|
* the order does matter.
|
|
|
|
|
*/
|
2016-02-09 20:07:48 +00:00
|
|
|
|
struct ExpectedArg
|
|
|
|
|
{
|
|
|
|
|
std::string label;
|
2020-05-10 19:35:07 +00:00
|
|
|
|
bool optional = false;
|
2020-05-11 13:46:18 +00:00
|
|
|
|
Handler handler;
|
|
|
|
|
std::function<void(size_t, std::string_view)> completer;
|
2016-02-09 20:07:48 +00:00
|
|
|
|
};
|
|
|
|
|
|
2024-03-04 03:38:33 +00:00
|
|
|
|
/**
|
|
|
|
|
* Queue of expected positional argument forms.
|
|
|
|
|
*
|
|
|
|
|
* Positional arugment descriptions are inserted on the back.
|
|
|
|
|
*
|
|
|
|
|
* As positional arguments are passed, these are popped from the
|
|
|
|
|
* front, until there are hopefully none left as all args that were
|
|
|
|
|
* expected in fact were passed.
|
|
|
|
|
*/
|
2016-02-09 20:07:48 +00:00
|
|
|
|
std::list<ExpectedArg> expectedArgs;
|
|
|
|
|
|
2024-03-04 03:38:33 +00:00
|
|
|
|
/**
|
|
|
|
|
* Process some positional arugments
|
|
|
|
|
*
|
|
|
|
|
* @param finish: We have parsed everything else, and these are the only
|
|
|
|
|
* arguments left. Used because we accumulate some "pending args" we might
|
|
|
|
|
* have left over.
|
|
|
|
|
*/
|
2016-02-09 20:07:48 +00:00
|
|
|
|
virtual bool processArgs(const Strings & args, bool finish);
|
|
|
|
|
|
2020-12-03 21:45:44 +00:00
|
|
|
|
virtual Strings::iterator rewriteArgs(Strings & args, Strings::iterator pos)
|
|
|
|
|
{ return pos; }
|
|
|
|
|
|
2017-06-07 16:41:20 +00:00
|
|
|
|
std::set<std::string> hiddenCategories;
|
|
|
|
|
|
2023-03-27 01:12:25 +00:00
|
|
|
|
/**
|
|
|
|
|
* Called after all command line flags before the first non-flag
|
|
|
|
|
* argument (if any) have been processed.
|
|
|
|
|
*/
|
2021-01-28 14:37:43 +00:00
|
|
|
|
virtual void initialFlagsProcessed() {}
|
|
|
|
|
|
2023-03-27 01:12:25 +00:00
|
|
|
|
/**
|
|
|
|
|
* Called after the command line has been processed if we need to generate
|
|
|
|
|
* completions. Useful for commands that need to know the whole command line
|
|
|
|
|
* in order to know what completions to generate.
|
|
|
|
|
*/
|
2022-06-20 02:15:38 +00:00
|
|
|
|
virtual void completionHook() { }
|
|
|
|
|
|
2016-02-09 20:07:48 +00:00
|
|
|
|
public:
|
|
|
|
|
|
2020-05-04 20:40:19 +00:00
|
|
|
|
void addFlag(Flag && flag);
|
2017-06-07 16:41:20 +00:00
|
|
|
|
|
2021-02-26 13:55:54 +00:00
|
|
|
|
void removeFlag(const std::string & longName);
|
|
|
|
|
|
2020-05-11 13:46:18 +00:00
|
|
|
|
void expectArgs(ExpectedArg && arg)
|
|
|
|
|
{
|
|
|
|
|
expectedArgs.emplace_back(std::move(arg));
|
|
|
|
|
}
|
|
|
|
|
|
2023-03-27 01:12:25 +00:00
|
|
|
|
/**
|
|
|
|
|
* Expect a string argument.
|
|
|
|
|
*/
|
2022-02-25 15:00:00 +00:00
|
|
|
|
void expectArg(const std::string & label, std::string * dest, bool optional = false)
|
2016-02-09 20:07:48 +00:00
|
|
|
|
{
|
2020-05-11 13:46:18 +00:00
|
|
|
|
expectArgs({
|
|
|
|
|
.label = label,
|
2020-09-25 08:27:40 +00:00
|
|
|
|
.optional = optional,
|
2020-05-11 13:46:18 +00:00
|
|
|
|
.handler = {dest}
|
|
|
|
|
});
|
2016-02-09 20:07:48 +00:00
|
|
|
|
}
|
|
|
|
|
|
2023-03-27 01:12:25 +00:00
|
|
|
|
/**
|
|
|
|
|
* Expect 0 or more arguments.
|
|
|
|
|
*/
|
2017-10-24 10:45:11 +00:00
|
|
|
|
void expectArgs(const std::string & label, std::vector<std::string> * dest)
|
2016-02-09 20:07:48 +00:00
|
|
|
|
{
|
2020-05-11 13:46:18 +00:00
|
|
|
|
expectArgs({
|
|
|
|
|
.label = label,
|
|
|
|
|
.handler = {dest}
|
|
|
|
|
});
|
2016-02-09 20:07:48 +00:00
|
|
|
|
}
|
2016-02-09 20:28:29 +00:00
|
|
|
|
|
2020-08-17 15:44:52 +00:00
|
|
|
|
virtual nlohmann::json toJSON();
|
|
|
|
|
|
2016-02-09 20:28:29 +00:00
|
|
|
|
friend class MultiCommand;
|
2021-09-13 12:41:28 +00:00
|
|
|
|
|
2024-03-04 03:38:33 +00:00
|
|
|
|
/**
|
|
|
|
|
* The parent command, used if this is a subcommand.
|
|
|
|
|
*/
|
2021-09-13 12:41:28 +00:00
|
|
|
|
MultiCommand * parent = nullptr;
|
2023-01-17 00:13:31 +00:00
|
|
|
|
|
|
|
|
|
private:
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Experimental features needed when parsing args. These are checked
|
|
|
|
|
* after flag parsing is completed in order to support enabling
|
|
|
|
|
* experimental features coming after the flag that needs the
|
|
|
|
|
* experimental feature.
|
|
|
|
|
*/
|
|
|
|
|
std::set<ExperimentalFeature> flagExperimentalFeatures;
|
2016-02-09 20:07:48 +00:00
|
|
|
|
};
|
|
|
|
|
|
2023-03-27 01:12:25 +00:00
|
|
|
|
/**
|
|
|
|
|
* A command is an argument parser that can be executed by calling its
|
|
|
|
|
* run() method.
|
|
|
|
|
*/
|
2021-09-13 12:41:28 +00:00
|
|
|
|
struct Command : virtual public Args
|
2018-11-22 15:03:31 +00:00
|
|
|
|
{
|
2019-06-19 21:37:40 +00:00
|
|
|
|
friend class MultiCommand;
|
|
|
|
|
|
2018-11-22 15:03:31 +00:00
|
|
|
|
virtual ~Command() { }
|
2019-06-18 14:01:35 +00:00
|
|
|
|
|
2023-03-27 01:12:25 +00:00
|
|
|
|
/**
|
|
|
|
|
* Entry point to the command
|
|
|
|
|
*/
|
2018-11-22 15:03:31 +00:00
|
|
|
|
virtual void run() = 0;
|
|
|
|
|
|
2020-05-05 13:18:23 +00:00
|
|
|
|
typedef int Category;
|
|
|
|
|
|
|
|
|
|
static constexpr Category catDefault = 0;
|
|
|
|
|
|
2023-01-17 04:01:18 +00:00
|
|
|
|
virtual std::optional<ExperimentalFeature> experimentalFeature ();
|
|
|
|
|
|
2020-05-05 13:18:23 +00:00
|
|
|
|
virtual Category category() { return catDefault; }
|
2018-11-22 15:03:31 +00:00
|
|
|
|
};
|
|
|
|
|
|
2019-06-18 14:01:35 +00:00
|
|
|
|
typedef std::map<std::string, std::function<ref<Command>()>> Commands;
|
2018-11-22 15:03:31 +00:00
|
|
|
|
|
2023-03-27 01:12:25 +00:00
|
|
|
|
/**
|
|
|
|
|
* An argument parser that supports multiple subcommands,
|
|
|
|
|
* i.e. ‘<command> <subcommand>’.
|
|
|
|
|
*/
|
2021-09-13 12:41:28 +00:00
|
|
|
|
class MultiCommand : virtual public Args
|
2018-11-22 15:03:31 +00:00
|
|
|
|
{
|
|
|
|
|
public:
|
|
|
|
|
Commands commands;
|
|
|
|
|
|
2020-05-05 13:18:23 +00:00
|
|
|
|
std::map<Command::Category, std::string> categories;
|
|
|
|
|
|
2023-03-27 01:12:25 +00:00
|
|
|
|
/**
|
|
|
|
|
* Selected command, if any.
|
|
|
|
|
*/
|
2020-05-05 13:18:23 +00:00
|
|
|
|
std::optional<std::pair<std::string, ref<Command>>> command;
|
2018-11-22 15:03:31 +00:00
|
|
|
|
|
2019-06-18 14:01:35 +00:00
|
|
|
|
MultiCommand(const Commands & commands);
|
2018-11-22 15:03:31 +00:00
|
|
|
|
|
|
|
|
|
bool processFlag(Strings::iterator & pos, Strings::iterator end) override;
|
|
|
|
|
|
|
|
|
|
bool processArgs(const Strings & args, bool finish) override;
|
2020-08-17 15:44:52 +00:00
|
|
|
|
|
2022-06-20 02:15:38 +00:00
|
|
|
|
void completionHook() override;
|
|
|
|
|
|
2020-08-17 15:44:52 +00:00
|
|
|
|
nlohmann::json toJSON() override;
|
2018-11-22 15:03:31 +00:00
|
|
|
|
};
|
|
|
|
|
|
2016-02-09 20:07:48 +00:00
|
|
|
|
Strings argvToStrings(int argc, char * * argv);
|
|
|
|
|
|
2020-10-09 07:39:51 +00:00
|
|
|
|
struct Completion {
|
|
|
|
|
std::string completion;
|
|
|
|
|
std::string description;
|
|
|
|
|
|
|
|
|
|
bool operator<(const Completion & other) const;
|
|
|
|
|
};
|
|
|
|
|
class Completions : public std::set<Completion> {
|
|
|
|
|
public:
|
|
|
|
|
void add(std::string completion, std::string description = "");
|
|
|
|
|
};
|
|
|
|
|
extern std::shared_ptr<Completions> completions;
|
2021-12-22 11:37:59 +00:00
|
|
|
|
|
|
|
|
|
enum CompletionType {
|
|
|
|
|
ctNormal,
|
|
|
|
|
ctFilenames,
|
|
|
|
|
ctAttrs
|
|
|
|
|
};
|
|
|
|
|
extern CompletionType completionType;
|
2020-05-10 18:32:21 +00:00
|
|
|
|
|
2020-05-11 13:46:18 +00:00
|
|
|
|
void completePath(size_t, std::string_view prefix);
|
2020-05-10 19:35:07 +00:00
|
|
|
|
|
2020-05-11 20:04:13 +00:00
|
|
|
|
void completeDir(size_t, std::string_view prefix);
|
|
|
|
|
|
2016-02-09 20:07:48 +00:00
|
|
|
|
}
|