Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Feature config file format #1075

Merged
merged 4 commits into from
Oct 9, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions book/chapters/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -323,6 +323,10 @@ char literalQuote = '\'';
uint8_t maximumLayers{255};
/// the separator used to separator parent layers
char parentSeparatorChar{'.'};
/// comment default values
bool commentDefaultsBool = false;
/// specify the config reader should collapse repeated field names to a single vector
bool allowMultipleDuplicateFields{false};
/// Specify the configuration index to use for arrayed sections
uint16_t configIndex{0};
/// Specify the configuration section that should be used
Expand All @@ -341,6 +345,10 @@ These can be modified via setter functions
and value
- `ConfigBase *quoteCharacter(char qString, char literalChar)` :specify the
characters to use around strings and single characters
- `ConfigBase *commentDefaults(bool comDef)` : set to true to comment lines with
a default value
- `ConfigBase *allowDuplicateFields(bool value)` :set to true to allow duplicate
fields to be merged even if not sequential
- `ConfigBase *maxLayers(uint8_t layers)` : specify the maximum number of parent
layers to process. This is useful to limit processing for larger config files
- `ConfigBase *parentSeparator(char sep)` : specify the character to separate
Expand Down Expand Up @@ -450,8 +458,8 @@ positional, or the environment variable name. When generating a config file it
will create an option name in following priority.

1. First long name
2. Positional name
3. First short name
2. First short name
3. Positional name
4. Environment name

In config files the name will be enclosed in quotes if there is any potential
Expand Down
5 changes: 5 additions & 0 deletions examples/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -251,6 +251,11 @@ add_cli_exe(custom_parse custom_parse.cpp)
add_test(NAME cp_test COMMAND custom_parse --dv 1.7)
set_property(TEST cp_test PROPERTY PASS_REGULAR_EXPRESSION "called correct")

#-----------------------------------------------------
add_cli_exe(help_usage help_usage.cpp)
add_test(NAME help_use COMMAND help_usage --help)
set_property(TEST help_use PROPERTY PASS_REGULAR_EXPRESSION "[1..9]")

#------------------------------------------------
# This executable is for manual testing and is expected to change regularly

Expand Down
37 changes: 20 additions & 17 deletions examples/help_usage.cpp
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// Copyright (c) 2017-2023, University of Cincinnati, developed by Henry Schreiner
// Copyright (c) 2017-2024, University of Cincinnati, developed by Henry Schreiner
// under NSF AWARD 1414736 and by the respective contributors.
// All rights reserved.
//
Expand All @@ -9,7 +9,7 @@

int main(int argc, char **argv) {
std::string input_file_name, output_file_name;
int level, subopt;
int level{5}, subopt{0};

// app caption
CLI::App app{"CLI11 help"};
Expand Down Expand Up @@ -47,26 +47,29 @@ int main(int argc, char **argv) {

/*
$ ./help_usage -h
CLI11 help
Usage: help_usage <command> [options] <input-file> <output-file>
CLI11 help

Options:
-h,--help
OPTIONS:
-h, --help

Subcommands:
SUBCOMMANDS:
e
encode
Positionals:
input input file
output output file
Options:
-l,--level [1..9] encoding level
-K,--remove INT remove input file
-s,--suboption suboption

POSITIONALS:
input input file
output output file

OPTIONS:
-l, --level [1..9] encoding level
-R, --remove remove input file
-s, --suboption suboption


d
decode
Positionals:
input input file
output output file

POSITIONALS:
input input file
output output file
*/
11 changes: 9 additions & 2 deletions include/CLI/ConfigFwd.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -102,10 +102,12 @@ class ConfigBase : public Config {
uint8_t maximumLayers{255};
/// the separator used to separator parent layers
char parentSeparatorChar{'.'};
/// Specify the configuration index to use for arrayed sections
int16_t configIndex{-1};
/// comment default values
bool commentDefaultsBool = false;
/// specify the config reader should collapse repeated field names to a single vector
bool allowMultipleDuplicateFields{false};
/// Specify the configuration index to use for arrayed sections
int16_t configIndex{-1};
/// Specify the configuration section that should be used
std::string configSection{};

Expand Down Expand Up @@ -151,6 +153,11 @@ class ConfigBase : public Config {
parentSeparatorChar = sep;
return this;
}
/// comment default value options
ConfigBase *commentDefaults(bool comDef = true) {
commentDefaultsBool = comDef;
return this;
}
/// get a reference to the configuration section
std::string &sectionRef() { return configSection; }
/// get the section
Expand Down
2 changes: 1 addition & 1 deletion include/CLI/Option.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -547,7 +547,7 @@ class Option : public OptionBase<Option> {

/// Get the flag names with specified default values
CLI11_NODISCARD const std::vector<std::string> &get_fnames() const { return fnames_; }
/// Get a single name for the option, first of lname, pname, sname, envname
/// Get a single name for the option, first of lname, sname, pname, envname
CLI11_NODISCARD const std::string &get_single_name() const {
if(!lnames_.empty()) {
return lnames_[0];
Expand Down
27 changes: 19 additions & 8 deletions include/CLI/impl/Config_inl.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -518,9 +518,7 @@ ConfigBase::to_config(const App *app, bool default_also, bool write_description,
std::vector<std::string> groups = app->get_groups();
bool defaultUsed = false;
groups.insert(groups.begin(), std::string("OPTIONS"));
if(write_description && (app->get_configurable() || app->get_parent() == nullptr || app->get_name().empty())) {
out << commentLead << detail::fix_newlines(commentLead, app->get_description()) << '\n';
}

for(auto &group : groups) {
if(group == "OPTIONS" || group.empty()) {
if(defaultUsed) {
Expand All @@ -529,10 +527,9 @@ ConfigBase::to_config(const App *app, bool default_also, bool write_description,
defaultUsed = true;
}
if(write_description && group != "OPTIONS" && !group.empty()) {
out << '\n' << commentLead << group << " Options\n";
out << '\n' << commentChar << commentLead << group << " Options\n";
}
for(const Option *opt : app->get_options({})) {

// Only process options that are configurable
if(opt->get_configurable()) {
if(opt->get_group() != group) {
Expand All @@ -548,14 +545,18 @@ ConfigBase::to_config(const App *app, bool default_also, bool write_description,
std::string value = detail::ini_join(
opt->reduced_results(), arraySeparator, arrayStart, arrayEnd, stringQuote, literalQuote);

bool isDefault = false;
if(value.empty() && default_also) {
if(!opt->get_default_str().empty()) {
value = detail::convert_arg_for_ini(opt->get_default_str(), stringQuote, literalQuote, false);
} else if(opt->get_expected_min() == 0) {
value = "false";
} else if(opt->get_run_callback_for_default()) {
} else if(opt->get_run_callback_for_default() || !opt->get_required()) {
value = "\"\""; // empty string default value
} else {
value = "\"<REQUIRED>\"";
}
isDefault = true;
}

if(!value.empty()) {
Expand All @@ -581,18 +582,23 @@ ConfigBase::to_config(const App *app, bool default_also, bool write_description,
}
}
if(write_description && opt->has_description()) {
out << '\n';
if(out.tellp() != std::streampos(0)) {
out << '\n';
}
out << commentLead << detail::fix_newlines(commentLead, opt->get_description()) << '\n';
}
clean_name_string(single_name, keyChars);

std::string name = prefix + single_name;

if(commentDefaultsBool && isDefault) {
name = commentChar + name;
}
out << name << valueDelimiter << value << '\n';
}
}
}
}

auto subcommands = app->get_subcommands({});
for(const App *subcom : subcommands) {
if(subcom->get_name().empty()) {
Expand Down Expand Up @@ -650,6 +656,11 @@ ConfigBase::to_config(const App *app, bool default_also, bool write_description,
}
}

if(write_description && !out.str().empty()) {
std::string outString =
commentChar + commentLead + detail::fix_newlines(commentChar + commentLead, app->get_description()) + '\n';
return outString + out.str();
}
return out.str();
}
// [CLI11:config_inl_hpp:end]
Expand Down
25 changes: 25 additions & 0 deletions tests/ConfigFileTest.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -3189,6 +3189,9 @@ TEST_CASE_METHOD(TApp, "TomlOutputHiddenOptions", "[config]") {
TEST_CASE_METHOD(TApp, "TomlOutputAppMultiLineDescription", "[config]") {
app.description("Some short app description.\n"
"That has multiple lines.");
// for descriptions to show up needs an option that was set
app.add_option("--test");
args = {"--test", "55"};
run();

std::string str = app.config_to_str(true, true);
Expand Down Expand Up @@ -3376,6 +3379,24 @@ TEST_CASE_METHOD(TApp, "TomlOutputDefault", "[config]") {

str = app.config_to_str(true);
CHECK_THAT(str, Contains("simple=7"));

app.get_config_formatter_base()->commentDefaults();
str = app.config_to_str(true);
CHECK_THAT(str, Contains("#simple=7"));
}

TEST_CASE_METHOD(TApp, "TomlOutputDefaultRequired", "[config]") {

int v{7};
auto *opt = app.add_option("--simple", v);
opt->required()->run_callback_for_default(false);

std::string str = app.config_to_str(true);
CHECK_THAT(str, Contains("simple=\"<REQUIRED>\""));

opt->required(false);
str = app.config_to_str(true);
CHECK_THAT(str, Contains("simple=\"\""));
}

TEST_CASE_METHOD(TApp, "TomlOutputSubcom", "[config]") {
Expand Down Expand Up @@ -3690,6 +3711,10 @@ TEST_CASE_METHOD(TApp, "IniOutputAppMultiLineDescription", "[config]") {
app.description("Some short app description.\n"
"That has multiple lines.");
app.config_formatter(std::make_shared<CLI::ConfigINI>());

// for descriptions to show up needs an option that was set
app.add_option("--test");
args = {"--test", "66"};
run();

std::string str = app.config_to_str(true, true);
Expand Down
Loading