From 36199498b429f33e793e21e019898fff3656e911 Mon Sep 17 00:00:00 2001 From: ToruNiina Date: Sat, 13 May 2017 15:04:02 +0900 Subject: [PATCH] add README --- README.md | 194 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 194 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..989da2c --- /dev/null +++ b/README.md @@ -0,0 +1,194 @@ +toml11 +====== + +c++11 header-only toml parser depending only on c++11 standard library. + +compatible to TOML v0.4.0. + +## How to use + +Just include the file after adding correct include path. + +```cpp +#include + +int main() +{ + /* do something ... */ +} +``` + +### decoding toml file + +The only thing you have to do is passing filename to `toml::parse` function. + +```cpp +const std::string fname("sample.toml"); +const auto data = toml::parse(fname); +``` + +In the case of file open error, it will throw `std::runtime_error`. + +You can pass also `stream` to `toml::parse` function. + +```cpp +std::ifstream ifs("sample.toml"); +assert(ifs.good()); +const auto data = toml::parse(ifs); +``` + +If there are syntax error in the toml file, +`toml::parse` will throw `toml::syntax_error`. + +#### toml::get() + +Then you can obtain the various value from the `data` using `toml::get` function +no matter what the value type is. + +``` cpp +const auto answer = toml::get(data.at("answer")); +const auto pi = toml::get(data.at("pi")); +const auto numbers = toml::get>(data.at("numbers")); +const auto timepoint = toml::get(data.at("time")); +``` + +You can set any kind of `container` class to obtain `toml::Array` except for +`map`-like class. + +``` cpp +const auto vc = toml::get>(data.at("numbers")); +const auto ls = toml::get>(data.at("numbers")); +const auto dq = toml::get>(data.at("numbers")); +// if size of data.at("numbers") is larger than 3, it will throw toml::type_error. +const auto ar = toml::get>(data.at("numbers")); +``` + +If the type you passed as a template parameter is incorrect, +it will throw `toml::type_error`. + +#### value\_t and toml::value::type() + +When you don't know the exact type of toml-value, you can get `enum` type from +`toml::value`. + +```cpp +int i; +double d; +std::string s; +std::vector a; +const auto t = data.at("something").type(); +switch(t) +{ + case toml::value_t::Integer: i = toml::get(data.at("something")); + case toml::value_t::Float : d = toml::get(data.at("something")); + case toml::value_t::String : s = toml::get(data.at("something")); + case toml::value_t::Array : a = toml::get>(data.at("something")); + default : throw std::runtime_error("unexpected type : " + stringize(t)); +} +``` + +Okey, but it is painful to write `switch-case` for many time. + +#### toml::from\_toml() + +The more sophisticated way is using `toml::from_toml` and `std::tie`. + +```cpp +int i = 0; +double d = 0.; +std::string s; +std::vector a; + +toml::from_toml(std::tie(i, d, s, a), data.at("something")); +``` + +Here, only matched value will be filled. +The others are left intact after calling `from_toml`. + +`from_toml` can be used also for single type. + +```cpp +int i; +toml::from_toml(i, data.at("something")); +``` + +Unlike `toml::get`, `toml::from_toml` does not require to specify the type +through the template argument because the type can be deduced from argument. + +#### toml::value + +In toml, `Array` is capable of having `Array` s and each of them possibly have +different types like this. + +```toml +array_of_array = [[1,2,3,4,5], ["foo", "bar", "baz"]] +``` + +In this case, you can use `toml::value` directly. + +```cpp +// use toml::value +const auto a = toml::get>(data.at("array_of_array")); +// you can obtain values from toml::value in the same way as described above. +const auto ns = toml::get>(a.at(0)); +const auto ss = toml::get>(a.at(1)); +``` + +## Documentation + +The toml types are listed below. + +| toml-type | c++ type | +| --------- | -------------- | +| Boolean | `bool` | +| Integer | `std::int64_t` | +| Float | `double` | +| String | `std::string` | +| Datetime | `toml::Datetime` | +| Array | `std::vector` | +| Table | `std::unordered_map` | + +`Datetime` is the `struct` that is defined in this library. +Because `std::chrono::system_clock::time_point` is a __time point__, not capable +of representing a Local Time independent from a specific day. + +For user-convenience, `toml::Datetime` is _implicitly_ convertible to +`std::chrono::system_clock::time_point`. If `toml::Datetime` does not have any +Date information, the information will be generated from +`std::chrono::system_clock::now()` when cast is performed. + +The definition of Datetime struct is below. + +```cpp +namespace toml +{ +template +struct basic_datetime +{ + uintT year; // since 0. + uintT month; // [1-12] + uintT day; // [1-31] + uintT hour; // [0-23] + uintT minite; // [0-59] + uintT second; // [0-59] + uintT millisecond // [0-999] + uintT microsecond // [0-999] + intT offset_hour; // [-12 - +12] + intT offset_minute; // [-59 - +59] +}; + +typedef basic_datetime Datetime; +} +``` + +It must be noted that the range of some values in `basic_datetime` is different +from `std::tm`. For example, month is in the range of `[1,12]` and year starts +from 0 (not 1900). + +## Licensing terms + +This product is licensed under the terms of the [MIT License](LICENSE). + +- Copyright (c) 2017 Toru Niina + +All rights reserved.