doc: update README

When non-table value is passed to the `operator<<`, it assumes that the
original C++ code looks like the following.

```cpp
std::cout << "key = " << v << std::endl;
```

In this case, the comment associated to `v` should be put just after
`v`, not before.
```toml
key = # comment <= bad
"value"

key = "value" # comment <= good
```

So, if `v` is not a table it would put comments just after the value.

.circleci/config.yml

@@ -15,6 +15,29 @@ jobs:
               g++ -std=c++11 -O2 -Wall -Wextra -Werror -I../ check_toml_test.cpp -o check_toml_test
               go get github.com/BurntSushi/toml-test
               $GOPATH/bin/toml-test ./check_toml_test
+  test_serialization:
+    docker:
+      - image: circleci/buildpack-deps:bionic
+    steps:
+      - checkout
+      - run:
+          command: |
+              g++ --version
+              cd tests/
+              g++ -std=c++11 -O2 -Wall -Wextra -Wpedantic -Werror -I../ check_serialization.cpp -o check_serialization
+              git clone https://github.com/BurntSushi/toml-test.git
+              cp check_serialization toml-test/tests/valid
+              cd toml-test/tests/valid
+              for f in $(ls ./*.toml);
+                do echo "==> ${f}";
+                cat ${f};
+                echo "---------------------------------------";
+                ./check_serialization ${f};
+                if [ $? -ne 0 ] ; then
+                  exit 1
+                fi
+                echo "=======================================";
+              done
   output_result:
     docker:
       - image: circleci/buildpack-deps:bionic
@@ -24,7 +47,7 @@ jobs:
           command: |
               g++ --version
               cd tests/
-              g++ -std=c++11 -O2 -Wall -Wextra -Werror -I../ check.cpp -o check
+              g++ -std=c++11 -O2 -Wall -Wextra -Wpedantic -Werror -I../ check.cpp -o check
               git clone https://github.com/BurntSushi/toml-test.git
               cp check toml-test/tests/invalid
               cp check toml-test/tests/valid
@@ -56,4 +79,5 @@ workflows:
   test:
     jobs:
       - test_suite
+      - test_serialization
       - output_result

CMakeLists.txt

@@ -3,11 +3,11 @@ enable_testing()
 
 project(toml11)
 
-set(toml11_VERSION_MAYOR  2)
-set(toml11_VERSION_MINOR  4)
+set(toml11_VERSION_MAYOR  3)
+set(toml11_VERSION_MINOR  0)
 set(toml11_VERSION_PATCH  0)
 set(toml11_VERSION
-  "${toml11_VERSION_MAYOR}.${toml11_VERSION_MINOR}.${toml11_VERSION_PATCH}"
+  "${toml11_VERSION_MAYOR}.${toml11_VERSION_MINOR}.${toml11_VERSION_PATCH}-beta"
 )
 
 option(toml11_BUILD_TEST "Build toml tests" ON)

README.md

@@ -22,7 +22,7 @@ You can see the error messages about invalid files and serialization results of
 ## Example
 
 ```cpp
-#include <toml11/toml.hpp>
+#include <toml.hpp>
 #include <iostream>
 
 int main()
@@ -107,13 +107,13 @@ const toml::table data = toml::parse(fname);
 If it encounters an error while opening a file, it will throw `std::runtime_error`.
 
 You can also pass a `std::istream` to the  `toml::parse` function.
-To show a filename in an error message, it is recommended to pass the filename
-with the stream.
+To show a filename in an error message, however, it is recommended to pass the
+filename with the stream.
 
 ```cpp
 std::ifstream ifs("sample.toml", std::ios_base::binary);
 assert(ifs.good());
-const auto data = toml::parse(ifs, /*optional*/ "sample.toml");
+const auto data = toml::parse(ifs, /*optional -> */ "sample.toml");
 ```
 
 **Note**: When you are **on Windows, open a file in binary mode**.
@@ -265,7 +265,6 @@ const int a = toml::find<int>(data, "answer", "to", "the", "ultimate", "question
 ```
 
 Of course, alternatively, you can call `toml::find` as many as you need.
-But it is a bother.
 
 ### In the case of type error
 
@@ -317,7 +316,7 @@ const auto color    = toml::find<std::string>(physical, "color");
 The following code does not work for the above toml file.
 
 ```cpp
-const auto color = toml::find<std::string>(data, "physical.color");
+const auto color = toml::find<std::string>(data, "physical.color"); // does not work
 ```
 
 The above code works with the following toml file.
@@ -909,10 +908,17 @@ const auto data = toml::parse<
     >("example.toml");
 ```
 
-__NOTE__: Needless to say, the result types from `toml::parse(...)` and
+Needless to say, the result types from `toml::parse(...)` and
 `toml::parse<Com, Map, Cont>(...)` are different (unless you specify the same
 types as default).
 
+Note that, since `toml::table` and `toml::array` is an alias for a table and an
+array of a default `toml::value`, so it is different from the types actually
+contained in a `toml::basic_value` when you customize containers.
+To get the actual type in a generic way, use
+`typename toml::basic_type<C, T, A>::table_type` and
+`typename toml::basic_type<C, T, A>::array_type`.
+
 ## TOML literal
 
 toml11 supports `"..."_toml` literal.
@@ -945,7 +951,6 @@ inline namespace literals
 inline namespace toml_literals
 {
 toml::value operator"" _toml(const char* str, std::size_t len);
-
 } // toml_literals
 } // literals
 } // toml
@@ -1237,7 +1242,7 @@ const toml::source_location loc = v.location();
 toml11 enables you to serialize data into toml format.
 
 ```cpp
-const auto data = toml::table{{"foo", 42}, {"bar", "baz"}};
+const toml::value data{{"foo", 42}, {"bar", "baz"}};
 std::cout << data << std::endl;
 // bar = "baz"
 // foo = 42
@@ -1247,10 +1252,10 @@ toml11 automatically makes a small table and small array inline.
 You can specify the width to make them inline by `std::setw` for streams.
 
 ```cpp
-const auto data = toml::table{
-    {"qux",    toml::table{{"foo", 42}, {"bar", "baz"}}},
-    {"quux",   toml::array{"small", "array", "of", "strings"}},
-    {"foobar", toml::array{"this", "array", "of", "strings", "is", "too", "long",
+const toml::value data{
+    {"qux",    {{"foo", 42}, {"bar", "baz"}}},
+    {"quux",   {"small", "array", "of", "strings"}},
+    {"foobar", {"this", "array", "of", "strings", "is", "too", "long",
                 "to", "print", "into", "single", "line", "isn't", "it?"}},
 };
 
@@ -1290,7 +1295,7 @@ To control the precision of floating point numbers, you need to pass
 `std::setprecision` to stream.
 
 ```cpp
-const auto data = toml::table{
+const toml::value data{
     {"pi", 3.141592653589793},
     {"e",  2.718281828459045}
 };
@@ -1356,6 +1361,9 @@ are used. See [Customizing containers](#customizing-containers) for detail.
 flag that represents a kind of a string, `string_t::basic` and `string_t::literal`.
 Although `std::string` is not an exact toml type, still you can get a reference
 that points to internal `std::string` by using `toml::get<std::string>()` for convenience.
+The most important difference between `std::string` and `toml::string` is that
+`toml::string` will be formatted as a TOML string when outputed with `ostream`.
+This feature is introduced to make it easy to write a custom serializer.
 
 `Datetime` variants are `struct` that are defined in this library.
 Because `std::chrono::system_clock::time_point` is a __time point__,
@@ -1386,6 +1394,9 @@ Between v2 and v3, those interfaces are rearranged.
   - Because type conversion between a table and a value causes ambiguity while overload resolution
   - Also because `toml::table` is a normal STL container, implementing utility function is easy.
   - See [Finding a toml::value](#finding-a-tomlvalue) for detail.
+- An overload of `operator<<` and `toml::format` for `toml::table`s are dropped.
+  - Use `toml::value` instead.
+  - See [Serializing TOML data](#serializing-toml-data) for detail.
 - Interface around comments.
   - See [Preserving Comments](#preserving-comments) for detail.
 - An ancient `from_toml/into_toml` has been removed. Use arbitrary type conversion support.

tests/CMakeLists.txt

@@ -1,5 +1,6 @@
 set(TEST_NAMES
     test_datetime
+    test_string
     test_utility
     test_result
     test_traits

tests/check_serialization.cpp

@@ -0,0 +1,57 @@
+#include "toml.hpp"
+#include <iostream>
+#include <iomanip>
+
+int main(int argc, char **argv)
+{
+    if(argc != 2)
+    {
+        std::cerr << "usage: ./check [filename]" << std::endl;
+        return 1;
+    }
+
+    const std::string filename(argv[1]);
+
+    {
+        const auto data = toml::parse(filename);
+        {
+            std::ofstream ofs("tmp.toml");
+            ofs << std::setprecision(16) << std::setw(80) << data;
+        }
+        const auto serialized = toml::parse("tmp.toml");
+
+        if(data != serialized)
+        {
+            std::cerr << "============================================================\n";
+            std::cerr << "result (w/o comment) different: " << filename << std::endl;
+            std::cerr << "------------------------------------------------------------\n";
+            std::cerr << "# serialized\n";
+            std::cerr << serialized;
+            std::cerr << "------------------------------------------------------------\n";
+            std::cerr << "# data\n";
+            std::cerr << data;
+            return 1;
+        }
+    }
+    {
+        const auto data = toml::parse<toml::preserve_comments>(filename);
+        {
+            std::ofstream ofs("tmp.toml");
+            ofs << std::setprecision(16) << std::setw(80) << data;
+        }
+        const auto serialized = toml::parse<toml::preserve_comments>("tmp.toml");
+        if(data != serialized)
+        {
+            std::cerr << "============================================================\n";
+            std::cerr << "result (w/  comment) different: " << filename << std::endl;
+            std::cerr << "------------------------------------------------------------\n";
+            std::cerr << "# serialized\n";
+            std::cerr << serialized;
+            std::cerr << "------------------------------------------------------------\n";
+            std::cerr << "# data\n";
+            std::cerr << data;
+            return 1;
+        }
+    }
+    return 0;
+}

tests/test_comments.cpp

@@ -460,3 +460,55 @@ BOOST_AUTO_TEST_CASE(test_overwrite_comments)
         BOOST_TEST(u.as_integer() == 42);
     }
 }
+
+BOOST_AUTO_TEST_CASE(test_output_comments)
+{
+    using value_type = toml::basic_value<toml::preserve_comments>;
+    {
+        const value_type v(42, {"comment1", "comment2"});
+        std::ostringstream oss;
+        oss << v.comments();
+
+        std::ostringstream ref;
+        ref << "#comment1\n";
+        ref << "#comment2\n";
+
+        BOOST_TEST(oss.str() == ref.str());
+    }
+    {
+        const value_type v(42, {"comment1", "comment2"});
+        std::ostringstream oss;
+
+        // If v is not a table, toml11 assumes that user is writing something
+        // like the following.
+
+        oss << "answer = " << v;
+
+        BOOST_TEST(oss.str() == "answer = 42 #comment1comment2");
+    }
+
+    {
+        const value_type v(42, {"comment1", "comment2"});
+        std::ostringstream oss;
+
+        // If v is not a table, toml11 assumes that user is writing something
+        // like the following.
+
+        oss << toml::nocomment << "answer = " << v;
+
+        BOOST_TEST(oss.str() == "answer = 42");
+    }
+
+    {
+        const value_type v(42, {"comment1", "comment2"});
+        std::ostringstream oss;
+
+        // If v is not a table, toml11 assumes that user is writing something
+        // like the following.
+
+        oss << toml::nocomment << toml::showcomment << "answer = " << v;
+
+        BOOST_TEST(oss.str() == "answer = 42 #comment1comment2");
+    }
+
+}

tests/test_serialize_file.cpp

@@ -11,6 +11,39 @@
 #include <iostream>
 #include <fstream>
 
+template<typename Comment,
+         template<typename ...> class Table,
+         template<typename ...> class Array>
+bool has_comment_inside(const toml::basic_value<Comment, Table, Array>& v)
+{
+    if(!v.comments().empty())
+    {
+        return false;
+    }
+    // v itself does not have a comment.
+    if(v.is_array())
+    {
+        for(const auto& x : v.as_array())
+        {
+            if(has_comment_inside(x))
+            {
+                return false;
+            }
+        }
+    }
+    if(v.is_table())
+    {
+        for(const auto& x : v.as_table())
+        {
+            if(has_comment_inside(x.second))
+            {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+
 BOOST_AUTO_TEST_CASE(test_example)
 {
     const auto data = toml::parse("toml/tests/example.toml");
@@ -37,12 +70,12 @@ BOOST_AUTO_TEST_CASE(test_example_map_dq)
     const auto data = toml::parse<toml::discard_comments, std::map, std::deque>(
             "toml/tests/example.toml");
     {
-        std::ofstream ofs("tmp1.toml");
+        std::ofstream ofs("tmp1_map_dq.toml");
         ofs << std::setw(80) << data;
     }
 
     auto serialized = toml::parse<toml::discard_comments, std::map, std::deque>(
-            "tmp1.toml");
+            "tmp1_map_dq.toml");
     {
         auto& owner = toml::find(serialized, "owner");
         auto& bio   = toml::find<std::string>(owner, "bio");
@@ -80,17 +113,46 @@ BOOST_AUTO_TEST_CASE(test_example_with_comment)
     }
 }
 
+BOOST_AUTO_TEST_CASE(test_example_with_comment_nocomment)
+{
+    {
+        const auto data = toml::parse<toml::preserve_comments>("toml/tests/example.toml");
+        {
+            std::ofstream ofs("tmp1_com_nocomment.toml");
+            ofs << std::setw(80) << toml::nocomment << data;
+        }
+        const auto serialized = toml::parse<toml::preserve_comments>("tmp1_com_nocomment.toml");
+        // check no comment exist
+        BOOST_TEST(!has_comment_inside(serialized));
+    }
+    {
+        const auto data_nocomment = toml::parse("toml/tests/example.toml");
+        auto serialized = toml::parse("tmp1_com_nocomment.toml");
+        {
+            auto& owner = toml::find(serialized, "owner");
+            auto& bio   = toml::find<std::string>(owner, "bio");
+            const auto CR = std::find(bio.begin(), bio.end(), '\r');
+            if(CR != bio.end())
+            {
+                bio.erase(CR);
+            }
+        }
+        // check collectly serialized
+        BOOST_TEST(data_nocomment == serialized);
+    }
+}
+
 BOOST_AUTO_TEST_CASE(test_example_with_comment_map_dq)
 {
     const auto data = toml::parse<toml::preserve_comments, std::map, std::deque>(
             "toml/tests/example.toml");
     {
-        std::ofstream ofs("tmp1_com.toml");
+        std::ofstream ofs("tmp1_com_map_dq.toml");
         ofs << std::setw(80) << data;
     }
 
     auto serialized = toml::parse<toml::preserve_comments, std::map, std::deque>(
-            "tmp1_com.toml");
+            "tmp1_com_map_dq.toml");
     {
         auto& owner = toml::find(serialized, "owner");
         auto& bio   = toml::find<std::string>(owner, "bio");
@@ -102,11 +164,38 @@ BOOST_AUTO_TEST_CASE(test_example_with_comment_map_dq)
     }
     BOOST_TEST(data == serialized);
     {
-        std::ofstream ofs("tmp1_com1.toml");
+        std::ofstream ofs("tmp1_com1_map_dq.toml");
         ofs << std::setw(80) << serialized;
     }
 }
 
+BOOST_AUTO_TEST_CASE(test_example_with_comment_map_dq_nocomment)
+{
+    {
+        const auto data = toml::parse<toml::preserve_comments, std::map, std::deque>("toml/tests/example.toml");
+        {
+            std::ofstream ofs("tmp1_com_map_dq_nocomment.toml");
+            ofs << std::setw(80) << toml::nocomment << data;
+        }
+        const auto serialized = toml::parse<toml::preserve_comments, std::map, std::deque>("tmp1_com_map_dq_nocomment.toml");
+        BOOST_TEST(!has_comment_inside(serialized));
+    }
+    {
+        const auto data_nocomment = toml::parse("toml/tests/example.toml");
+        auto serialized = toml::parse("tmp1_com_map_dq_nocomment.toml");
+        {
+            auto& owner = toml::find(serialized, "owner");
+            auto& bio   = toml::find<std::string>(owner, "bio");
+            const auto CR = std::find(bio.begin(), bio.end(), '\r');
+            if(CR != bio.end())
+            {
+                bio.erase(CR);
+            }
+        }
+        BOOST_TEST(data_nocomment == serialized);
+    }
+}
+
 BOOST_AUTO_TEST_CASE(test_fruit)
 {
     const auto data = toml::parse("toml/tests/fruit.toml");
@@ -194,3 +283,23 @@ BOOST_AUTO_TEST_CASE(test_hard_example_with_comment)
     }
     BOOST_TEST(data == serialized);
 }
+
+BOOST_AUTO_TEST_CASE(test_format_key)
+{
+    {
+        const toml::key key("normal_bare-key");
+        BOOST_TEST("normal_bare-key" == toml::format_key(key));
+    }
+    {
+        const toml::key key("key.include.dots");
+        BOOST_TEST("\"key.include.dots\"" == toml::format_key(key));
+    }
+    {
+        const toml::key key("key-include-unicode-\xE3\x81\x82");
+        BOOST_TEST("\"key-include-unicode-\xE3\x81\x82\"" == toml::format_key(key));
+    }
+    {
+        const toml::key key("special-chars-\\-\"-\b-\f-\r-\n-\t");
+        BOOST_TEST("\"special-chars-\\\\-\\\"-\\b-\\f-\\r-\\n-\\t\"" == toml::format_key(key));
+    }
+}

tests/test_string.cpp

@@ -0,0 +1,113 @@
+#define BOOST_TEST_MODULE "test_string"
+#include <boost/test/unit_test.hpp>
+#include <toml.hpp>
+
+BOOST_AUTO_TEST_CASE(test_basic_string)
+{
+    {
+        const toml::string str("basic string");
+        std::ostringstream oss;
+        oss << str;
+        BOOST_TEST(oss.str() == "\"basic string\"");
+    }
+    {
+        const std::string  s1 ("basic string");
+        const toml::string str(s1);
+        std::ostringstream oss;
+        oss << str;
+        BOOST_TEST(oss.str() == "\"basic string\"");
+    }
+    {
+        const toml::string str("basic string", toml::string_t::basic);
+        std::ostringstream oss;
+        oss << str;
+        BOOST_TEST(oss.str() == "\"basic string\"");
+    }
+    {
+        const std::string  s1 ("basic string");
+        const toml::string str(s1, toml::string_t::basic);
+        std::ostringstream oss;
+        oss << str;
+        BOOST_TEST(oss.str() == "\"basic string\"");
+    }
+}
+
+BOOST_AUTO_TEST_CASE(test_basic_ml_string)
+{
+    {
+        const toml::string str("basic\nstring");
+        std::ostringstream oss1;
+        oss1 << str;
+        std::ostringstream oss2;
+        oss2 << "\"\"\"\nbasic\nstring\\\n\"\"\"";
+        BOOST_TEST(oss1.str() == oss2.str());
+    }
+    {
+        const std::string  s1 ("basic\nstring");
+        const toml::string str(s1);
+        std::ostringstream oss1;
+        oss1 << str;
+        std::ostringstream oss2;
+        oss2 << "\"\"\"\nbasic\nstring\\\n\"\"\"";
+        BOOST_TEST(oss1.str() == oss2.str());
+    }
+    {
+        const toml::string str("basic\nstring", toml::string_t::basic);
+        std::ostringstream oss1;
+        oss1 << str;
+        std::ostringstream oss2;
+        oss2 << "\"\"\"\nbasic\nstring\\\n\"\"\"";
+        BOOST_TEST(oss1.str() == oss2.str());
+
+    }
+    {
+        const std::string  s1 ("basic\nstring");
+        const toml::string str(s1, toml::string_t::basic);
+        std::ostringstream oss1;
+        oss1 << str;
+        std::ostringstream oss2;
+        oss2 << "\"\"\"\nbasic\nstring\\\n\"\"\"";
+        BOOST_TEST(oss1.str() == oss2.str());
+    }
+}
+
+
+BOOST_AUTO_TEST_CASE(test_literal_string)
+{
+    {
+        const toml::string str("literal string", toml::string_t::literal);
+        std::ostringstream oss;
+        oss << str;
+        BOOST_TEST(oss.str() == "'literal string'");
+    }
+    {
+        const std::string  s1 ("literal string");
+        const toml::string str(s1, toml::string_t::literal);
+        std::ostringstream oss;
+        oss << str;
+        BOOST_TEST(oss.str() == "'literal string'");
+    }
+}
+
+BOOST_AUTO_TEST_CASE(test_literal_ml_string)
+{
+    {
+        const toml::string str("literal\nstring", toml::string_t::literal);
+        std::ostringstream oss1;
+        oss1 << str;
+        std::ostringstream oss2;
+        oss2 << "'''\nliteral\nstring'''";
+        BOOST_TEST(oss1.str() == oss2.str());
+
+    }
+    {
+        const std::string  s1 ("literal\nstring");
+        const toml::string str(s1, toml::string_t::literal);
+        std::ostringstream oss1;
+        oss1 << str;
+        std::ostringstream oss2;
+        oss2 << "'''\nliteral\nstring'''";
+        BOOST_TEST(oss1.str() == oss2.str());
+    }
+}
+

toml/comments.hpp

@@ -162,12 +162,15 @@ struct preserve_comments
     const_reverse_iterator crbegin() const noexcept {return comments.crbegin();}
     const_reverse_iterator crend()   const noexcept {return comments.crend();}
 
-    friend bool operator==(const preserve_comments& lhs, const preserve_comments& rhs);
-    friend bool operator!=(const preserve_comments& lhs, const preserve_comments& rhs);
-    friend bool operator< (const preserve_comments& lhs, const preserve_comments& rhs);
-    friend bool operator<=(const preserve_comments& lhs, const preserve_comments& rhs);
-    friend bool operator> (const preserve_comments& lhs, const preserve_comments& rhs);
-    friend bool operator>=(const preserve_comments& lhs, const preserve_comments& rhs);
+    friend bool operator==(const preserve_comments&, const preserve_comments&);
+    friend bool operator!=(const preserve_comments&, const preserve_comments&);
+    friend bool operator< (const preserve_comments&, const preserve_comments&);
+    friend bool operator<=(const preserve_comments&, const preserve_comments&);
+    friend bool operator> (const preserve_comments&, const preserve_comments&);
+    friend bool operator>=(const preserve_comments&, const preserve_comments&);
+
+    friend void swap(preserve_comments&, std::vector<std::string>&);
+    friend void swap(std::vector<std::string>&, preserve_comments&);
 
   private:
 
@@ -186,6 +189,27 @@ inline void swap(preserve_comments& lhs, preserve_comments& rhs)
     lhs.swap(rhs);
     return;
 }
+inline void swap(preserve_comments& lhs, std::vector<std::string>& rhs)
+{
+    lhs.comments.swap(rhs);
+    return;
+}
+inline void swap(std::vector<std::string>& lhs, preserve_comments& rhs)
+{
+    lhs.swap(rhs.comments);
+    return;
+}
+
+template<typename charT, typename traits>
+std::basic_ostream<charT, traits>&
+operator<<(std::basic_ostream<charT, traits>& os, const preserve_comments& com)
+{
+    for(const auto& c : com)
+    {
+        os << '#' << c << '\n';
+    }
+    return os;
+}
 
 namespace detail
 {
@@ -381,5 +405,12 @@ inline bool operator>=(const discard_comments&, const discard_comments&) noexcep
 
 inline void swap(const discard_comments&, const discard_comments&) noexcept {return;}
 
+template<typename charT, typename traits>
+std::basic_ostream<charT, traits>&
+operator<<(std::basic_ostream<charT, traits>& os, const discard_comments&)
+{
+    return os;
+}
+
 } // toml11
 #endif// TOML11_COMMENTS_HPP

toml/parser.hpp

@@ -1973,7 +1973,7 @@ parse(std::istream& is, const std::string& fname = "unknown file")
 template<typename                     Comment = ::toml::discard_comments,
          template<typename ...> class Table   = std::unordered_map,
          template<typename ...> class Array   = std::vector>
-inline basic_value<Comment, Table, Array> parse(const std::string& fname)
+basic_value<Comment, Table, Array> parse(const std::string& fname)
 {
     std::ifstream ifs(fname.c_str(), std::ios_base::binary);
     if(!ifs.good())

toml/serializer.hpp

@@ -10,6 +10,45 @@
 namespace toml
 {
 
+// This function serialize a key. It checks a string is a bare key and
+// escapes special characters if the string is not compatible to a bare key.
+// ```cpp
+// std::string k("non.bare.key"); // the key itself includes `.`s.
+// std::string formatted = toml::format_key(k);
+// assert(formatted == "\"non.bare.key\"");
+// ```
+//
+// This function is exposed to make it easy to write a user-defined serializer.
+// Since toml restricts characters available in a bare key, generally a string
+// should be escaped. But checking whether a string needs to be surrounded by
+// a `"` and escaping some special character is boring.
+inline std::string format_key(const toml::key& key)
+{
+    detail::location<toml::key> loc(key, key);
+    detail::lex_unquoted_key::invoke(loc);
+    if(loc.iter() == loc.end())
+    {
+        return key; // all the tokens are consumed. the key is unquoted-key.
+    }
+    std::string token("\"");
+    for(const char c : key)
+    {
+        switch(c)
+        {
+            case '\\': {token += "\\\\"; break;}
+            case '\"': {token += "\\\""; break;}
+            case '\b': {token += "\\b";  break;}
+            case '\t': {token += "\\t";  break;}
+            case '\f': {token += "\\f";  break;}
+            case '\n': {token += "\\n";  break;}
+            case '\r': {token += "\\r";  break;}
+            default  : {token += c;      break;}
+        }
+    }
+    token += "\"";
+    return token;
+}
+
 template<typename Comment,
          template<typename ...> class Table,
          template<typename ...> class Array>
@@ -32,9 +71,10 @@ struct serializer
     serializer(const std::size_t w              = 80u,
                const int         float_prec     = std::numeric_limits<toml::floating>::max_digits10,
                const bool        can_be_inlined = false,
+               const bool        no_comment     = false,
                std::vector<toml::key> ks        = {})
-        : can_be_inlined_(can_be_inlined), float_prec_(float_prec), width_(w),
-          keys_(std::move(ks))
+        : can_be_inlined_(can_be_inlined), no_comment_(no_comment),
+          float_prec_(float_prec), width_(w), keys_(std::move(ks))
     {}
     ~serializer() = default;
 
@@ -217,12 +257,15 @@ struct serializer
                         failed = true;
                         break;
                     }
+                    if(!no_comment_)
+                    {
                         for(const auto& c : item.comments())
                         {
                             token += '#';
                             token += c;
                             token += '\n';
                         }
+                    }
 
                     const auto t = this->make_inline_table(item.as_table());
 
@@ -245,6 +288,8 @@ struct serializer
 
             std::string token;
             for(const auto& item : v)
+            {
+                if(!no_comment_)
                 {
                     for(const auto& c : item.comments())
                     {
@@ -252,6 +297,7 @@ struct serializer
                         token += c;
                         token += '\n';
                     }
+                }
                 token += "[[";
                 token += this->serialize_dotted_key(keys_);
                 token += "]]\n";
@@ -287,7 +333,7 @@ struct serializer
         token += "[\n";
         for(const auto& item : v)
         {
-            if(!item.comments().empty())
+            if(!item.comments().empty() && !no_comment_)
             {
                 // if comment exists, the element must be the only element in the line.
                 // e.g. the following is not allowed.
@@ -369,7 +415,8 @@ struct serializer
                 token += " = ";
             }
             token += this->make_inline_table(v);
-            if(token.size() < this->width_)
+            if(token.size() < this->width_ &&
+               token.end() == std::find(token.begin(), token.end(), '\n'))
             {
                 return token;
             }
@@ -390,16 +437,7 @@ struct serializer
 
     std::string serialize_key(const toml::key& key) const
     {
-        detail::location<toml::key> loc(key, key);
-        detail::lex_unquoted_key::invoke(loc);
-        if(loc.iter() == loc.end())
-        {
-            return key; // all the tokens are consumed. the key is unquoted-key.
-        }
-        std::string token("\"");
-        token += this->escape_basic_string(key);
-        token += "\"";
-        return token;
+        return ::toml::format_key(key);
     }
 
     std::string serialize_dotted_key(const std::vector<toml::key>& keys) const
@@ -472,6 +510,9 @@ struct serializer
     // if an element of a table or an array has a comment, it cannot be inlined.
     bool has_comment_inside(const array_type& a) const noexcept
     {
+        // if no_comment is set, comments would not be written.
+        if(this->no_comment_) {return false;}
+
         for(const auto& v : a)
         {
             if(!v.comments().empty()) {return true;}
@@ -480,6 +521,9 @@ struct serializer
     }
     bool has_comment_inside(const table_type& t) const noexcept
     {
+        // if no_comment is set, comments would not be written.
+        if(this->no_comment_) {return false;}
+
         for(const auto& kv : t)
         {
             if(!kv.second.comments().empty()) {return true;}
@@ -536,7 +580,7 @@ struct serializer
                 continue;
             }
 
-            if(!kv.second.comments().empty())
+            if(!kv.second.comments().empty() && !no_comment_)
             {
                 for(const auto& c : kv.second.comments())
                 {
@@ -575,8 +619,8 @@ struct serializer
             std::vector<toml::key> ks(this->keys_);
             ks.push_back(kv.first);
 
-            auto tmp = visit(serializer(
-                this->width_, this->float_prec_, !multiline_table_printed, ks),
+            auto tmp = visit(serializer(this->width_, this->float_prec_,
+                !multiline_table_printed, this->no_comment_, ks),
                 kv.second);
 
             if((!multiline_table_printed) &&
@@ -590,7 +634,7 @@ struct serializer
                 tmp += '\n';
             }
 
-            if(!kv.second.comments().empty())
+            if(!kv.second.comments().empty() && !no_comment_)
             {
                 for(const auto& c : kv.second.comments())
                 {
@@ -614,6 +658,7 @@ struct serializer
   private:
 
     bool        can_be_inlined_;
+    bool        no_comment_;
     int         float_prec_;
     std::size_t width_;
     std::vector<toml::key> keys_;
@@ -624,7 +669,7 @@ template<typename C,
 std::string
 format(const basic_value<C, M, V>& v, std::size_t w = 80u,
        int fprec = std::numeric_limits<toml::floating>::max_digits10,
-       bool force_inline = false)
+       bool no_comment = false, bool force_inline = false)
 {
     // if value is a table, it is considered to be a root object.
     // the root object can't be an inline table.
@@ -633,18 +678,43 @@ format(const basic_value<C, M, V>& v, std::size_t w = 80u,
         std::ostringstream oss;
         if(!v.comments().empty())
         {
-            for(const auto& c : v.comments())
-            {
-                oss << '#' << c << '\n';
+            oss << v.comments();
+            oss << '\n'; // to split the file comment from the first element
         }
-            oss << '\n';
-        }
-        oss << visit(serializer<C, M, V>(w, fprec, false), v);
+        oss << visit(serializer<C, M, V>(w, fprec, no_comment, false), v);
         return oss.str();
     }
     return visit(serializer<C, M, V>(w, fprec, force_inline), v);
 }
 
+namespace detail
+{
+template<typename charT, typename traits>
+int comment_index(std::basic_ostream<charT, traits>&)
+{
+    static const int index = std::ios_base::xalloc();
+    return index;
+}
+} // detail
+
+template<typename charT, typename traits>
+std::basic_ostream<charT, traits>&
+nocomment(std::basic_ostream<charT, traits>& os)
+{
+    // by default, it is zero. and by defalut, it shows comments.
+    os.iword(detail::comment_index(os)) = 1;
+    return os;
+}
+
+template<typename charT, typename traits>
+std::basic_ostream<charT, traits>&
+showcomment(std::basic_ostream<charT, traits>& os)
+{
+    // by default, it is zero. and by defalut, it shows comments.
+    os.iword(detail::comment_index(os)) = 0;
+    return os;
+}
+
 template<typename charT, typename traits, typename C,
          template<typename ...> class M, template<typename ...> class V>
 std::basic_ostream<charT, traits>&
@@ -655,16 +725,40 @@ operator<<(std::basic_ostream<charT, traits>& os, const basic_value<C, M, V>& v)
     const int  fprec = static_cast<int>(os.precision());
     os.width(0);
 
-    if(!v.comments().empty())
+    // by defualt, iword is initialized byl 0. And by default, toml11 outputs
+    // comments. So `0` means showcomment. 1 means nocommnet.
+    const bool no_comment = (1 == os.iword(detail::comment_index(os)));
+
+    if(!no_comment && v.is_table() && !v.comments().empty())
     {
-        for(const auto& c : v.comments())
-        {
-            os << '#' << c << '\n';
-        }
-        os << '\n';
+        os << v.comments();
+        os << '\n'; // to split the file comment from the first element
     }
     // the root object can't be an inline table. so pass `false`.
-    os << visit(serializer<C, M, V>(w, fprec, false), v);
+    os << visit(serializer<C, M, V>(w, fprec, false, no_comment), v);
+
+    // if v is a non-table value, and has only one comment, then
+    // put a comment just after a value. in the following way.
+    //
+    // ```toml
+    // key = "value" # comment.
+    // ```
+    //
+    // Since the top-level toml object is a table, one who want to put a
+    // non-table toml value must use this in a following way.
+    //
+    // ```cpp
+    // toml::value v;
+    // std::cout << "user-defined-key = " << v << std::endl;
+    // ```
+    //
+    // In this case, it is impossible to put comments before key-value pair.
+    // The only way to preserve comments is to put all of them after a value.
+    if(!no_comment && !v.is_table() && !v.comments().empty())
+    {
+        os << " #";
+        for(const auto& c : v.comments()) {os << c;}
+    }
     return os;
 }
 

toml/string.hpp

@@ -139,9 +139,74 @@ operator>=(const char* lhs, const string& rhs) {return std::string(lhs) >= rhs.s
 
 template<typename charT, typename traits>
 std::basic_ostream<charT, traits>&
-operator<<(std::basic_ostream<charT, traits>& os, const string& str)
+operator<<(std::basic_ostream<charT, traits>& os, const string& s)
 {
-    os << str.str;
+    if(s.kind == string_t::basic)
+    {
+        if(std::find(s.str.cbegin(), s.str.cend(), '\n') != s.str.cend())
+        {
+            // it contains newline. make it multiline string.
+            os << "\"\"\"\n";
+            for(auto i=s.str.cbegin(), e=s.str.cend(); i!=e; ++i)
+            {
+                switch(*i)
+                {
+                    case '\\': {os << "\\\\"; break;}
+                    case '\"': {os << "\\\""; break;}
+                    case '\b': {os << "\\b";  break;}
+                    case '\t': {os << "\\t";  break;}
+                    case '\f': {os << "\\f";  break;}
+                    case '\n': {os << '\n';   break;}
+                    case '\r':
+                    {
+                        // since it is a multiline string,
+                        // CRLF is not needed to be escaped.
+                        if(std::next(i) != e && *std::next(i) == '\n')
+                        {
+                            os << "\r\n";
+                            ++i;
+                        }
+                        else
+                        {
+                            os << "\\r";
+                        }
+                        break;
+                    }
+                    default: {os << *i; break;}
+                }
+            }
+            os << "\\\n\"\"\"";
+            return os;
+        }
+        // no newline. make it inline.
+        os << "\"";
+        for(const auto c : s.str)
+        {
+            switch(c)
+            {
+                case '\\': {os << "\\\\"; break;}
+                case '\"': {os << "\\\""; break;}
+                case '\b': {os << "\\b";  break;}
+                case '\t': {os << "\\t";  break;}
+                case '\f': {os << "\\f";  break;}
+                case '\n': {os << "\\n";  break;}
+                case '\r': {os << "\\r";  break;}
+                default  : {os << c;      break;}
+            }
+        }
+        os << "\"";
+        return os;
+    }
+    // the string `s` is literal-string.
+    if(std::find(s.str.cbegin(), s.str.cend(), '\n') != s.str.cend() ||
+       std::find(s.str.cbegin(), s.str.cend(), '\'') != s.str.cend() )
+    {
+        // contains newline or single quote. make it multiline.
+        os << "'''\n" << s.str << "'''";
+        return os;
+    }
+    // normal literal string
+    os << '\'' << s.str << '\'';
     return os;
 }
 

toml/value.hpp

@@ -1569,7 +1569,7 @@ class basic_value
 
     source_location location() const
     {
-        return source_location(this->region_info_);
+        return source_location(this->region_info_.get());
     }
 
     comment_type const& comments() const noexcept {return this->comments_;}