Merge pull request #13 from ToruNiina/error-format

enable to show user-defined error message with (a) toml::value(s)

README.md

@@ -402,6 +402,59 @@ terminate called after throwing an instance of 'std::range_error'
    |                     ~~~~~~~~~ should be in [0x00..0x10FFFF]
 ```
 
+### Formatting your error
+
+When you encounter an error after you read the toml value, you may want to
+show the error with the value.
+
+toml11 provides you a function that formats user-defined error message with
+related values. With a code like the following,
+
+```cpp
+const auto value = toml::find<int>(data, "num");
+if(value < 0)
+{
+    std::cerr << toml::format_error("[error] value should be positive",
+                                    data.at("num"), "positive number required")
+              << std::endl;
+}
+```
+
+you will get an error message like this.
+
+```console
+[error] value should be positive
+ --> example.toml
+ 3 | num = -42
+   |       ~~~ positive number required
+```
+
+When you pass two values to `toml::format_error`,
+
+```cpp
+const auto min = toml::find<int>(range, "min");
+const auto max = toml::find<int>(range, "max");
+if(max < min)
+{
+    std::cerr << toml::format_error("[error] max should be larger than min",
+                                    data.at("min"), "minimum number here",
+                                    data.at("max"), "maximum number here");
+              << std::endl;
+}
+```
+
+you will get an error message like this.
+
+```console
+[error] value should be positive
+ --> example.toml
+ 3 | min = 54
+   |       ~~ minimum number here
+ ...
+ 4 | max = 42
+   |       ~~ maximum number here
+```
+
 ## Underlying types
 
 The toml types (can be used as `toml::*` in this library) and corresponding `enum` names are listed in the table below.

toml/value.hpp

@@ -800,5 +800,19 @@ inline bool operator>=(const toml::value& lhs, const toml::value& rhs)
     return !(lhs < rhs);
 }
 
+inline std::string format_error(const std::string& err_msg,
+        const toml::value& v, const std::string& comment)
+{
+    return detail::format_underline(err_msg, detail::get_region(v), comment);
+}
+
+inline std::string format_error(const std::string& err_msg,
+        const toml::value& v1, const std::string& comment1,
+        const toml::value& v2, const std::string& comment2)
+{
+    return detail::format_underline(err_msg, detail::get_region(v1), comment1,
+                                             detail::get_region(v2), comment2);
+}
+
 }// toml
 #endif// TOML11_VALUE