Set the default configuration file output as TOML (#435)

* Set the default configuration file output as TOML * update formatting

Set the default configuration file output as TOML (#435)
* Set the default configuration file output as TOML * update formatting
Philip Top · GitHub
1 parent d8a5bdc2
Showing 6 changed files with 415 additions and 102 deletions
README.md
book/chapters/config.md
include/CLI/App.hpp
include/CLI/Config.hpp
include/CLI/ConfigFwd.hpp
tests/ConfigFileTest.cpp
@@ -679,39 +679,39 @@ app.set_config(option_name=&quot;&quot;,
                required=false)
 ```
-If this is called with no arguments, it will remove the configuration file option (like `set_help_flag`). Setting a configuration option is special. If it is present, it will be read along with the normal command line arguments. The file will be read if it exists, and does not throw an error unless `required` is `true`. Configuration files are in `ini` format by default,  The reader can also accept many files in [TOML] format 🆕.  (other formats can be added by an adept user, some variations are available through customization points in the default formatter). An example of a file:
+If this is called with no arguments, it will remove the configuration file option (like `set_help_flag`). Setting a configuration option is special. If it is present, it will be read along with the normal command line arguments. The file will be read if it exists, and does not throw an error unless `required` is `true`. Configuration files are in [TOML] format by default 🚧, though the default reader can also accept files in INI format as well 🆕. It should be noted that CLI11 does not contain a full TOML parser but can read strings from most TOML file and run them through the CLI11 parser. Other formats can be added by an adept user, some variations are available through customization points in the default formatter. An example of a TOML file 🆕:
 ```ini
-; Comments are supported, using a ;
-; The default section is [default], case insensitive
+# Comments are supported, using a #
+# The default section is [default], case insensitive
 value = 1
 str = "A string"
-vector = 1 2 3
-str_vector = "one" "two" "and three"
+vector = [1,2,3]
+str_vector = ["one","two","and three"]
-; Sections map to subcommands
+# Sections map to subcommands
 [subcommand]
 in_subcommand = Wow
 sub.subcommand = true
 ```
- or equivalently in TOML 🆕
-```toml
-# Comments are supported, using a #
-# The default section is [default], case insensitive
+or equivalently in INI format
+```ini
+; Comments are supported, using a ;
+; The default section is [default], case insensitive
 value = 1
 str = "A string"
-vector = [1,2,3]
-str_vector = ["one","two","and three"]
+vector = 1 2 3
+str_vector = "one" "two" "and three"
-# Sections map to subcommands
+; Sections map to subcommands
 [subcommand]
 in_subcommand = Wow
 sub.subcommand = true
 ```
-Spaces before and after the name and argument are ignored. Multiple arguments are separated by spaces. One set of quotes will be removed, preserving spaces (the same way the command line works). Boolean options can be `true`, `on`, `1`, `yes`, `enable`; or `false`, `off`, `0`, `no`, `disable` (case insensitive). Sections (and `.` separated names) are treated as subcommands (note: this does not necessarily mean that subcommand was passed, it just sets the "defaults"). You cannot set positional-only arguments.  🆕 Subcommands can be triggered from config files if the `configurable` flag was set on the subcommand.  Then use `[subcommand]` notation will trigger a subcommand and cause it to act as if it were on the command line.
+Spaces before and after the name and argument are ignored. Multiple arguments are separated by spaces. One set of quotes will be removed, preserving spaces (the same way the command line works). Boolean options can be `true`, `on`, `1`, `yes`, `enable`; or `false`, `off`, `0`, `no`, `disable` (case insensitive). Sections (and `.` separated names) are treated as subcommands (note: this does not necessarily mean that subcommand was passed, it just sets the "defaults"). You cannot set positional-only arguments.  🆕 Subcommands can be triggered from configuration files if the `configurable` flag was set on the subcommand.  Then the use of `[subcommand]` notation will trigger a subcommand and cause it to act as if it were on the command line.
 To print a configuration file from the passed
 arguments, use `.config_to_str(default_also=false, prefix="", write_description=false)`, where `default_also` will also show any defaulted arguments, `prefix` will add a prefix, and `write_description` will include option descriptions.  See [Config files](https://cliutils.github.io/CLI11/book/chapters/config.html) for some additional details.
@@ -744,7 +744,7 @@ The App class was designed allow toolkits to subclass it, to provide preset defa
 but before run behavior, while
 still giving the user freedom to `callback` on the main app.
-The most important parse function is `parse(std::vector<std::string>)`, which takes a reversed list of arguments (so that `pop_back` processes the args in the correct order). `get_help_ptr` and `get_config_ptr` give you access to the help/config option pointers. The standard `parse` manually sets the name from the first argument, so it should not be in this vector. You can also use `parse(string, bool)` to split up and parse a string; the optional bool should be set to true if you are
+The most important parse function is `parse(std::vector<std::string>)`, which takes a reversed list of arguments (so that `pop_back` processes the args in the correct order). `get_help_ptr` and `get_config_ptr` give you access to the help/config option pointers. The standard `parse` manually sets the name from the first argument, so it should not be in this vector. You can also use `parse(string, bool)` to split up and parse a string; the optional boolean should be set to true if you are
 including the program name in the string, and false otherwise.
 Also, in a related note, the `App` you get a pointer to is stored in the parent `App` in a `shared_ptr`s (similar to `Option`s) and are deleted when the main `App` goes out of scope unless the object has another owner.
@@ -41,39 +41,39 @@ If it is needed to get the configuration file name used this can be obtained via
 ## Configure file format
-Here is an example configuration file, in INI format:
+Here is an example configuration file, in [TOML](https://github.com/toml-lang/toml) format:
 ```ini
-; Comments are supported, using a ;
-; The default section is [default], case insensitive
+# Comments are supported, using a #
+# The default section is [default], case insensitive
 value = 1
 str = "A string"
-vector = 1 2 3
+vector = [1,2,3]
-; Section map to subcommands
+# Section map to subcommands
 [subcommand]
 in_subcommand = Wow
-sub.subcommand = true
+[subcommand.sub]
+subcommand = true # could also be give as sub.subcommand=true
 ```
 Spaces before and after the name and argument are ignored. Multiple arguments are separated by spaces. One set of quotes will be removed, preserving spaces (the same way the command line works). Boolean options can be `true`, `on`, `1`, `y`, `t`, `+`, `yes`, `enable`; or `false`, `off`, `0`, `no`, `n`, `f`, `-`, `disable`, (case insensitive). Sections (and `.` separated names) are treated as subcommands (note: this does not necessarily mean that subcommand was passed, it just sets the "defaults". If a subcommand is set to `configurable` then passing the subcommand using `[sub]` in a configuration file will trigger the subcommand.)
-CLI11 also supports configuration file in [TOML](https://github.com/toml-lang/toml) format.
+CLI11 also supports configuration file in INI format.
-```toml
-# Comments are supported, using a #
-# The default section is [default], case insensitive
+```ini
+; Comments are supported, using a ;
+; The default section is [default], case insensitive
 value = 1
 str = "A string"
-vector = [1,2,3]
+vector = 1 2 3
-# Section map to subcommands
+; Section map to subcommands
 [subcommand]
 in_subcommand = Wow
-[subcommand.sub]
-subcommand = true # could also be give as sub.subcommand=true
+sub.subcommand = true
 ```
 The main differences are in vector notation and comment character.  Note: CLI11 is not a full TOML parser as it just reads values as strings.  It is possible (but not recommended) to mix notation.
@@ -83,16 +83,16 @@ The main differences are in vector notation and comment character.  Note: CLI11 
 To print a configuration file from the passed arguments, use `.config_to_str(default_also=false, prefix="", write_description=false)`, where `default_also` will also show any defaulted arguments, `prefix` will add a prefix, and `write_description` will include option descriptions.
 ### Customization of configure file output
-The default config parser/generator has some customization points that allow variations on the INI format.  The default formatter has a base configuration that matches the INI format.  It defines 5 characters that define how different aspects of the configuration are handled
+The default config parser/generator has some customization points that allow variations on the TOML format.  The default formatter has a base configuration that matches the TOML format.  It defines 5 characters that define how different aspects of the configuration are handled
 ```cpp
 /// the character used for comments
-char commentChar = ';';
+char commentChar = '#';
 /// the character used to start an array '\0' is a default to not use
-char arrayStart = '\0';
+char arrayStart = '[';
 /// the character used to end an array '\0' is a default to not use
-char arrayEnd = '\0';
+char arrayEnd = ']';
 /// the character used to separate elements in an array
-char arraySeparator = ' ';
+char arraySeparator = ',';
 /// the character used separate the name from the value
 char valueDelimiter = '=';
 ```
@@ -111,11 +111,11 @@ auto config_base=app.get_config_formatter_base();
 config_base->valueSeparator(':');
 ```
-The default configuration file will read TOML files, but will write out files in the INI format.  To specify outputting TOML formatted files use
+The default configuration file will read INI files, but will write out files in the TOML format.  To specify outputting INI formatted files use
 ```cpp
-app.config_formatter(std::make_shared<CLI::ConfigTOML>());
+app.config_formatter(std::make_shared<CLI::ConfigINI>());
 ```
-which makes use of a predefined modification of the ConfigBase class which INI also uses.
+which makes use of a predefined modification of the ConfigBase class which TOML also uses.
 ## Custom formats
@@ -247,7 +247,7 @@ class App {
     Option *config_ptr_{nullptr};
     /// This is the formatter for help printing. Default provided. INHERITABLE (same pointer)
-    std::shared_ptr<Config> config_formatter_{new ConfigINI()};
+    std::shared_ptr<Config> config_formatter_{new ConfigTOML()};
     ///@}
@@ -167,10 +167,11 @@ inline std::vector&lt;ConfigItem&gt; ConfigBase::from_config(std::istream &amp;input) cons
     std::string section = "default";
     std::vector<ConfigItem> output;
-    bool defaultArray = (arrayStart == '\0' || arrayStart == ' ') && arrayStart == arrayEnd;
-    char aStart = (defaultArray) ? '[' : arrayStart;
-    char aEnd = (defaultArray) ? ']' : arrayEnd;
-    char aSep = (defaultArray && arraySeparator == ' ') ? ',' : arraySeparator;
+    bool isDefaultArray = (arrayStart == '[' && arrayEnd == ']' && arraySeparator == ',');
+    bool isINIArray = (arrayStart == '\0' || arrayStart == ' ') && arrayStart == arrayEnd;
+    char aStart = (isINIArray) ? '[' : arrayStart;
+    char aEnd = (isINIArray) ? ']' : arrayEnd;
+    char aSep = (isINIArray && arraySeparator == ' ') ? ',' : arraySeparator;
     while(getline(input, line)) {
         std::vector<std::string> items_buffer;
@@ -212,9 +213,9 @@ inline std::vector&lt;ConfigItem&gt; ConfigBase::from_config(std::istream &amp;input) cons
             std::string item = detail::trim_copy(line.substr(pos + 1));
             if(item.size() > 1 && item.front() == aStart && item.back() == aEnd) {
                 items_buffer = detail::split_up(item.substr(1, item.length() - 2), aSep);
-            } else if(defaultArray && item.find_first_of(aSep) != std::string::npos) {
+            } else if((isDefaultArray || isINIArray) && item.find_first_of(aSep) != std::string::npos) {
                 items_buffer = detail::split_up(item, aSep);
-            } else if(defaultArray && item.find_first_of(' ') != std::string::npos) {
+            } else if((isDefaultArray || isINIArray) && item.find_first_of(' ') != std::string::npos) {
                 items_buffer = detail::split_up(item);
             } else {
                 items_buffer = {item};
@@ -71,17 +71,17 @@ class Config {
     virtual ~Config() = default;
 };
-/// This converter works with INI/TOML files; to write proper TOML files use ConfigTOML
+/// This converter works with INI/TOML files; to write INI files use ConfigINI
 class ConfigBase : public Config {
   protected:
     /// the character used for comments
-    char commentChar = ';';
+    char commentChar = '#';
     /// the character used to start an array '\0' is a default to not use
-    char arrayStart = '\0';
+    char arrayStart = '[';
     /// the character used to end an array '\0' is a default to not use
-    char arrayEnd = '\0';
+    char arrayEnd = ']';
     /// the character used to separate elements in an array
-    char arraySeparator = ' ';
+    char arraySeparator = ',';
     /// the character used separate the name from the value
     char valueDelimiter = '=';
@@ -113,18 +113,18 @@ class ConfigBase : public Config {
     }
 };
-/// the default Config is the INI file format
-using ConfigINI = ConfigBase;
+/// the default Config is the TOML file format
+using ConfigTOML = ConfigBase;
-/// ConfigTOML generates a TOML compliant output
-class ConfigTOML : public ConfigINI {
+/// ConfigINI generates a "standard" INI compliant output
+class ConfigINI : public ConfigTOML {
   public:
-    ConfigTOML() {
-        commentChar = '#';
-        arrayStart = '[';
-        arrayEnd = ']';
-        arraySeparator = ',';
+    ConfigINI() {
+        commentChar = ';';
+        arrayStart = '\0';
+        arrayEnd = '\0';
+        arraySeparator = ' ';
         valueDelimiter = '=';
     }
 };
@@ -690,12 +690,12 @@ TEST_F(TApp, IniVector) {
 }
 TEST_F(TApp, TOMLVector) {
-    TempFile tmpini{"TestIniTmp.ini"};
+    TempFile tmptoml{"TestTomlTmp.toml"};
-    app.set_config("--config", tmpini);
+    app.set_config("--config", tmptoml);
     {
-        std::ofstream out{tmpini};
+        std::ofstream out{tmptoml};
         out << "#this is a comment line\n";
         out << "[default]\n";
         out << "two=[2,3]\n";
@@ -1050,12 +1050,12 @@ TEST_F(TApp, IniSubcommandMultipleSections) {
 TEST_F(TApp, DuplicateSubcommandCallbacks) {
-    TempFile tmpini{"TestIniTmp.ini"};
+    TempFile tmptoml{"TesttomlTmp.toml"};
-    app.set_config("--config", tmpini);
+    app.set_config("--config", tmptoml);
     {
-        std::ofstream out{tmpini};
+        std::ofstream out{tmptoml};
         out << "[[foo]]" << std::endl;
         out << "[[foo]]" << std::endl;
         out << "[[foo]]" << std::endl;
@@ -1195,6 +1195,7 @@ TEST_F(TApp, IniFlagDual) {
     TempFile tmpini{"TestIniTmp.ini"};
     bool boo{false};
+    app.config_formatter(std::make_shared<CLI::ConfigINI>());
     app.add_flag("--flag", boo);
     app.set_config("--config", tmpini);
@@ -1362,7 +1363,7 @@ TEST_F(TApp, IniFalseFlagsDefDisableOverrideSuccess) {
     EXPECT_EQ(15, val);
 }
-TEST_F(TApp, IniOutputSimple) {
+TEST_F(TApp, TomlOutputSimple) {
     int v{0};
     app.add_option("--simple", v);
@@ -1375,7 +1376,7 @@ TEST_F(TApp, IniOutputSimple) {
     EXPECT_EQ("simple=3\n", str);
 }
-TEST_F(TApp, IniOutputNoConfigurable) {
+TEST_F(TApp, TomlOutputNoConfigurable) {
     int v1{0}, v2{0};
     app.add_option("--simple", v1);
@@ -1389,7 +1390,7 @@ TEST_F(TApp, IniOutputNoConfigurable) {
     EXPECT_EQ("simple=3\n", str);
 }
-TEST_F(TApp, IniOutputShortSingleDescription) {
+TEST_F(TApp, TomlOutputShortSingleDescription) {
     std::string flag = "some_flag";
     const std::string description = "Some short description.";
     app.add_flag("--" + flag, description);
@@ -1397,10 +1398,10 @@ TEST_F(TApp, IniOutputShortSingleDescription) {
     run();
     std::string str = app.config_to_str(true, true);
-    EXPECT_THAT(str, HasSubstr("; " + description + "\n" + flag + "=false\n"));
+    EXPECT_THAT(str, HasSubstr("# " + description + "\n" + flag + "=false\n"));
 }
-TEST_F(TApp, IniOutputShortDoubleDescription) {
+TEST_F(TApp, TomlOutputShortDoubleDescription) {
     std::string flag1 = "flagnr1";
     std::string flag2 = "flagnr2";
     const std::string description1 = "First description.";
@@ -1412,10 +1413,10 @@ TEST_F(TApp, IniOutputShortDoubleDescription) {
     std::string str = app.config_to_str(true, true);
     EXPECT_THAT(
-        str, HasSubstr("; " + description1 + "\n" + flag1 + "=false\n\n; " + description2 + "\n" + flag2 + "=false\n"));
+        str, HasSubstr("# " + description1 + "\n" + flag1 + "=false\n\n# " + description2 + "\n" + flag2 + "=false\n"));
 }
-TEST_F(TApp, IniOutputGroups) {
+TEST_F(TApp, TomlOutputGroups) {
     std::string flag1 = "flagnr1";
     std::string flag2 = "flagnr2";
     const std::string description1 = "First description.";
@@ -1430,7 +1431,7 @@ TEST_F(TApp, IniOutputGroups) {
     EXPECT_THAT(str, HasSubstr("group2"));
 }
-TEST_F(TApp, IniOutputHiddenOptions) {
+TEST_F(TApp, TomlOutputHiddenOptions) {
     std::string flag1 = "flagnr1";
     std::string flag2 = "flagnr2";
     double val{12.7};
@@ -1454,7 +1455,7 @@ TEST_F(TApp, IniOutputHiddenOptions) {
     EXPECT_EQ(loc, std::string::npos);
 }
-TEST_F(TApp, IniOutputMultiLineDescription) {
+TEST_F(TApp, TomlOutputMultiLineDescription) {
     std::string flag = "some_flag";
     const std::string description = "Some short description.\nThat has lines.";
     app.add_flag("--" + flag, description);
@@ -1462,12 +1463,12 @@ TEST_F(TApp, IniOutputMultiLineDescription) {
     run();
     std::string str = app.config_to_str(true, true);
-    EXPECT_THAT(str, HasSubstr("; Some short description.\n"));
-    EXPECT_THAT(str, HasSubstr("; That has lines.\n"));
+    EXPECT_THAT(str, HasSubstr("# Some short description.\n"));
+    EXPECT_THAT(str, HasSubstr("# That has lines.\n"));
     EXPECT_THAT(str, HasSubstr(flag + "=false\n"));
 }
-TEST_F(TApp, IniOutputOptionGroup) {
+TEST_F(TApp, TomlOutputOptionGroup) {
     std::string flag1 = "flagnr1";
     std::string flag2 = "flagnr2";
     double val{12.7};
@@ -1496,20 +1497,7 @@ TEST_F(TApp, IniOutputOptionGroup) {
     EXPECT_GT(locg3, locg1);
 }
-TEST_F(TApp, IniOutputVector) {
-
-    std::vector<int> v;
-    app.add_option("--vector", v);
-
-    args = {"--vector", "1", "2", "3"};
-
-    run();
-
-    std::string str = app.config_to_str();
-    EXPECT_EQ("vector=1 2 3\n", str);
-}
-
-TEST_F(TApp, IniOutputVectorTOML) {
+TEST_F(TApp, TomlOutputVector) {
     std::vector<int> v;
     app.add_option("--vector", v);
@@ -1522,7 +1510,7 @@ TEST_F(TApp, IniOutputVectorTOML) {
     EXPECT_EQ("vector=[1, 2, 3]\n", str);
 }
-TEST_F(TApp, IniOutputVectorCustom) {
+TEST_F(TApp, ConfigOutputVectorCustom) {
     std::vector<int> v;
     app.add_option("--vector", v);
@@ -1537,7 +1525,7 @@ TEST_F(TApp, IniOutputVectorCustom) {
     EXPECT_EQ("vector:{1; 2; 3}\n", str);
 }
-TEST_F(TApp, IniOutputFlag) {
+TEST_F(TApp, TomlOutputFlag) {
     int v{0}, q{0};
     app.add_option("--simple", v);
@@ -1553,13 +1541,13 @@ TEST_F(TApp, IniOutputFlag) {
     EXPECT_THAT(str, HasSubstr("simple=3"));
     EXPECT_THAT(str, Not(HasSubstr("nothing")));
     EXPECT_THAT(str, HasSubstr("onething=true"));
-    EXPECT_THAT(str, HasSubstr("something=true true"));
+    EXPECT_THAT(str, HasSubstr("something=[true, true]"));
     str = app.config_to_str(true);
     EXPECT_THAT(str, HasSubstr("nothing"));
 }
-TEST_F(TApp, IniOutputSet) {
+TEST_F(TApp, TomlOutputSet) {
     int v{0};
     app.add_option("--simple", v)->check(CLI::IsMember({1, 2, 3}));
@@ -1572,7 +1560,7 @@ TEST_F(TApp, IniOutputSet) {
     EXPECT_THAT(str, HasSubstr("simple=2"));
 }
-TEST_F(TApp, IniOutputDefault) {
+TEST_F(TApp, TomlOutputDefault) {
     int v{7};
     app.add_option("--simple", v, "", true);
@@ -1586,7 +1574,7 @@ TEST_F(TApp, IniOutputDefault) {
     EXPECT_THAT(str, HasSubstr("simple=7"));
 }
-TEST_F(TApp, IniOutputSubcom) {
+TEST_F(TApp, TomlOutputSubcom) {
     app.add_flag("--simple");
     auto subcom = app.add_subcommand("other");
@@ -1600,7 +1588,7 @@ TEST_F(TApp, IniOutputSubcom) {
     EXPECT_THAT(str, HasSubstr("other.newer=true"));
 }
-TEST_F(TApp, IniOutputSubcomConfigurable) {
+TEST_F(TApp, TomlOutputSubcomConfigurable) {
     app.add_flag("--simple");
     auto subcom = app.add_subcommand("other")->configurable();
@@ -1616,7 +1604,7 @@ TEST_F(TApp, IniOutputSubcomConfigurable) {
     EXPECT_EQ(str.find("other.newer=true"), std::string::npos);
 }
-TEST_F(TApp, IniOutputSubsubcom) {
+TEST_F(TApp, TomlOutputSubsubcom) {
     app.add_flag("--simple");
     auto subcom = app.add_subcommand("other");
@@ -1633,7 +1621,7 @@ TEST_F(TApp, IniOutputSubsubcom) {
     EXPECT_THAT(str, HasSubstr("other.sub2.newest=true"));
 }
-TEST_F(TApp, IniOutputSubsubcomConfigurable) {
+TEST_F(TApp, TomlOutputSubsubcomConfigurable) {
     app.add_flag("--simple");
     auto subcom = app.add_subcommand("other")->configurable();
@@ -1654,7 +1642,7 @@ TEST_F(TApp, IniOutputSubsubcomConfigurable) {
     EXPECT_EQ(str.find("sub2.newest=true"), std::string::npos);
 }
-TEST_F(TApp, IniOutputSubsubcomConfigurableDeep) {
+TEST_F(TApp, TomlOutputSubsubcomConfigurableDeep) {
     app.add_flag("--simple");
     auto subcom = app.add_subcommand("other")->configurable();
@@ -1677,7 +1665,7 @@ TEST_F(TApp, IniOutputSubsubcomConfigurableDeep) {
     EXPECT_EQ(str.find(".absolute_newest=true"), std::string::npos);
 }
-TEST_F(TApp, IniQuotedOutput) {
+TEST_F(TApp, TomlOutputQuoted) {
     std::string val1;
     app.add_option("--val1", val1);
@@ -1697,7 +1685,7 @@ TEST_F(TApp, IniQuotedOutput) {
     EXPECT_THAT(str, HasSubstr("val2='I am a \"confusing\" string'"));
 }
-TEST_F(TApp, DefaultsIniQuotedOutput) {
+TEST_F(TApp, DefaultsTomlOutputQuoted) {
     std::string val1{"I am a string"};
     app.add_option("--val1", val1, "", true);
@@ -1755,3 +1743,327 @@ TEST_F(TApp, ConfigWriteReadWrite) {
     EXPECT_EQ(config1, config2);
 }
+
+///////INI output tests
+
+TEST_F(TApp, IniOutputSimple) {
+
+    int v{0};
+    app.add_option("--simple", v);
+    app.config_formatter(std::make_shared<CLI::ConfigINI>());
+    args = {"--simple=3"};
+
+    run();
+
+    std::string str = app.config_to_str();
+    EXPECT_EQ("simple=3\n", str);
+}
+
+TEST_F(TApp, IniOutputNoConfigurable) {
+
+    int v1{0}, v2{0};
+    app.add_option("--simple", v1);
+    app.add_option("--noconf", v2)->configurable(false);
+    app.config_formatter(std::make_shared<CLI::ConfigINI>());
+    args = {"--simple=3", "--noconf=2"};
+
+    run();
+
+    std::string str = app.config_to_str();
+    EXPECT_EQ("simple=3\n", str);
+}
+
+TEST_F(TApp, IniOutputShortSingleDescription) {
+    std::string flag = "some_flag";
+    const std::string description = "Some short description.";
+    app.add_flag("--" + flag, description);
+    app.config_formatter(std::make_shared<CLI::ConfigINI>());
+    run();
+
+    std::string str = app.config_to_str(true, true);
+    EXPECT_THAT(str, HasSubstr("; " + description + "\n" + flag + "=false\n"));
+}
+
+TEST_F(TApp, IniOutputShortDoubleDescription) {
+    std::string flag1 = "flagnr1";
+    std::string flag2 = "flagnr2";
+    const std::string description1 = "First description.";
+    const std::string description2 = "Second description.";
+    app.add_flag("--" + flag1, description1);
+    app.add_flag("--" + flag2, description2);
+    app.config_formatter(std::make_shared<CLI::ConfigINI>());
+    run();
+
+    std::string str = app.config_to_str(true, true);
+    EXPECT_THAT(
+        str, HasSubstr("; " + description1 + "\n" + flag1 + "=false\n\n; " + description2 + "\n" + flag2 + "=false\n"));
+}
+
+TEST_F(TApp, IniOutputGroups) {
+    std::string flag1 = "flagnr1";
+    std::string flag2 = "flagnr2";
+    const std::string description1 = "First description.";
+    const std::string description2 = "Second description.";
+    app.add_flag("--" + flag1, description1)->group("group1");
+    app.add_flag("--" + flag2, description2)->group("group2");
+    app.config_formatter(std::make_shared<CLI::ConfigINI>());
+    run();
+
+    std::string str = app.config_to_str(true, true);
+    EXPECT_THAT(str, HasSubstr("group1"));
+    EXPECT_THAT(str, HasSubstr("group2"));
+}
+
+TEST_F(TApp, IniOutputHiddenOptions) {
+    std::string flag1 = "flagnr1";
+    std::string flag2 = "flagnr2";
+    double val{12.7};
+    const std::string description1 = "First description.";
+    const std::string description2 = "Second description.";
+    app.add_flag("--" + flag1, description1)->group("group1");
+    app.add_flag("--" + flag2, description2)->group("group2");
+    app.add_option("--dval", val, "", true)->group("");
+    app.config_formatter(std::make_shared<CLI::ConfigINI>());
+    run();
+
+    std::string str = app.config_to_str(true, true);
+    EXPECT_THAT(str, HasSubstr("group1"));
+    EXPECT_THAT(str, HasSubstr("group2"));
+    EXPECT_THAT(str, HasSubstr("dval=12.7"));
+    auto loc = str.find("dval=12.7");
+    auto locg1 = str.find("group1");
+    EXPECT_GT(locg1, loc);
+    // make sure it doesn't come twice
+    loc = str.find("dval=12.7", loc + 4);
+    EXPECT_EQ(loc, std::string::npos);
+}
+
+TEST_F(TApp, IniOutputMultiLineDescription) {
+    std::string flag = "some_flag";
+    const std::string description = "Some short description.\nThat has lines.";
+    app.add_flag("--" + flag, description);
+    app.config_formatter(std::make_shared<CLI::ConfigINI>());
+    run();
+
+    std::string str = app.config_to_str(true, true);
+    EXPECT_THAT(str, HasSubstr("; Some short description.\n"));
+    EXPECT_THAT(str, HasSubstr("; That has lines.\n"));
+    EXPECT_THAT(str, HasSubstr(flag + "=false\n"));
+}
+
+TEST_F(TApp, IniOutputOptionGroup) {
+    std::string flag1 = "flagnr1";
+    std::string flag2 = "flagnr2";
+    double val{12.7};
+    const std::string description1 = "First description.";
+    const std::string description2 = "Second description.";
+    app.add_flag("--" + flag1, description1)->group("group1");
+    app.add_flag("--" + flag2, description2)->group("group2");
+    auto og = app.add_option_group("group3", "g3 desc");
+    og->add_option("--dval", val, "", true)->group("");
+    app.config_formatter(std::make_shared<CLI::ConfigINI>());
+    run();
+
+    std::string str = app.config_to_str(true, true);
+    EXPECT_THAT(str, HasSubstr("group1"));
+    EXPECT_THAT(str, HasSubstr("group2"));
+    EXPECT_THAT(str, HasSubstr("dval=12.7"));
+    EXPECT_THAT(str, HasSubstr("group3"));
+    EXPECT_THAT(str, HasSubstr("g3 desc"));
+    auto loc = str.find("dval=12.7");
+    auto locg1 = str.find("group1");
+    auto locg3 = str.find("group3");
+    EXPECT_LT(locg1, loc);
+    // make sure it doesn't come twice
+    loc = str.find("dval=12.7", loc + 4);
+    EXPECT_EQ(loc, std::string::npos);
+    EXPECT_GT(locg3, locg1);
+}
+
+TEST_F(TApp, IniOutputVector) {
+
+    std::vector<int> v;
+    app.add_option("--vector", v);
+
+    args = {"--vector", "1", "2", "3"};
+    app.config_formatter(std::make_shared<CLI::ConfigINI>());
+    run();
+
+    std::string str = app.config_to_str();
+    EXPECT_EQ("vector=1 2 3\n", str);
+}
+
+TEST_F(TApp, IniOutputFlag) {
+
+    int v{0}, q{0};
+    app.add_option("--simple", v);
+    app.add_flag("--nothing");
+    app.add_flag("--onething");
+    app.add_flag("--something", q);
+
+    args = {"--simple=3", "--onething", "--something", "--something"};
+    app.config_formatter(std::make_shared<CLI::ConfigINI>());
+    run();
+
+    std::string str = app.config_to_str();
+    EXPECT_THAT(str, HasSubstr("simple=3"));
+    EXPECT_THAT(str, Not(HasSubstr("nothing")));
+    EXPECT_THAT(str, HasSubstr("onething=true"));
+    EXPECT_THAT(str, HasSubstr("something=true true"));
+
+    str = app.config_to_str(true);
+    EXPECT_THAT(str, HasSubstr("nothing"));
+}
+
+TEST_F(TApp, IniOutputSet) {
+
+    int v{0};
+    app.add_option("--simple", v)->check(CLI::IsMember({1, 2, 3}));
+
+    args = {"--simple=2"};
+    app.config_formatter(std::make_shared<CLI::ConfigINI>());
+    run();
+
+    std::string str = app.config_to_str();
+    EXPECT_THAT(str, HasSubstr("simple=2"));
+}
+
+TEST_F(TApp, IniOutputDefault) {
+
+    int v{7};
+    app.add_option("--simple", v, "", true);
+    app.config_formatter(std::make_shared<CLI::ConfigINI>());
+    run();
+
+    std::string str = app.config_to_str();
+    EXPECT_THAT(str, Not(HasSubstr("simple=7")));
+
+    str = app.config_to_str(true);
+    EXPECT_THAT(str, HasSubstr("simple=7"));
+}
+
+TEST_F(TApp, IniOutputSubcom) {
+
+    app.add_flag("--simple");
+    auto subcom = app.add_subcommand("other");
+    subcom->add_flag("--newer");
+    app.config_formatter(std::make_shared<CLI::ConfigINI>());
+    args = {"--simple", "other", "--newer"};
+    run();
+
+    std::string str = app.config_to_str();
+    EXPECT_THAT(str, HasSubstr("simple=true"));
+    EXPECT_THAT(str, HasSubstr("other.newer=true"));
+}
+
+TEST_F(TApp, IniOutputSubcomConfigurable) {
+
+    app.add_flag("--simple");
+    auto subcom = app.add_subcommand("other")->configurable();
+    subcom->add_flag("--newer");
+    app.config_formatter(std::make_shared<CLI::ConfigINI>());
+    args = {"--simple", "other", "--newer"};
+    run();
+
+    std::string str = app.config_to_str();
+    EXPECT_THAT(str, HasSubstr("simple=true"));
+    EXPECT_THAT(str, HasSubstr("[other]"));
+    EXPECT_THAT(str, HasSubstr("newer=true"));
+    EXPECT_EQ(str.find("other.newer=true"), std::string::npos);
+}
+
+TEST_F(TApp, IniOutputSubsubcom) {
+
+    app.add_flag("--simple");
+    auto subcom = app.add_subcommand("other");
+    subcom->add_flag("--newer");
+    auto subsubcom = subcom->add_subcommand("sub2");
+    subsubcom->add_flag("--newest");
+    app.config_formatter(std::make_shared<CLI::ConfigINI>());
+    args = {"--simple", "other", "--newer", "sub2", "--newest"};
+    run();
+
+    std::string str = app.config_to_str();
+    EXPECT_THAT(str, HasSubstr("simple=true"));
+    EXPECT_THAT(str, HasSubstr("other.newer=true"));
+    EXPECT_THAT(str, HasSubstr("other.sub2.newest=true"));
+}
+
+TEST_F(TApp, IniOutputSubsubcomConfigurable) {
+
+    app.add_flag("--simple");
+    auto subcom = app.add_subcommand("other")->configurable();
+    subcom->add_flag("--newer");
+
+    auto subsubcom = subcom->add_subcommand("sub2");
+    subsubcom->add_flag("--newest");
+    app.config_formatter(std::make_shared<CLI::ConfigINI>());
+    args = {"--simple", "other", "--newer", "sub2", "--newest"};
+    run();
+
+    std::string str = app.config_to_str();
+    EXPECT_THAT(str, HasSubstr("simple=true"));
+    EXPECT_THAT(str, HasSubstr("[other]"));
+    EXPECT_THAT(str, HasSubstr("newer=true"));
+    EXPECT_THAT(str, HasSubstr("[other.sub2]"));
+    EXPECT_THAT(str, HasSubstr("newest=true"));
+    EXPECT_EQ(str.find("sub2.newest=true"), std::string::npos);
+}
+
+TEST_F(TApp, IniOutputSubsubcomConfigurableDeep) {
+
+    app.add_flag("--simple");
+    auto subcom = app.add_subcommand("other")->configurable();
+    subcom->add_flag("--newer");
+
+    auto subsubcom = subcom->add_subcommand("sub2");
+    subsubcom->add_flag("--newest");
+    auto sssscom = subsubcom->add_subcommand("sub-level2");
+    subsubcom->add_flag("--still_newer");
+    auto s5com = sssscom->add_subcommand("sub-level3");
+    s5com->add_flag("--absolute_newest");
+    app.config_formatter(std::make_shared<CLI::ConfigINI>());
+    args = {"--simple", "other", "sub2", "sub-level2", "sub-level3", "--absolute_newest"};
+    run();
+
+    std::string str = app.config_to_str();
+    EXPECT_THAT(str, HasSubstr("simple=true"));
+    EXPECT_THAT(str, HasSubstr("[other.sub2.sub-level2.sub-level3]"));
+    EXPECT_THAT(str, HasSubstr("absolute_newest=true"));
+    EXPECT_EQ(str.find(".absolute_newest=true"), std::string::npos);
+}
+
+TEST_F(TApp, IniOutputQuoted) {
+
+    std::string val1;
+    app.add_option("--val1", val1);
+
+    std::string val2;
+    app.add_option("--val2", val2);
+    app.config_formatter(std::make_shared<CLI::ConfigINI>());
+    args = {"--val1", "I am a string", "--val2", R"(I am a "confusing" string)"};
+
+    run();
+
+    EXPECT_EQ("I am a string", val1);
+    EXPECT_EQ("I am a \"confusing\" string", val2);
+
+    std::string str = app.config_to_str();
+    EXPECT_THAT(str, HasSubstr("val1=\"I am a string\""));
+    EXPECT_THAT(str, HasSubstr("val2='I am a \"confusing\" string'"));
+}
+
+TEST_F(TApp, DefaultsIniOutputQuoted) {
+
+    std::string val1{"I am a string"};
+    app.add_option("--val1", val1, "", true);
+
+    std::string val2{R"(I am a "confusing" string)"};
+    app.add_option("--val2", val2, "", true);
+    app.config_formatter(std::make_shared<CLI::ConfigINI>());
+    run();
+
+    std::string str = app.config_to_str(true);
+    EXPECT_THAT(str, HasSubstr("val1=\"I am a string\""));
+    EXPECT_THAT(str, HasSubstr("val2='I am a \"confusing\" string'"));
+}