zhangyiss/toml11
1
0
Fork 0
mirror of https://github.com/ToruNiina/toml11.git synced 2025-09-16 08:27:31 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

doc: add reference manual

Browse Source
This commit is contained in:
ToruNiina
2024-06-15 19:27:42 +09:00
parent 7210e708a6
commit 64197caa05
77 changed files with 18139 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
docs/config.toml Normal file
View File

@@ -0,0 +1,38 @@
baseURL = "https://toruniina.github.io/toml11"
title = "toml11"
languageCode = "en-us"
disablePathToLower = true
[module]
[[module.imports]]
path = 'github.com/alex-shpak/hugo-book'
[languages]
[languages.en]
weight = 1
languageName = "English"
contentDir = "content.en"
[languages.ja]
weight = 2
languageName = "日本語"
contentDir = "content.ja"
[menu]
[[menu.after]]
name = "GitHub"
url = "https://github.com/ToruNiina/toml11"
weight = 10
[params]
BookTheme = 'auto'
BookToC = true
BookSection = 'docs'
BookSearch = true
BookComments = false
BookRepo = 'https://github.com/ToruNiina/toml11'
[markup.tableOfContents]
startLevel = 1
endLevel = 3

25
docs/content.en/_index.md Normal file
View File

@@ -0,0 +1,25 @@
+++
title = "Introduction"
type = "docs"
+++
# Introduction
日本語版は[こちら](/toml11/ja/)
## [Installation]({{< relref "/installation" >}})
This section describes how to build and install toml11.
## [Features]({{< relref "/features" >}})
This section describes how to use toml11's features with examples.
## [Reference]({{< relref "/reference" >}})
This section details toml11 functions and classes.
## [ChangeLog]({{< relref "/changelog" >}})
This section describes changes from release to release.

293
docs/content.en/docs/changelog/_index.md Normal file
View File

@@ -0,0 +1,293 @@
+++
title = "changelog"
type = "docs"
weight = 4
+++
# Change Log
# Changes from v3
## Breaking Changes
### Changed `template` Parameters of `toml::basic_value`
In toml11 v3, `toml::basic_value` took separate template arguments for the comment container, table-type container, and array-type container.
```cpp
template<typename Comment,
template<typename ...> class Table = std::unordered_map,
template<typename ...> class Array = std::vector>
class basic_value;
```
However, this approach does not accommodate changes to types such as `integer_type`.
In toml11 v4, `toml::basic_value` now accepts a single `TypeConfig`, allowing for more types to be customized.
```cpp
template<typename TypeConfig>
class basic_value;
```
By default, the types stored in `toml::value` remain unchanged.
For more information on changing types, please refer to the
[`type_config`]({{< ref "/docs/reference/types.md">}}) documentation.
### Removed `std::initializer_list` Support for `toml::basic_value`
In toml11 v3, there was an overload for `toml::value` that accepted `std::initializer_list`. This allowed for more intuitive initialization of `toml::value` with arrays and tables.
```cpp
// toml11 v3
toml::value v{1,2,3,4,5};
toml::value v{ {"a", 42}, {"b", "foo"} };
```
However, this caused the following issues:
First, it was impossible to distinguish between a single-element array and a regular value, as it always became an array.
```cpp
// toml11 v3
toml::value v{1}; // Becomes [1,] instead of 1
```
With the widespread use of uniform initialization, this became very inconvenient.
Second, it was unclear whether the value represented a table with all string values or a nested array.
```cpp
// toml11 v3
toml::value v{ {"a", "foo"}, {"b", "bar"} };
// Could be either:
// {a = "foo", b = "bar"}
// [["a", "foo"], ["b", "bar"]]
```
These issues were difficult to resolve due to language specifications.
To avoid confusion, toml11 v4 has removed `std::initializer_list` support.
When initializing `toml::value` with an array, you must explicitly specify `toml::array`, and when initializing with a table, you must explicitly specify `toml::table`.
```cpp
// toml11 v4
toml::value v(toml::array{1,2,3,4,5});
toml::value v(toml::table{ {"a", 42}, {"b", "foo"} });
toml::value v{toml::array{1}}; // [1,]
toml::value v{1} // 1
toml::value v{toml::table{{"a", "foo"}, {"b", "bar"}}};
toml::value v{toml::array{toml::array{"a", "foo"}, toml::array{"b", "bar"}}};
```
While this makes initializing `toml::value` with tables or arrays slightly less convenient, it ensures that the values will not become unpredictable by requiring explicit type information.
### Renamed `toml::basic_value::is_uninitialized()` to `is_empty()`
In toml11 v3, the function to check whether a `basic_value` was uninitialized was called `is_uninitialized`.
However, in toml11 v4, the library supports `null` values as an extension, allowing for the intentional construction of empty values.
Therefore, the function has been renamed to `is_empty` to reflect this change.
### Added Format Information and Removed `toml::string`
In toml11 v3, to retain information on whether a string was `basic` or `literal`, the library used a thin wrapper around `std::string` called `toml::string`.
```cpp
// toml11 v3
namespace toml
{
enum class string_t : std::uint8_t
{
basic = 0,
literal = 1,
};
struct string
{
string_t kind;
std::string str;
};
} // namespace toml
```
In toml11 v4, to accommodate more format information such as the numeric base or whether arrays should be multiline, every type now has an associated `xxx_format` type, which is stored alongside the value.
```cpp
// toml11 v4
enum class string_format : std::uint8_t
{
basic = 0,
literal = 1,
multiline_basic = 2,
multiline_literal = 3
};
struct string_format_info
{
string_format fmt = string_format::basic;
bool start_with_newline = false;
};
```
This change allows for more detailed format information to be preserved, ensuring that format specifics for numeric types, arrays, and tables are maintained even after parsing.
### Changed Arguments of `toml::format`
In toml11 v3, `toml::format` accepted values such as the precision and width of numeric types.
However, this approach did not allow for detailed formatting specifications, resulting in serialized files that did not match expectations.
In toml11 v4, each `toml::value` now carries its own format information, enabling more detailed formatting options to be preserved within the `toml::value` itself.
As a result, `toml::format` no longer accepts specific formatting values. Instead, it now only takes a `toml::spec`, which includes language feature flags used during formatting.
### Changed Member Functions of `toml::source_location`
In toml11 v3, the member types of `toml::source_location` were designed to handle only single lines.
In toml11 v4, the member types of `toml::source_location` are designed to handle multiple lines.
### Renamed `toml::format_underline` to `toml::format_location`
In toml11 v3, the function used to format location information from `toml::source_location` was called `toml::format_underline`.
To make the name clearer, it has been renamed to `toml::format_location`.
## Changed Arguments of `toml::format_error`
In toml11 v3, there was no class to represent error information, resulting in complex arguments for `toml::format_error`.
```cpp
template<typename C, template<typename ...> class T, template<typename ...> class A>
std::string format_error(const std::string& err_msg,
const basic_value<C, T, A>& v, const std::string& comment,
std::vector<std::string> hints = {},
const bool colorize = TOML11_ERROR_MESSAGE_COLORIZED);
template<typename C, template<typename ...> class T, template<typename ...> class A>
inline std::string format_error(const std::string& err_msg,
const toml::basic_value<C, T, A>& v1, const std::string& comment1,
const toml::basic_value<C, T, A>& v2, const std::string& comment2,
std::vector<std::string> hints = {},
const bool colorize = TOML11_ERROR_MESSAGE_COLORIZED);
template<typename C, template<typename ...> class T, template<typename ...> class A>
inline std::string format_error(const std::string& err_msg,
const toml::basic_value<C, T, A>& v1, const std::string& comment1,
const toml::basic_value<C, T, A>& v2, const std::string& comment2,
const toml::basic_value<C, T, A>& v3, const std::string& comment3,
std::vector<std::string> hints = {},
const bool colorize = TOML11_ERROR_MESSAGE_COLORIZED);
```
In toml11 v4, we have introduced `class error_info` and `make_error_info`, simplifying the arguments for `format_error`.
```cpp
std::string format_error(const error_info& err);
std::string format_error(const std::string& errkind, const error_info& err);
template<typename ... Ts>
std::string format_error(std::string title,
source_location loc, std::string msg, Ts&& ... tail);
template<typename TC, typename ... Ts>
std::string format_error(std::string title,
const basic_value<TC>& v, std::string msg, Ts&& ... tail);
```
### Changed Control of `toml::color`
In toml11 v3, to control whether to colorize the output, we used the manipulator `toml::colorize` in conjunction with `toml::color::enable/disable`.
The manipulator allowed us to decide whether to apply color to each stream,
but in v4, the frequency of using streams has decreased,
and issues such as the fact that `std::ios_base::xalloc` used internally is not thread-safe in C++11 have arisen.
Therefore, we have decided to use only `toml::color::enable/disable` and have removed `toml::colorize`.
## Non-Breaking Changes
### Added `parse_str`
In toml11 v3, there was no function to directly parse a string itself.
Therefore, when parsing a string, it was necessary to use `std::istringstream`.
To address this inconvenience, we have added `toml::parse_str`, allowing for direct parsing of strings.
### Added `try_parse`
In toml11 v3, when a parser encountered an error, it threw `toml::syntax_error`.
However, there are cases where you do not want to throw exceptions due to environments where exceptions cannot be thrown, or for reasons of performance.
In toml11 v4, we have implemented `toml::try_parse` using `toml::result`, which communicates parsing failures without throwing exceptions.
This doesn't mean exceptions are never thrown. Errors in the standard library being used, such as `std::bad_alloc` due to allocation failure from memory exhaustion, may still be thrown.
### Support for Parsing Byte Sequences
To allow for parsing TOML content obtained through means other than files, we have added `toml::parse` and `toml::try_parse` functions that accept `std::vector<unsigned char>`.
### Added `toml::spec`
In toml11 v3, all new features of the TOML language were incorporated, and features that were decided to be introduced in future versions of the TOML language were controlled by the macro `TOML11_USE_UNRELEASED_TOML_FEATURES`.
This was because, at the time of developing toml11 v3, the TOML language had not yet reached version 1.0.0, being at versions 0.4.0 to 0.5.0.
As not all users are familiar with the latest TOML language specification, displaying error messages based on an older language usage could confuse the entire community. Therefore, until reaching version 1.0.0, it was necessary to provide new language specifications as quickly as possible and encourage users to update.
However, the current TOML language specification is at version 1.0.0. Therefore, there was a need to be mindful of the choice to continue using version 1.0.0 even after TOML v1.1.0 was released.
To allow for more flexibility in selecting the TOML language specification, we introduced `toml::spec`, enabling the TOML language version to be changed at runtime.
Additionally, in `toml::spec`, flags are set for each language feature, allowing for the testing of specific language features only.
This mechanism is also used for TOML-specific language extensions in toml11 v4.
### Added Format Information
In toml11 v3, format information was not saved except for strings, and during serialization, only width and precision were considered.
However, this resulted in hexadecimal integers being serialized as decimal integers and no reliable way to ensure inline tables.
In toml11 v4, format information (`integer_format`, etc.) has been added to all TOML types, and it is now considered during parsing and serialization.
This allows for more detailed format information to be set for values, such as hexadecimal integers or inline tables.
### Changed to `preserve_comments` by Default
In toml11 v3, comments were not parsed by default and were also not serialized.
This was because comments were a later introduced feature and were being read through a special hack.
In toml11 v4, comments are parsed, preserved, and serialized by default.
Furthermore, the parser implementation has been significantly changed to ensure comments are parsed alongside other elements.
### Changed to Preserve Comments by Default
In toml11 v3, comments were neither parsed nor serialized by default. This was because comment support was a late addition, implemented through a special hack.
In toml11 v4, comments are now parsed, preserved, and serialized by default. The parser implementation has also been significantly revised so that comments are parsed just like any other element.
### Added `single_include/toml.hpp`
toml11 is a versatile library with different header files for various features to enhance development efficiency. However, this required a certain amount of effort to install.
Starting with toml11 v4, a `single_include/toml.hpp` file has been added, which combines all the header files in the correct order. This allows the library to be installed by simply copying a single file.
### Option to Use Precompiled Library
Due to the extensive use of templates in toml11, compile times have been long.
In toml11 v4, the number of precompilable functions has been increased, allowing them to be compiled ahead of time into a library. This is expected to reduce compile times when using the library in large-scale development projects.
### Reference Documentation
Previously, all features were documented in the README, with no detailed function definitions or reference materials available in Japanese.
In toml11 v4, reference documentation has been included, provided in both Japanese and English. However, since the library author is a native Japanese speaker, the Japanese content is considered primary. If there are discrepancies between the Japanese and English content, the Japanese version takes precedence.

100
docs/content.en/docs/features/_index.md Normal file
View File

@@ -0,0 +1,100 @@
+++
title = "features"
type = "docs"
weight = 2
bookCollapseSection = true
+++
# Features
This section explains the main features provided by toml11, with examples.
## [Parsing Files and Strings](parsing_files)
Describes the functions for parsing files and strings, and how to handle the errors they produce.
Includes:
- Parsing files
- Parsing strings
- Parsing byte arrays
- Parsing files without throwing exceptions
- Parsing strings without throwing exceptions
- Parsing byte arrays without throwing exceptions
## [Extracting Values from `toml::value`](value)
Explains how to examine, extract, and convert the data types held by `toml::value`.
Includes:
- Checking the type of a value using member functions
- Accessing values using member functions
- Accessing comments
- Handling inline tables and dotted keys
- Handling date information
- Using `toml::get<T>` for conversion
- Using `toml::get_or` to specify a fallback value
- Using `toml::find<T>` for searching and conversion
- Using `toml::find_or` to specify a fallback value
- Defining conversions with user-defined types
- Applying functions with `toml::visit`
- Constructing `toml::value`
## [Creating Error Messages](error_message)
Explains how to generate error messages with location information from a TOML file using `toml::value`.
Includes:
- Extracting location information from `toml::value`
- Constructing error messages
- Adding color to the output
## [Serializing TOML Files](serialize)
Describes how to format the values of `toml::value` and the available formatting options.
Includes:
- Specifying formats for each value of `toml::value`
- Formatting `toml::value` into a string
## [Configuring Types of `toml::value`](configure_types)
Explains how to customize the types stored in `toml::value` (such as `integer_type` and `table_type`).
Includes:
- Defining `type_config`
- Using `ordered_type_config`
- Disabling comment preservation
- Using different containers like `std::deque`
- Using different numeric types like `boost::multiprecision`
## [TOML Literals](literal)
Explains the `_toml` literal for embedding TOML files directly in C++ code.
Includes:
- Using TOML literals
## [TOML Language Version](toml_spec)
Describes the versions of the TOML language supported by toml11 and how to control language features added in TOML-v1.1.0.
Includes:
- Using TOML language version 1.1.0
- Using specific features of TOML language version 1.1.0
## [TOML Language Extensions](extension)
Explains the custom extensions to the TOML language provided by toml11.
Includes:
- Supporting `null`
- Supporting hexadecimal format for floating-point numbers
- Allowing units for numbers

188
docs/content.en/docs/features/configure_types.md Normal file
View File

@@ -0,0 +1,188 @@
+++
title = "configuring types"
type = "docs"
weight = 50
+++
# Customizing Types
The `toml::value` class uses `std::int64_t` for `integer_type` and `std::unordered_map<key_type, value_type>` for `table_type`.
However, in some cases, you may want to use `boost::multiprecision::int128_t` or `std::map`.
To accommodate this, `toml::value` is implemented with template parameters that allow you to change the stored types.
Just as `std::string` is actually an alias for `std::basic_string<char, std::char_traits<char>, std::allocator<char>>`, `toml::value` is an alias for `toml::basic_value<toml::type_config>`.
Here, we will explain the types contained in `toml::type_config` and how to define a different `config` type.
## `type_config`
The `type_config` class contains the following member types and `static` member functions:
```cpp
namespace toml
{
struct type_config
{
using comment_type = preserve_comments;
using boolean_type = bool;
using integer_type = std::int64_t;
using floating_type = double;
using string_type = std::string;
template<typename T>
using array_type = std::vector<T>;
template<typename K, typename T>
using table_type = std::unordered_map<K, T>;
static result<integer_type, error_info>
parse_int(const std::string& str, const source_location src, const std::uint8_t base);
static result<floating_type, error_info>
parse_float(const std::string& str, const source_location src, const bool is_hex);
};
}
```
`toml::basic_value<TypeConfig>` defines the stored `boolean_type` as `TypeConfig::boolean_type`, the stored `integer_type` as `TypeConfig::integer_type`, and so on.
Additionally, `array_type` is defined as `TypeConfig::array_type<toml::basic_value<TypeConfig>>` and `table_type` is defined as `TypeConfig::table_type<key_type, toml::basic_value<TypeConfig>>`.
By passing a class that defines these member types and functions to `toml::basic_value`, you can customize the types used by that `toml::basic_value`.
The `parse_int` and `parse_float` functions provide parsing methods when custom numeric types are used. These functions receive strings with prefixes like `0x` and digit separators like `_` removed, such as `123456` or `DEADBEEF`. The `base` parameter will be one of `10`, `16`, `8`, or `2`. Implement these functions to parse your custom `integer_type` and `floating_type`.
As a default implementation, `toml::read_int` and `toml::read_float` are provided.
```cpp
static result<integer_type, error_info>
parse_int(const std::string& str, const source_location src, const std::uint8_t base)
{
return toml::read_int<integer_type>(str, src, base);
}
static result<floating_type, error_info>
parse_float(const std::string& str, const source_location src, const bool is_hex)
{
return toml::read_float<floating_type>(str, src, is_hex);
}
```
The `read_int` function uses `istream` and employs `std::hex` and `std::oct` for hexadecimal and octal parsing, respectively. For binary parsing, it is implemented using multiplication and addition. If your type supports these operations, you can use `read_int` as-is.
The `read_float` function also uses `istream`. Hexadecimal floating-point numbers are only supported for `double` and `float` types. If `read_float` is called with any other type and `hexfloat` is used, it will always return a parse error. Therefore, if you need to use a floating-point type other than `double` or `float` with `hexfloat`, you will need to implement support for that. If `hexfloat` is not used, no additional implementation is necessary.
## Preserving Order of Values in Tables
In addition to the default `toml::type_config`, there is also `toml::ordered_type_config`. This changes the `table_type` to an [ordered_map]({{< ref "docs/reference/ordered_map" >}}).
Using this, `toml::ordered_value` is defined, along with aliases for its array and table types as `toml::ordered_array` and `toml::ordered_table`, respectively.
You can use `toml::ordered_value` by calling `toml::parse(...)` as `toml::parse<toml::ordered_type_config>(...)`.
## Not Preserving Comments
The `type_config` defines a container for storing comments via `comment_type`.
If comments do not contain significant information and can be discarded during parsing, specify `toml::discard_comments` for `comment_type`.
```cpp
struct wo_comment_config
{
using comment_type = toml::discard_comments; // XXX
using boolean_type = bool;
using integer_type = std::int64_t;
using floating_type = double;
using string_type = std::string;
template<typename T>
using array_type = std::vector<T>;
template<typename K, typename T>
using table_type = std::unordered_map<K, T>;
static result<integer_type, error_info>
parse_int(const std::string& str, const source_location src, const std::uint8_t base)
{
return toml::read_int<integer_type>(str, src, base);
}
static result<floating_type, error_info>
parse_float(const std::string& str, const source_location src, const bool is_hex)
{
return toml::read_float<floating_type>(str, src, is_hex);
}
};
```
## Using Containers Other Than `std::vector` for Arrays
To use a container other than `vector` (e.g., `std::deque`) for implementing TOML arrays, modify `array_type` as follows.
Similarly, to use a container other than `unordered_map` (e.g., `std::map`) for table types, modify `table_type` as shown below.
```cpp
struct deque_map_config
{
using comment_type = toml::preserve_comments;
using boolean_type = bool;
using integer_type = std::int64_t;
using floating_type = double;
using string_type = std::string;
template<typename T>
using array_type = std::deque<T>; // XXX
template<typename K, typename T>
using table_type = std::map<K, T>; // XXX
static result<integer_type, error_info>
parse_int(const std::string& str, const source_location src, const std::uint8_t base)
{
return toml::read_int<integer_type>(str, src, base);
}
static result<floating_type, error_info>
parse_float(const std::string& str, const source_location src, const bool is_hex)
{
return toml::read_float<floating_type>(str, src, is_hex);
}
};
```
## Using `boost::multiprecision` for Numeric Types
By using `boost::multiprecision::cpp_int` and `boost::multiprecision::cpp_bin_float_oct`, you can utilize a wider integer type and a more precise floating-point type.
These types implement stream operators, so you can use the default implementations of `read_int` and `read_float` without modification.
```cpp
struct large_num_config
{
using comment_type = toml::preserve_comments;
using boolean_type = bool;
using integer_type = boost::multiprecision::cpp_int;
using floating_type = boost::multiprecision::cpp_bin_float_oct;
using string_type = std::string;
template<typename T>
using array_type = std::vector<T>;
template<typename K, typename T>
using table_type = std::unordered_map<K, T>;
static toml::result<integer_type, toml::error_info>
parse_int(const std::string& str, const toml::source_location src, const std::uint8_t base)
{
return toml::read_int<integer_type>(str, src, base);
}
static toml::result<floating_type, toml::error_info>
parse_float(const std::string& str, const toml::source_location src, const bool is_hex)
{
return toml::read_float<floating_type>(str, src, is_hex);
}
};
```

212
docs/content.en/docs/features/error_message.md Normal file
View File

@@ -0,0 +1,212 @@
+++
title = "error message"
type = "docs"
weight = 30
+++
# Outputting Error Messages
`toml11` provides error messages that include location information within the file when using functions like `toml::parse`, `toml::get<T>/find<T>`, and `as_integer()`, among others.
For instance, if a syntax error in an integer is detected during parsing, an error message might look like this:
```
[error] bad integer: `_` must be surrounded by digits
--> internal string at line 64 in file main.cpp
|
1 | a = 123__456
| ^-- invalid underscore
Hint: valid : -42, 1_000, 1_2_3_4_5, 0xC0FFEE, 0b0010, 0o755
Hint: invalid: _42, 1__000, 0123
```
Or, if a type different from the one actually stored is requested:
```
[error] toml::value::as_string(): bad_cast to string
--> input.toml
|
1 | a = 123_456
| ^^^^^^^-- the actual type is integer
```
`toml11` provides methods to create such error messages from `toml::value`.
By utilizing this feature, you can inform users not only about TOML syntax errors but also about application-specific errors. For example, if a negative number appears where only positive values are allowed, you can highlight the location within the TOML file to convey the error to the user.
## Creating Error Messages from `toml::value` Location Information
`toml::value` retains information about the location where it was parsed.
This information is encapsulated in `toml::source_location` and can be retrieved using `toml::value::location()`.
```cpp
const toml::value& a = input.at("a");
const toml::source_location src = a.location();
```
When a file is parsed with `toml::parse`, the TOML filename and line numbers are stored.
If parsed with `toml::parse_str`, the TOML filename is not available, but instead, the filename and line number of the C++ source code that called `toml::parse_str` are stored as the TOML filename. The first example on this page was output from `toml::parse_str`. Note the filename part.
For details, see the [reference]({{<ref "/docs/reference/source_location">}}).
You can build error information by passing a `toml::source_location` or `toml::value` and the associated error message to `toml::make_error_info`. Passing this to `toml::format_error` formats the error message into a `std::string`.
```cpp
const toml::value& a = input.at("a");
if(a.as_integer() < 0)
{
const toml::error_info err = toml::make_error_info(
"positive integer is required", // Error title
a, "but got negative value" // Message next to the value
);
std::cerr << toml::format_error(err) << std::endl;
}
```
This will output:
```
[error] positive integer is required
--> input.toml
|
1 | a = -123456
| ^^^^^^^-- but got negative value
```
You can also add a supplementary message at the end. This part is not indented.
```cpp
const toml::value& a = input.at("a");
if(a.as_integer() < 0)
{
const toml::error_info err = toml::make_error_info(
"positive integer is required", // Error title
a, "but got negative value", // Message next to the value
"Hint: `a` means length of the data" // Supplementary message
);
std::cerr << toml::format_error(err) << std::endl;
}
```
This will output:
```
[error] positive integer is required
--> input.toml
|
1 | a = -123456
| ^^^^^^^-- but got negative value
Hint: `a` means length of the data
```
{{<hint info>}}
The ability to output lines from the file using `toml::value` is because the parsed file is retained in memory as a string.
The parsed string is shared by `toml::value` via a `std::shared_ptr`. Copying it does not duplicate the entire file string. The file information is freed from memory when all `toml::value` instances constructed from parsing the file are destructed.
Therefore, when using this in an application, it is recommended to extract and store the required values during loading rather than directly storing `toml::value`.
{{</hint>}}
## Adding Colors to Strings
You can add color to error messages using ANSI escape codes.
If `TOML11_COLORIZE_ERROR_MESSAGE` is defined at compile time, the error messages output by toml11 will be colored by default.
If not, you can enable color for subsequent error messages by calling `toml::color::enable()`. Conversely, if you do not want colored output, for example, because the output is not to a console, call `toml::color::disable()`. You can check whether coloring is enabled at any point by calling `toml::color::should_color()`.
Additionally, while the error title, error message, and supplementary information are not colored by default, you can use manipulators from toml::color to add color to them.
```cpp
std::ostringstream oss;
oss << toml::color::red << "but got negative value";
const toml::error_info err = toml::make_error_info(
"positive integer is required", // Error title
a, oss.str(), // Message next to the value
"Hint: `a` means length of the data" // Supplementary message
);
```
For more details, see the [reference]({{<ref "docs/reference/color">}}).
## Changing the Prefix of Error Messages from `[error]`
There may be different types of errors, and the default `[error]` prefix might not always be appropriate.
With `toml::format_error`, you can provide a `std::string` before `toml::error_info` to replace the `[error]` prefix.
For example:
```cpp
const toml::value& a = input.at("a");
if(a.as_integer() < 0)
{
const toml::error_info err = toml::make_error_info(
"positive integer is required", // Error title
a, "but got negative value" // Message next to the value
);
std::ostringstream prefix;
prefix << toml::color::bold << toml::color::yellow << "[warn]";
std::cerr << toml::format_error(prefix.str(), err) << std::endl;
return 0;
}
else
{
return a.as_integer();
}
```
This will output a warning starting with `[warn]`.
Additionally, you can create error messages without the `[error]` prefix by directly passing the components of `error_info` to `toml::format_error`.
```cpp
const toml::value& a = input.at("a");
if(a.as_integer() < 0)
{
std::cerr << toml::format_error(
"[warn] positive integer is required", // Error title
a, "but got negative value" // Message next to the value
) << std::endl;
return 0;
}
else
{
return a.as_integer()
}
```
## Creating Error Messages Referencing Multiple `toml::value`
In application settings, the range of permissible values might change based on previously read values.
In such cases, you may want to output the values causing the error simultaneously.
`toml::format_error` and `toml::make_error_info` can take multiple pairs of `toml::value` and their corresponding error messages as `std::string`.
```cpp
std::cerr << toml::format_error(
"[error] invalid range",
a, "minimum value is defined here",
b, "maximum value is defined here",
c, "and it exceeds the range"
) << std::endl;
```
You can also add supplementary information at the end.
```cpp
std::cerr << toml::format_error(
"[error] invalid range",
a, "minimum value is defined here",
b, "maximum value is defined here",
c, "and it exceeds the range",
"Hint: all the values must be in the range [a, b)"
) << std::endl;
```
When passing `toml::value` or `toml::source_location`, an error message related to it must follow. If not, it will result in a very confusing compilation error.

124
docs/content.en/docs/features/extension.md Normal file
View File

@@ -0,0 +1,124 @@
+++
title = "extension"
type = "docs"
weight = 80
+++
# TOML Language Extensions
The TOML language is currently at version v1.0.0, but several new features have been discussed and merged, with ongoing discussions for v1.1.0.
Among the proposed features, some were deemed to have limited use cases, some faced implementation challenges in their proposed form, and others were not adopted at all.
In toml11, we have experimentally implemented a selection of these features. Please note that these features are supported in toml11 but are not supported by other parsers and are unlikely to be supported in the future.
Additionally, these features are disabled by default. To use them, you must explicitly set the corresponding feature flags to `true`. This design choice ensures that non-standard features are only used intentionally.
Some of these features may eventually be merged into the TOML language itself. If a feature is officially adopted, the corresponding experimental implementation in toml11 may be removed in a minor version update after the official feature is implemented.
## `null`
This feature allows the use of `null` as a value in TOML files.
```
a = null
b = [ 1, 2, 3, null, 5]
```
To enable this, set the `ext_null_value` flag in `toml::spec` to `true`.
When parsed, it will be treated as `toml::value_t::empty`, similar to a default-constructed value. However, the location information within the file will be set.
`null` is parsed only in the context of values. Therefore, if `null` is used as a key, it will be interpreted as the string `"null"`, as it has been in the standard TOML.
```cpp
#include <toml.hpp>
int main()
{
toml::spec spec;
spec.ext_null_value = true;
const auto v = toml::parse_str("a = null", spec);
assert(v.at("a").is_empty());
assert(v.at("a").is(toml::value_t::empty));
return 0;
}
```
## Hexadecimal Format for Floating-Point Numbers
This feature allows the use of hexadecimal format for floating-point numbers in TOML files.
```
a = 0x1.91eb851eb851fp+1 # 3.14
```
To enable this, set the `ext_hex_float` flag in `toml::spec` to `true`.
The format follows the `printf` specification for `%a/%A`.
```cpp
#include <toml.hpp>
int main()
{
toml::spec spec;
spec.ext_hex_float = true;
const auto v = toml::parse_str("a = 0x1.91eb851eb851fp+1", spec);
assert(v.at("a").is_floating());
assert(v.at("a").as_floating() == 3.14);
return 0;
}
```
## Suffixes for Integers and Floating-Point Numbers
This feature allows the use of suffixes for numbers in TOML files. It can be applied to integers and floating-point numbers in decimal notation.
This is particularly useful for displaying units.
```
a = 86_400_sec
b = 3.1416_rad
c = 10_μm
```
However, these are purely suffixes and do not perform any unit conversion. If unit conversion is needed, users should implement it by referencing the suffix.
To enable this, set the `ext_num_suffix` flag in `toml::spec` to `true`.
The suffix must be separated from the number by an underscore (`_`).
For clarity, the suffix cannot start with a digit.
```
distance = 100_m # valid
distance = 10_0m # invalid
distance = 10_0_m # valid
```
The suffix is stored as `std::string suffix` in the format information.
```cpp
#include <toml.hpp>
int main()
{
toml::spec spec;
spec.ext_hex_float = true;
const auto v = toml::parse_str("a = 86_400_sec", spec);
assert(v.at("a").is_integer());
assert(v.at("a").as_integer() == 86400);
assert(v.at("a").as_integer_fmt().suffix == "sec");
return 0;
}
```

92
docs/content.en/docs/features/literal.md Normal file
View File

@@ -0,0 +1,92 @@
+++
title = "toml literal"
type = "docs"
weight = 60
+++
# `_toml` Literal
With the `""_toml` literal, you can format TOML files inline.
```cpp
#include <toml.hpp>
int main()
{
using namespace toml::literals::toml_literals;
const auto v = "a = 42"_toml;
assert(v.at("a").as_integer() == 42);
return 0;
}
```
When including line breaks, raw string literals come in handy.
```cpp
#include <toml.hpp>
int main()
{
using namespace toml::literals::toml_literals;
const auto v = R"(
a = 42
b = "foo"
)"_toml;
assert(v.at("a").as_integer() == 42);
assert(v.at("b").as_string() == "foo");
return 0;
}
```
If a value is written on its own, that value is returned.
```cpp
#include <toml.hpp>
int main()
{
using namespace toml::literals::toml_literals;
const auto a = "42"_toml;
const auto b = "12:34:56"_toml;
assert(a.as_integer() == 42);
assert(b.as_local_time().hour == 12);
assert(b.as_local_time().minute == 34);
assert(b.as_local_time().second == 56);
return 0;
}
```
TOML allows keys consisting solely of numbers. Therefore, `[1]` is a valid table name.
When there's ambiguity between table definitions and arrays, table definitions take precedence.
To interpret as an array, please use a trailing comma.
```cpp
#include <toml.hpp>
int main()
{
using namespace toml::literals::toml_literals;
const auto t = "[1]"_toml; // {1 = {}}
const auto a = "[1,]"_toml; // [1,]
assert(t.is_table());
assert(t.at("1").is_table());
assert(a.is_array());
assert(a.at(0).as_integer() == 1);
return 0;
}
```

240
docs/content.en/docs/features/parsing_files.md Normal file
View File

@@ -0,0 +1,240 @@
+++
title = "parsing files"
type = "docs"
weight = 10
+++
# Parsing Files and Strings
In toml11, you can parse files, strings, and byte arrays using `toml::parse` or `toml::try_parse`.
Upon success, these functions return a `toml::value`.
Although the parsed file is always a table, the return type is not `toml::table`.
This is because `toml::value` contains metadata about the file, whereas `toml::table` is merely an alias for `std::unordered_map<std::string, toml::value>`.
To include metadata, a `toml::value` is returned instead of a `toml::table`.
The `toml::value` corresponding to the root of the file will always hold a `table_type`.
## Parsing Files
To parse files, use either
[`toml::parse`]({{< ref "docs/reference/parser#parse" >}})
or
[`toml::try_parse`]({{< ref "docs/reference/parser#try_parse" >}}).
### `toml::parse`
#### Specifying the Filename with `std::string`
[`toml::parse`]({{< ref "docs/reference/parser#parse" >}})
accepts a filename as a string, opens the file, and parses it.
The following sample code parses a file named `input.toml`, extracts the `title` variable as a string, and prints it.
```cpp
#include <toml.hpp>
#include <iostream>
int main()
{
const toml::value input = toml::parse("input.toml");
std::cout << input.at("title").as_string() << std::endl;
return 0;
}
```
#### Specifying an Input Stream with `std::istream`
[`toml::parse`]({{< ref "docs/reference/parser#parse" >}}) can also accept an `std::istream`.
Without the filename information, error messages will display `"unknown file"`. To avoid this, you can pass the filename as a `std::string` in the second argument when using `std::istream`.
You can use streams other than `std::ifstream`, such as `std::istringstream`. Note that the entire content is readable at the time of the call.
```cpp
#include <toml.hpp>
#include <iostream>
int main()
{
std::string filename("input.toml");
std::ifstream ifs(filename);
const toml::value input = toml::parse(ifs, filename);
std::cout << input.at("title").as_string() << std::endl;
return 0;
}
```
#### Specifying a File with `std::filesystem::path`
[`toml::parse`]({{< ref "docs/reference/parser#parse" >}}) can accept a `std::filesystem::path`.
This requires C++17 or later, as it relies on the `<filesystem>` support.
#### Specifying a File with `FILE*`
[`toml::parse`]({{< ref "docs/reference/parser#parse" >}}) can also accept a `FILE*`.
As with `std::istream`, you need to provide the filename as a string in the second argument.
When passing a `FILE*`, if the file read fails, `errno` will be reported.
#### Error Handling
[`toml::parse`]({{< ref "docs/reference/parser#parse" >}}) throws a [`toml::syntax_error`]({{< ref "docs/reference/parser#syntax_error" >}}) if it encounters a syntax error.
[`toml::syntax_error`]({{< ref "docs/reference/parser#syntax_error" >}}) is derived from [`toml::exception`]({{< ref "docs/reference/exception" >}}), which in turn is derived from `std::exception`.
Therefore, you can use the `what()` member function to retrieve the error message from a [`toml::syntax_error`]({{< ref "docs/reference/parser#syntax_error" >}}).
Additionally, [`toml::syntax_error`]({{< ref "docs/reference/parser#syntax_error" >}}) contains a [`std::vector<toml::error_info>`]({{< ref "docs/reference/error_info" >}}), which can be accessed using the `errors()` member function.
`toml::parse` attempts to recover from minor errors and report multiple errors whenever possible. While it can often recover from simple errors like number format issues, errors within arrays or tables might not be recoverable and may lead to multiple similar error reports. If you find the error messages redundant, you can use only the `front()` of the `std::vector<toml::error_info>` to get a message about the most critical issue.
```cpp
#include <toml.hpp>
int main()
{
try {
const toml::value input = toml::parse("input.toml");
std::cout << input.at("title").as_string() << std::endl;
} catch(const toml::syntax_error& err) {
// report all the errors
std::cerr << err.what() << std::endl;
// report the first error only
std::cerr << err.errors().front() << std::endl;
}
}
```
### `toml::try_parse`
While `toml::parse` throws an exception on failure, `toml::try_parse` does not throw exceptions when it fails.
Instead, its return type is [`toml::result<toml::value, std::vector<toml::error_info>>`]({{<ref "docs/reference/result#result">}}).
The [`result`]({{<ref "docs/reference/result#result">}}) type holds either a success value or a failure value, similar to Rust's `Result` or Haskell's `Either`.
```cpp
#include <toml.hpp>
int main()
{
const auto parse_result = toml::try_parse("input.toml");
if(parse_result.is_ok())
{
std::cout << parse_result.unwrap().at("title").as_string() << std::endl;
}
else
{
std::cerr << parse_result.unwrap_err().at(0) << std::endl;
}
return 0;
}
```
To check which value the [`result`]({{<ref "docs/reference/result#result">}}) type holds, use the `is_ok()` and `is_err()` functions. The success or failure value can be retrieved using `unwrap()` and `unwrap_err()`, respectively. If `unwrap` fails, it throws a `bad_result_access` exception. Using the `as_ok()` and `as_err()` functions does not throw exceptions on failure, but results in undefined behavior.
{{<hint warning>}}
Although `try_parse` does not throw `syntax_error` or `file_io_error`, it returns the same `toml::error_info` as the failure type in the `result`. However, it is not entirely exception-free.
If an internal standard library error occurs, such as `std::bad_alloc` when a `vector` fails to allocate memory, `toml::try_parse` does not catch this and will let it propagate. Thus, exceptions originating from the standard library may still be thrown.
{{</hint>}}
## Parsing Strings
### `toml::parse_str`
[`toml::parse_str`]({{<ref "docs/reference/parser#parse_str">}}) accepts the string to be parsed directly, instead of a filename.
For the part of the error message that corresponds to the TOML file's name, if the `std::source_location` equivalent compiler extension is available, the name and line number of the C++ file that called `parse_str` will be used instead.
```cpp
#include <toml.hpp>
#include <iostream>
int main()
{
const toml::value input = toml::parse_str("title = \"parse_str\"");
std::cout << input.at("title").as_string() << std::endl;
return 0;
}
```
### `toml::try_parse_str`
[`toml::try_parse_str`]({{<ref "docs/reference/parser#try_parse_str">}}) also takes the string to be parsed directly, similar to `parse_str`. Like `try_parse`, it uses [`toml::result`]({{<ref "docs/reference/result#result">}}) to report errors.
```cpp
#include <toml.hpp>
#include <iostream>
int main()
{
const auto parse_result = toml::try_parse_str("title = \"parse_str\"");
if(parse_result.is_ok())
{
std::cout << parse_result.unwrap().at("title").as_string() << std::endl;
}
else
{
std::cerr << parse_result.unwrap_err().at(0) << std::endl;
}
return 0;
}
```
## Parsing Byte Arrays
It is also possible to parse byte arrays instead of files.
Since the byte arrays must be encoded in UTF-8, `unsigned char` is used.
### `toml::parse(std::vector<unsigned char>)`
The behavior is the same as [`toml::parse`]({{<ref "docs/reference/parser#parse">}}).
When parsing byte arrays, a `filename` is required.
```cpp
#include <toml.hpp>
#include <iostream>
int main()
{
std::vector<unsigned char> bytes{/* ... */};
const toml::value input = toml::parse(bytes, "internal bytes");
std::cout << input.at("title").as_string() << std::endl;
return 0;
}
```
### `toml::try_parse(std::vector<unsigned char>)`
The behavior is the same as [`toml::try_parse`]({{<ref "docs/reference/parser#try_parse">}}).
When parsing byte arrays, a `filename` is required.
```cpp
#include <toml.hpp>
#include <iostream>
int main()
{
std::vector<unsigned char> bytes{/* ... */};
const auto parse_result = toml::try_parse(bytes, "internal bytes");
if(parse_result.is_ok())
{
std::cout << parse_result.unwrap().at("title").as_string() << std::endl;
}
else
{
std::cerr << parse_result.unwrap_err().at(0) << std::endl;
}
return 0;
}
```

198
docs/content.en/docs/features/serialize.md Normal file
View File

@@ -0,0 +1,198 @@
+++
title = "serializing values"
type = "docs"
weight = 40
+++
# Outputting TOML Files
Using `toml::format`, you can convert a `toml::value` to a string.
```cpp
#include <toml.hpp>
#include <cassert>
int main()
{
const toml::value v(toml::table{
{"a", 42},
{"b", "foo"},
});
const std::string s = toml::format(v);
const toml::value u = toml::parse_str(s);
assert(u.at("a").as_integer() == 42);
assert(u.at("b").as_string() == "foo");
return 0;
}
```
If the `toml::value` contains a `table_type`, it is interpreted as the root table of the file.
If a `toml::value` containing anything other than `table_type` is passed, only that value is formatted.
Certain format specifications may require a key to be provided for formatting. For example, `toml::array_format::array_of_tables` formats as `[[array.of.tables]]`, which requires key access.
If a format specification that requires a key is provided without a key, a `toml::serialization_error` is thrown.
Additionally, if there are values that contradict the format specification, a `toml::serialization_error` is thrown. For instance, specifying `integer_format::hex` for a negative integer, or `string_format::literal` for a string containing newlines, will cause an error.
The method for specifying formats is explained later.
## Outputting with Keys
You can pass a key to `toml::format` as a `std::string`.
In this case, the key is considered to be under the root table, and the passed value corresponds to that key.
For nested keys, you can pass a `std::vector<std::string>`.
```cpp
#include <toml.hpp>
#include <cassert>
int main()
{
const toml::value v(toml::table{
{"a", 42},
{"b", "foo"},
});
const std::string s = toml::format("bar", v);
const toml::value u = toml::parse_str(s);
assert(u.at("bar").at("a").as_integer() == 42);
assert(u.at("bar").at("b").as_string() == "foo");
return 0;
}
```
## Specifying Formats
Each type in `toml::value` has a corresponding format information type.
For `toml::value::integer_type`, there is `toml::integer_format_info`.
For `toml::value::table_type`, there is `toml::table_format_info`.
These format information types are set when parsing and are retained even if the value is changed, as long as the type remains the same.
You can access and directly edit these formats using member functions like `as_integer_fmt()` or `as_table_fmt()`.
Below are some examples explaining how to use these formats.
For more details on how to access formats, refer to the [`toml::value` reference]({{< ref "/docs/reference/value" >}}). For a complete list and detailed information on format information classes, see the [format reference]({{< ref "/docs/reference/format" >}}).
### Specifying Integer Formats
For integers, you can specify the radix, width, and the position of `_`.
When using `hex`, `oct`, or `bin`, values are padded with zeros until the specified width is reached. For `dec`, the width specification adds spaces, which are not parsed.
For more details, see the [integer format reference]({{< ref "/docs/reference/format#integer_format" >}}).
### Single-Line and Multi-Line Arrays
For arrays, you can specify `toml::array_format::oneline` or `toml::array_format::multiline`.
```toml
# oneline
a = [1, 2, 3, 4, 5]
# multiline
a = [
1,
2,
3,
4,
5
]
```
When using `multiline`, you can specify the indentation. Each element is indented by the amount specified in `body_indent`, and the closing bracket `]` is indented by the amount specified in `closing_indent`.
The type of character used for indentation is specified by `indent_type`, and you can choose between `toml::indent_char::space` or `toml::indent_char::tab`.
{{<hint warning>}}
Ensure that the same type of character is used for indentation throughout the document.
If different types of characters are specified for indentation within the same file, the result is undefined. Some form of indentation will be applied, but the type of character and the depth of the indentation may be inconsistent.
{{</hint>}}
If all elements of an `array` have `table_type`, you can specify `toml::array_format::array_of_tables`.
If you do not specify `array_of_tables` and use `multiline`, the tables will be formatted as inline tables.
```toml
# multiline
a = [
{foo = 42},
{bar = "hoge"},
]
# array_of_tables
[[a]]
foo = 42
[[a]]
bar = "hoge"
```
By default, `toml::array_format::default_format` is used. This automatically selects an appropriate format.
For example, with `default_format`, if all elements are `table_type`, it will choose `array_of_tables`. Short arrays are formatted as `oneline`, while long or nested arrays, or those with complex elements, are formatted as `multiline`.
For more details, see the [array format reference]({{< ref "/docs/reference/format#array_format" >}}).
### Inline Tables
To format a table as an inline table, specify `toml::table_format::oneline`.
For standard tables, use `toml::table_format::multiline`.
```toml
oneline = {a = 42, b = "foo"}
[multiline]
a = 42
b = "foo"
```
In TOML v1.1.0, line breaks within inline tables are allowed. In this case, use `toml::table_format::multiline_oneline`. This is only applied if the corresponding feature flag is set to `true` as per the TOML version specification described later.
```toml
multiline_oneline = {
a = 42,
b = "foo"
}
```
For more details, see the [table format reference]({{< ref "/docs/reference/format#table_format" >}}).
## Specifying the TOML Language Version for Output
Certain language features, such as line breaks within inline tables and `\x` escape sequences, are only available after TOML v1.1.0.
The `toml::format` function accepts a `toml::spec` as its argument.
This allows you to specify the version of TOML to use during serialization.
When you use `toml::parse` with a `toml::spec` to leverage new features,
the parsed values may contain format information that is only compatible with that specific version.
Ensure that you pass the same `toml::spec` to `toml::format` to maintain compatibility.
```cpp
#include <toml.hpp>
#include <iostream>
int main()
{
const auto spec = toml::spec::v(1, 1, 0);
const toml::value v = toml::parse("input.toml", spec);
std::cout << toml::format(v, spec) << std::endl;
return 0;
}
```

107
docs/content.en/docs/features/toml_spec.md Normal file
View File

@@ -0,0 +1,107 @@
+++
title = "toml spec"
type = "docs"
weight = 70
+++
# TOML Language Version
You can specify the version of the TOML language and individual feature flags to use with `toml::parse` or `toml::format` through [`toml::spec`](docs/reference/spec#tomlspec).
## Specifying TOML Version
You can construct a [`toml::spec`](docs/reference/spec#tomlspec) from [`toml::semantic_version`](docs/reference/spec#tomlsemantic_version).
```cpp
#include <toml.hpp>
int main()
{
toml::spec spec(toml::semantic_version(1, 1, 0));
return 0;
}
```
However, to make this shorter, the `toml::spec::v()` function is provided.
```cpp
#include <toml.hpp>
int main()
{
toml::spec spec = toml::spec::v(1, 1, 0);
return 0;
}
```
If not specified explicitly, `toml::spec::default_version()` is used to construct with default values.
The default value depends on the version of toml11 and follows the latest version of the TOML language released at that time.
As of v4.0.0, TOML v1.1.0 has not been released yet, so the default TOML version is v1.0.0.
{{<hint warning>}}
Some features of TOML v1.1.0 are still under fairly lengthy discussion and may still be reverted.
If they are indeed reverted, toml11 will remove those features in a minor version upgrade or move them to a corresponding later version.
As such, any features related to future versions should be considered unstable.
{{</hint>}}
### Parsing with Version Specification
The overload of [`toml::parse`](docs/reference/parser) takes a `toml::spec` following the file name.
This allows you to change the TOML version being used.
```cpp
#include <toml.hpp>
int main()
{
toml::value input = toml::parse("input.toml", toml::spec::v(1, 1, 0));
return 0;
}
```
### Serializing with Version Specification
The overload of [`toml::format`](docs/reference/serializer) takes a `toml::spec` following the `toml::value`.
This allows you to change the TOML version being used.
```cpp
#include <toml.hpp>
int main()
{
toml::value v = toml::parse("input.toml", toml::spec::v(1, 1, 0));
std::cout << toml::format(v, toml::spec::v(1, 1, 0)) << std::endl;
return 0;
}
```
If a format is passed that is not permitted by the provided `toml::spec`, it will be ignored, and another format will be used as a fallback.
## Specifying Newly Added Features in TOML
With version upgrades in TOML, multiple new features are introduced, and it's possible to enable only some of them.
```cpp
#include <toml.hpp>
int main()
{
toml::spec spec = toml::spec::v(1, 0, 0);
// Allowing newlines in inline tables
spec.v1_1_0_allow_newlines_in_inline_tables = true;
toml::value input = toml::parse("input.toml", spec);
return 0;
}
```
For a full list of all flags, refer to [`toml::spec`](docs/reference/spec#tomlspec).

799
docs/content.en/docs/features/value.md Normal file
View File

@@ -0,0 +1,799 @@
+++
title = "getting values"
type = "docs"
weight = 20
+++
# Retrieving Values
This section explains how to access the values stored in `toml::value`.
## Accessing Values Using Member Functions
### `is_something` and `as_something`
`toml::value` has member functions like `is_boolean()` and `is_integer()` which allow you to check the type of the stored value.
Additionally, it has member functions like `as_boolean()` and `as_integer()` that allow you to access the value of that type.
For a complete list, refer to the [`toml::value` reference]({{<ref "docs/reference/value#is_xxx">}}).
```cpp
toml::value v = /* ... */;
if(v.is_string())
{
std::cout << v.as_string() << std::endl;
}
```
If the stored value is of a different type than specified, a [`toml::type_error`]({{<ref "docs/reference/value#tomltype_error">}}) is thrown.
The `what()` method will contain a message like the following:
```
[error] toml::value::as_string(): bad_cast to string
--> input.toml
|
1 | a = 123_456
| ^^^^^^^-- the actual type is integer
```
### `toml::value_t`
Type information can be identified using [`enum class toml::value_t`]({{<ref "docs/reference/value_t">}}).
The [`type()`]({{<ref "docs/reference/value#type">}}) member function returns the type information of the currently stored value.
```cpp
toml::value v = /* ... */;
switch(v.type())
{
case toml:value_t::empty : { /*...*/ break; }
case toml:value_t::boolean : { /*...*/ break; }
case toml:value_t::integer : { /*...*/ break; }
case toml:value_t::floating : { /*...*/ break; }
case toml:value_t::string : { /*...*/ break; }
case toml:value_t::offset_datetime: { /*...*/ break; }
case toml:value_t::local_datetime : { /*...*/ break; }
case toml:value_t::local_date : { /*...*/ break; }
case toml:value_t::local_time : { /*...*/ break; }
case toml:value_t::array : { /*...*/ break; }
case toml:value_t::table : { /*...*/ break; }
default: {break;}
}
```
The [`is(toml::value_t)`]({{<ref "docs/reference/value#istomlvalue_t">}}) member function returns `true` if the stored value is of the given `value_t` type, otherwise it returns `false`.
```cpp
toml::value v = /* ... */;
if(v.is(toml::value_t::integer))
{
std::cout << v.as_integer() << std::endl;
}
```
### `at`, `[]`, `contains`, `size`, `push_back`, `emplace_back`
`toml::value` provides some member functions similar to those of standard library containers.
These functions internally convert `toml::value` to the corresponding type and call the respective member functions.
#### `at(std::size_t i)`, `operator[](std::size_t i)`
These are equivalent to `as_array().at(i)` and `as_array()[i]`.
`toml::value` uses `std::vector<toml::value>` as `array_type` by default, so `at` throws `std::out_of_range` on error, while `operator[]` results in undefined behavior.
```cpp
toml::value v(toml::array{1,2,3});
std::cout << v.at(1);
```
If the stored type is not `array_type`, a `type_error` is thrown.
#### `at(std::string key)`, `operator[](std::string key)`
These are equivalent to `as_table().at(key)` and `as_table()[key]`.
`toml::value` uses `std::unordered_map<std::string, toml::value>` as `table_type` by default, so if the corresponding value does not exist, `at` throws `std::out_of_range`, while `operator[]` constructs a new `toml::value` and returns a reference to it. Therefore, there is no `const` version of `operator[]`.
```cpp
toml::value v(toml::table{});
v["a"] = 42;
```
If the stored type is not `table_type`, a `type_error` is thrown.
#### `size()`
Returns the length.
For `array_type` or `table_type`, it returns the number of elements; for `string_type`, it returns the number of characters (in bytes).
If the stored type is none of these, a `type_error` is thrown.
#### `push_back()`, `emplace_back()`
These are equivalent to `as_array().push_back()` and `as_array().emplace_back()`.
If the stored type is not `array_type`, a `type_error` is thrown.
## Accessing Comments
In toml11, comments are parsed by default and saved line by line with the corresponding value.
A comment corresponds to the value that comes immediately after the consecutive lines of comments, or to the value on the same line as the comment.
If there is no value immediately before or after the comment, it is not associated with any value and is ignored.
```toml
# input.toml
# This is a comment about a.
a = 42
b = 3.14 # This is a comment about b.
# This comment is ignored because it has no corresponding value.
# This is the 1st comment about c.
# This is the 2nd comment about c.
c = "foo" # This is the final comment about c.
# This comment is NOT a comment about c.
```
Comments corresponding to a value can be accessed using the `comments()` member function of `toml::value`.
`comments()` returns a container that has the same member functions as `std::vector<std::string>`.
```cpp
const auto v = toml::parse("input.toml");
const auto& a = v.at("a");
const auto& b = v.at("b");
const auto& c = v.at("c");
assert(a.comments().size() == 1);
assert(a.comments().at(0) == "# This is a comment about a.");
assert(b.comments().size() == 1);
assert(b.comments().at(0) == "# This is a comment about b.");
assert(c.comments().size() == 3);
assert(c.comments().at(0) == "# This is the 1st comment about c.");
assert(c.comments().at(1) == "# This is the 2nd comment about c.");
assert(c.comments().at(2) == "# This is the final comment about c.");
```
Comments related to the root table of the entire file are written at the beginning of the file.
```toml
# This is a comment about the root table.
# This is also a comment about the root table.
# This comment is ignored.
# This is a comment about a.
a = 42
```
However, if a value immediately follows the initial comment, the comment is interpreted as pertaining to that value, and there are no comments for the root table.
```toml
# This is a comment about a.
# This is also a comment about a.
a = 42
```
## Handling Inline Tables and Dotted Keys
An inline table is simply a table, and there is no difference in handling it compared to other tables in C++ code.
```toml
a = {b = 42, c = "foo"}
```
Dotted keys are also just tables, with no difference in handling compared to other tables in C++ code.
```toml
a.b = 42
a.c = "foo"
```
These TOML files are identical to the following file.
```toml
[a]
b = 42
c = "foo"
```
Thus, they can all be processed with the exact same code.
```cpp
const auto input = toml::parse("input.toml");
assert(input.at("a").at("b").as_integer() == 42);
assert(input.at("a").at("c").as_string() == "foo");
```
However, it is possible to distinguish them based on format information.
```cpp
const auto input = toml::parse("input.toml");
switch(input.at("a").as_table_fmt().fmt)
{
case toml::table_format::oneline:
{
std::cout << "inline table" << std::endl;
break;
}
case toml::table_format::multiline:
{
std::cout << "normal table" << std::endl;
break;
}
case toml::table_format::dotted:
{
std::cout << "dotted keys" << std::endl;
break;
}
}
```
This format information is also considered during serialization, which will be described later.
## Handling Date and Time Information
[`local_date`]({{<ref "docs/reference/datetime#local_date">}}),
[`local_time`]({{<ref "docs/reference/datetime#local_time">}}),
[`local_datetime`]({{<ref "docs/reference/datetime#local_datetime">}}), and
[`offset_datetime`]({{<ref "docs/reference/datetime#offset_datetime">}})
are parsed into dedicated structures with corresponding member variables in toml11.
When using these, you can directly extract the values or use `toml::get` and `toml::find` to convert them into types such as `std::chrono::system_clock::time_point` or `std::tm`.
## Converting Using `toml::get<T>`
`toml::get<T>` is a function that converts and retrieves the value stored in `toml::value`.
Specify the desired target type as `T`.
```cpp
const toml::value v = /*...*/;
std::cout << toml::get<int>(v) << std::endl;
```
The `toml::find<T>` function, described later, also has the same functionality for type conversion.
If an unsupported type is specified for the stored value, a `toml::type_error` is thrown.
### Simple Conversions
#### boolean_type
Conversion from `boolean_type` is possible only to `bool`.
#### integer_type
Any type for which `std::is_integral<T>` is `true`, except `bool`, can be converted from `integer_type`.
```cpp
toml::value v(42);
const auto u32 = toml::get<std::uint32_t>(v);
const auto i16 = toml::get<short>(v);
```
#### floating_type
Any type for which `std::is_floating_point<T>` is `true` can be converted from `floating_type`.
```cpp
toml::value v(3.14);
const auto f64 = toml::get<double>(v);
const auto f32 = toml::get<float >(v);
```
#### string_type
`string_type` can be converted to `std::string`.
From C++17 onwards, it can also be converted to `std::string_view`.
```cpp
toml::value v("foo");
const auto s = toml::get<std::string>(v);
// C++17
const auto sv = toml::get<std::string_view>(v);
```
#### datetime variants
[`local_date`]({{<ref "docs/reference/datetime#local_date">}}),
[`local_datetime`]({{<ref "docs/reference/datetime#local_datetime">}}), and
[`offset_datetime`]({{<ref "docs/reference/datetime#offset_datetime">}}) represent specific dates and times,
so they can be converted to `std::chrono::system_clock::time_point`.
However, since [`local_time`]({{<ref "docs/reference/datetime#local_time">}}) does not include date information, it supports conversion to `std::chrono::duration` as the elapsed time from `00:00.00`.
Additionally, `local_date` and `local_datetime` conversions take the executing machine's timezone into account.
```toml
date = 2024-01-23
time = 12:30:00
l_dt = 2024-01-23T12:30:00
o_dt = 2024-01-23T12:30:00+09:00
```
```cpp
const auto input = toml::parse("input.toml");
const auto date = toml::get<std::chrono::system_clock::time_point>(input.at("date"));
const auto l_dt = toml::get<std::chrono::system_clock::time_point>(input.at("l_dt"));
const auto o_dt = toml::get<std::chrono::system_clock::time_point>(input.at("o_dt"));
const auto time = toml::get<std::chrono::minutes>(input.at("time")); // 12 * 60 + 30 min
```
### Conditions for Obtaining References
`toml::get<T>` can return a reference if `T` is the exact type stored in `toml::value`.
Conversely, if a conversion is necessary (e.g., extracting an integer stored as `std::int64_t` into `std::uint32_t`), it is not possible to return a reference to the converted type.
When no conversion is needed, the returned reference can be used to modify the value.
```cpp
toml::value v(42);
toml::get<toml::value::integer_type>(v) = 6 * 9;
assert(v.as_integer() == 54);
```
### Converting Arrays to STL Containers
If all elements in an array have the same type and can be converted to `T`, it is possible to convert them to `std::vector<T>`.
```toml
a = [1, 2, 3, 4, 5]
```
```cpp
const auto a = toml::get<std::vector<int>>(input.at("a"));
```
Other STL containers can also be used.
```cpp
const auto a1 = toml::get<std::deque<int>>(input.at("a"));
const auto a2 = toml::get<std::list <int>>(input.at("a"));
const auto a3 = toml::get<std::array<int, 5>>(input.at("a"));
```
When converting to `std::array`, the number of elements must match. If they don't match, a `std::out_of_range` exception is thrown.
Non-STL containers that have a default constructor and a `push_back` method can also be converted using `toml::get`.
```cpp
const auto a = toml::get<boost::container::small_vector<int, 8>>(input.at("a"));
```
### Converting Arrays to `std::pair` or `std::tuple`
If an array contains elements of different types, it can be converted to `std::pair` or `std::tuple`.
```toml
a = [true, 3.14]
b = [42, 2.718, "foo"]
```
```cpp
const auto a = toml::get<std::pair<bool, double>>(input.at("a"));
const auto b = toml::get<std::tuple<int, double, std::string>>(input.at("b"));
```
As with `std::array`, the length of the array must match the number of elements in the `std::pair` or `std::tuple`. If they don't match, a `std::out_of_range` exception is thrown.
Additionally, each element must be convertible to the corresponding element in the `std::pair` or `std::tuple`. If conversion is not possible, a `toml::type_error` exception is thrown.
### Converting Nested Arrays
Nested arrays can be converted to nested containers.
```toml
a = [ [1, 2, 3], [4, 5, 6] ]
```
```cpp
const auto a = toml::get<std::vector<std::vector<int>>>(input.at("a"));
```
If the types are different, `std::pair` or `std::tuple` can be useful.
```toml
a = [ [1, 2, 3], ["foo", "bar"] ]
```
```cpp
const auto a = toml::get<
std::pair<std::vector<int>, std::vector<std::string>>
>(input.at("a"));
```
### Converting Tables to `std::map`
If all values in a table have the same type, they can be converted to `std::map` or `std::unordered_map`.
```toml
t = {a = 1, b = 2}
```
```cpp
const auto t = toml::get<std::map<std::string, int>>(input.at("t"));
```
Non-STL containers that have a default constructor and an `emplace(key, mapped)` method can also be converted using `toml::get`.
```cpp
const auto t = toml::get<boost::container::flat_map<std::string, int>>(input.at("t"));
```
If the conversion of any element fails, a `toml::type_error` exception is thrown.
## Using `toml::get_or` to Specify a Value on Failure
`toml::get` throws a `toml::type_error` exception if the conversion fails.
By using `toml::get_or`, you can specify a default value to return instead of an exception in case of a conversion failure.
Unlike `toml::get<T>`, `get_or` infers the target type from the arguments, so there is no need to specify `<T>`.
```cpp
const auto a = toml::get_or(input.at("a"), 42);
```
The types that can be converted are the same as for `toml::get`.
If you specify `toml::value::xxx_type`, you can also retrieve a reference, but in that case, the argument must also be a reference.
```cpp
toml::value::integer_type a_default = 42;
auto a& = toml::get_or(input.at("a"), a_default);
```
## Using `toml::find<T>` to Search and Convert Simultaneously
`toml::find<T>` is a function that searches for a value in a `toml::value` holding a table and simultaneously performs the same type conversion as `toml::get`.
```cpp
const auto a = toml::find<int>(input, "a");
// Equivalent to: const auto a = toml::get<int>(input.at("a"));
```
`toml::find<T>` can also be used with arrays.
```cpp
const auto a = input.at("a");
const auto a2 = toml::find<int>(a, 2);
// Equivalent to: const auto a2 = toml::get<int>(input.at("a").at(2));
```
If an error occurs during type conversion, `toml::find<T>` throws the same `toml::type_error` as `toml::get`.
If the key is not found or the index does not exist, it throws `std::out_of_range`.
If no type is specified, `toml::find` returns a `toml::value` without type conversion.
```cpp
const auto a = toml::find(input, "a");
// Equivalent to: const auto a = input.at("a");
```
`toml::find<T>` can access values recursively.
```toml
a = {b = {c = 42}}
```
```cpp
const auto a_b_c = toml::find<int>(input, "a", "b", "c");
// Equivalent to: const auto a = toml::get<int>(input.at("a").at("b").at("c"));
```
You can mix keys and indexes.
```toml
a = [ {b = 1}, {b = 2}, {b = 3} ]
```
```cpp
const auto a_2_b = toml::find<int>(input, "a", 2, "b");
// Equivalent to: const auto a = toml::get<int>(input.at("a").at(2).at("c"));
```
{{<hint info>}}
TOML supports a feature called quoted keys, which allows using normally disallowed characters in keys by enclosing them in `""` or `''`. Within quoted keys, `.` does **not** introduce tables.
```toml
"127.0.0.1" = "value"
site."google.com" = true
```
You can read this TOML file as follows:
```cpp
const auto input = toml::parse("input.toml");
assert(input.at("127.0.0.1").as_string() == "value");
assert(input.at("site").at("google.com").as_boolean());
```
To handle such cases seamlessly, toml11 does not automatically split keys containing `.`. Explicitly specifying the table hierarchy helps in structuring the input file correctly.
Reference: [toml.io/Key](https://toml.io/en/v1.0.0#key)
{{</hint>}}
## Using `toml::find_or` to Search and Specify a Value on Failure
`toml::find_or` works similarly to `toml::find<T>`, but allows specifying a default value to return if the search or conversion fails.
This is useful when you want to provide a fallback value instead of handling exceptions.
```cpp
const auto a = toml::find_or(input, "a", 42);
```
## Defining Conversions for User-Defined Types
With `toml::get` and `toml::find`, you can use user-defined types by employing one of the following methods.
### Defining `toml::from`
In toml11, there is a `toml::from` type that supports conversions from user-defined types by specializing it as follows:
```cpp
namespace extlib
{
struct foo
{
int a;
std::string b;
};
} // extlib
namespace toml
{
template<>
struct from<extlib::foo>
{
static extlib::foo from_toml(const toml::value& v)
{
return extlib::foo{
toml::find<int>(v, "a"),
toml::find<std::string>(v, "b")
};
}
};
} // toml
```
If you also want to support `toml::value` with a modified type configuration, do as follows:
```cpp
namespace extlib
{
struct foo
{
int a;
std::string b;
};
} // extlib
namespace toml
{
template<>
struct from<extlib::foo>
{
template<typename <TC>
static extlib::foo from_toml(const toml::basic_value<TC>& v)
{
return extlib::foo{
toml::find<int>(v, "a"),
toml::find<std::string>(v, "b")
};
}
};
} // toml
```
This definition can be automatically generated using `TOML11_DEFINE_CONVERSION_NON_INTRUSIVE`.
```cpp
namespace extlib
{
struct foo
{
int a;
std::string b;
};
} // extlib
TOML11_DEFINE_CONVERSION_NON_INTRUSIVE(extlib::foo, a, b)
```
Alternatively, you can use a reflection library. Refer to the sample in `example` using `boost-ext/reflect`.
### Defining a `from_toml` Member Function
You can also define a conversion by defining a `from_toml` member function.
When using this method, a default constructor is required.
```cpp
struct bar
{
int a;
std::string b;
void from_toml(const toml::value& v)
{
this->a = toml::find<int>(v, "a");
this->b = toml::find<std::string>(v, "b");
return ;
}
};
```
If both are defined, `toml::from` takes precedence.
### Constructor Accepting `toml::value`
If there is a constructor that accepts `toml::value`, conversion via `toml::get` can be performed.
```cpp
struct baz
{
explicit baz(const toml::value& v)
: a(toml::find<int>(v, "a")), b(toml::find<std::string>(v, "b"))
{}
int a;
std::string b;
};
```
If both are defined, `toml::from` and `from_toml` take precedence.
## Applying Functions with `toml::visit`
If you have a function object that can be applied to all types stored in `toml::value`, you can directly call that function without type conversion using `toml::visit`.
```cpp
struct type_name_of
{
std::string operator()(const toml::value::boolean_type &) const {return "boolean";}
std::string operator()(const toml::value::integer_type &) const {return "integer";}
std::string operator()(const toml::value::floating_type &) const {return "floating";}
std::string operator()(const toml::value::string_type &) const {return "string";}
std::string operator()(const toml::value::local_time_type &) const {return "local_time";}
std::string operator()(const toml::value::local_date_type &) const {return "local_date";}
std::string operator()(const toml::value::local_datetime_type &) const {return "local_datetime";}
std::string operator()(const toml::value::offset_datetime_type&) const {return "offset_datetime";}
std::string operator()(const toml::value::array_type &) const {return "array";}
std::string operator()(const toml::value::table_type &) const {return "table";}
};
toml::value v(3.14);
std::cout << toml::visit(type_name_of{}, v) << std::endl; // floating
```
## Constructing `toml::value`
`toml::value` can be constructed not only internally by the parser but also in user code.
You can construct it by passing a type that is either the same as or convertible to the types stored in `toml::value`.
```cpp
toml::value v1(true);
toml::value v2(42);
toml::value v3(3.14);
```
For arrays, you can use `toml::array`:
```cpp
toml::value v(toml::array{1, 2, 3});
```
Alternatively, you can pass containers such as `std::vector` directly:
```cpp
const std::vector<toml::value> a{1,2,3};
toml::value v(a);
```
For tables, you can use `toml::table`:
```cpp
toml::value v(toml::table{{"foo", 1}, {"bar", 2}, {"baz", 3}});
```
Or pass containers such as `std::map` directly:
```cpp
const std::map<std::string, toml::value> t{
{"foo", 1}, {"bar", 2}, {"baz", 3}
}
toml::value v(t);
```
You can pass `format_info` and comments to the constructor.
The type of comments is `std::vector<std::string>`.
Each element corresponds to a line.
```cpp
toml::integer_format_info fmt;
fmt.fmt = toml::integer_format::hex;
fmt.spacer = 4;
toml::value v1(0xDEADBEEF, fmt);
toml::value v2(0xC0FFEE, fmt, {"hex value!"});
```
## Converting to `toml::value`
When constructing `toml::value` from user-defined types, you can customize the behavior by defining `toml::into` or `into_toml`.
`toml::into` is particularly useful when converting types from other libraries.
### Defining `toml::into`
By specializing `toml::into`, you can enable conversions to `toml::value`.
This is useful for types from external libraries that do not provide a conversion to `toml::value`.
Since `toml::value` passes `type_config` during conversion, you need to accept the `template` argument of `basic_value`.
```cpp
namespace extlib
{
struct foo
{
int a;
std::string b;
};
} // extlib
template<>
struct into<extlib::foo>
{
template<typename TC>
static toml::basic_value<TC> into_toml(const extlib::foo& f)
{
return toml::basic_value<TC>(typename toml::basic_value<TC>::table_type{{"a", f.a}, {"b", f.b}});
}
};
```
### Defining `into_toml` Member Function
Similar to `from_toml`, you can define the conversion through a member function.
If `toml::into` is defined, it takes precedence.
```cpp
struct bar
{
int a;
std::string b;
template<typename TC>
toml::basic_value<TC> into_toml() const
{
return toml::basic_value<TC>(typename toml::basic_value<TC>::table_type{
{"a", this->a}, {"b", this->b}
});
}
};
```

102
docs/content.en/docs/installation/_index.md Normal file
View File

@@ -0,0 +1,102 @@
+++
title = "installation"
type = "docs"
weight = 1
+++
# Installation
## Using `single_include`
The `ingle_include/toml.hpp`s is a single-file, header-only library that consolidates all the functionalities of toml11 into one file.
The simplest way to use it is to copy this file to a location included in your `INCLUDE_PATH` and then add `#include <toml.hpp>` to your source code.
The MIT license notice is included in both the comments and the `toml::license_notice()` function.
If you are redistributing the software without releasing the source code, you must either copy the toml11 license file and include it with your distribution, or ensure that the `toml::license_notice()` function can be called.
## Cloning toml11 and using cmake
If you place toml11 within your repository, for example by using git submodule, and you are using cmake, you can make use of it by adding `add_subdirectory(toml11)` to your `CMakeLists.txt`.
```cmake
add_subdirectory(toml11)
add_executable(main main.cpp)
target_link_libraries(main PUBLIC toml11::toml11)
```
toml11 will only run tests and install when it is the root project.
## Installing using cmake
After cloning toml11, you can install it using cmake.
```console
$ cmake -B ./build/ -DTOML11_BUILD_TESTS=ON
$ cmake --install ./build/ --prefix=/opt/toml11
```
If you want to run the test programs before installation, make sure to set `-DTOML11_BUILD_TESTS=ON` first.
Once the installation is complete, you can use it as follows:
```cmake
find_package(toml11)
add_executable(main main.cpp)
target_link_libraries(main PRIVATE toml11::toml11)
```
## Compiling with cmake to Create a Static Library
By defining `-DTOML11_PRECOMPILE=ON` when running cmake, you can precompile some of the functions in toml11, thereby reducing the overall compile time.
```console
$ cmake -B ./build/ -DTOML11_PRECOMPILE=ON
```
However, since toml11 supports multiple C++ versions and may switch types based on the value of `__cplusplus`,
there is a possibility of link failures if the version used during build differs from the version used during usage.
If you encounter issues, set the required version using `CMAKE_CXX_STANDARD` during compilation.
If this is difficult, use it as a header-only library as usual.
The `find_package(toml11)` command defines `TOML11_INCLUDE_DIR`.
Even if you install it as a precompiled library, you can still use it as a header-only library by adding `TOML11_INCLUDE_DIR` to `target_include_directories` and avoiding the use of `target_link_libraries`.
```cmake
find_package(toml11)
add_executable(main main.cpp)
# Include only, do not link
target_include_directories(main PRIVATE ${TOML11_INCLUDE_DIR})
```
## Compiling Examples
You can compile the `examples/` directory by setting `-DTOML11_BUILD_EXAMPLES=ON`.
```console
$ cmake -B ./build/ -DTOML11_BUILD_EXAMPLES=ON
$ cmake --build ./build/
```
The executable binaries for the examples will be generated in the `examples/` directory.
## Running Tests
To build the tests, set `-DTOML11_BUILD_TESTS=ON`.
```console
$ git submodule update --init --recursive
$ cmake -B ./build/ -DTOML11_BUILD_TESTS=ON
$ cmake --build ./build/
$ ctest --test-dir ./build/
```
To run the `toml-lang/toml-tests`, set `-DTOML11_BUILD_TOML_TESTS=ON`. This will build `toml11_decoder` and `toml11_encoder` in the `tests/` directory.
```console
$ git submodule update --init --recursive
$ cmake -B ./build/ -DTOML11_BUILD_TOML_TESTS=ON
$ cmake --build ./build/
$ ctest --test-dir ./build/
```

122
docs/content.en/docs/reference/_index.md Normal file
View File

@@ -0,0 +1,122 @@
+++
title = "reference"
type = "docs"
weight = 3
bookCollapseSection = true
+++
# Reference
Here, we explain the effects of the classes and functions provided by toml11.
## Directory Structure
`toml.hpp` and `toml_fwd.hpp` reside in `${TOML11_INCLUDE_DIR}`.
Other files are located in `${TOML11_INCLUDE_DIR}/toml11`.
If you want to `#include` each feature's file individually, use `#include <toml11/color.hpp>`.
If you want to include all at once, use `#include <toml.hpp>`.
## [color.hpp](color)
Defines functions related to colorizing error messages.
## [comments.hpp](comments)
Defines types `preserve_comment` and `discard_comment` for preserving comments.
## [conversion.hpp](conversion)
Defines macros to automatically convert `toml::value` and user-defined classes.
## [datetime.hpp](datetime)
Defines classes for datetime information.
## [error_info.hpp](error_info)
Defines a class for error information.
## [exception.hpp](exception)
Defines the base class for exceptions used in toml11, `toml::exception`.
## [find.hpp](find)
Defines the `toml::find` function to search for and convert values.
## [format.hpp](format)
Defines classes for formatting information of values.
## [from.hpp](from)
Forward declaration of the `from<T>` type for converting user-defined types.
## [get.hpp](get)
Defines the `toml::get<T>` function to retrieve and convert values from `toml::value`.
## [into.hpp](into)
Forward declaration of the `into<T>` type for converting user-defined types.
## [literal.hpp](literal)
Defines the `operator"" _toml` literal.
## [ordered_map.hpp](ordered_map)
Defines `toml::ordered_map`.
## [parser.hpp](parser)
Defines functions to parse files or strings.
## [result.hpp](result)
Defines the `result<T, E>` type for representing success or failure values used as return types in other functions.
## [serializer.hpp](serializer)
Defines the `toml::format` function and `toml::serializer` used for serialization.
## [source_location.hpp](source_location)
Defines the `source_location` type used for error information, pointing to a location within a file.
## [spec.hpp](spec)
Defines the `toml::semantic_version` and `toml::spec` types to control TOML language version information and feature flags.
## [toml.hpp](toml)
`toml.hpp` includes all other headers, making all toml11 features available.
## [toml_fwd.hpp](toml_fwd)
`toml_fwd.hpp` contains forward declarations of structs defined in toml11 and macro definitions.
## [types.hpp](types)
Defines the `toml::type_config` type for controlling the types held by `toml::value`.
## [value.hpp](value)
Defines the `toml::value` type.
## [value_t.hpp](value_t)
Defines the `toml::value_t` enumeration.
## [version.hpp](version)
Defines the version information for toml11.
## [visit.hpp](visit)
Defines the `toml::visit` function to apply functions to the values held by `toml::value`.
## Notes
Functions not explicitly mentioned here (mostly those defined under `namespace toml::detail` or `namespace toml::cxx`) are available by inspecting the source code but are not guaranteed to maintain their interface across future versions (including patch version updates).

138
docs/content.en/docs/reference/color.md Normal file
View File

@@ -0,0 +1,138 @@
+++
title = "color.hpp"
type = "docs"
+++
# color.hpp
In `color.hpp`, functions related to colorizing error messages are defined.
Colors are specified using ANSI escape code.
In terminals or other output destinations that do not support ANSI escape code, the output may become difficult to read.
## Macros
```cpp
TOML11_COLORIZE_ERROR_MESSAGE
```
If this macro is defined during compilation (`-DTOML11_COLORIZE_ERROR_MESASGE`), error messages are colored by default.
If not defined, colors are not applied by default. You need to specify them using `toml::color::enable()`.
## Functions
### `enable()`
```cpp
namespace toml {
namespace color {
void enable();
} // color
} // toml
```
Enables colorization using ANSI escape code.
#### Example
```cpp
#include <toml.hpp>
int main()
{
toml::color::enable(); // All subsequent errors will be colored.
const auto input = toml::parse("input.toml");
return 0;
}
```
### `disable()`
```cpp
namespace toml {
namespace color {
void disable();
} // color
} // toml
```
Disables colorization using ANSI escape code.
#### Example
```cpp
#include <toml.hpp>
int main()
{
toml::color::disable(); // All subsequent errors will not be colored.
const auto input = toml::parse("input.toml");
return 0;
}
```
### `should_color()`
```cpp
namespace toml {
namespace color {
bool should_color();
} // color
} // toml
```
Returns `true` if colorization is enabled, `false` otherwise.
#### Example
```cpp
#include <toml.hpp>
#include <iomanip>
#include <iostream>
int main()
{
std::cout << "colorized? : " << std::boolalpha << toml::color::should_color() << std::endl;
return 0;
}
```
## Manipulators
```cpp
namespace toml {
namespace color {
std::ostream& reset (std::ostream&);
std::ostream& bold (std::ostream&);
std::ostream& grey (std::ostream&);
std::ostream& gray (std::ostream&);
std::ostream& red (std::ostream&);
std::ostream& green (std::ostream&);
std::ostream& yellow (std::ostream&);
std::ostream& blue (std::ostream&);
std::ostream& magenta(std::ostream&);
std::ostream& cyan (std::ostream&);
std::ostream& white (std::ostream&);
} // color
} // toml
```
Colorizes the foreground with ANSI escape code.
#### Example
```cpp
#include <toml.hpp>
#include <iostream>
int main()
{
std::cout << toml::color::red << "red!" << toml::color::reset << std::endl;
return 0;
}
```
# Related
- [error_info.hpp]({{<ref "error_info.md">}})

776
docs/content.en/docs/reference/comments.md Normal file
View File

@@ -0,0 +1,776 @@
+++
title = "comments.hpp"
type = "docs"
+++
# comments.hpp
In `comments.hpp`, comment containers are provided.
# `toml::preserve_comments`
`preserve_comments` is a container that preserves comments.
It has all the member functions of `std::vector<std::string>`.
Comments are preserved as `std::string`.
If the comment does not start with `#`, it will be prefixed with `#` during output.
However, this prefixing is not done when adding comments to the container.
Spaces are not automatically added, so if you want a space immediately after `#`,
either start the comment with a space or pass the comment with `#`.
```cpp
namespace toml
{
class preserve_comments;
bool operator==(const preserve_comments&, const preserve_comments&);
bool operator!=(const preserve_comments&, const preserve_comments&);
bool operator< (const preserve_comments&, const preserve_comments&);
bool operator<=(const preserve_comments&, const preserve_comments&);
bool operator> (const preserve_comments&, const preserve_comments&);
bool operator>=(const preserve_comments&, const preserve_comments&);
void swap(preserve_comments&, preserve_comments&);
void swap(preserve_comments&, std::vector<std::string>&);
void swap(std::vector<std::string>&, preserve_comments&);
std::ostream& operator<<(std::ostream&, const preserve_comments&);
} //toml
```
## Member types
```cpp
using container_type = std::vector<std::string>;
using size_type = container_type::size_type;
using difference_type = container_type::difference_type;
using value_type = container_type::value_type;
using reference = container_type::reference;
using const_reference = container_type::const_reference;
using pointer = container_type::pointer;
using const_pointer = container_type::const_pointer;
using iterator = container_type::iterator;
using const_iterator = container_type::const_iterator;
using reverse_iterator = container_type::reverse_iterator;
using const_reverse_iterator = container_type::const_reverse_iterator;
```
## Member Functions
### Default Constructor
```cpp
preserve_comments() = default;
```
Constructs an empty `preserve_comments`.
### Copy and Move Constructors
```cpp
preserve_comments(preserve_comments const&) = default;
preserve_comments(preserve_comments &&) = default;
```
Constructs a `preserve_comments` by copying or moving.
### Constructor (`std::vector<std::string>`)
```cpp
explicit preserve_comments(const std::vector<std::string>& c);
explicit preserve_comments(std::vector<std::string>&& c);
```
Constructs a `preserve_comments` holding the contents of `std::vector<std::string>`.
### Constructor (`discard_comments`)
```cpp
explicit preserve_comments(const discard_comments&);
```
Constructs an empty `preserve_comments`.
### Constructor (`Iterator`)
```cpp
template<typename InputIterator>
preserve_comments(InputIterator first, InputIterator last);
```
Constructs a `preserve_comments` from the range represented by `InputIterator` pointing to `std::string`.
### Constructor (`std::initializer_list`)
```cpp
preserve_comments(std::initializer_list<std::string> x);
```
Constructs a `preserve_comments` from the range represented by `std::initializer_list<std::string>`.
### Constructor (Size Specified)
```cpp
explicit preserve_comments(size_type n);
preserve_comments(size_type n, const std::string& x);
```
Constructs a `preserve_comments` with `n` comments.
If a `std::string` is passed, it replicates that comment `n` times.
### Destructor
```cpp
~preserve_comments() = default;
```
Destroys the `preserve_comments`.
### `operator=(preserve_comments)`
```cpp
preserve_comments& operator=(preserve_comments const&) = default;
preserve_comments& operator=(preserve_comments &&) = default;
```
Assigns a `preserve_comments` by copying or moving.
### `operator=(std::vector<std::string>)`
```cpp
preserve_comments& operator=(const std::vector<std::string>& c);
preserve_comments& operator=(std::vector<std::string>&& c);
```
Assigns a `std::vector<std::string>` by copying or moving.
### `assign`
```cpp
template<typename InputIterator>
void assign(InputIterator first, InputIterator last);
void assign(std::initializer_list<std::string> ini);
void assign(size_type n, const std::string& val);
```
The same as `std::vector<std::string>::assign`.
### `insert`
```cpp
iterator insert(const_iterator p, const std::string& x);
iterator insert(const_iterator p, std::string&& x);
iterator insert(const_iterator p, size_type n, const std::string& x);
template<typename InputIterator>
iterator insert(const_iterator p, InputIterator first, InputIterator last);
iterator insert(const_iterator p, std::initializer_list<std::string> ini);
```
The same as `std::vector<std::string>::insert`.
### `emplace`
```cpp
template<typename ... Ts>
iterator emplace(const_iterator p, Ts&& ... args);
```
The same as `std::vector<std::string>::emplace`.
### `erase`
```cpp
iterator erase(const_iterator pos);
iterator erase(const_iterator first, const_iterator last);
```
The same as `std::vector<std::string>::erase`.
### `swap`
```cpp
void swap(preserve_comments& other);
```
Swaps the comments.
### `push_back`
```cpp
void push_back(const std::string& v);
void push_back(std::string&& v);
```
The same as `std::vector<std::string>::push_back`.
### `pop_back`
```cpp
void pop_back();
```
The same as `std::vector<std::string>::pop_back`.
### `emplace_back`
```cpp
template<typename ... Ts>
void emplace_back(Ts&& ... args);
```
The same as `std::vector<std::string>::emplace_back`.
### `clear`
```cpp
void clear();
```
The same as `std::vector<std::string>::clear`.
### `size`
```cpp
size_type size() const noexcept;
```
The same as `std::vector<std::string>::size`.
### `max_size`
```cpp
size_type max_size() const noexcept;
```
The same as `std::vector<std::string>::max_size`.
### `capacity`
```cpp
size_type capacity() const noexcept;
```
The same as `std::vector<std::string>::capacity`.
### `empty`
```cpp
bool empty() const noexcept;
```
The same as `std::vector<std::string>::empty`.
### `reserve`
```cpp
void reserve(size_type n);
```
The same as `std::vector<std::string>::reserve`.
### `resize`
```cpp
void resize(size_type n);
void resize(size_type n, const std::string& c);
```
The same as `std::vector<std::string>::resize`.
### `shrink_to_fit`
```cpp
void shrink_to_fit();
```
The same as `std::vector<std::string>::shrink_to_fit`.
### `operator[]`
```cpp
reference operator[](const size_type n) noexcept;
const_reference operator[](const size_type n) const noexcept;
```
The same as `std::vector<std::string>::operator[]`.
### `at`
```cpp
reference at(const size_type n) ;
const_reference at(const size_type n) const;
```
The same as `std::vector<std::string>::at`.
### `front`
```cpp
reference front() noexcept;
const_reference front() const noexcept;
```
The same as `std::vector<std::string>::front`.
### `back`
```cpp
reference back() noexcept;
const_reference back() const noexcept;
```
The same as `std::vector<std::string>::back`.
### `data`
```cpp
pointer data() noexcept;
const_pointer data() const noexcept;
```
The same as `std::vector<std::string>::data`.
### `begin/end`
```cpp
iterator begin() noexcept;
iterator end() noexcept;
const_iterator begin() const noexcept;
const_iterator end() const noexcept;
const_iterator cbegin() const noexcept;
const_iterator cend() const noexcept;
```
The same as `std::vector<std::string>::begin/end`.
### `rbegin/rend`
```cpp
reverse_iterator rbegin() noexcept;
reverse_iterator rend() noexcept;
const_reverse_iterator rbegin() const noexcept;
const_reverse_iterator rend() const noexcept;
const_reverse_iterator crbegin() const noexcept;
const_reverse_iterator crend() const noexcept;
```
The same as `std::vector<std::string>::rbegin/rend`
## non-member functions
### Comparison operator
```cpp
bool operator==(const preserve_comments&, const preserve_comments&);
bool operator!=(const preserve_comments&, const preserve_comments&);
bool operator< (const preserve_comments&, const preserve_comments&);
bool operator<=(const preserve_comments&, const preserve_comments&);
bool operator> (const preserve_comments&, const preserve_comments&);
bool operator>=(const preserve_comments&, const preserve_comments&);
```
It compares two `preserve_comments` in the same way as `std::vector<std::string>`.
### `swap`
```cpp
void swap(preserve_comments&, preserve_comments&);
void swap(preserve_comments&, std::vector<std::string>&);
void swap(std::vector<std::string>&, preserve_comments&);
```
### Stream operator
```cpp
std::ostream& operator<<(std::ostream&, const preserve_comments&);
```
Outputs as TOML comments.
If the first character is not `#`, it adds `#`.
# `toml::discard_comments`
`discard_comments` serves as a container for discarding comments.
It encompasses all the member functions of `std::vector<std::string>`, but invoking functions that modify the content has no effect, leaving it perpetually empty.
```cpp
namespace toml
{
class discard_comments;
bool operator==(const discard_comments&, const discard_comments&);
bool operator!=(const discard_comments&, const discard_comments&);
bool operator< (const discard_comments&, const discard_comments&);
bool operator<=(const discard_comments&, const discard_comments&);
bool operator> (const discard_comments&, const discard_comments&);
bool operator>=(const discard_comments&, const discard_comments&);
void swap(discard_comments&, discard_comments&);
std::ostream& operator<<(std::ostream&, const discard_comments&);
} //toml
```
## Member types
```cpp
// container_type is not defined
using size_type = std::size_t;
using difference_type = std::ptrdiff_t;
using value_type = std::string;
using reference = std::string&;
using const_reference = std::string const&;
using pointer = std::string*;
using const_pointer = std::string const*;
using iterator = /* internal type: empty-iterator */
using const_iterator = /* internal type: empty-iterator */
using reverse_iterator = /* internal type: empty-iterator */
using const_reverse_iterator = /* internal type: empty-iterator */
```
### Default Constructor
```cpp
discard_comments() = default;
```
Constructs an empty `discard_comments`.
### Copy / Move Constructor
```cpp
discard_comments(discard_comments const&) = default;
discard_comments(discard_comments &&) = default;
```
Constructs a `discard_comments` by copying or moving.
### Constructor(`std::vector<std::string>`)
```cpp
explicit discard_comments(const std::vector<std::string>& c);
explicit discard_comments(std::vector<std::string>&& c);
```
Constructs an empty `discard_comments`. Arguments are ignored.
### Constructor(`preserve_comments`)
```cpp
explicit discard_comments(const preserve_comments&);
```
Constructs an empty `discard_comments`. Arguments are ignored.
### Constructor(`Iterator`)
```cpp
template<typename InputIterator>
discard_comments(InputIterator first, InputIterator last);
```
Constructs an empty `discard_comments`. Arguments are ignored.
### Constructor(`std::initializer_list`)
```cpp
discard_comments(std::initializer_list<std::string> x);
```
Constructs an empty `discard_comments`. Arguments are ignored.
### Constructor(サイズ指定)
```cpp
explicit discard_comments(size_type n);
discard_comments(size_type n, const std::string& x);
```
Constructs an empty `discard_comments`. Arguments are ignored.
### Destructor
```cpp
~discard_comments() = default;
```
Destroys `discard_comments`.
### `operator=(discard_comments)`
```cpp
discard_comments& operator=(discard_comments const&) = default;
discard_comments& operator=(discard_comments &&) = default;
```
Assigns `discard_comments` by copying or moving.
### `operator=(std::vector<std::string>)`
```cpp
discard_comments& operator=(const std::vector<std::string>& c);
discard_comments& operator=(std::vector<std::string>&& c);
```
Does nothing.
### `assign`
```cpp
template<typename InputIterator>
void assign(InputIterator first, InputIterator last);
void assign(std::initializer_list<std::string> ini);
void assign(size_type n, const std::string& val);
```
Does nothing.
### `insert`
```cpp
iterator insert(const_iterator p, const std::string& x);
iterator insert(const_iterator p, std::string&& x);
iterator insert(const_iterator p, size_type n, const std::string& x);
template<typename InputIterator>
iterator insert(const_iterator p, InputIterator first, InputIterator last);
iterator insert(const_iterator p, std::initializer_list<std::string> ini);
```
Does nothing.
### `emplace`
```cpp
template<typename ... Ts>
iterator emplace(const_iterator p, Ts&& ... args);
```
Does nothing.
### `erase`
```cpp
iterator erase(const_iterator pos);
iterator erase(const_iterator first, const_iterator last);
```
Does nothing.
### `swap`
```cpp
void swap(discard_comments& other);
```
Swaps two `discard_comments`. Effectively it does nothing.
### `push_back`
```cpp
void push_back(const std::string& v);
void push_back(std::string&& v);
```
Does nothing.
### `pop_back`
```cpp
void pop_back();
```
Does nothing.
### `emplace_back`
```cpp
template<typename ... Ts>
void emplace_back(Ts&& ... args);
```
Does nothing.
### `clear`
```cpp
void clear();
```
Does nothing.
### `size`
```cpp
size_type size() const noexcept;
```
Returns `0`.
### `max_size`
```cpp
size_type max_size() const noexcept;
```
Returns `0`.
### `capacity`
```cpp
size_type capacity() const noexcept;
```
Returns `0`.
### `empty`
```cpp
bool empty() const noexcept;
```
Returns `true`.
### `reserve`
```cpp
void reserve(size_type n);
```
Does nothing.
### `resize`
```cpp
void resize(size_type n);
void resize(size_type n, const std::string& c);
```
Does nothing.
### `shrink_to_fit`
```cpp
void shrink_to_fit();
```
Does nothing.
### `operator[]`
```cpp
reference operator[](const size_type n) noexcept;
const_reference operator[](const size_type n) const noexcept;
```
Causes undefined behavior.
### `at`
```cpp
reference at(const size_type n) ;
const_reference at(const size_type n) const;
```
Throws `std::out_of_range`.
### `front`
```cpp
reference front() noexcept;
const_reference front() const noexcept;
```
Causes undefined behavior.
### `back`
```cpp
reference back() noexcept;
const_reference back() const noexcept;
```
Causes undefined behavior.
### `data`
```cpp
pointer data() noexcept;
const_pointer data() const noexcept;
```
Returns `nullptr`.
### `begin/end`
```cpp
iterator begin() noexcept;
iterator end() noexcept;
const_iterator begin() const noexcept;
const_iterator end() const noexcept;
const_iterator cbegin() const noexcept;
const_iterator cend() const noexcept;
```
Returns an internally defined `empty-iterator`.
The `empty-iterator` remains at the same value after incrementing or decrementing and all values are equivalent.
Accessing the target of the `empty-iterator` always calls `std::terminate`.
### `rbegin/rend`
```cpp
reverse_iterator rbegin() noexcept;
reverse_iterator rend() noexcept;
const_reverse_iterator rbegin() const noexcept;
const_reverse_iterator rend() const noexcept;
const_reverse_iterator crbegin() const noexcept;
const_reverse_iterator crend() const noexcept;
```
Returns an internally defined `empty-iterator`.
The `empty-iterator` remains at the same value after incrementing or decrementing and all values are equivalent.
Accessing the target of the `empty-iterator` always calls `std::terminate`.
## non-member functions
### Comparison operator
```cpp
bool operator==(const discard_comments&, const discard_comments&);
bool operator!=(const discard_comments&, const discard_comments&);
bool operator< (const discard_comments&, const discard_comments&);
bool operator<=(const discard_comments&, const discard_comments&);
bool operator> (const discard_comments&, const discard_comments&);
bool operator>=(const discard_comments&, const discard_comments&);
```
All the instances of `discard_comments` are the same value. `operator==` returns `true`, `operator=!` returns `false`.
### `swap`
```cpp
void swap(discard_comments&, discard_comments&);
```
Swaps `discard_comments`. Effectively it does nothing.
### Stream operator
```cpp
std::ostream& operator<<(std::ostream&, const discard_comments&);
```
Outputs nothing.
# Related
- [value.hpp]({{<ref "value.md">}})

33
docs/content.en/docs/reference/conversion.md Normal file
View File

@@ -0,0 +1,33 @@
+++
title = "conversion.hpp"
type = "docs"
+++
# conversion.hpp
Provides macros to automatically define conversion functions for supporting user-defined types with `toml::get` and `toml::find`.
```cpp
TOML11_DEFINE_CONVERSION_NON_INTRUSIVE(NAME, ...)
```
## Example
```cpp
namespace foo
{
struct Foo
{
std::string s;
double d;
int i;
};
} // foo
TOML11_DEFINE_CONVERSION_NON_INTRUSIVE(foo::Foo, s, d, i)
```
# Related
- [from.hpp]({{<ref "from.md">}})
- [into.hpp]({{<ref "into.md">}})

779
docs/content.en/docs/reference/datetime.md Normal file
View File

@@ -0,0 +1,779 @@
+++
title = "datetime.hpp"
type = "docs"
+++
# datetime.hpp
Defines a class that stores date and time information used in TOML's `datetime`.
# `enum class month_t`
Enum class to specify months.
Due to its relationship with `std::tm`, `local_date` treats January as `0`.
To avoid confusion, `month_t` allows specification of months by their names.
```cpp
namespace toml
{
enum class month_t : std::uint8_t
{
Jan = 0,
Feb = 1,
Mar = 2,
Apr = 3,
May = 4,
Jun = 5,
Jul = 6,
Aug = 7,
Sep = 8,
Oct = 9,
Nov = 10,
Dec = 11
};
}
```
# `local_date`
`local_date` holds a date.
`year` represents the year in AD. For `month`, January is represented as `0` to align with `std::tm`. `day` holds the day of the month.
```cpp
namespace toml
{
struct local_date
{
std::int16_t year;
std::uint8_t month;
std::uint8_t day;
local_date() = default;
~local_date() = default;
local_date(local_date const&) = default;
local_date(local_date&&) = default;
local_date& operator=(local_date const&) = default;
local_date& operator=(local_date&&) = default;
local_date(int y, month_t m, int d);
explicit local_date(const std::tm& t);
explicit local_date(const std::chrono::system_clock::time_point& tp);
explicit local_date(const std::time_t t);
operator std::chrono::system_clock::time_point() const;
operator std::time_t() const;
};
bool operator==(const local_date&, const local_date&);
bool operator!=(const local_date&, const local_date&);
bool operator< (const local_date&, const local_date&);
bool operator<=(const local_date&, const local_date&);
bool operator> (const local_date&, const local_date&);
bool operator>=(const local_date&, const local_date&);
std::ostream& operator<<(std::ostream& os, const local_date& date);
std::string to_string(const local_date& date);
}
```
## Member Variables
### `year`
```cpp
std::int16_t year;
```
Represents the year in AD. There's no offset. `2024` is simply `2024`.
### `month`
```cpp
std::uint8_t month;
```
Represents the month. To align with `std::tm`, January is `0`, February is `1`, and so on.
To avoid confusion, use `month_t` during construction.
### `day`
```cpp
std::uint8_t day;
```
Represents the day of the month. The first day is `1`.
## Member Functions
### Constructor
```cpp
local_date() = default;
```
Uses the default implementation.
### Destructor
```cpp
~local_date() = default;
```
Uses the default implementation.
### Copy and Move Constructors
```cpp
local_date(local_date const&) = default;
local_date(local_date&&) = default;
```
Uses the default implementations.
### Copy and Move Assignment Operators
```cpp
local_date& operator=(local_date const&) = default;
local_date& operator=(local_date&&) = default;
```
Uses the default implementations.
### Constructor (`int year, month_t month, int day`)
```cpp
local_date(int y, month_t m, int d);
```
Constructs a `local_date` from the specified values.
Does not perform boundary checks.
### Constructor (`std::tm`)
```cpp
local_date(const std::tm&);
```
Constructs a `local_date` from the specified `std::tm` value.
### Constructor (`std::chrono::system_clock::time_point`)
```cpp
local_date(const std::chrono::system_clock::time_point&);
```
Constructs a `local_date` from the specified `std::chrono::system_clock::time_point` value.
Time zone is determined by the environment.
### Constructor (`std::time_t`)
```cpp
local_date(const std::time_t);
```
Constructs a `local_date` from the specified `std::time_t` value.
Time zone is determined by the environment.
### `operator std::chrono::system_clock::time_point`
```cpp
operator std::chrono::system_clock::time_point() const;
```
Converts to `std::chrono::system_clock::time_point`.
Time zone is determined by the environment.
Time is set to 0 hours and 0 minutes.
### `operator std::time_t`
```cpp
operator std::time_t() const;
```
Converts to `std::time_t`.
Time zone is determined by the execution environment.
Time is set to 0 hours and 0 minutes.
## Non-member Functions
### Comparison Operators
```cpp
bool operator==(const local_date&, const local_date&);
bool operator!=(const local_date&, const local_date&);
bool operator< (const local_date&, const local_date&);
bool operator<=(const local_date&, const local_date&);
bool operator> (const local_date&, const local_date&);
bool operator>=(const local_date&, const local_date&);
```
Compares two dates.
### Stream Operators
```cpp
std::ostream& operator<<(std::ostream& os, const local_date& date);
```
Outputs in the default TOML format.
### `to_string`
```cpp
std::string to_string(const local_date& date);
```
Converts to a string in the default TOML format.
# `local_time`
```cpp
namespace toml
{
struct local_time
{
std::uint8_t hour; // [0, 23]
std::uint8_t minute; // [0, 59]
std::uint8_t second; // [0, 60]
std::uint16_t millisecond; // [0, 999]
std::uint16_t microsecond; // [0, 999]
std::uint16_t nanosecond; // [0, 999]
local_time(int h, int m, int s, int ms = 0, int us = 0, int ns = 0);
explicit local_time(const std::tm& t);
template<typename Rep, typename Period>
explicit local_time(const std::chrono::duration<Rep, Period>& t);
operator std::chrono::nanoseconds() const;
local_time() = default;
~local_time() = default;
local_time(local_time const&) = default;
local_time(local_time&&) = default;
local_time& operator=(local_time const&) = default;
local_time& operator=(local_time&&) = default;
};
bool operator==(const local_time& lhs, const local_time& rhs);
bool operator!=(const local_time& lhs, const local_time& rhs);
bool operator< (const local_time& lhs, const local_time& rhs);
bool operator<=(const local_time& lhs, const local_time& rhs);
bool operator> (const local_time& lhs, const local_time& rhs);
bool operator>=(const local_time& lhs, const local_time& rhs);
std::ostream& operator<<(std::ostream& os, const local_time& time);
std::string to_string(const local_time& time);
}
```
## Member Values
### `hour`
```cpp
std::uint8_t hour;
```
Represents the hour. Values range from `0` to `23`.
### `minute`
```cpp
std::uint8_t minute; // [0, 59]
```
Represents the minute. Values range from `0` to `59`.
### `second`
```cpp
std::uint8_t second; // [0, 60]
```
Represents the second. Values range from `0` to `60`.
### `millisecond`
```cpp
std::uint16_t millisecond; // [0, 999]
```
Represents the millisecond. Values range from `0` to `999`.
### `microsecond`
```cpp
std::uint16_t microsecond; // [0, 999]
```
Represents the microsecond. Values range from `0` to `999`.
### `nanosecond`
```cpp
std::uint16_t nanosecond; // [0, 999]
```
Represents the nanosecond. Values range from `0` to `999`.
## Member Functions
### default constructor
```cpp
local_time() = default;
```
Initializes all values to `0`.
### constructor (h, m, s, ms = 0, us = 0, ns = 0)
```cpp
local_time(int h, int m, int s, int ms = 0, int us = 0, int ns = 0);
```
Constructs using the specified time components.
No boundary checks are performed.
### constructor(`std::tm`)
```cpp
explicit local_time(const std::tm& t);
```
Constructs using `tm_hour`, `tm_min`, and `tm_sec` from `std::tm`.
Subseconds are initialized to `0`.
### constructor(`std::chrono::duration`)
```cpp
template<typename Rep, typename Period>
explicit local_time(const std::chrono::duration<Rep, Period>& t);
```
Constructs as the time of day from `0` hours of the day specified by `duration`.
### `operator std::chrono::nanoseconds`
```cpp
operator std::chrono::nanoseconds() const;
```
Converts to `std::chrono::nanoseconds`.
## Non-member Functions
### Comparison Operators
```cpp
bool operator==(const local_time& lhs, const local_time& rhs);
bool operator!=(const local_time& lhs, const local_time& rhs);
bool operator< (const local_time& lhs, const local_time& rhs);
bool operator<=(const local_time& lhs, const local_time& rhs);
bool operator> (const local_time& lhs, const local_time& rhs);
bool operator>=(const local_time& lhs, const local_time& rhs);
```
Compares based on time values.
### Stream Operator
```cpp
std::ostream& operator<<(std::ostream& os, const local_time& time);
```
Outputs in the default TOML format.
### `to_string`
```cpp
std::string to_string(const local_time& time);
```
Converts to a string in the default TOML format.
# `time_offset`
```cpp
namespace toml
{
struct time_offset
{
std::int8_t hour{0}; // [-12, 12]
std::int8_t minute{0}; // [-59, 59]
time_offset(int h, int m);
operator std::chrono::minutes() const;
time_offset() = default;
~time_offset() = default;
time_offset(time_offset const&) = default;
time_offset(time_offset&&) = default;
time_offset& operator=(time_offset const&) = default;
time_offset& operator=(time_offset&&) = default;
};
bool operator==(const time_offset&, const time_offset&);
bool operator!=(const time_offset&, const time_offset&);
bool operator< (const time_offset&, const time_offset&);
bool operator<=(const time_offset&, const time_offset&);
bool operator> (const time_offset&, const time_offset&);
bool operator>=(const time_offset&, const time_offset&);
std::ostream& operator<<(std::ostream& os, const time_offset& offset);
std::string to_string(const time_offset& offset);
}
```
## Member Variables
### `hour`
```cpp
std::int8_t hour{0}; // [-12, 12]
```
Represents the hour offset, ranging from -12 to +12.
### `minute`
```cpp
std::int8_t minute{0}; // [-59, 59]
```
Represents the minute offset, ranging from -59 to +59.
## Member Functions
### Constructor
```cpp
time_offset(int h, int m);
```
Constructs with given hours and minutes.
No boundary checking is performed.
### `operator std::chrono::minutes`
```cpp
operator std::chrono::minutes() const;
```
Converts to `std::chrono::minutes`.
## Non-member Functions
### Comparison Operators
```cpp
bool operator==(const time_offset&, const time_offset&);
bool operator!=(const time_offset&, const time_offset&);
bool operator< (const time_offset&, const time_offset&);
bool operator<=(const time_offset&, const time_offset&);
bool operator> (const time_offset&, const time_offset&);
bool operator>=(const time_offset&, const time_offset&);
```
Compares based on time length.
### Stream Output Operator
```cpp
std::ostream& operator<<(std::ostream& os, const time_offset&);
```
Outputs in the default TOML format.
### `to_string`
```cpp
std::string to_string(const time_offset&);
```
Converts to a string in the default TOML format.
# `local_datetime`
```cpp
namespace toml
{
struct local_datetime
{
local_date date;
local_time time;
local_datetime(local_date d, local_time t);
explicit local_datetime(const std::tm& t);
explicit local_datetime(const std::chrono::system_clock::time_point& tp);
explicit local_datetime(const std::time_t t);
operator std::chrono::system_clock::time_point() const;
operator std::time_t() const;
local_datetime() = default;
~local_datetime() = default;
local_datetime(local_datetime const&) = default;
local_datetime(local_datetime&&) = default;
local_datetime& operator=(local_datetime const&) = default;
local_datetime& operator=(local_datetime&&) = default;
};
bool operator==(const local_datetime&, const local_datetime&);
bool operator!=(const local_datetime&, const local_datetime&);
bool operator< (const local_datetime&, const local_datetime&);
bool operator<=(const local_datetime&, const local_datetime&);
bool operator> (const local_datetime&, const local_datetime&);
bool operator>=(const local_datetime&, const local_datetime&);
std::ostream& operator<<(std::ostream& os, const local_datetime& dt);
std::string to_string(const local_datetime& dt);
}
```
## Member Variables
### `local_date date`
```cpp
local_date date;
```
Stores the date component data.
### `local_time time`
```cpp
local_time time;
```
Stores the time component data.
## Member Functions
### Default Constructor
Constructs both `date` and `time` with default values.
### Constructor (`local_date, local_time`)
Constructs with the specified `date` and `time`.
### Constructor (`std::tm`)
Constructs from `std::tm`.
The timezone is selected based on the execution environment.
### Constructor (`std::chrono::system_clock::time_point`)
Constructs from `std::chrono::system_clock::time_point`.
The timezone is selected based on the execution environment.
### Constructor (`std::time_t`)
Constructs from `std::time_t`.
The timezone is selected based on the execution environment.
### `operator std::chrono::system_clock::time_point`
Converts to `std::chrono::system_clock::time_point`.
### `operator std::time_t`
Converts to `std::time_t`.
## Non-member Functions
### Comparison Operators
```cpp
bool operator==(const local_datetime&, const local_datetime&);
bool operator!=(const local_datetime&, const local_datetime&);
bool operator< (const local_datetime&, const local_datetime&);
bool operator<=(const local_datetime&, const local_datetime&);
bool operator> (const local_datetime&, const local_datetime&);
bool operator>=(const local_datetime&, const local_datetime&);
```
Compares based on chronological order.
### Stream Output Operator
```cpp
std::ostream& operator<<(std::ostream& os, const local_datetime&);
```
Outputs in the default TOML format.
### `to_string`
```cpp
std::string to_string(const local_datetime&);
```
Converts to a string in the default TOML format.
# `offset_datetime`
```cpp
namespace toml
{
struct offset_datetime
{
local_date date;
local_time time;
time_offset offset;
offset_datetime(local_date d, local_time t, time_offset o);
offset_datetime(const local_datetime& dt, time_offset o);
explicit offset_datetime(const local_datetime& ld);
explicit offset_datetime(const std::chrono::system_clock::time_point& tp);
explicit offset_datetime(const std::time_t& t);
explicit offset_datetime(const std::tm& t);
operator std::chrono::system_clock::time_point() const;
operator std::time_t() const;
offset_datetime() = default;
~offset_datetime() = default;
offset_datetime(offset_datetime const&) = default;
offset_datetime(offset_datetime&&) = default;
offset_datetime& operator=(offset_datetime const&) = default;
offset_datetime& operator=(offset_datetime&&) = default;
};
bool operator==(const offset_datetime&, const offset_datetime&);
bool operator!=(const offset_datetime&, const offset_datetime&);
bool operator< (const offset_datetime&, const offset_datetime&);
bool operator<=(const offset_datetime&, const offset_datetime&);
bool operator> (const offset_datetime&, const offset_datetime&);
bool operator>=(const offset_datetime&, const offset_datetime&);
std::ostream& operator<<(std::ostream& os, const offset_datetime& dt);
std::string to_string(const offset_datetime& dt);
}
```
## Member Variables
### `date`
```cpp
local_date date;
```
Stores the date component.
### `time`
```cpp
local_time time;
```
Stores the time component.
### `offset`
```cpp
time_offset offset;
```
Stores the offset component.
## Member Functions
### Default Constructor
Constructs `date`, `time`, and `offset` with default values.
### Constructor (`local_date, local_time, time_offset`)
Constructs with the specified `date`, `time`, and `offset`.
### Constructor (`local_datetime, time_offset`)
Constructs from `local_datetime` and `offset`.
### Constructor (`std::tm`)
Constructs from `std::tm`.
The timezone is UTC (00:00).
### Constructor (`std::chrono::system_clock::time_point`)
Constructs from `std::chrono::system_clock::time_point`.
The timezone is UTC (00:00).
### Constructor (`std::time_t`)
Constructs from `std::time_t`.
The timezone is UTC (00:00).
### `operator std::chrono::system_clock::time_point`
Converts to `std::chrono::system_clock::time_point`.
The timezone is UTC (00:00).
### `operator std::time_t`
Converts to `std::time_t`.
The timezone is UTC (00:00).
## Non-member Functions
### Comparison Operators
```cpp
bool operator==(const offset_datetime&, const offset_datetime&);
bool operator!=(const offset_datetime&, const offset_datetime&);
bool operator< (const offset_datetime&, const offset_datetime&);
bool operator<=(const offset_datetime&, const offset_datetime&);
bool operator> (const offset_datetime&, const offset_datetime&);
bool operator>=(const offset_datetime&, const offset_datetime&);
```
Compares based on chronological order.
If dates are the same, compares based on timezone order.
### Stream Output Operator
```cpp
std::ostream& operator<<(std::ostream& os, const offset_datetime&);
```
Outputs in the default TOML format.
### `to_string`
```cpp
std::string to_string(const offset_datetime&);
```
Converts to a string in the default TOML format.

145
docs/content.en/docs/reference/error_info.md Normal file
View File

@@ -0,0 +1,145 @@
+++
title = "error_info.hpp"
type = "docs"
+++
# error_info.hpp
In `error_info.hpp`, definitions for `error_info` and functions to format it are provided.
# `toml::error_info`
```cpp
namespace toml
{
struct error_info
{
error_info(std::string t, source_location l, std::string m, std::string s = "");
error_info(std::string t, std::vector<std::pair<source_location, std::string>> l, std::string s = "");
std::string const& title() const noexcept;
std::string & title() noexcept;
std::vector<std::pair<source_location, std::string>> const& locations() const noexcept;
void add_locations(source_location loc, std::string msg) noexcept;
std::string const& suffix() const noexcept;
std::string & suffix() noexcept;
};
template<typename ... Ts>
error_info make_error_info(
std::string title, source_location loc, std::string msg, Ts&& ... tail);
std::string format_error(const std::string& errkind, const error_info& err);
std::string format_error(const error_info& err);
template<typename ... Ts>
std::string format_error(std::string title,
source_location loc, std::string msg, Ts&& ... tail);
std::ostream& operator<<(std::ostream& os, const error_info& e);
}
```
## Member Functions
### Constructor (`title, loc, msg, suffix`)
Constructs `error_info` with specified `title`, location information `loc`, message `msg`, and optional `suffix`.
`suffix` defaults to empty.
### Constructor (`title, [{loc, msg}, ...], suffix`)
Constructs `error_info` with specified `title`, an array of location-message pairs `[{loc, msg}, ...]`, and optional `suffix`.
`suffix` defaults to empty.
### `std::string title()`
Returns the title of the error message.
### `std::vector<std::pair<source_location, std::string>> locations()`
Returns the list of locations where errors occurred along with their respective messages.
Multiple locations can be specified.
### `std::string suffix()`
Returns the suffix message to display at the end, providing hints or additional information.
## Non-Member Functions
### `make_error_info`
```cpp
template<typename ... Ts>
error_info make_error_info(
std::string title, source_location loc, std::string msg, Ts&& ... tail);
```
Creates a new `error_info`.
Must be followed by a `msg` related to `source_location` or `basic_value`.
Overloads are added in [`value.hpp`](docs/reference/value#tomlmake_error_info) when passing `toml::basic_value` instead of `source_location`.
Possible to pass `suffix` at the end.
### `format_error`
Formats `error_info` as follows:
```
{title}
--> {locations().at(0).first.file_name()}
|
1 | {locations().at(0).first.line()}
| ^-- {locations().at(0).second}
|
2 | {locations().at(1).first.line()}
| ^-- {locations().at(1).second}
{suffix}
```
If file names differ between two `source_location`, the file name is displayed again.
```cpp
std::string format_error(const std::string& errkind, const error_info& err);
std::string format_error(const error_info& err);
```
Formats `error_info`.
If `errkind` is not provided, a red-bold `[error]` prefix is added before `title`.
If `errkind` is provided (including an empty string), it replaces `[error]`.
```cpp
namespace toml
{
template<typename ... Ts>
std::string format_error(std::string title,
source_location loc, std::string msg, Ts&& ... tail);
} // toml
```
Returns a formatted string using `format_error` for `error_info` created with `make_error_info`.
Overloads are added in [`value.hpp`](docs/reference/value#tomlformat_error) when passing `toml::basic_value` instead of `source_location`.
### Stream Operator
```cpp
std::ostream& operator<<(std::ostream& os, const error_info& e);
```
Calls `format_error(e)` and outputs it.
# Related
- [color.hpp](color.md)
- [parser.hpp](parser.md)
- [source_location.hpp](source_location.md)

40
docs/content.en/docs/reference/exception.md Normal file
View File

@@ -0,0 +1,40 @@
+++
title = "exception.hpp"
type = "docs"
+++
# exception.hpp
# `toml::exception`
Base class for exception types defined in toml11.
```cpp
namespace toml
{
struct exception : public std::exception
{
public:
virtual ~exception() noexcept override = default;
virtual const char* what() const noexcept override {return "";}
};
} // toml
```
## Member Functions
### Destructor
```cpp
virtual ~exception() noexcept override = default;
```
Override when derived.
### `what`
```cpp
virtual const char* what() const noexcept override {return "";}
```
Returns the error message. Override when derived.

244
docs/content.en/docs/reference/find.md Normal file
View File

@@ -0,0 +1,244 @@
+++
title = "find.hpp"
type = "docs"
+++
# find.hpp
This function searches for a value in a `toml::value` and performs type conversion if necessary.
{{< hint info >}}
`toml::value` can change the type it stores, and `toml::find` accommodates these types.
Technically, all functions use `toml::basic_value<TC>`.
However, for simplicity, we refer to it as `toml::value` in explanations unless a distinction is necessary.
In the documentation, if the template parameter `TC` changes the type, assume that types like `toml::value::integer_type` will also change accordingly.
{{< /hint >}}
# `toml::find`
## Overview
`toml::find` uses template arguments for the type you want to retrieve and function arguments for the key of the value you want to find.
```cpp
template<typename T, typename TC, typename ... Keys>
T find(const basic_value<TC>& v, Keys ... keys);
```
The supported types for `T` and the behavior of the conversion are the same as for `toml::get`.
If `T` is not specified, a `toml::value` will be returned.
Keys can be of type `toml::value::key_type` or `std::size_t`.
When multiple keys are provided, the function will search recursively through sub-tables or arrays.
If a `toml::value::key_type` is given, `toml::value` is interpreted as a `toml::table`; if a `std::size_t` is given, `toml::value` is interpreted as a `toml::array`.
### Note on Recursive Search
TOML allows for bare keys as well as quoted keys (enclosed in `"` or `'`). Using a quoted key like `"foo.bar" = "baz"` means no sub-table is constructed, and the key is `"foo.bar"`. To handle such patterns, toml11 does not split keys containing `.` and searches using the full string.
Consider the following TOML file:
```toml
[foo]
[foo.bar]
baz = "hoge"
["foo.bar"]
baz = "fuga"
```
The corresponding usage of `toml::find` is shown below:
```cpp
const auto input = toml::parse("input.toml");
const auto baz1 = toml::find<std::string>(input, "foo", "bar", "baz"); // hoge
const auto baz2 = toml::find<std::string>(input, "foo.bar", "baz"); // fuga
```
cf. [toml.io/en/v1.0.0#keys](https://toml.io/en/v1.0.0#keys)
## `toml::find(value, key)`
Searches for `key` in `value` as if `value` were a `toml::table`, then converts using `toml::get`.
```cpp
template<typename T, typename TC>
/* Equivalent to toml::get<T>(const value&) */ find(
const basic_value<TC>& v, const typename basic_value<TC>::key_type& ky);
template<typename T, typename TC>
/* Equivalent to toml::get<T>(value&) */ find(
basic_value<TC>& v, const typename basic_value<TC>::key_type& ky);
template<typename T, typename TC>
/* Equivalent to toml::get<T>(value&&) */ find(
basic_value<TC>&& v, const typename basic_value<TC>::key_type& ky);
```
If `T` is not specified, the function returns a `toml::value` without conversion.
```cpp
template<typename TC>
basic_value<TC> const& find(
basic_value<TC> const& v, const typename basic_value<TC>::key_type& ky);
template<typename TC>
basic_value<TC>& find(
basic_value<TC>& v, const typename basic_value<TC>::key_type& ky);
template<typename TC>
basic_value<TC> find(
basic_value<TC>&& v, const typename basic_value<TC>::key_type& ky);
```
### Exceptions
If the `toml::value` does not contain a `table`, a `toml::type_error` is thrown.
If the contained `table` does not have the specified element, a `std::out_of_range` is thrown.
If the specified element cannot be converted to `T` (i.e., `toml::get` fails), a `toml::type_error` is thrown.
## `toml::find(value, index)`
Accesses the `index`-th element of `value` as if `value` were a `toml::array`, then converts using `toml::get`.
```cpp
template<typename T, typename TC>
/* Equivalent to toml::get<T>(const value&) */ find(
const basic_value<TC>& v, const std::size_t index);
template<typename T, typename TC>
/* Equivalent to toml::get<T>(value&) */ find(
basic_value<TC>& v, const std::size_t index);
template<typename T, typename TC>
/* Equivalent to toml::get<T>(value&&) */ find(
basic_value<TC>&& v, const std::size_t index);
```
If `T` is not specified, the function returns a `toml::value` without conversion.
```cpp
template<typename TC>
basic_value<TC> const& find(basic_value<TC> const& v, const std::size_t ky);
template<typename TC>
basic_value<TC>& find(basic_value<TC>& v, const std::size_t ky);
template<typename TC>
basic_value<TC> find(basic_value<TC>&& v, const std::size_t ky);
```
### Exceptions
If the `toml::value` does not contain an `array`, a `toml::type_error` is thrown.
If the contained `array` does not have the specified number of elements, a `std::out_of_range` is thrown.
If the specified element cannot be converted to `T` (i.e., `toml::get` fails), a `toml::type_error` is thrown.
## `toml::find(value, keys...)`
```cpp
template<typename T, typename TC, typename K1, typename K2, typename ... Ks>
/* Equivalent to toml::get<T>(const value&) */ find(
const basic_value<TC>& v, const K1& k1, const K2& k2, const Ks& ... ks);
template<typename T, typename TC, typename K1, typename K2, typename ... Ks>
/* Equivalent to toml::get<T>(value&) */ find(
basic_value<TC>& v, const K1& k1, const K2& k2, const Ks& ... ks);
template<typename T, typename TC, typename K1, typename K2, typename ... Ks>
/* Equivalent to toml::get<T>(value&&) */ find(
basic_value<TC>&& v, const K1& k1, const K2& k2, const Ks& ... ks);
```
This function calls `toml::find` recursively.
The failure conditions and the exceptions thrown are the same as those for `toml::find`.
# `toml::find_or(value, key, fallback)`
```cpp
template<typename T, typename TC, typename Key>
T find_or(const basic_value<TC>& v, const Key& key, T&& opt);
```
The `find_or` function takes a default value to avoid throwing an exception when the search fails.
The default value must be of the same type as the return type `T`. Therefore, unlike `toml::find<T>`, `find_or` infers the type `T`.
You can specify `T` explicitly with `find_or<T>`, but this always returns a new value. To obtain a reference, do not specify `T`.
## When `T` is `basic_value`
```cpp
template<typename TC, typename K>
basic_value<TC>& find_or(basic_value<TC>& v, const K& key, basic_value<TC>& opt) noexcept
template<typename TC, typename K>
basic_value<TC> const& find_or(const basic_value<TC>& v, const K& key, const basic_value<TC>& opt) noexcept
```
Searches for the corresponding value and returns it without conversion. Because no conversion is needed, a reference can be returned.
If the value is not found, the default value is returned.
## When `T` is `toml::value::{some_type}`
```cpp
template<typename T, typename TC, typename K>
T& find_or(basic_value<TC>& v, const K& key, T& opt) noexcept
template<typename T, typename TC, typename K>
T const& find_or(const basic_value<TC>& v, const K& key, const T& opt) noexcept
```
Searches for the corresponding value and returns it without conversion. Because no conversion is needed, a reference can be returned.
If the value is not found or if a different type is stored, the default value is returned.
## When `T` is `const char*`
```cpp
template<typename T, typename TC, typename K>
T find_or(const basic_value<TC>& v, const K& key, T opt)
```
Searches for the corresponding value and returns it as a `std::string`.
Since the fallback is constructed from `const char*` to `std::string`, a reference cannot be returned in case of failure.
## When `T` is any other type
```cpp
template<typename T, typename TC, typename K>
T find_or(const basic_value<TC>& v, const K& key, T opt);
```
Searches for the corresponding value and converts it to `T` before returning it.
Because conversion is performed, a reference cannot be returned.
## When multiple keys are provided
```cpp
template<typename Value, typename K1, typename K2, typename K3, typename ... Ks>
auto find_or(Value&& v, const K1& k1, const K2& k2, K3&& k3, Ks&& ... keys) noexcept
-> decltype(find_or(v, k2, std::forward<K3>(k3), std::forward<Ks>(keys)...))
```
Interprets the last element in the key sequence as the default value and applies `find_or` recursively.
If the inferred type of `T` is `toml::value` or `toml::value::some_type`, a reference can be returned.
If `T` is explicitly specified, conversion is always performed.
# Related
- [get.hpp]({{<ref "get.md">}})
- [value.hpp]({{<ref "value.md">}})

446
docs/content.en/docs/reference/format.md Normal file
View File

@@ -0,0 +1,446 @@
+++
title = "format.hpp"
type = "docs"
+++
# format.hpp
Defines structures and enumerations related to formatting information for `toml::value`.
# `indent_char`
An enumeration representing the indentation character choice.
```cpp
enum class indent_char : std::uint8_t
{
space, // use space
tab, // use tab
none // no indent
};
std::ostream& operator<<(std::ostream& os, const indent_char& c);
std::string to_string(const indent_char);
```
Choosing `none` means no indentation is used, regardless of the value in super tables.
If both `space` and `tab` are specified within the serializable value, the behavior is unspecified; typically, the unspecified indentation character appears.
# `boolean_format_info`
Formatting information for `boolean`.
```cpp
struct boolean_format_info {};
bool operator==(const boolean_format_info&, const boolean_format_info&) noexcept;
bool operator!=(const boolean_format_info&, const boolean_format_info&) noexcept;
```
There is only one way to format `boolean`, so no configurable values are provided.
# `integer_format`
```cpp
enum class integer_format : std::uint8_t
{
dec = 0,
bin = 1,
oct = 2,
hex = 3,
};
std::ostream& operator<<(std::ostream& os, const integer_format f);
std::string to_string(const integer_format);
```
Specifies the radix of an `integer`.
# `integer_format_info`
```cpp
struct integer_format_info
{
integer_format fmt = integer_format::dec;
std::size_t width = 0; // minimal width (may exceed)
std::size_t spacer = 0; // position of `_` (if 0, no spacer)
std::string suffix = ""; // _suffix (library extension)
};
bool operator==(const integer_format_info&, const integer_format_info&) noexcept;
bool operator!=(const integer_format_info&, const integer_format_info&) noexcept;
```
## Member Variables
### `integer_format fmt`
Specifies the radix.
### `std::size_t width`
Specifies the minimum width. The formatted value may exceed this width.
For values smaller than this width, if `integer_format::dec`, no effect. Otherwise, leading zeros are added.
### `std::size_t spacer`
Specifies the width at which underscores `_` are inserted.
- If `3`, formatted as `1_234_567`.
- If `4`, formatted as `0xdead_beef`.
- If `0`, no underscores are inserted.
Irregular widths are not allowed.
### `std::string suffix`
Stores the suffix when `spec::ext_num_suffix` of toml11 extension is `true`.
cf. [spec.hpp](spec.md)
# `floating_format`
```cpp
enum class floating_format : std::uint8_t
{
defaultfloat = 0,
fixed = 1, // does not include exponential part
scientific = 2, // always include exponential part
hex = 3 // hexfloat extension
};
std::ostream& operator<<(std::ostream& os, const floating_format f);
std::string to_string(const floating_format);
```
Specifies the formatting style for `floating` numbers.
Corresponds to `std::defaultfloat`, `std::fixed`, `std::scientific`, `std::hexfloat`.
`hexfloat` is available only if `toml::spec::ext_hex_float` is `true`.
cf. [spec.hpp](spec.md)
# `floating_format_info`
```cpp
struct floating_format_info
{
floating_format fmt = floating_format::defaultfloat;
std::size_t prec = 0; // precision (if 0, use the default)
std::string suffix = ""; // 1.0e+2_suffix (library extension)
};
bool operator==(const floating_format_info&, const floating_format_info&) noexcept;
bool operator!=(const floating_format_info&, const floating_format_info&) noexcept;
```
## Member Variables
### `floating_format fmt`
Specifies the formatting style.
### `std::size_t prec`
Specifies the precision after the decimal point.
### `std::string suffix`
Stores the suffix when `spec::ext_num_suffix` of toml11 extension is `true`.
cf. [spec.hpp](spec.md)
# `string_format`
```cpp
enum class string_format : std::uint8_t
{
basic = 0,
literal = 1,
multiline_basic = 2,
multiline_literal = 3
};
std::ostream& operator<<(std::ostream& os, const string_format f);
std::string to_string(const string_format);
```
Specifies the formatting style for strings.
# `string_format_info`
```cpp
struct string_format_info
{
string_format fmt = string_format::basic;
bool start_with_newline = false;
};
bool operator==(const string_format_info&, const string_format_info&) noexcept;
bool operator!=(const string_format_info&, const string_format_info&) noexcept;
```
## Member Variables
### `string_format fmt`
Specifies the formatting information for strings.
### `bool start_with_newline`
For `multiline_basic` or `multiline_literal`, specifies whether to include a newline after the initial `"""` or `'''`.
# `datetime_delimiter_kind`
```cpp
enum class datetime_delimiter_kind : std::uint8_t
{
upper_T = 0,
lower_t = 1,
space = 2,
};
std::ostream& operator<<(std::ostream& os, const datetime_delimiter_kind d);
std::string to_string(const datetime_delimiter_kind);
```
Specifies the delimiter used between date and time in `datetime`.
Possible options include `T`, `t`, and a space ` `.
# `offset_datetime_format_info`
```cpp
struct offset_datetime_format_info
{
datetime_delimiter_kind delimiter = datetime_delimiter_kind::upper_T;
bool has_seconds = true;
std::size_t subsecond_precision = 6; // [us]
};
bool operator==(const offset_datetime_format_info&, const offset_datetime_format_info&) noexcept;
bool operator!=(const offset_datetime_format_info&, const offset_datetime_format_info&) noexcept;
```
## Member Variables
### `datetime_delimiter_kind delimiter`
Specifies the delimiter to use.
### `bool has_seconds`
Specifies whether to omit seconds.
### `std::size_t subsecond_precision`
Specifies how many digits to output for subseconds.
# `local_datetime_format_info`
```cpp
struct local_datetime_format_info
{
datetime_delimiter_kind delimiter = datetime_delimiter_kind::upper_T;
bool has_seconds = true;
std::size_t subsecond_precision = 6; // [us]
};
bool operator==(const local_datetime_format_info&, const local_datetime_format_info&) noexcept;
bool operator!=(const local_datetime_format_info&, const local_datetime_format_info&) noexcept;
```
## Member Variables
### `datetime_delimiter_kind delimiter`
Specifies the delimiter to use.
### `bool has_seconds`
Specifies whether to omit seconds.
### `std::size_t subsecond_precision`
Specifies how many digits to output for subseconds.
# `local_date_format_info`
```cpp
struct local_date_format_info
{
// nothing, for now
};
bool operator==(const local_date_format_info&, const local_date_format_info&) noexcept;
bool operator!=(const local_date_format_info&, const local_date_format_info&) noexcept;
```
No formatting parameters are specified for `local_date`.
# `local_time_format_info`
```cpp
struct local_time_format_info
{
bool has_seconds = true;
std::size_t subsecond_precision = 6; // [us]
};
bool operator==(const local_time_format_info&, const local_time_format_info&) noexcept;
bool operator!=(const local_time_format_info&, const local_time_format_info&) noexcept;
```
## Member Variables
### `bool has_seconds`
Specifies whether to omit seconds.
### `std::size_t subsecond_precision`
Specifies how many digits to output for subseconds.
# `array_format`
```cpp
enum class array_format : std::uint8_t
{
default_format = 0,
oneline = 1,
multiline = 2,
array_of_tables = 3 // [[format.in.this.way]]
};
std::ostream& operator<<(std::ostream& os, const array_format f);
std::string to_string(const array_format);
```
- `default_format`
- Automatically selects the appropriate format. Longer arrays may span multiple lines.
- `oneline`
- Formats all elements in a single line.
- `multiline`
- Outputs each element on its own line.
- `array_of_tables`
- Formats in the `[[array.of.tables]]` style. Cannot contain elements other than `table`.
# `array_format_info`
```cpp
struct array_format_info
{
array_format fmt = array_format::default_format;
indent_char indent_type = indent_char::space;
std::int32_t body_indent = 4; // indent in case of multiline
std::int32_t closing_indent = 0; // indent of `]`
};
bool operator==(const array_format_info&, const array_format_info&) noexcept;
bool operator!=(const array_format_info&, const array_format_info&) noexcept;
```
## Member Variables
### `array_format fmt`
Specifies the format style.
### `indent_char indent_type`
Selects the type of character used for indentation.
### `std::int32_t body_indent`
Specifies the number of characters to indent before each element in `array_format::multiline`.
### `std::int32_t closing_indent`
Specifies the number of characters to indent before the closing bracket `]` in `array_format::multiline`.
# `table_format`
```cpp
enum class table_format : std::uint8_t
{
multiline = 0, // [foo] \n bar = "baz"
oneline = 1, // foo = {bar = "baz"}
dotted = 2, // foo.bar = "baz"
multiline_oneline = 3, // foo = { \n bar = "baz" \n }
implicit = 4 // [x] defined by [x.y.z]. skip in serializer.
};
std::ostream& operator<<(std::ostream& os, const table_format f);
std::string to_string(const table_format);
```
- `multiline`
- Formats as a multiline normal table.
- `oneline`
- Formats as an inline table.
- `dotted`
- Formats in the form of `a.b.c = "d"`.
- `multiline_oneline`
- Formats as a multiline inline table with line breaks. Available from TOML v1.1.0 onwards.
- cf. [spec.hpp](spec.md)
- `implicit`
- Skips implicit definitions like `[x.y.z.w]`, leaving `[x]`, `[x.y]`, `[x.y.z]` as implicit.
{{< hint warning >}}
According to TOML syntax, `dotted` table can have sub-tables:
```toml
[fruit]
apple.color = "red"
apple.taste.sweet = true
# [fruit.apple] # INVALID
# [fruit.apple.taste] # INVALID
[fruit.apple.texture] # you can add sub-tables
smooth = true
```
toml11 currently does not support this format.
Sub-tables under a `dotted` table would all be `dotted`, and tables are forced into inline table format.
{{< /hint >}}
# `table_format_info`
```cpp
struct table_format_info
{
table_format fmt = table_format::multiline;
indent_char indent_type = indent_char::space;
std::int32_t body_indent = 0; // indent of values
std::int32_t name_indent = 0; // indent of [table]
std::int32_t closing_indent = 0; // in case of {inline-table}
};
bool operator==(const table_format_info&, const table_format_info&) noexcept;
bool operator!=(const table_format_info&, const table_format_info&) noexcept;
```
## Member Variables
### `table_format fmt`
Specifies the formatting method.
### `indent_char indent_type`
Specifies the character used for indentation.
### `std::int32_t body_indent`
Specifies the width of indentation before keys.
The indentation width of the super table is not added.
### `std::int32_t name_indent`
Specifies the indentation of keys in `[table]` format.
The indentation width of the super table is not added.
### `std::int32_t closing_indent`
Specifies the indentation width before the closing brace `}` in the case of `multiline_oneline`.

56
docs/content.en/docs/reference/from.md Normal file
View File

@@ -0,0 +1,56 @@
+++
title = "from.hpp"
type = "docs"
+++
# from.hpp
Defines a `struct` used for conversion from `toml::value` in `toml::get` and `toml::find`.
You can achieve the same functionality by adding a `from_toml` member function, but for classes where you cannot add member functions, use `from<T>`.
This file does not provide specific implementations. Please specialize this `struct` when using.
```cpp
namespace toml
{
template<typename T>
struct from;
} // toml
```
## Example
```cpp
namespace extlib
{
struct foo
{
int a;
std::string b;
};
} // extlib
#include <toml11/from.hpp>
namespace toml
{
template<>
struct from<extlib::foo>
{
template<typename TC>
static extlib::foo from_toml(const toml::basic_value<TC>& v)
{
return extlib::foo{toml::find<int>(v, "a"), toml::find<std::string>(v, "b")};
}
};
} // toml
```
# Related
- [conversion.hpp]({{<ref "conversion.md">}})
- [into.hpp]({{<ref "into.md">}})

427
docs/content.en/docs/reference/get.md Normal file
View File

@@ -0,0 +1,427 @@
+++
title = "get.hpp"
type = "docs"
+++
# get.hpp
These are functions for extracting values from `toml::value` and performing type conversions if necessary.
{{< hint info >}}
`toml::value` can change the type it stores, and `toml::get` accommodates these types.
Technically, all functions use `toml::basic_value<TC>`.
However, for simplicity, we refer to it as `toml::value` in explanations unless a distinction is necessary.
In the documentation, if the template parameter `TC` changes the type, assume that types like `toml::value::integer_type` will also change accordingly.
{{< /hint >}}
# `toml::get<T>`
## Overview
Generally, `toml::get` behaves as follows:
You specify `T` as in `toml::get<int>(v)`.
```cpp
template<typename T, typename TC>
T get(const basic_value<TC>& v);
```
However, depending on the type of `T`, `toml::get` can exhibit different behaviors.
The types of `T` can be categorized into:
1. Types that do not require conversion
2. Types that require conversion
Detailed conditions and the specific types supported are discussed later.
### Types that Do Not Require Conversion
No conversion is needed if the provided `toml::value` is already storing the desired type. For instance, since `toml::value::integer_type` is an alias for `std::int64_t`, `toml::get<std::int64_t>(v)` requires no conversion. In this case, `toml::get` retrieves the `integer` value from `toml::value` and returns a reference to it.
If the provided `toml::value` is a mutable reference (`&`), the returned value is also a mutable reference (`&`). If it is an immutable reference (`const&`), the returned value will also be an immutable reference (`const&`). Returning a mutable reference allows you to overwrite the value stored in `toml::value` through that reference.
### Types that Require Conversion
Types other than the ones mentioned above require conversion. For example, since `toml::value::integer_type` is an alias for `std::int64_t`, `toml::get<std::size_t>(toml::value&)` requires conversion. In this case, `toml::get` retrieves the `integer` value from `toml::value` and casts it to return the appropriate type.
toml11 supports not only simple casts but also complex type conversions like converting from `toml::array` to `std::tuple<int, double, std::string>`, `std::array<double, 4>`, or from `toml::table` to `std::map<std::string, int>`. For specifics, refer to the subsequent sections.
### When Conversion Fails
Sometimes, the expected type conversion cannot be performed. For example, applying `toml::get<int>(v)` to a `toml::value` that holds a `table`.
In such cases, an attempt to convert to the type most similar to the desired type (in this case, `int` using `as_integer`) fails, and a `toml::type_error` is thrown.
When parsing from a file, an error message similar to the following is output:
```
terminate called after throwing an instance of 'toml::type_error'
what(): toml::value::as_integer(): bad_cast to integer
--> input.toml
|
6 | [fruit]
| ^^^^^^^-- the actual type is table
```
## When `T` is identical to `toml::value`
```cpp
template<typename T, typename TC>
T& get(basic_value<TC>& v);
template<typename T, typename TC>
T const& get(const basic_value<TC>& v);
template<typename T, typename TC>
T get(basic_value<TC>&& v);
```
Condition:
- `std::is_same<T, basic_value<TC>>` is satisfied.
Since this involves retrieving `toml::value` from `toml::value`, no conversion is performed, and the value is returned as is. This exists solely to generalize the implementation of other functions.
This does not fail.
## When `T` is one of `toml::value::{some_type}`
```cpp
template<typename T, typename TC>
T& get(basic_value<TC>& v);
template<typename T, typename TC>
T const& get(const basic_value<TC>& v);
template<typename T, typename TC>
T get(basic_value<TC>&& v);
```
Condition:
- `T` must be the same as one of the types that `toml::value` can store (e.g., `toml::value::boolean_type`).
If `toml::value` is storing a type that matches the specified type in `toml::get<T>`, such as `toml::value::integer_type`, no type conversion is needed, and a reference can be returned.
If a different type is stored, a `toml::type_error` is thrown.
## When `T` is `basic_value<OtherTC>` with a different `TypeConfig`
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
Condition:
- `T` is not `toml::basic_value<TC>`.
- `T` is `toml::basic_value<OtherTC>`.
When a `basic_value` that can store different types is specified, conversion is performed.
Since type conversion occurs, the returned value is a new value and not a reference.
This does not fail (except in cases like memory exhaustion).
## When `T` is an integer type
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
Condition:
- `std::is_integral<T>` is satisfied
- `T` is not `bool`
- `T` is not `toml::value::integer_type`
The function assumes that `toml::value` holds an `integer_type`, retrieves its value, converts it to `T`, and returns it.
If a type other than `toml::value::integer_type` is stored, a `toml::type_error` is thrown.
## When `T` is a floating-point type
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
Condition:
- `std::is_floating_point<T>` is satisfied
- `T` is not `toml::value::floating_type`
The function assumes that `toml::value` holds a `floating_type`, retrieves its value, converts it to `T`, and returns it.
If a type other than `toml::value::floating_type` is stored, a `toml::type_error` is thrown.
## When `T` is `std::string_view`
This is only available in C++17 and later.
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
Condition:
- `std::is_same<std::string_view, T>` is satisfied
The function assumes that `toml::value` holds a `string_type`, retrieves its value, constructs a `std::string_view` from it, and returns it.
If a type other than `toml::value::string_type` is stored, a `toml::type_error` is thrown.
## When `T` is `std::chrono::duration`
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
Condition:
- `T` is `std::chrono::duration<Rep, Period>`
The function assumes that `toml::value` holds a `local_time`, retrieves its value, converts it to `std::chrono::duration`, and returns it.
If a type other than `toml::value::local_time` is stored, a `toml::type_error` is thrown.
## When `T` is `std::chrono::system_clock::time_point`
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
Condition:
- `std::is_same<T, std::chrono::system_clock::time_point>` is satisfied
If the `toml::value` holds a `local_date`, `local_datetime`, or `offset_datetime`, this function retrieves the value and converts it to `std::chrono::system_clock::time_point`, returning the result.
If the value is of a type other than `local_date`, `local_datetime`, or `offset_datetime`, a `toml::type_error` is thrown.
## When `T` is array-like
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
Conditions:
- `T` has an `iterator`
- `T` has a `value_type`
- `T` supports `push_back(x)`
- `T` is not `toml::value::array_type`
- `T` is not `std::string`
- `T` is not `std::string_view`
- `T` is not map-like
- `T` does not have `from_toml()` member function
- `toml::from<T>` is not defined
- A constructor from `toml::basic_value<TC>` is not defined
This includes types like `std::vector<int>` and `std::deque<std::string>`.
If the `toml::value` holds an `array`, this function retrieves the value and converts it to the specified container type, returning the result.
If the value is of a type other than `toml::value::array_type`, a `toml::type_error` is thrown.
## When `T` is `std::array`
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
条件：
- `T` is `std::array<U, N>`
If the `toml::value` holds an `array`, this function retrieves the value and converts it to the specified container type, returning the result.
If the value is of a type other than `toml::value::array_type`, a `toml::type_error` is thrown.
If the `array` held by `toml::value` does not contain enough elements, a `std::out_of_range` is thrown.
## When `T` is `std::forward_list`
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
Condition:
- `T` is `std::forward_list<U>`
If the `toml::value` holds an `array`, this function retrieves the value and converts it to a `std::forward_list`, returning the result.
If the value is of a type other than `toml::value::array_type`, a `toml::type_error` is thrown.
## When `T` is `std::pair`
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
Condition:
- `T` is `std::pair<T1, T2>`
If the `toml::value` holds an `array`, this function retrieves the value and converts it to `std::pair<T1, T2>`, returning the result.
The `first` and `second` elements are recursively converted.
If the value is of a type other than `basic_value::array_type`, a `toml::type_error` is thrown.
If the `array` held by `toml::value` does not contain exactly 2 elements, a `std::out_of_range` is thrown.
## When `T` is `std::tuple`
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
Condition:
- `T` is `std::tuple<T1, T2, ... TN>`
If the `toml::value` holds an `array`, this function retrieves the value and converts it to `std::tuple<T1, T2, ...TN>`, returning the result.
Each element is recursively converted.
If the value is of a type other than `basic_value::array_type`, a `toml::type_error` is thrown.
If the `array` held by `toml::value` does not contain exactly `std::tuple_size<T>::value` elements, a `std::out_of_range` is thrown.
## When `T` is map-like
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
Conditions:
- `T` has an `iterator`
- `T` has a `key_type`
- `T` has a `value_type`
- `T` has a `mapped_type`
- `T` is not `toml::value::table_type`
- `T` does not have a `from_toml()` member function
- `toml::from<T>` is not defined
- A constructor from `toml::basic_value<TC>` is not defined
This includes types like `std::map<std::string, int>` and `std::unordered_map<std::string, float>`.
If the `toml::value` holds a `table`, this function retrieves the value and converts it to `T`, returning the result.
Elements are recursively converted.
If the value is of a type other than `basic_value::table_type`, a `toml::type_error` is thrown.
## When `T` is a user-defined type with a specialization of `toml::from<T>`
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
Condition:
- A specialization of `toml::from<T>` is defined
If a specialization of `toml::from` for `T` is defined, it is used for type conversion.
Ensure this does not conflict with individually supported types (`std::array`, `std::pair`, `std::tuple` etc).
## When `T` is a user-defined type with a `from_toml` member function
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
Conditions:
- `toml::from<T>` is not defined
- `T` has `from_toml()` member function
If `T` has a `from_toml(toml::basic_value<TC>)` member function, it is used for type conversion.
If `toml::from<T>` is defined, it takes precedence.
## When `T` is a user-defined type with a constructor that takes `toml::basic_value<TC>`
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
Conditions:
- `toml::from<T>` is not defined
- `T` does not have `from_toml()` member function
- `T` has a constructor that takes `toml::basic_value<TC>`
If `T` has a constructor that takes `toml::basic_value<TC>`, it is used for type conversion.
If `toml::from<T>` or `T::from_toml` is defined, they take precedence.
# `toml::get_or<T>`
`get_or` takes a default value for use when the conversion fails, avoiding exceptions.
The default value must be of the same type as the target type `T`.
Therefore, unlike `toml::get<T>`, `T` can be inferred in `get_or`.
## When `T` is `basic_value<TC>`
```cpp
template<typename TC>
basic_value<TC> const& get_or(const basic_value<TC>& v, const basic_value<TC>& opt)
template<typename TC>
basic_value<TC> & get_or(basic_value<TC>& v, basic_value<TC>& opt)
template<typename TC>
basic_value<TC> get_or(basic_value<TC>&& v, basic_value<TC>&& opt)
```
Since the conversion target is the same `toml::value`, this never fails.
It exists solely to generalize the implementation of other functions.
## When `T` is `basic_value<TC>::{some_type}`
```cpp
template<typename T, typename TC>
T const& get_or(const basic_value<TC>& v, const T& opt) noexcept
template<typename T, typename TC>
T & get_or(basic_value<TC>& v, T& opt) noexcept
template<typename T, typename TC>
T get_or(basic_value<TC>&& v, T&& opt) noexcept
```
Performs the same conversion as `toml::get<T>`. If it fails, the second argument is returned.
## When `T` is `const char*`
```cpp
template<typename TC>
typename basic_value<TC>::string_type
get_or(const basic_value<TC>& v,
const typename basic_value<TC>::string_type::value_type* opt);
```
When `const char*` is passed, the conversion target is interpreted as `std::string`.
## When `T` is something else
```cpp
template<typename TC>
typename std::remove_cv<typename std::remove_reference<T>::type>::type
get_or(const basic_value<TC>& v, T&& opt);
```
Performs the same conversion as `toml::get<T>`. If it fails, the second argument is returned.
# Related
- [find.hpp]({{<ref "find.md">}})
- [from.hpp]({{<ref "from.md">}})
- [value.hpp]({{<ref "value.md">}})

58
docs/content.en/docs/reference/into.md Normal file
View File

@@ -0,0 +1,58 @@
+++
title = "into.hpp"
type = "docs"
+++
# into.hpp
Defines a `struct` used for conversion from user-defined types into `toml::value` constructors.
You can achieve the same functionality by adding an `into_toml` member function, but for classes where you cannot add member functions, use `into<T>`.
This file does not provide specific implementations. Please specialize this `struct` when using.
```cpp
namespace toml
{
template<typename T>
struct into;
} // toml
```
## Example
```cpp
namespace extlib
{
struct foo
{
int a;
std::string b;
};
} // extlib
#include <toml11/into.hpp>
namespace toml
{
template<>
struct into<extlib::foo>
{
template<typename TC>
static toml::basic_value<TC> into_toml(const extlib::foo& f)
{
using value_type = toml::basic_value<TC>;
using table_type = typename value_type::table_type;
return value_type(table_type{{"a", f.a}, {"b", f.b}});
}
};
} // toml
```
# Related
- [conversion.hpp]({{<ref "conversion.md">}})
- [from.hpp]({{<ref "from.md">}})

82
docs/content.en/docs/reference/literal.md Normal file
View File

@@ -0,0 +1,82 @@
+++
title = "literal.hpp"
type = "docs"
+++
# literal.hpp
In `literal.hpp`, the `_toml` literal is defined.
The `_toml` literal parses string literals into `toml::value`.
```cpp
namespace toml
{
inline namespace literals
{
inline namespace toml_literals
{
toml::value operator"" _toml(const char* str, std::size_t len);
toml::value operator"" _toml(const char8_t* str, std::size_t len); // Available in C++20 and later
} // toml_literals
} // literals
} // toml
```
## Free Functions
### `operator"" _toml(const char*)`
```cpp
toml::value operator"" _toml(const char* str, std::size_t len);
```
Converts a string literal into a `toml::value` by parsing it.
For typical TOML files, this performs equivalent parsing to `toml::parse`.
```cpp
const auto v1 = "a = 'foo'"_toml; // v1: {a = 'foo'}
```
When dealing with multiline content, raw string literal is convenient.
```cpp
const auto v1 = R"(
a = 42
b = "foo"
)"_toml;
```
If the value is a standalone entity, it represents that value.
```cpp
const auto v2 = "'foo'"_toml; // v2: 'foo'
```
TOML allows keys consisting solely of numbers. When distinguishing between table definitions and arrays is ambiguous (e.g., `[1]`), table definitions take precedence.
To interpret as an array, use a trailing comma.
```cpp
const auto v3 = "[1]"_toml; // v3: {1 = {}}
const auto v4 = "[1,]"_toml; // v4: [1,]
```
### `operator"" _toml(const char8_t*)`
Defined when `char8_t` is available. Otherwise identical in functionality, differing only in argument type.
# Example
```cpp
#include <toml.hpp>
int main()
{
using namespace toml::literals::toml_literals;
const auto v = "a = \"foo\""_toml;
assert(v.at("a").as_string() == "foo");
return 0;
}
```

344
docs/content.en/docs/reference/ordered_map.md Normal file
View File

@@ -0,0 +1,344 @@
+++
title = "ordered_map.hpp"
type = "docs"
+++
# ordered_map.hpp
Defines `toml::ordered_map`, which is used to maintain the order of values in a file.
# `class ordered_map`
```cpp
namespace toml
{
template<typename Key, typename Val, typename Cmp = std::equal_to<Key>,
typename Allocator = std::allocator<std::pair<Key, Val>>>
class ordered_map;
}
```
The `ordered_map` is a `map` type that preserves the insertion order of values, allowing iteration in that order.
As a linear container, searches require `O(n)` time relative to the number of elements.
Use this when search operations are infrequent and maintaining the order of values is important.
## Non-Member Types
```cpp
namespace toml
{
struct ordered_type_config;
using ordered_value = basic_value<ordered_type_config>;
using ordered_table = typename ordered_value::table_type;
using ordered_array = typename ordered_value::array_type;
}
```
Use these in place of `toml::type_config` and `toml::value`.
{{< hint info >}}
Since `toml::parse` defaults to using `type_config`, specify
```cpp
const auto input = toml::parse<toml::ordered_type_config>("input.toml");
```
when parsing.
{{< /hint >}}
## Member Types
```cpp
using key_type = Key;
using mapped_type = Val;
using value_type = std::pair<Key, Val>;
using key_compare = Cmp;
using allocator_type = Allocator;
using container_type = std::vector<value_type, Allocator>;
using reference = typename container_type::reference;
using pointer = typename container_type::pointer;
using const_reference = typename container_type::const_reference;
using const_pointer = typename container_type::const_pointer;
using iterator = typename container_type::iterator;
using const_iterator = typename container_type::const_iterator;
using size_type = typename container_type::size_type;
using difference_type = typename container_type::difference_type;
```
## Member Functions
### Constructors
```cpp
ordered_map() = default;
```
Constructs an empty `ordered_map`.
### Constructors (Comparator, Allocator)
```cpp
explicit ordered_map(const Cmp& cmp, const Allocator& alloc = Allocator());
explicit ordered_map(const Allocator& alloc);
```
Constructs an `ordered_map` with a specified comparator for key comparison and an allocator for memory management.
### Copy and Move Constructors
```cpp
ordered_map(const ordered_map&) = default;
ordered_map(ordered_map&&) = default;
ordered_map(const ordered_map& other, const Allocator& alloc);
ordered_map(ordered_map&& other, const Allocator& alloc);
```
Constructs an `ordered_map` by copying or moving the contents from another `ordered_map`.
An allocator can also be specified for memory management.
### Constructors (Iterator)
```cpp
template<typename InputIterator>
ordered_map(InputIterator first, InputIterator last, const Cmp& cmp = Cmp(), const Allocator& alloc = Allocator());
template<typename InputIterator>
ordered_map(InputIterator first, InputIterator last, const Allocator& alloc = Allocator());
```
Constructs an `ordered_map` with a range represented by iterators.
The order of the elements follows the order of the iterators.
### Constructors (std::initializer_list)
```cpp
ordered_map(std::initializer_list<value_type> v, const Cmp& cmp = Cmp(), const Allocator& alloc = Allocator());
ordered_map(std::initializer_list<value_type> v, const Allocator& alloc);
```
Initializes the `ordered_map` using an initializer list.
### Copy and Move Assignment Operators
```cpp
ordered_map& operator=(const ordered_map&) = default;
ordered_map& operator=(ordered_map&&) = default;
```
Assigns the contents of another `ordered_map` to this one, using copy or move semantics.
### Assignment Operator (std::initializer_list)
```cpp
ordered_map& operator=(std::initializer_list<value_type> v);
```
Assigns the contents of an initializer list to the `ordered_map`.
### Destructor
```cpp
~ordered_map() = default;
```
Destroys the `ordered_map`.
### `begin()`, `end()`
```cpp
iterator begin() noexcept;
iterator end() noexcept;
const_iterator begin() const noexcept;
const_iterator end() const noexcept;
const_iterator cbegin() const noexcept;
const_iterator cend() const noexcept;
```
Returns iterators to the beginning and end of the container, allowing iteration over its contents in order.
### `empty()`
```cpp
bool empty() const noexcept;
```
Returns `true` if the `ordered_map` is empty, `false` otherwise.
### `size()`
```cpp
std::size_t size() const noexcept;
```
Returns the number of elements in the `ordered_map`.
### `max_size()`
```cpp
std::size_t max_size() const noexcept;
```
Returns the maximum number of elements the `ordered_map` can hold.
### `clear()`
```cpp
void clear();
```
Clears all elements from the `ordered_map`.
### `push_back(kv)`
```cpp
void push_back(const value_type&);
void push_back(value_type&&);
```
Appends a key-value pair to the end of the `ordered_map`.
### `emplace_back(k, v)`
```cpp
void emplace_back(key_type, mapped_type);
```
Appends a key-value pair to the end of the `ordered_map` by constructing it in place.
### `pop_back()`
```cpp
void pop_back();
```
Removes the last element from the `ordered_map`.
### `insert(kv)`
```cpp
void insert(value_type);
```
Inserts a key-value pair at the end of the `ordered_map`.
### `emplace(k, v)`
```cpp
void emplace(key_type, mapped_type);
```
Inserts a key-value pair at the end of the `ordered_map` by constructing it in place.
### `count(k)`
```cpp
std::size_t count(const key_type&) const noexcept;
```
Returns the number of elements with the specified key.
Since duplicate keys are not allowed, this will return either `1` if the key exists or `0` if it does not.
### `contains(k)`
```cpp
bool contains(const key_type&) const noexcept;
```
Returns `true` if the `ordered_map` contains an element with the specified key, `false` otherwise.
### `find(k)`
```cpp
iterator find(const key_type& key) noexcept;
const_iterator find(const key_type& key) const noexcept;
```
Finds an element with the specified key and returns an iterator to it. If the key is not found, returns `end()`.
### `at(k)`
```cpp
mapped_type& at(const key_type& k);
mapped_type const& at(const key_type& k) const;
```
Finds an element with the specified key and returns a reference to its value. Throws `std::out_of_range` if the key is not found.
### `operator[](k)`
```cpp
mapped_type& operator[](const key_type& k);
mapped_type const& operator[](const key_type& k) const;
```
Finds an element with the specified key and returns a reference to its value.
If the key is not found, a new value is constructed and returned.
If the `ordered_map` is `const`, throws `std::out_of_range` instead.
### `key_comp()`
```cpp
key_compare key_comp() const;
```
Returns the comparator used for key comparison.
## Notes
### Key Modification
{{< hint warning >}}
Since `ordered_map` uses `std::pair<Key, Val>` for `value_type`, it is possible to modify the key through an iterator. However, this practice is not recommended.
If you modify a key this way and it conflicts with an existing key, one of the conflicting keys will become unsearchable.
When using `operator[]`, `push_back`, or `insert`, collisions with existing keys are detected.
{{< /hint >}}
### Order Preservation Details
{{< hint warning >}}
`ordered_map` maintains the order of keys, but this order preservation applies only to keys defined within the same table. Order across different tables is not maintained.
For example, the order in the following file will be preserved:
```cpp
apple.type = "fruit"
apple.skin = "thin"
apple.color = "red"
orange.type = "fruit"
orange.skin = "thick"
orange.color = "orange"
```
In contrast, the order in the following file will not be preserved:
```cpp
apple.type = "fruit"
orange.type = "fruit"
apple.skin = "thin"
orange.skin = "thick"
apple.color = "red"
orange.color = "orange"
```
`ordered_map` preserves the order of the `apple` and `orange` definitions at the root table level, and the order of `type`, `skin`, `color` within each `apple` and `orange` table.
{{< /hint >}}
## Related
- [parser.hpp]({{<ref "parser.md">}})
- [types.hpp]({{<ref "types.md">}})
- [value.hpp]({{<ref "value.md">}})

375
docs/content.en/docs/reference/parser.md Normal file
View File

@@ -0,0 +1,375 @@
+++
title = "parser.hpp"
type = "docs"
+++
# parser.hpp
Defines functions for parsing files or strings and the exceptions they use.
While `parse` throws an exception on failure, `try_parse` returns error information.
# `parse`
Parses the content of a given file and returns a `toml::basic_value`.
In case of failure, `toml::syntax_error` is thrown.
The type information of `basic_value` is provided by a `template`, and the TOML language version is specified by `toml::spec`.
### `parse(std::istream&, std::string filename, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config>
basic_value<TC>
parse(std::istream& is,
std::string fname = "unknown file",
spec s = spec::default_version());
}
```
Parses the content of the given `std::istream&`.
The filename information is taken as the third argument. If the filename is not provided, it defaults to `"unknown file"`.
### `parse(std::string filename, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config>
basic_value<TC>
parse(std::string fname,
spec s = spec::default_version());
}
```
Parses the content of the given filename.
If reading the file fails, `toml::file_io_error` is thrown.
If parsing fails, `toml::syntax_error` is thrown.
### `parse(const char (&)[N] filename, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config, std::size_t N>
basic_value<TC>
parse(const char (&fname)[N],
spec s = spec::default_version());
}
```
Parses the content of the given filename from a string literal.
If reading the file fails, `toml::file_io_error` is thrown.
If parsing fails, `toml::syntax_error` is thrown.
### `parse(std::filesystem::path, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config>
basic_value<TC>
parse(const std::filesystem::path& fpath,
spec s = spec::default_version());
}
```
This is defined only if `<filesystem>` is available.
Parses the content of the file at the given file path.
If reading the file fails, `toml::file_io_error` is thrown.
If parsing fails, `toml::syntax_error` is thrown.
### `parse(FILE*, std::string filename, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config>
result<basic_value<TC>, std::vector<error_info>>
parse(FILE* fp,
std::string filename,
spec s = spec::default_version());
}
```
Parses the content of the file pointed to by `FILE*`.
If reading the file fails, `file_io_error` containing `errno` is thrown.
If parsing fails, `syntax_error` is thrown.
### `parse(std::vector<unsigned char>, std::string filename, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config>
basic_value<TC>
parse(std::vector<unsigned char> content,
std::string filename,
spec s = spec::default_version());
}
```
Parses the byte sequence as a TOML file.
If parsing fails, `toml::syntax_error` is thrown.
# `parse_str`
### `parse_str(std::string, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config>
basic_value<TC>
parse_str(std::string content,
spec s = spec::default_version(),
cxx::source_location loc = cxx::source_location::current());
}
```
Parses a string as a TOML file.
In case of failure, `toml::syntax_error` is thrown.
The type information of `basic_value` is provided by a `template`, and the TOML language version is specified by `toml::spec`.
You generally don't need to manually set the third argument, `cxx::source_location`.
If `std::source_location`, `std::experimental::source_location`, or `__builtin_FILE` is available,
the location information where `parse_str` was called will be stored.
# `try_parse`
Parses the contents of the given file and returns a `toml::basic_value` if successful, or a `std::vector<toml::error_info>` if it fails.
The type information of `basic_value` is specified by `template`, and the version of the TOML language is specified by `toml::spec`.
{{< hint warning >}}
Unlike `parse`, `try_parse` does not throw exceptions defined in toml11 such as `syntax_error`.
However, please note that exceptions thrown by the standard library will still propagate.
For instance, errors occurring internally within `std::ifstream` or memory exhaustion in `std::vector` will throw exceptions.
{{< /hint >}}
### `try_parse(std::istream&, std::string filename, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config>
result<basic_value<TC>, std::vector<error_info>>
try_parse(std::istream& is,
std::string fname = "unknown file",
spec s = spec::default_version());
}
```
Takes a `std::istream&` and parses its content.
The file name information is taken as the second argument. If a file name is not provided, it defaults to `"unknown file"`.
If parsing fails, a `result` holding the error type `std::vector<error_info>` is returned.
If successful, a `result` holding a `basic_value` is returned.
### `try_parse(std::string filename, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config>
result<basic_value<TC>, std::vector<error_info>>
try_parse(std::string fname,
spec s = spec::default_version());
}
```
Takes a file name and parses its content.
If parsing fails, a `result` holding the error type `std::vector<error_info>` is returned.
If successful, a `result` holding a `basic_value` is returned.
### `try_parse(const char (&)[N] filename, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config, std::size_t N>
result<basic_value<TC>, std::vector<error_info>>
try_parse(const char (&fname)[N],
spec s = spec::default_version());
}
```
Takes a string literal as a file name and parses its content.
If parsing fails, a `result` holding the error type `std::vector<error_info>` is returned.
If successful, a `result` holding a `basic_value` is returned.
### `try_parse(std::filesystem::path, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config>
result<basic_value<TC>, std::vector<error_info>>
try_parse(const std::filesystem::path& fpath,
spec s = spec::default_version());
}
```
Takes a file path and parses its content.
If parsing fails, a `result` holding the error type `std::vector<error_info>` is returned.
If successful, a `result` holding a `basic_value` is returned.
### `try_parse(FILE*, std::string filename, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config>
result<basic_value<TC>, std::vector<error_info>>
try_parse(FILE* fp,
std::string filename,
spec s = spec::default_version());
}
```
Takes a `FILE*` and parses its content.
If parsing fails, a `result` holding the error type `std::vector<error_info>` is returned.
If successful, a `result` holding a `basic_value` is returned.
### `try_parse(std::vector<unsigned char>, std::string filename, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config>
result<basic_value<TC>, std::vector<error_info>>
try_parse(std::vector<unsigned char> content,
std::string filename,
spec s = spec::default_version());
}
```
Takes a byte array and parses its content as a TOML file.
If parsing fails, a `result` holding the error type `std::vector<error_info>` is returned.
If successful, a `result` holding a `basic_value` is returned.
# `try_parse_str`
### `try_parse_str(std::string, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config>
result<basic_value<TC>, std::vector<error_info>>
try_parse_str(std::string content,
spec s = spec::default_version(),
cxx::source_location loc = cxx::source_location::current());
}
```
Parses a string as a TOML file, returning a `toml::basic_value` if successful, or a `std::vector<toml::error_info>` if it fails.
Unlike `parse_str`, it does not throw `syntax_error`, but instead returns error information as the failure type of the `result`.
If `std::source_location`, `std::experimental::source_location`, or `__builtin_FILE` is available, it will record the location information.
Typically, you do not need to manually set the third argument `cxx::source_location`. If any of `std::source_location`, `std::experimental::source_location`, or `__builtin_FILE` are available, the information of the location where `parse_str` was called will be saved as the location information.
{{< hint warning >}}
Unlike `parse`, `try_parse` does not throw exceptions defined in toml11 such as `syntax_error`. However, please note that exceptions thrown by the standard library will still propagate.
For instance, errors occurring internally within `std::ifstream` or memory exhaustion in `std::vector` will throw exceptions.
{{< /hint >}}
# `syntax_error`
```cpp
namespace toml
{
struct syntax_error final : public ::toml::exception
{
public:
syntax_error(std::string what_arg, std::vector<error_info> err);
~syntax_error() noexcept override = default;
const char* what() const noexcept override;
std::vector<error_info> const& errors() const noexcept
};
}
```
An exception thrown when a syntax error is detected in TOML.
It is thrown by `parse` but not by `try_parse`.
# `file_io_error`
```cpp
namespace toml
{
struct file_io_error final : public ::toml::exception
{
public:
file_io_error(const std::string& msg, const std::string& fname);
file_io_error(int errnum, const std::string& msg, const std::string& fname);
~file_io_error() noexcept override = default;
const char* what() const noexcept override;
bool has_errno() const noexcept;
int get_errno() const noexcept;
};
}
```
An exception thrown when reading the contents of a file fails.
When using `FILE*` to read a file, `errno` is set.
### `has_errno`
If `std::ifstream` fails, `errno` is not set.
In this case, `has_errno` returns `false`.
### `get_errno`
Particularly when passing a `FILE*`, retrieves the value of `errno`.
If `has_errno` is `false`, it returns `0`.
# Related
- [error_info.hpp]({{<ref "error_info.md">}})
- [result.hpp]({{<ref "result.md">}})
- [spec.hpp]({{<ref "spec.md">}})
- [value.hpp]({{<ref "value.md">}})

518
docs/content.en/docs/reference/result.md Normal file
View File

@@ -0,0 +1,518 @@
+++
title = "result.hpp"
type = "docs"
+++
# result.hpp
`result.hpp` defines the `result` type, which can hold either a success value or a failure value.
This is used as the return type for `toml::try_parse`, which does not throw exceptions.
# success
A type that holds a success value.
```cpp
namespace toml
{
template<typename T>
struct success
{
using value_type = T;
explicit success(value_type v);
~success() = default;
success(const success&) = default;
success(success&&) = default;
success& operator=(const success&) = default;
success& operator=(success&&) = default;
template<typename U>
explicit success(U&& v);
template<typename U>
explicit success(success<U> v);
value_type& get() noexcept;
value_type const& get() const noexcept;
};
template<typename T>
success<typename std::decay<T>::type> ok(T&& v);
template<std::size_t N>
success<std::string> ok(const char (&literal)[N])
}
```
## Member Types
```cpp
using value_type = T;
```
The type of the success value.
## Member Functions
### Constructor
```cpp
explicit success(value_type v);
```
Constructs with a `value_type` argument.
```cpp
template<typename U>
explicit success(U&& v);
```
Constructs with another type that can be converted to `value_type`.
```cpp
template<typename U>
explicit success(success<U> v);
```
Constructs with another `success` type that can be converted to `value_type`.
### `get()`
```cpp
value_type& get() noexcept;
value_type const& get() const noexcept;
```
Accesses the stored value.
## Non-Member Functions
### `ok(T)`
```cpp
template<typename T>
success<typename std::decay<T>::type> ok(T&& v);
template<std::size_t N>
success<std::string> ok(const char (&literal)[N]);
```
Constructs and returns a `success` type from a success value.
Converts a string literal into `std::string`.
# `success<reference_wrapper<T>>`
Specialization of `success` for when the success value is a reference.
```cpp
namespace toml
{
template<typename T>
struct success<std::reference_wrapper<T>>
{
using value_type = T;
explicit success(std::reference_wrapper<value_type> v) noexcept;
value_type& get() noexcept;
value_type const& get() const noexcept;
};
}
```
## Member Types
```cpp
using value_type = T;
```
The type of the success value. It is `T` from `std::reference_wrapper<T>`, not the reference itself.
### `get()`
```cpp
value_type& get() noexcept;
value_type const& get() const noexcept;
```
Accesses the stored value.
# failure
A type that holds a failure value.
```cpp
namespace toml
{
template<typename T>
struct failure
{
using value_type = T;
explicit failure(value_type v);
~failure() = default;
failure(const failure&) = default;
failure(failure&&) = default;
failure& operator=(const failure&) = default;
failure& operator=(failure&&) = default;
template<typename U>
explicit failure(U&& v);
template<typename U>
explicit failure(failure<U> v);
value_type& get() noexcept;
value_type const& get() const noexcept;
};
template<typename T>
failure<typename std::decay<T>::type> err(T&& v);
template<std::size_t N>
failure<std::string> err(const char (&literal)[N]);
}
```
## Member Types
```cpp
using value_type = T;
```
The type of the failure value.
## Member Functions
### Constructor
```cpp
explicit failure(value_type v);
```
Constructs with a `value_type` argument.
```cpp
template<typename U>
explicit failure(U&& v);
```
Constructs with another type that can be converted to `value_type`.
```cpp
template<typename U>
explicit failure(failure<U> v);
```
Constructs with another `failure` type that can be converted to `value_type`.
### `get()`
```cpp
value_type& get() noexcept;
value_type const& get() const noexcept;
```
Accesses the stored value.
## Non-Member Functions
### `err(T)`
```cpp
template<typename T>
failure<typename std::decay<T>::type> err(T&& v);
template<std::size_t N>
failure<std::string> err(const char (&literal)[N]);
```
Constructs and returns a `failure` type from a failure value.
Converts a string literal into `std::string`.
# `failure<reference_wrapper<T>>`
Specialization of `failure` for when the failure value is a reference.
```cpp
namespace toml
{
template<typename T>
struct failure<std::reference_wrapper<T>>
{
using value_type = T;
explicit failure(std::reference_wrapper<value_type> v) noexcept;
value_type& get() noexcept {return value.get();}
value_type const& get() const noexcept {return value.get();}
};
}
```
## Member Types
```cpp
using value_type = T;
```
The type of the failure value. It is `T` from `std::reference_wrapper<T>`, not the reference itself.
### `get()`
```cpp
value_type& get() noexcept;
value_type const& get() const noexcept;
```
Accesses the stored value.
# result
A type that holds either a success value or a failure value.
```cpp
namespace toml
{
template<typename T, typename E>
struct result
{
using success_type = success<T>;
using failure_type = failure<E>;
using value_type = typename success_type::value_type;
using error_type = typename failure_type::value_type;
result(success_type s);
result(failure_type f);
template<typename U>
result(success<U> s);
template<typename U>
result(failure<U> f);
result& operator=(success_type s);
result& operator=(failure_type f);
template<typename U>
result& operator=(success<U> s);
template<typename U>
result& operator=(failure<U> f);
~result() noexcept;
result(const result& other);
result(result&& other);
result& operator=(const result& other);
result& operator=(result&& other);
template<typename U, typename F>
result(result<U, F> other);
template<typename U, typename F>
result& operator=(result<U, F> other);
bool is_ok() const noexcept;
bool is_err() const noexcept;
explicit operator bool() const noexcept;
value_type& unwrap(cxx::source_location loc = cxx::source_location::current());
value_type const& unwrap(cxx::source_location loc = cxx::source_location::current()) const;
value_type& unwrap_or(value_type& opt) noexcept;
value_type const& unwrap_or(value_type const& opt) const noexcept;
error_type& unwrap_err(cxx::source_location loc = cxx::source_location::current());
error_type const& unwrap_err(cxx::source_location loc = cxx::source_location::current()) const;
value_type& as_ok() noexcept;
value_type const& as_ok() const noexcept;
error_type& as_err() noexcept;
error_type const& as_err() const noexcept;
};
}
```
## Member Types
### `success_type`
`success<T>`.
### `failure_type`
`failure<E>`.
### `value_type`
The type `T` of the success value, alias for `success_type::value_type`.
If `T` is `std::reference_wrapper<U>`, then it is `U`.
### `error_type`
The type `E` of the failure value, alias for `failure_type::value_type`.
If `E` is `std::reference_wrapper<F>`, then it is `F`.
## Member Functions
### Constructor
```cpp
result() = delete;
```
Cannot construct `result` type by default. Needs to be given either a success or failure type.
```cpp
result(success_type s);
result(failure_type f);
```
Constructs with a `success_type` or `failure_type`.
```cpp
template<typename U>
result(success<U> s);
template<typename U>
result(failure<U> f);
```
Constructs with a `success<U>` or `failure<U>` that is convertible to `value_type` or `error_type`.
```cpp
template<typename U, typename F>
result(result<U, F> other);
template<typename U, typename F>
result& operator=(result<U, F> other);
```
Constructs from or assigns to another `result` with convertible `success` or `failure` types.
### Copy and Move Constructors
```cpp
result(const result& other);
result(result&& other);
```
Can be copy or move constructed.
### `operator=`
```cpp
result& operator=(const result& other);
result& operator=(result&& other);
```
Can be copy or move assigned.
```cpp
template<typename U>
result& operator=(success<U> s);
template<typename U>
result& operator=(failure<U> f);
```
Can be assigned from convertible `success` or `failure` types.
### `is_ok()`
```cpp
bool is_ok() const noexcept;
```
Returns `true` if it holds a success value, `false` otherwise.
### `is_err()`
```cpp
bool is_err() const noexcept;
```
Returns `true` if it holds a failure value, `false` otherwise.
### `operator bool()`
```cpp
explicit operator bool() const noexcept;
```
Returns `true` if it holds a success value, `false` otherwise.
### `unwrap()`
```cpp
value_type& unwrap(cxx::source_location loc = cxx::source_location::current());
value_type const& unwrap(cxx::source_location loc = cxx::source_location::current()) const;
```
Returns the stored success value.
Throws `toml::bad_result_access` if it holds a failure value.
If `std::source_location` or equivalent compiler extension is available, the file name and line number where `unwrap()` occurred are included in the `what()` string.
### `unwrap_or()`
```cpp
value_type& unwrap_or(value_type& opt) noexcept;
value_type const& unwrap_or(value_type const& opt) const noexcept;
```
Returns the stored success value if present, otherwise returns the provided default value.
### `unwrap_err()`
```cpp
error_type& unwrap_err(cxx::source_location loc = cxx::source_location::current());
error_type const& unwrap_err(cxx::source_location loc = cxx::source_location::current()) const;
```
Returns the stored failure value.
Throws `toml::bad_result_access` if it holds a success value.
If `std::source_location` or equivalent compiler extension is available, the file name and line number where `unwrap_err()` occurred are included in the `what()` string.
### `as_ok()`
```cpp
value_type& as_ok() noexcept;
value_type const& as_ok() const noexcept;
```
Returns the success value without checking.
Behavior is undefined if it holds a failure value.
### `as_err()`
```cpp
error_type& as_err() noexcept;
error_type const& as_err() const noexcept;
```
Returns the failure value without checking.
Behavior is undefined if it holds a success value.
# bad_result_access
An exception thrown when `unwrap` or `unwrap_err` fails in a `result`.
```cpp
namespace toml
{
struct bad_result_access : public ::toml::exception
{
public:
explicit bad_result_access(const std::string& what_arg);
virtual ~bad_result_access() noexcept override = default;
virtual const char* what() const noexcept override;
protected:
std::string what_;
};
}
```

65
docs/content.en/docs/reference/serializer.md Normal file
View File

@@ -0,0 +1,65 @@
+++
title = "serializer.hpp"
type = "docs"
+++
# serializer.hpp
## `format`
Serializes the data.
```cpp
namespace toml
{
template<typename TC>
std::string format(const basic_value<TC>& v,
const spec s = spec::default_version());
template<typename TC>
std::string format(const typename basic_value<TC>::key_type& k,
const basic_value<TC>& v,
const spec s = spec::default_version());
template<typename TC>
std::string format(const std::vector<typename basic_value<TC>::key_type>& ks,
const basic_value<TC>& v,
const spec s = spec::default_version());
}
```
If there's a conflict between the format information and the `spec`, for example, when using `v1.0.0` with `table_format::multiline_oneline`, the `spec` takes precedence.
### `format(v, spec)`
Formats a `toml::value` according to its format information and the provided `spec`.
If it's a `table_type`, it's formatted as if it were the root table. Otherwise, only the value is formatted.
### `format(k, v, spec)`
Formats a `toml::value` along with the given key.
`v` is interpreted as being defined under that key.
### `format([k,...], v, spec)`
`v` is interpreted as being defined under those keys.
If multiple keys are provided, it's interpreted as a recursively defined table.
## `serialization_error`
Reports errors that occurred during serialization.
```cpp
namespace toml
{
struct serialization_error final : public ::toml::exception
{
public:
explicit serialization_error(std::string what_arg, source_location loc);
~serialization_error() noexcept override = default;
const char* what() const noexcept override;
source_location const& location() const noexcept;
};
}
```

235
docs/content.en/docs/reference/source_location.md Normal file
View File

@@ -0,0 +1,235 @@
+++
title = "source_location.hpp"
type = "docs"
+++
# source_location.hpp
`source_location.hpp` defines a class representing a specific area within a TOML file.
This class is used to represent problematic areas in error messages.
# `toml::source_location`
`source_location` is a class representing a specific area within a TOML file.
```cpp
namespace toml
{
struct source_location
{
public:
explicit source_location(/* implementation-defined */);
~source_location() = default;
source_location(source_location const&) = default;
source_location(source_location &&) = default;
source_location& operator=(source_location const&) = default;
source_location& operator=(source_location &&) = default;
bool is_ok() const noexcept;
std::size_t length() const noexcept;
std::size_t first_line_number() const noexcept;
std::size_t first_column_number() const noexcept;
std::size_t last_line_number() const noexcept;
std::size_t last_column_number() const noexcept;
std::string const& file_name() const noexcept;
std::size_t num_lines() const noexcept;
std::string const& first_line() const;
std::string const& last_line() const;
std::vector<std::string> const& lines() const noexcept;
};
template<typename ... Ts>
std::string format_location(const source_location& loc, const std::string& msg, const Ts& ... locs_and_msgs);
} //toml
```
## Member Functions
### Constructor
```cpp
explicit source_location(/* implementation-defined */);
```
`toml::source_location` can only be constructed via `toml::parse` or the `_toml` literal.
### `is_ok()`
```cpp
bool is_ok() const noexcept;
```
Returns `true` if the `source_location` holds a valid value, `false` otherwise.
The result of `location()` from `toml::value` constructed outside of `toml::parse` or `_toml` literals returns `false` for `is_ok` as it points to nothing.
### `length()`
```cpp
std::size_t length() const noexcept;
```
Returns the length of the area pointed to by the `source_location`.
Returns `0` if it does not hold a valid value.
### `first_line_number()`
```cpp
std::size_t first_line_number() const noexcept;
```
Returns the line number of the first line of the area pointed to by the `source_location`.
Returns `1` if it does not hold a valid value.
### `first_column_number()`
```cpp
std::size_t first_column_number() const noexcept;
```
Returns the column number of the first column of the area pointed to by the `source_location`.
Returns `1` if it does not hold a valid value.
### `last_line_number()`
```cpp
std::size_t last_line_number() const noexcept;
```
Returns the line number of the last line of the area pointed to by the `source_location`.
Returns `1` if it does not hold a valid value.
### `last_column_number()`
```cpp
std::size_t last_column_number() const noexcept;
```
Returns the column number of the last column of the area pointed to by the `source_location`.
Returns `1` if it does not hold a valid value.
### `file_name()`
```cpp
std::string const& file_name() const noexcept;
```
Returns the file name containing the area pointed to by the `source_location`.
Returns `"unknown file"` if it does not hold a valid value.
### `num_lines()`
```cpp
std::size_t num_lines() const noexcept;
```
Returns the number of lines in the area pointed to by the `source_location`.
Returns `0` if it does not hold a valid value.
### `first_line()`
```cpp
std::string const& first_line() const;
```
Returns the first line of the area pointed to by the `source_location`.
Throws `std::out_of_range` if it does not hold a valid value.
### `last_line()`
```cpp
std::string const& last_line() const;
```
Returns the last line of the area pointed to by the `source_location`.
Throws `std::out_of_range` if it does not hold a valid value.
### `lines()`
```cpp
std::vector<std::string> const& lines() const noexcept;
```
Returns all lines in the area pointed to by the `source_location`.
Returns a reference to an empty `std::vector` if it does not hold a valid value.
## Non-Member Functions
### `format_location`
```cpp
template<typename ... Ts>
std::string format_location(const source_location& loc, const std::string& msg,
const Ts& ... locs_and_msgs);
```
Formats the specified `source_location` and its associated message as follows:
```
-> {filename.toml}
|
1 | a = 42
| ^-- {message}
```
If colorization is enabled, ANSI escape sequences will be added for coloring.
When multiple `locs_and_msgs` are provided, they must be in the order of `const source_location&` followed by `const std::string&`, and the next pair in the same order, and so on.
#### Example: Multiple `source_location` and `std::string`
When multiple `source_location` and `std::string` pairs are provided, they are formatted as follows:
```cpp
source_location& loc0;
source_location& loc1;
source_location& loc2;
std::string msg0;
std::string msg1;
std::string msg2;
format_location(loc0, msg0,
loc1, msg1,
loc2, msg2);
```
```
-> {filename0.toml}
|
1 | a = 42
| ^-- {message0}
|
-> {filename1.toml}
|
2 | b = 3.14
| ^-- {message1}
|
-> {filename2.toml}
|
3 | c = "foo"
| ^-- {message2}
```
# Related
- [error_info.hpp]({{<ref "error_info.md">}})
- [value.hpp]({{<ref "value.md">}})

309
docs/content.en/docs/reference/spec.md Normal file
View File

@@ -0,0 +1,309 @@
+++
title = "spec.hpp"
type = "docs"
+++
# spec.hpp
`spec.hpp` defines classes for specifying the version of TOML.
# `toml::semantic_version`
`semantic_version` is a class that stores version information.
```cpp
namespace toml
{
struct semantic_version
{
constexpr semantic_version(std::uint32_t mjr, std::uint32_t mnr, std::uint32_t p) noexcept;
std::uint32_t major;
std::uint32_t minor;
std::uint32_t patch;
};
constexpr semantic_version
make_semver(std::uint32_t major, std::uint32_t minor, std::uint32_t patch) noexcept;
constexpr bool operator==(const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator!=(const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator< (const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator<=(const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator> (const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator>=(const semantic_version&, const semantic_version&) noexcept;
std::ostream& operator<<(std::ostream& os, const semantic_version& ver);
} //toml
```
## Member Functions
### Constructor
```cpp
constexpr semantic_version(std::uint32_t mjr, std::uint32_t mnr, std::uint32_t p) noexcept;
```
Constructs a `semantic_version` instance with the specified `major`, `minor`, and `patch` version numbers.
## Non-Member Functions
### Comparison Operators
```cpp
constexpr bool operator==(const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator!=(const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator< (const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator<=(const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator> (const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator>=(const semantic_version&, const semantic_version&) noexcept;
```
Compares two `semantic_version` instances according to semantic versioning rules.
### Stream Operator
```cpp
std::ostream& operator<<(std::ostream& os, const semantic_version& ver);
```
Outputs the version in the format `{major}.{minor}.{patch}`.
### `to_string`
```cpp
std::string to_string(const semantic_version& ver);
```
Converts the version to a string in the format `{major}.{minor}.{patch}`.
# `toml::spec`
`spec` is a class that stores TOML version information.
```cpp
struct spec
{
constexpr static spec default_version() noexcept;
constexpr static spec v(std::uint32_t mjr, std::uint32_t mnr, std::uint32_t p) noexcept;
constexpr explicit spec(const semantic_version& semver) noexcept;
semantic_version version; // toml version
// diff from v1.0.0 -> v1.1.0
bool v1_1_0_allow_control_characters_in_comments;
bool v1_1_0_allow_newlines_in_inline_tables;
bool v1_1_0_allow_trailing_comma_in_inline_tables;
bool v1_1_0_allow_non_english_in_bare_keys;
bool v1_1_0_add_escape_sequence_e;
bool v1_1_0_add_escape_sequence_x;
bool v1_1_0_make_seconds_optional;
// library extensions
bool ext_hex_float; // allow hex float
bool ext_num_suffix; // allow number suffix
bool ext_null_value; // allow null value
};
```
## Member Functions
### Constructor
```cpp
constexpr explicit spec(const semantic_version& semver) noexcept;
```
Constructs a `spec` with the specified TOML version.
Supports TOML v1.0.0 and TOML v1.1.0.
### `default_version()`
```cpp
constexpr static spec default_version() noexcept;
```
Constructs a `spec` with the default version.
Used as the default value for `toml::parse` and `toml::format`.
In toml11 v4.0.0, the value is v1.0.0.
### `v(major, minor, patch)`
```cpp
constexpr static spec v(std::uint32_t mjr, std::uint32_t mnr, std::uint32_t p) noexcept;
```
Constructs a `spec` with the specified version.
## Member Variables
Each flag is automatically set to `true` when the specified version includes the corresponding feature.
You can modify these flags to change the behavior of `toml::parse` and `toml::format`.
{{<hint warning>}}
Some features of TOML v1.1.0 are still under fairly lengthy discussion and may still be reverted.
If they are indeed reverted, toml11 will remove those features in a minor version upgrade or move them to a corresponding later version.
As such, any features related to future versions should be considered unstable.
{{</hint>}}
### Example
```cpp
auto spec = toml::spec::v(1, 0, 0);
// Allow newlines in inline tables in addition to v1.0.0 features.
// Other v1.1.0 features are not enabled.
spec.v1_1_0_allow_newlines_in_inline_tables = true;
auto input = toml::parse("input_file.toml", spec);
```
### `v1_1_0_allow_control_characters_in_comments`
```cpp
bool v1_1_0_allow_control_characters_in_comments;
```
Allows most control characters in comments.
Added in TOML v1.1.0.
### `v1_1_0_allow_newlines_in_inline_tables`
```cpp
bool v1_1_0_allow_newlines_in_inline_tables;
```
Allows newlines in inline tables.
Added in TOML v1.1.0.
### `v1_1_0_allow_trailing_comma_in_inline_tables`
```cpp
bool v1_1_0_allow_trailing_comma_in_inline_tables;
```
Allows trailing commas in inline tables.
Added in TOML v1.1.0.
### `v1_1_0_add_escape_sequence_e`
```cpp
bool v1_1_0_add_escape_sequence_e;
```
Allows `\e` to represent the ESC character.
Added in TOML v1.1.0.
### `v1_1_0_add_escape_sequence_x`
```cpp
bool v1_1_0_add_escape_sequence_x;
```
Allows `\xHH` to represent a single byte character.
Added in TOML v1.1.0.
### `v1_1_0_make_seconds_optional`
```cpp
bool v1_1_0_make_seconds_optional;
```
Makes the seconds component in time optional.
Unspecified seconds default to `0`.
Added in TOML v1.1.0.
### `ext_hex_float`
```cpp
bool ext_hex_float;
```
This is a language extension specific to toml11.
It is initialized to `false` regardless of the specified version.
You must explicitly set it to `true` if you want to use it.
Allows hexadecimal representation of floating-point numbers.
The hexadecimal representation conforms to the `printf` format specifier `%a/%A`.
```
hexf = 0xC0FFEEp-10
```
`toml::format` will format using hexadecimal notation only if the passed `toml::spec` has `ext_hex_float` set to `true`.
If the format specifier indicates `hex` but the `toml::spec` passed to `toml::format` has `ext_hex_float` set to `false`, the hexadecimal specification is ignored, and the number is output in decimal notation with maximum precision.
### `ext_num_suffix`
```cpp
bool ext_num_suffix;
```
This is a language extension specific to toml11.
It is initialized to `false` regardless of the specified version.
You must explicitly set it to `true` if you want to use it.
Allows the addition of suffixes to decimal integers and floating-point numbers. This does not apply to hexadecimal, octal, or binary notations.
There must be an `_` separator between the number and the suffix.
The suffix cannot start with a digit to avoid confusion with the numeric part.
```
distance = 10_m # valid
distance = 10_2m # invalid
distance = 10_2_m # valid
```
The suffix is stored in the format information as `std::string suffix`.
The `_` separating the number from the suffix is not included in the `suffix`.
```cpp
toml::value distance = toml::find(input, "distance");
assert(distance.as_integer_fmt().suffix == std::string("m"));
```
`toml::format` will format the value with the suffix only if the passed `toml::spec` has `ext_num_suffix` set to `true`.
The `suffix` follows the grammar defined as:
```abnf
non-digit-graph = ALPHA / non-ascii
graph = ALPHA / DIGIT / non-ascii
suffix = _ non-digit-graph *( graph / ( _ graph ) )
```
### `ext_null_value`
```cpp
bool ext_null_value;
```
This is a language extension specific to toml11.
Allows the use of `null` as a value.
A `toml::value` specified as `null` will have no value, and `is_empty()` will return `true`.
`toml::format` will format it as `null` only if the passed `toml::spec` has `ext_null_value` set to `true`.
Otherwise, `toml::format` will terminate with an error.

13
docs/content.en/docs/reference/toml.md Normal file
View File

@@ -0,0 +1,13 @@
+++
title = "toml.hpp"
type = "docs"
+++
# toml.hpp
`toml.hpp` includes all other headers.
This allows access to all features of toml11.
This header file and `toml_fwd.hpp` are located under `${TOML11_INCLUDE_DIR}/`,
while other header files are located under `${toml11_include_dir}/toml11/`.

18
docs/content.en/docs/reference/toml_fwd.md Normal file
View File

@@ -0,0 +1,18 @@
+++
title = "toml_fwd.hpp"
type = "docs"
+++
# toml_fwd.hpp
`toml_fwd.hpp` contains forward declarations of structures defined in toml11 and macro definitions.
When only forward declarations of toml11 structures are needed and implementation is not required, including `toml_fwd.hpp` instead of `toml.hpp` can reduce compilation time.
{{<hint warning>}}
Since this file only contains forward declarations, you cannot use `toml::table`, defined as `toml::basic_value<toml::type_config>::table_type`, and similarly defined `toml::array`. This is because they require the implementation of `basic_value`.
{{</hint>}}
This header file and `toml.hpp` are located under `${TOML11_INCLUDE_DIR}/`, while other header files are located under `${TOML11_INCLUDE_DIR}/toml11/`.

156
docs/content.en/docs/reference/types.md Normal file
View File

@@ -0,0 +1,156 @@
+++
title = "types.hpp"
type = "docs"
+++
# types.hpp
This document defines classes that specifies type information.
# `type_config`
`type_config` is a type that encapsulates parameters given to `toml::basic_value`.
When using different types within `toml::basic_value<T>`, you need to define and pass this type separately.
All elements listed are required.
If you use numerical types that cannot use standard stream operators, define and replace the equivalents for `read_int` and `read_float`.
```cpp
namespace toml
{
struct type_config
{
using comment_type = preserve_comments;
using boolean_type = bool;
using integer_type = std::int64_t;
using floating_type = double;
using string_type = std::string;
template<typename T>
using array_type = std::vector<T>;
template<typename K, typename T>
using table_type = std::unordered_map<K, T>;
static result<integer_type, error_info>
parse_int(const std::string& str, const source_location src, const std::uint8_t base);
static result<floating_type, error_info>
parse_float(const std::string& str, const source_location src, const bool is_hex);
};
using value = basic_value<type_config>;
using table = typename value::table_type;
using array = typename value::array_type;
} // toml
```
## `static` Member Functions
### `parse_int(str, src, base)`
```cpp
static result<integer_type, error_info>
parse_int(const std::string& str, const source_location src, const std::uint8_t base);
```
If you use a type as `integer_type` that cannot utilize standard stream operators, implement this function.
Otherwise, use `read_int` described later.
The `str` parameter receives a string with prefixes, leading zeros, and underscores removed.
The `src` parameter receives a `source_location` pointing to where the string was defined.
The `base` parameter receives one of `10`, `2`, `8`, or `16`.
### `parse_float(str, src, is_hex)`
```cpp
static result<floating_type, error_info>
parse_float(const std::string& str, const source_location src, const bool is_hex);
```
If you use a type as `floating_type` that cannot utilize standard stream operators, implement this function.
Otherwise, use `read_float` described later.
The `str` parameter receives a string with prefixes, leading zeros, and underscores removed.
The `src` parameter receives a `source_location` pointing to where the string was defined.
The `is_hex` parameter indicates whether the format is `hexfloat`. If you don't use the `hexfloat` extension, you don't need to implement this.
For details on the `hexfloat` extension, refer to [spec.hpp]({{<ref "spec.md">}}).
## Non-member Functions
### `read_int`
```cpp
template<typename T>
result<T, error_info>
read_int(const std::string& str, const source_location src, const std::uint8_t base);
```
This is the default function used. It parses using `std::istringstream`.
If `operator>>` and manipulators like `std::hex`, and `std::numeric_limits<T>` are defined (such as for `boost::multiprecision`), you can use this without modifications.
### `read_float`
```cpp
template<typename T>
result<T, error_info>
read_float(const std::string& str, const source_location src, const bool is_hex);
```
This is the default function used. It parses decimals using `std::istringstream` and hexfloats using `sscanf()`.
It supports `double` and `float`.
For other types, if `operator>>` is defined and `hex` is not used, you can use this function.
# `ordered_type_config`
`ordered_type_config` is a variation of `toml::type_config` where the table type is replaced with `toml::ordered_map`.
Additionally, it defines the `toml::ordered_value` alias.
Other than these changes, it is identical to `type_config`.
```cpp
namespace toml
{
struct ordered_type_config
{
using comment_type = preserve_comments;
using boolean_type = bool;
using integer_type = std::int64_t;
using floating_type = double;
using string_type = std::string;
template<typename T>
using array_type = std::vector<T>;
template<typename K, typename T>
using table_type = ordered_map<K, T>;
static result<integer_type, error_info>
parse_int(const std::string& str, const source_location src, const std::uint8_t base)
{
return read_int<integer_type>(str, src, base);
}
static result<floating_type, error_info>
parse_float(const std::string& str, const source_location src, const bool is_hex)
{
return read_float<floating_type>(str, src, is_hex);
}
};
using ordered_value = basic_value<ordered_type_config>;
using ordered_table = typename ordered_value::table_type;
using ordered_array = typename ordered_value::array_type;
} // toml
```

896
docs/content.en/docs/reference/value.md Normal file
View File

@@ -0,0 +1,896 @@
+++
title = "value.hpp"
type = "docs"
+++
# value.hpp
`value.hpp` defines `basic_value`.
# `toml::basic_value`
`basic_value` is a class that stores TOML values.
```cpp
namespace toml
{
template <class TypeConfig>
class basic_value;
// Defined in types.hpp
// using value = basic_value<type_config>;
// using table = typename basic_value<type_config>::table_type;
// using array = typename basic_value<type_config>::array_type;
template<typename TC>
bool operator==(const basic_value<TC>&, const basic_value<TC>&);
template<typename TC>
bool operator!=(const basic_value<TC>&, const basic_value<TC>&);
template<typename TC>
bool operator< (const basic_value<TC>&, const basic_value<TC>&);
template<typename TC>
bool operator<=(const basic_value<TC>&, const basic_value<TC>&);
template<typename TC>
bool operator> (const basic_value<TC>&, const basic_value<TC>&);
template<typename TC>
bool operator>=(const basic_value<TC>&, const basic_value<TC>&);
} //toml
```
## Member Types
The following member types are defined.
You can modify the member types using `TypeConfig`.
See also: [types.hpp]({{<ref "types.md">}})
| Name | Definition |
|:-----------------------|:-------------------------------------|
| `char_type` | `typename TypeConfig::char_type` |
| `key_type` | `typename TypeConfig::string_type` |
| `value_type` | `basic_value<TypeConfig>` |
| `boolean_type` | `typename TypeConfig::boolean_type` |
| `integer_type` | `typename TypeConfig::integer_type` |
| `floating_type` | `typename TypeConfig::floating_type` |
| `string_type` | `typename TypeConfig::string_type` |
| `local_time_type` | `toml::local_time` |
| `local_date_type` | `toml::local_date` |
| `local_datetime_type` | `toml::local_datetime` |
| `offset_datetime_type` | `toml::offset_datetime` |
| `array_type` | `typename TypeConfig::template array_type<value_type>`|
| `table_type` | `typename TypeConfig::template table_type<key_type, value_type>`|
| `comment_type` | `typename TypeConfig::comment_type` |
## Member Functions
### Default Constructor
```cpp
basic_value() noexcept
```
Constructs an empty `toml::value`.
The constructed `toml::value` will be empty.
### Copy and Move Constructors
```cpp
basic_value(const basic_value& v)
basic_value(basic_value&& v)
```
Copies or moves all information including values, format information, comments, and file regions.
### Copy and Move Constructors with Comments
```cpp
basic_value(basic_value v, std::vector<std::string> com)
```
Copies or moves the object while overwriting comments.
### Conversion Constructors
```cpp
template<typename TI>
basic_value(basic_value<TI> other)
template<typename TI>
basic_value(basic_value<TI> other, std::vector<std::string> com)
```
Copies or moves from a `basic_value` with a different `type_config`.
### Constructor (boolean)
```cpp
basic_value(boolean_type x)
basic_value(boolean_type x, boolean_format_info fmt)
basic_value(boolean_type x, std::vector<std::string> com)
basic_value(boolean_type x, boolean_format_info fmt, std::vector<std::string> com)
```
Constructs an object with a `bool`, its format information, and comments.
### Constructor (integer)
```cpp
template<typename T, /* std::is_integral<T> is true */>
basic_value(T x)
template<typename T, /* std::is_integral<T> is true */>
basic_value(T x, integer_format_info fmt)
template<typename T, /* std::is_integral<T> is true */>
basic_value(T x, std::vector<std::string> com)
template<typename T, /* std::is_integral<T> is true */>
basic_value(T x, integer_format_info fmt, std::vector<std::string> com)
```
Constructs an object with an `integer`, its format information, and comments.
### Constructor (floating)
```cpp
template<typename T, /* std::is_floating_point<T> is true */>
basic_value(T x)
template<typename T, /* std::is_floating_point<T> is true */>
basic_value(T x, floating_format_info fmt)
template<typename T, /* std::is_floating_point<T> is true */>
basic_value(T x, std::vector<std::string> com)
template<typename T, /* std::is_floating_point<T> is true */>
basic_value(T x, floating_format_info fmt, std::vector<std::string> com)
```
Constructs an object with a `floating` point number, its format information, and comments.
### Constructor (string)
```cpp
basic_value(string_type x)
basic_value(string_type x, string_format_info fmt)
basic_value(string_type x, std::vector<std::string> com)
basic_value(string_type x, string_format_info fmt, std::vector<std::string> com)
basic_value(const string_type::value_type* x)
basic_value(const string_type::value_type* x, string_format_info fmt)
basic_value(const string_type::value_type* x, std::vector<std::string> com)
basic_value(const string_type::value_type* x, string_format_info fmt, std::vector<std::string> com)
// C++17以降
basic_value(string_view_type x)
basic_value(string_view_type x, string_format_info fmt)
basic_value(string_view_type x, std::vector<std::string> com)
basic_value(string_view_type x, string_format_info fmt, std::vector<std::string> com)
```
Constructs an object with a `string`, its format information, and comments.
`string_view_type` shares the same `value_type` and `traits_type` as `string_type`.
### Constructor (local_date)
```cpp
basic_value(local_date_type x)
basic_value(local_date_type x, local_date_format_info fmt)
basic_value(local_date_type x, std::vector<std::string> com)
basic_value(local_date_type x, local_date_format_info fmt, std::vector<std::string> com)
```
Constructs an object with a `local_date_type`, its format information, and comments.
### Constructor (local_time)
```cpp
basic_value(local_time_type x)
basic_value(local_time_type x, local_time_format_info fmt)
basic_value(local_time_type x, std::vector<std::string> com)
basic_value(local_time_type x, local_time_format_info fmt, std::vector<std::string> com)
template<typename Rep, typename Period>
basic_value(const std::chrono::duration<Rep, Period>& x)
template<typename Rep, typename Period>
basic_value(const std::chrono::duration<Rep, Period>& x, local_time_format_info fmt)
template<typename Rep, typename Period>
basic_value(const std::chrono::duration<Rep, Period>& x, std::vector<std::string> com)
template<typename Rep, typename Period>
basic_value(const std::chrono::duration<Rep, Period>& x, local_time_format_info fmt, std::vector<std::string> com)
```
Constructs an object with a `local_time_type`, its format information, and comments.
For `std::chrono::duration`, constructs as a time span from `00:00:00`.
### Constructor (local_datetime)
```cpp
basic_value(local_datetime_type x)
basic_value(local_datetime_type x, local_date_format_info fmt)
basic_value(local_datetime_type x, std::vector<std::string> com)
basic_value(local_datetime_type x, local_date_format_info fmt, std::vector<std::string> com)
```
Constructs an object with a `local_datetime_type`, its format information, and comments.
### Constructor (offset_datetime)
```cpp
basic_value(offset_datetime_type x)
basic_value(offset_datetime_type x, offset_date_format_info fmt)
basic_value(offset_datetime_type x, std::vector<std::string> com)
basic_value(offset_datetime_type x, offset_date_format_info fmt, std::vector<std::string> com)
basic_value(std::chrono::system_clock::time_point x)
basic_value(std::chrono::system_clock::time_point x, offset_date_format_info fmt)
basic_value(std::chrono::system_clock::time_point x, std::vector<std::string> com)
basic_value(std::chrono::system_clock::time_point x, offset_date_format_info fmt, std::vector<std::string> com)
```
Constructs an object with an `offset_datetime_type`, its format information, and comments.
For `std::chrono::system_clock::time_point`, constructs for the pointed time.
### Constructor (array)
```cpp
basic_value(array_type x)
basic_value(array_type x, integer_format_info fmt)
basic_value(array_type x, std::vector<std::string> com)
basic_value(array_type x, integer_format_info fmt, std::vector<std::string> com)
template<typename T, /* T is array-like */>
basic_value(T x)
template<typename T, /* T is array-like */>
basic_value(T x, array_format_info fmt)
template<typename T, /* T is array-like */>
basic_value(T x, std::vector<std::string> com)
template<typename T, /* T is array-like */>
basic_value(T x, array_format_info fmt, std::vector<std::string> com)
```
Constructs an object with an `array`, its format information, and comments.
`array-like` types must meet the following criteria:
- Has `T::iterator`.
- Has `T::value_type`.
- Does **not** have `T::key_type`.
- Does **not** have `T::mapped_type`.
- Is **not** `std::string`.
- Is **not** `std::string_view` (since C++17).
### Constructor (table)
```cpp
basic_value(table_type x)
basic_value(table_type x, integer_format_info fmt)
basic_value(table_type x, std::vector<std::string> com)
basic_value(table_type x, integer_format_info fmt, std::vector<std::string> com)
template<typename T, /* T is table-like */>
basic_value(T x)
template<typename T, /* T is table-like */>
basic_value(T x, table_format_info fmt)
template<typename T, /* T is table-like */>
basic_value(T x, std::vector<std::string> com)
template<typename T, /* T is table-like */>
basic_value(T x, table_format_info fmt, std::vector<std::string> com)
```
Constructs an object with a `table`, its format information, and comments.
`table-like` types must meet the following criteria:
- Has `T::iterator`.
- Has `T::value_type`.
- Has `T::key_type`.
- Has `T::mapped_type`.
### Constructor (user-defined)
```cpp
template<typename T /* toml::into<T> is defined */>
basic_value(const T& ud);
template<typename T /* toml::into<T> is defined */>
basic_value(const T& ud, std::vector<std::string> com);
template<typename T /* toml::into<T> is not defined, but T{}.into_toml() exists */>
basic_value(const T& ud);
template<typename T /* toml::into<T> is not defined, but T{}.into_toml() exists */>
basic_value(const T& ud, std::vector<std::string> com);
```
If `toml::into<T>` is defined, constructs from the result of `toml::into<T>(ud)`.
If `toml::into<T>` is not defined but `T` has a `into_toml()` member function, constructs from the result of `ud.into_toml()`.
-----
### `operator=(basic_value)`
```cpp
basic_value& operator=(const basic_value& v)
basic_value& operator=(basic_value&& v)
template<typename TI>
basic_value& operator=(basic_value<TI> other)
```
Assigns the right-hand side `basic_value` to the current object.
### `operator=(T)`
```cpp
template<typename T>
basic_value& operator=(T x)
```
Assigns a value corresponding to `T`.
The contents pointed to by `source_location` are discarded.
If the object already holds a value of the same type, the original format information is retained.
-----
### `is<T>()`
```cpp
bool is<T>() const noexcept
```
#### Requirements
`T` must be an exact TOML type, meaning it corresponds to one of the `toml::value::xxx_type`.
#### Return Value
Returns `true` if the stored type matches `T`, otherwise returns `false`.
-----
### `is(toml::value_t)`
```cpp
bool is(toml::value_t t) const noexcept
```
#### Return Value
Returns `true` if the tag of the stored type matches `t`, otherwise returns `false`.
-----
### `is_xxx()`
```cpp
bool is_boolean() const noexcept;
bool is_integer() const noexcept;
bool is_floating() const noexcept;
bool is_string() const noexcept;
bool is_offset_datetime() const noexcept;
bool is_local_datetime() const noexcept;
bool is_local_date() const noexcept;
bool is_local_time() const noexcept;
bool is_array() const noexcept;
bool is_table() const noexcept;
```
#### Return Value
Returns `true` if the stored type matches the corresponding type, otherwise returns `false`.
------
### `is_empty()`
```cpp
bool is_empty() const noexcept;
```
#### Return Value
Returns `true` if the object is default constructed and no value is assigned, otherwise returns `false`.
### `is_array_of_tables()`
```cpp
bool is_array_of_tables() const noexcept;
```
#### Return Value
Returns `true` if the stored type is an array that is not empty and all elements are tables, otherwise returns `false`.
-----
### `type()`
```cpp
toml::value_t type() const noexcept
```
#### Return Value
Returns the tag corresponding to the stored type.
-----
### `as_xxx()`
```cpp
boolean_type const& as_boolean () const;
integer_type const& as_integer () const;
floating_type const& as_floating () const;
string_type const& as_string () const;
offset_datetime_type const& as_offset_datetime() const;
local_datetime_type const& as_local_datetime () const;
local_date_type const& as_local_date () const;
local_time_type const& as_local_time () const;
array_type const& as_array () const;
table_type const& as_table () const;
boolean_type & as_boolean ();
integer_type & as_integer ();
floating_type & as_floating ();
string_type & as_string ();
offset_datetime_type& as_offset_datetime();
local_datetime_type & as_local_datetime ();
local_date_type & as_local_date ();
local_time_type & as_local_time ();
array_type & as_array ();
table_type & as_table ();
```
#### Return Value
Returns a reference to the value of the specified type.
#### Exception
Throws `toml::type_error` if the stored value's type does not match the specified type.
-----
### `as_xxx(std::nothrow)`
Invoke with a `std::nothrow` object.
```cpp
boolean_type const& as_boolean (const std::nothrow_t&) const noexcept;
integer_type const& as_integer (const std::nothrow_t&) const noexcept;
floating_type const& as_floating (const std::nothrow_t&) const noexcept;
string_type const& as_string (const std::nothrow_t&) const noexcept;
offset_datetime_type const& as_offset_datetime(const std::nothrow_t&) const noexcept;
local_datetime_type const& as_local_datetime (const std::nothrow_t&) const noexcept;
local_date_type const& as_local_date (const std::nothrow_t&) const noexcept;
local_time_type const& as_local_time (const std::nothrow_t&) const noexcept;
array_type const& as_array (const std::nothrow_t&) const noexcept;
table_type const& as_table (const std::nothrow_t&) const noexcept;
boolean_type & as_boolean (const std::nothrow_t&) noexcept;
integer_type & as_integer (const std::nothrow_t&) noexcept;
floating_type & as_floating (const std::nothrow_t&) noexcept;
string_type & as_string (const std::nothrow_t&) noexcept;
offset_datetime_type& as_offset_datetime(const std::nothrow_t&) noexcept;
local_datetime_type & as_local_datetime (const std::nothrow_t&) noexcept;
local_date_type & as_local_date (const std::nothrow_t&) noexcept;
local_time_type & as_local_time (const std::nothrow_t&) noexcept;
array_type & as_array (const std::nothrow_t&) noexcept;
table_type & as_table (const std::nothrow_t&) noexcept;
```
#### Return Value
Returns a reference to the value of the specified type.
#### Note
If the type of the stored value does not match the specified type, the behavior is undefined.
-----
### `as_xxx_fmt()`
Accesses format information.
```cpp
boolean_format_info & as_boolean_fmt ();
integer_format_info & as_integer_fmt ();
floating_format_info & as_floating_fmt ();
string_format_info & as_string_fmt ();
offset_datetime_format_info& as_offset_datetime_fmt();
local_datetime_format_info & as_local_datetime_fmt ();
local_date_format_info & as_local_date_fmt ();
local_time_format_info & as_local_time_fmt ();
array_format_info & as_array_fmt ();
table_format_info & as_table_fmt ();
boolean_format_info const& as_boolean_fmt () const;
integer_format_info const& as_integer_fmt () const;
floating_format_info const& as_floating_fmt () const;
string_format_info const& as_string_fmt () const;
offset_datetime_format_info const& as_offset_datetime_fmt() const;
local_datetime_format_info const& as_local_datetime_fmt () const;
local_date_format_info const& as_local_date_fmt () const;
local_time_format_info const& as_local_time_fmt () const;
array_format_info const& as_array_fmt () const;
table_format_info const& as_table_fmt () const;
```
#### Return Value
Returns a reference to the structure holding the format information for the specified type.
#### Exception
Throws `toml::type_error` if the stored value's type does not match the specified type.
-----
### `as_xxx_fmt(std::nothrow)`
Invoke with a `std::nothrow` object.
```cpp
boolean_format_info & as_boolean_fmt (const std::nothrow_t&) noexcept;
integer_format_info & as_integer_fmt (const std::nothrow_t&) noexcept;
floating_format_info & as_floating_fmt (const std::nothrow_t&) noexcept;
string_format_info & as_string_fmt (const std::nothrow_t&) noexcept;
offset_datetime_format_info& as_offset_datetime_fmt(const std::nothrow_t&) noexcept;
local_datetime_format_info & as_local_datetime_fmt (const std::nothrow_t&) noexcept;
local_date_format_info & as_local_date_fmt (const std::nothrow_t&) noexcept;
local_time_format_info & as_local_time_fmt (const std::nothrow_t&) noexcept;
array_format_info & as_array_fmt (const std::nothrow_t&) noexcept;
table_format_info & as_table_fmt (const std::nothrow_t&) noexcept;
boolean_format_info const& as_boolean_fmt (const std::nothrow_t&) const noexcept;
integer_format_info const& as_integer_fmt (const std::nothrow_t&) const noexcept;
floating_format_info const& as_floating_fmt (const std::nothrow_t&) const noexcept;
string_format_info const& as_string_fmt (const std::nothrow_t&) const noexcept;
offset_datetime_format_info const& as_offset_datetime_fmt(const std::nothrow_t&) const noexcept;
local_datetime_format_info const& as_local_datetime_fmt (const std::nothrow_t&) const noexcept;
local_date_format_info const& as_local_date_fmt (const std::nothrow_t&) const noexcept;
local_time_format_info const& as_local_time_fmt (const std::nothrow_t&) const noexcept;
array_format_info const& as_array_fmt (const std::nothrow_t&) const noexcept;
table_format_info const& as_table_fmt (const std::nothrow_t&) const noexcept;
```
#### Return Value
Returns a reference to the structure holding the format information for the specified type.
#### Note
If the type of the stored value does not match the specified type, the behavior is undefined.
-----
### `at(key)`
```cpp
value_type& at(const key_type& key);
value_type const& at(const key_type& key) const;
```
#### Return Value
Casts the current `value` to a `table` and returns the element specified by `key`.
#### Exception
Throws `toml::type_error` if the stored value is not a `table`.
Throws `std::out_of_range` if the `table` does not contain the specified element.
-----
#### `operator[](key)`
```cpp
value_type& operator[](const key_type& k);
```
##### Return Value
Casts the current `value` to a `table` and returns a reference to the element specified by `key`.
If the element specified by `key` does not exist, it is default-constructed.
##### Exception
Throws `toml::type_error` if the stored value is not a `table`.
-----
### `count(key)`
```cpp
std::size_t count(const key_type& key) const;
```
#### Return Value
Casts the current `value` to a `table` and returns `1` if the element corresponding to `key` is present, otherwise returns `0`.
#### Exception
Throws `toml::type_error` if the stored value is not a `table`.
-----
### `contains(key)`
```cpp
bool contains(const key_type& key) const;
```
#### Return Value
Casts the current `value` to a `table` and returns `true` if the element corresponding to `key` is present, otherwise returns `false`.
#### Exception
Throws `toml::type_error` if the stored value is not a `table`.
-----
### `at(idx)`
```cpp
value_type& at(const std::size_t idx);
value_type const& at(const std::size_t idx) const;
```
#### Return Value
Casts the current `value` to an `array` and returns the element specified by `idx`.
#### Exception
Throws `toml::type_error` if the stored value is not an `array`.
Throws `std::out_of_range` if the specified element does not exist in the `array`.
-----
### `operator[](idx)`
```cpp
value_type& operator[](const std::size_t idx) noexcept;
value_type const& operator[](const std::size_t idx) const noexcept;
```
#### Return Value
Casts the current `value` to an `array` and returns a reference to the element specified by `idx`.
#### Note
Performs no checks. Behavior is undefined if the stored value is not an `array` or if the specified element does not exist.
-----
### `push_back(value)`
```cpp
void push_back(const value_type& x);
void push_back(value_type&& x);
```
Casts the current `value` to an `array` and performs `push_back` on the `array`.
#### Return Value
None.
#### Exception
Throws `toml::type_error` if the stored value is not an `array`.
-----
### `emplace_back(args...)`
```cpp
template<typename ... Ts>
value_type& emplace_back(Ts&& ... args)
```
Casts the current `value` to an `array` and performs `emplace_back` on the `array`.
#### Return Value
A reference to the constructed value.
#### Exception
Throws `toml::type_error` if the stored value is not an `array`.
-----
### `size()`
```cpp
std::size_t size() const;
```
#### Return Value
Casts the current `value` to an `array`, `string`, or `table` and returns the number of elements. For a `string`, it returns the number of characters.
#### Exception
Throws `toml::type_error` if the stored value is not an `array`, `string`, or `table`.
-----
### `location()`
```cpp
source_location location() const;
```
#### Return Value
Returns a `source_location` object representing the position within the TOML document where the `value` is defined.
If the `value` was not constructed by parsing a TOML document, returns a `source_location` that points to nowhere.
-----
### `comments()`
```cpp
comment_type const& comments() const noexcept;
comment_type& comments() noexcept;
```
#### Return Value
Returns a reference to the comment container.
## Non-Member Functions
### `operator==`
```cpp
template<typename TC>
bool operator==(const basic_value<TC>&, const basic_value<TC>&);
```
Two `basic_value<T>` instances are considered equal if they satisfy the following conditions:
- The contained type is the same.
- The contained values are identical.
- The comments are identical at the byte level.
### `operator!=`
```cpp
template<typename TC>
bool operator!=(const basic_value<TC>& lhs, const basic_value<TC>& rhs)
{
return !(lhs == rhs);
}
```
### `operator<`
Defined only if `array_type` and `table_type` have `operator<`.
```cpp
template<typename TC>
bool operator<(const basic_value<TC>&, const basic_value<TC>&);
```
Comparison order:
1. TOML type
2. If TOML types are the same, their values
3. If both the TOML types and values are the same, the comments
TOML types have the following order (from smallest to largest):
1. `toml::value_t::empty`
2. `toml::value_t::boolean`
3. `toml::value_t::integer`
4. `toml::value_t::floating`
5. `toml::value_t::string`
6. `toml::value_t::offset_datetime`
7. `toml::value_t::local_datetime`
8. `toml::value_t::local_date`
9. `toml::value_t::local_time`
10. `toml::value_t::array`
11. `toml::value_t::table`
### `operator<=`
Defined only if `array_type` and `table_type` have `operator<`.
```cpp
template<typename TC>
bool operator<=(const basic_value<TC>& lhs, const basic_value<TC>& rhs)
{
return (lhs < rhs) || (lhs == rhs);
}
```
### `operator>`
Defined only if `array_type` and `table_type` have `operator<`.
```cpp
template<typename TC>
bool operator>(const basic_value<TC>& lhs, const basic_value<TC>& rhs)
{
return !(lhs <= rhs);
}
```
### `operator>=`
Defined only if `array_type` and `table_type` have `operator<`.
```cpp
template<typename TC>
bool operator>=(const basic_value<TC>& lhs, const basic_value<TC>& rhs)
{
return !(lhs < rhs);
}
```
# `toml::type_error`
Exception thrown in case of a type error.
Contains the location information of the value that caused the type error.
```cpp
struct type_error final : public ::toml::exception
{
public:
type_error(std::string what_arg, source_location loc);
~type_error() noexcept override = default;
const char* what() const noexcept override;
source_location const& location() const noexcept;
};
```
# `toml::make_error_info`
```cpp
template<typename TC, typename ... Ts>
error_info make_error_info(
std::string title, const basic_value<TC>& v, std::string msg, Ts&& ... tail);
```
Calls `location()` on a `basic_value`, passes the resulting `source_location` to
[`make_error_info`]({{<ref "docs/reference/error_info#make_error_info">}})
to create an `error_info`.
Refer to [`error_info`]({{<ref "docs/reference/error_info">}}) for more details.
# `toml::format_error`
```cpp
template<typename TC, typename ... Ts>
std::string format_error(std::string title,
const basic_value<TC>& v, std::string msg, Ts&& ... tail);
```
Calls `location()` on a `basic_value`, passes the resulting `source_location` to
[`format_error`]({{<ref "docs/reference/error_info#format_error">}})
to create an `error_info`, then converts it to a string and returns it.
Refer to [`error_info`]({{<ref "docs/reference/error_info">}}) for more details.
# Related
- [comments.hpp]({{<ref "comments.md">}})
- [source_location.hpp]({{<ref "source_location.md">}})
- [types.hpp]({{<ref "types.md">}})
- [visit.hpp]({{<ref "visit.md">}})

51
docs/content.en/docs/reference/value_t.md Normal file
View File

@@ -0,0 +1,51 @@
+++
title = "value_t.hpp"
type = "docs"
+++
# value_t.hpp
# `value_t`
`value_t` is used to handle the type information of `toml::value`.
```cpp
namespace toml
{
enum class value_t : std::uint8_t
{
empty = 0,
boolean = 1,
integer = 2,
floating = 3,
string = 4,
offset_datetime = 5,
local_datetime = 6,
local_date = 7,
local_time = 8,
array = 9,
table = 10
};
std::ostream& operator<<(std::ostream& os, value_t t);
std::string to_string(value_t t);
} // toml
```
## Non-member Functions
### Stream Operator
```cpp
std::ostream& operator<<(std::ostream& os, value_t t);
```
Outputs the string representation of the `value_t` to the stream.
### `to_string`
```cpp
std::string to_string(value_t t);
```
Returns the string representation of the `value_t`.

37
docs/content.en/docs/reference/version.md Normal file
View File

@@ -0,0 +1,37 @@
+++
title = "version.hpp"
type = "docs"
+++
# version.hpp
In `version.hpp`, macros related to the version information of toml11 are defined.
## Macros
### `TOML11_VERSION_MAJOR`
The major version of toml11.
### `TOML11_VERSION_MINOR`
The minor version of toml11.
### `TOML11_VERSION_PATCH`
The patch version of toml11.
## Function
### `license_notice`
```cpp
namespace toml
{
const char* license_notice() noexcept;
}
```
Returns the license notice.
Provided for convenience when redistributing without source code.

69
docs/content.en/docs/reference/visit.md Normal file
View File

@@ -0,0 +1,69 @@
+++
title = "visit.hpp"
type = "docs"
+++
# visit.hpp
In `visit.hpp`, `toml::visit` is defined.
# `toml::visit`
## Functions
```cpp
namespace toml
{
template<typename Visitor, typename TC>
/* Return value when Visitor is called with a value of basic_value<TC> */
visit(Visitor&& visitor, const basic_value<TC>& v);
template<typename Visitor, typename TC>
/* Return value when Visitor is called with a value of basic_value<TC> */
visit(Visitor&& visitor, basic_value<TC>& v);
template<typename Visitor, typename TC>
/* Return value when Visitor is called with a value of basic_value<TC> */
visit(Visitor&& visitor, basic_value<TC>&& v);
}
```
`toml::visit` calls the overload of `Visitor` corresponding to the type held by `basic_value<TC>`, and returns the result.
#### Requirements
`Visitor` must be a function or function object callable with any type held by `basic_value<TC>`.
Additionally, the return value must be consistent across all overloads.
#### Example
```cpp
#include <toml.hpp>
#include <iostream>
struct type_name_of
{
std::string operator()(const toml::value::boolean_type &) const {return "boolean";}
std::string operator()(const toml::value::integer_type &) const {return "integer";}
std::string operator()(const toml::value::floating_type &) const {return "floating";}
std::string operator()(const toml::value::string_type &) const {return "string";}
std::string operator()(const toml::value::local_time_type &) const {return "local_time";}
std::string operator()(const toml::value::local_date_type &) const {return "local_date";}
std::string operator()(const toml::value::local_datetime_type &) const {return "local_datetime";}
std::string operator()(const toml::value::offset_datetime_type&) const {return "offset_datetime";}
std::string operator()(const toml::value::array_type &) const {return "array";}
std::string operator()(const toml::value::table_type &) const {return "table";}
};
int main()
{
toml::value v(3.14);
std::cout << toml::visit(type_name_of{}, v) << std::endl; // floating
return 0;
}
```
# Related
- [value.hpp]({{<ref "value.md">}})

25
docs/content.ja/_index.md Normal file
View File

@@ -0,0 +1,25 @@
+++
title = "Introduction"
type = "docs"
+++
# Introduction
English version is [here](../en/)
## [Installation]({{< relref "/installation" >}})
toml11のインストール方法について説明します。
## [Features]({{< relref "/features" >}})
toml11の機能と使い方を例に沿って説明します。
## [Reference]({{< relref "/reference" >}})
toml11が持つ関数・クラスの詳細を説明します。
## [ChangeLog]({{< relref "/changelog" >}})
v3系から、そしてリリースごとの変化を説明します。

313
docs/content.ja/docs/changelog/_index.md Normal file
View File

@@ -0,0 +1,313 @@
+++
title = "changelog"
type = "docs"
weight = 4
+++
# Change Log
# v3からの変化
## 破壊的変更
### `toml::basic_value`の`template`引数を変更
toml11 v3では、`toml::basic_value`はコメントコンテナ、テーブル型コンテナ、配列型コンテナをそれぞれ取っていました。
```cpp
template<typename Comment,
template<typename ...> class Table = std::unordered_map,
template<typename ...> class Array = std::vector>
class basic_value;
```
ですが、`integer_type`などを変更したいという場合にはこれでは対応できません。
toml11 v4では、`toml::basic_value`は単一の`TypeConfig`を受け取り、より多くの型を変更可能にします。
```cpp
template<typename TypeConfig>
class basic_value;
```
デフォルトでは`toml::value`が格納する型は変わりません。
型を変更する際は、
[`type_config`]({{< ref "/docs/reference/types.md">}})
を参照してください。
### `toml::basic_value`の`std::initializer_list`サポートを削除
toml11 v3では、 `toml::value` に `std::initializer_list` を取るオーバーロードが用意されていました。
これにより、 `toml::value` を配列やテーブルで初期化する際により直観的な書き方が可能でした。
```cpp
// toml11 v3
toml::value v{1,2,3,4,5};
toml::value v{ {"a", 42}, {"b", "foo"} };
```
しかし、これは同時に以下のような問題を引き起こしました。
一つ目は、1要素の配列と通常の値の区別がつかず、常に配列になってしまうことです。
```cpp
// toml11 v3
toml::value v{1}; // 1 ではなく [1,] になってしまう
```
統一初期化記法が普及した現在、これは非常に不便です。
二つ目は、値が全て文字列のテーブルと、ネストされた配列の区別がつかないことです。
```cpp
// toml11 v3
toml::value v{ {"a", "foo"}, {"b", "bar"} };
// {a = "foo", b = "bar"}
// [["a", "foo"], ["b", "bar"]]
// のどちらでもあり得る
```
これらの問題は言語仕様上解決が困難です。
toml11 v4では、混乱を避けるため、`std::initializer_list`サポートを削除しました。
`toml::value` を配列で初期化する際はexplicitに `toml::array` を、
テーブルで初期化する際はexplicitに `toml::table` を指定する必要があります。
```cpp
// toml11 v4
toml::value v(toml::array{1,2,3,4,5});
toml::value v(toml::table{ {"a", 42}, {"b", "foo"} });
toml::value v{toml::array{1}}; // [1,]
toml::value v{1} // 1
toml::value v{toml::table{{"a", "foo"}, {"b", "bar"}}};
toml::value v{toml::array{toml::array{"a", "foo"}, toml::array{"b", "bar"}}};
```
これにより `toml::value` をテーブルや配列で初期化する際に少し不便になりますが、
explicitに型情報を記述することにより予測不能な値になることは避けることができます。
### `toml::basic_value::is_uninitialized()` を `is_empty()` に変更
toml11 v3では、初期化されていない `basic_value` かどうかを判定する関数は
`is_uninitialized` でした。
しかし、toml11 v4では言語拡張で `null `をサポートするため、意図的に空にされた値が構築される可能性があります。
なので命名を変更し、 `is_empty` としました。
### `toml::string` を廃止、フォーマット情報を陽に格納
toml11 v3では、文字列が `basic` か `literal` かの情報を保持するため、
格納する文字列型に `toml::string` という `std::string` の薄いラッパーを使用していました。
```cpp
// toml11 v3
namespace toml
{
enum class string_t : std::uint8_t
{
basic = 0,
literal = 1,
};
struct string
{
string_t kind;
std::string str;
};
} // toml
```
toml11 v4では、数値型の基数や配列を複数行にするかどうかなどのより多くのフォーマット情報を持たせるため、
全ての型に `xxx_format` 型を用意し、値とペアで格納することにしました。
```cpp
// toml11 v4
enum class string_format : std::uint8_t
{
basic = 0,
literal = 1,
multiline_basic = 2,
multiline_literal = 3
};
struct string_format_info
{
string_format fmt = string_format::basic;
bool start_with_newline = false;
};
```
これにより、より細かいフォーマット情報を保持することができるようになり、
特に数値型や配列、テーブル型のフォーマット情報がパース後も維持できるようになりました。
### `toml::format`の引数を変更
toml11 v3では、 `toml::format` が数値型の精度や幅などの値を受け取っていました。
しかし、これでは細かなフォーマット指定ができず、予想したようなファイルにシリアライズできませんでした。
toml11 v4では、各 `toml::value` にそれぞれのフォーマット情報を格納したため、
より細かいフォーマット情報を `toml::value` 自体が持ち運べるようになりました。
これにより、 `toml::format` 自体はフォーマット指定を受け取らず、
フォーマット時に使用できる言語機能フラグを持つ `toml::spec` のみを取るようになりました。
### `toml::source_location`のメンバ関数を変更
toml11 v3では、 `toml::source_location` のメンバ型は一行分だけを意識したものでした。
toml11 v4では、 `toml::source_location` のメンバ型は複数行が前提になります。
### `toml::format_underline`を`toml::format_location`に変更
toml11 v3では、 `toml::source_location` を使用して位置情報を文字列化するとき、
`toml::format_underline` を使用していました。
しかしこれは名称としてわかりにくいため、 `toml::format_location` に変更しました。
### `format_error`の引数を変更
toml11 v3ではエラー情報を表すクラスがなかったため、`toml::format_error`の引数が複雑になっていました。
```cpp
template<typename C, template<typename ...> class T, template<typename ...> class A>
std::string format_error(const std::string& err_msg,
const basic_value<C, T, A>& v, const std::string& comment,
std::vector<std::string> hints = {},
const bool colorize = TOML11_ERROR_MESSAGE_COLORIZED);
template<typename C, template<typename ...> class T, template<typename ...> class A>
inline std::string format_error(const std::string& err_msg,
const toml::basic_value<C, T, A>& v1, const std::string& comment1,
const toml::basic_value<C, T, A>& v2, const std::string& comment2,
std::vector<std::string> hints = {},
const bool colorize = TOML11_ERROR_MESSAGE_COLORIZED);
template<typename C, template<typename ...> class T, template<typename ...> class A>
inline std::string format_error(const std::string& err_msg,
const toml::basic_value<C, T, A>& v1, const std::string& comment1,
const toml::basic_value<C, T, A>& v2, const std::string& comment2,
const toml::basic_value<C, T, A>& v3, const std::string& comment3,
std::vector<std::string> hints = {},
const bool colorize = TOML11_ERROR_MESSAGE_COLORIZED);
```
toml11 v4では、`class error_info`と`make_error_info`を導入し、`format_error`の引数を簡略化しました。
```cpp
std::string format_error(const error_info& err);
std::string format_error(const std::string& errkind, const error_info& err);
template<typename ... Ts>
std::string format_error(std::string title,
source_location loc, std::string msg, Ts&& ... tail);
template<typename TC, typename ... Ts>
std::string format_error(std::string title,
const basic_value<TC>& v, std::string msg, Ts&& ... tail);
```
### `toml::color` の制御を変更
toml11 v3では、出力に色を付けるかどうかに `toml::colorize` というマニピュレータを、
`toml::color::enable/disable` と並列で使用していました。
マニピュレータはストリームごとに色を付けるかどうかを決定できるものでしたが、
v4でストリームを使用する頻度が下がったことと、内部で使用する
`std::ios_base::xalloc` がC++11ではスレッドセーフではないことなどから、
`toml::color::enable/disable` のみを使用するようにし、 `toml::colorize` を削除しました。
## 破壊的でない変更
### `parse_str`の追加
toml11 v3では、文字列そのものを取る`toml::parse`関数はありませんでした。
なので文字列をパースする際には`std::istringstream`を使う必要がありました。
これは不便なので、`toml::parse_str`を追加し、文字列を直接パース出来るようにしました。
### `try_parse`の追加
toml11 v3では、パーサはエラーを発見した際には`toml::syntax_error`を送出していました。
しかし、例外を投げられない環境や、パフォーマンスの都合や記法の都合によって例外を投げたくない場合があります。
toml11 v4では `toml::result` を使用して、例外を投げずにパース失敗を伝える `toml::try_parse` を実装しました。
これも必ず例外を投げないというわけではなく、使用している標準ライブラリの内部でのエラー、
例えばメモリ不足によるアロケーション失敗での `std::bad_alloc` などは送出される可能性があります。
### バイト列のパースをサポート
ファイルなど以外の方法で得られたTOMLコンテンツをパース出来るようにするため、
`std::vector<unsigned char>` を受け取る `toml::parse`, `toml::try_parse` を追加しました。
### `toml::spec`の追加
toml11 v3では、TOML言語側の新機能は全て取り込み、またTOML言語の新バージョンに導入されることが決定した機能も
マクロ `TOML11_USE_UNRELEASED_TOML_FEATURES` によって制御していました。
これは、toml11 v3を開発していた時点では TOML言語は0.4.0から0.5.0で、1.0.0に到達していなかったためです。
最新のTOML言語仕様に全てのユーザーが詳しいわけではないため、
古い言語使用に基づいたエラーメッセージを表示すると、コミュニティ全体を混乱させてしまいます。
よって、v1.0.0に達するまでは、できる限り素早く新しい言語仕様を提供し、かつユーザーにもアップデートを促す必要がありました。
しかし、現在のTOML言語仕様はv1.0.0です。
そのため、TOML v1.1.0がリリースされた後でもv1.0.0を使用する、という選択肢に気を配る必要が生じました。
よって、より柔軟にTOML言語仕様を選択できるよう、`toml::spec`を導入して、TOML言語バージョンを実行時に変更できるようにしました。
また、`toml::spec`では言語機能ごとにフラグを設定し、特定の言語機能のみを試すこともできるようにしました。
これは、toml11 v4特有の言語拡張でも使用します。
### フォーマット情報の追加
toml11 v3では、文字列を除いてフォーマット情報が保存されず、シリアライズ時に考慮できるのは幅と精度だけでした。
しかし、これでは16進数整数がシリアライズ時に10進数になってしまったり、確実にinline tableにする方法がありませんでした。
toml11 v4では、全てのTOML型にフォーマット情報（`integer_format` etc）を追加し、
パース時とシリアライズ時に考慮するようにしました。
これによって、16進数整数や、インラインテーブル等のフォーマット情報をより細かく、値ごとに設定できるようになりました。
### デフォルトでコメントを維持するよう変更
toml11 v3では、デフォルトではコメントがパースされず、シリアライズもされませんでした。
これは、コメントが後期に導入された機能で、特別なハックによって読み込まれていたためです。
toml11 v4では、デフォルトでコメントをパースし、保存し、シリアライズするようになりました。
また、パーサの実装も大幅に変更され、コメントが他の要素と同様にパースされるようになりました。
### `single_include/toml.hpp` の追加
toml11は多機能なライブラリなので、開発効率のために機能ごとに異なるヘッダファイルを持っています。
ですが、これはインストールにある程度の手間が必要ということでもあります。
そこで、toml11 v4から全てのヘッダファイルを適切な順序で結合した `single_include/toml.hpp` ファイルを追加し、
単一のファイルで完結するライブラリをコピーするだけで導入できるようにしました。
### コンパイル済みライブラリを選択可能に
toml11は `template` を多用しているため、コンパイル時間が長くなります。
toml11 v4では、できるだけコンパイル可能な関数を増やし、それらを先にライブラリとしてコンパイルできるようにしました。
これにより、大規模な開発で使用する際にコンパイル時間を短くできると期待できます。
### リファレンス・ドキュメントの追加
これまでは、READMEにすべてのfeatureを記載しており、関数の詳細な定義を示すリファレンスや、また日本語での資料などがありませんでした。
toml11 v4では、リファレンスを追加したドキュメントを同梱し、また日本語・英語両方で同一の内容を記載します。
ただし、ライブラリ作者は日本語母語話者であるため、日本語の内容を第一とし、英語の内容がそれと異なっていた場合は日本語の内容が正しいものとします。

101
docs/content.ja/docs/features/_index.md Normal file
View File

@@ -0,0 +1,101 @@
+++
title = "features"
type = "docs"
weight = 2
bookCollapseSection = true
+++
# features
ここでは、toml11が提供する主な機能について、例を挙げながら説明します。
## [ファイル・文字列をパースする](parsing_files)
ファイルや文字列をパースする関数と、それが出力するエラーの扱い方について説明します。
以下の内容を含みます。
- ファイルをパースする
- 文字列をパースする
- バイト列をパースする
- 例外を投げずにファイルをパースする
- 例外を投げずに文字列をパースする
- 例外を投げずにバイト列をパースする
## [`toml::value`から値を取り出す](value)
`toml::value`が持つデータの型を調べ、取り出す方法、型変換を行う方法について説明します。
以下の内容を含みます。
- メンバ関数を使って値の型を調べる
- メンバ関数を使って値にアクセスする
- コメントにアクセスする
- インラインテーブル・ドットキーの取り扱い
- 日付情報の取り扱い
- `toml::get<T>`を使って変換する
- `toml::get_or`を使って失敗時の値を指定する
- `toml::find<T>`を使って検索と変換を行う
- `toml::find_or`を使って失敗時の値を指定する
- ユーザー定義型との変換を定義する
- `toml::visit`で関数を適用する
- `toml::value`を構築する
## [エラーメッセージを作る](error_message)
`toml::value`の値を使って、TOMLファイル中の位置情報つきのエラーメッセージを生成する方法について説明します。
以下の内容を含みます。
- `toml::value` の位置情報を取り出す
- エラーメッセージを構築する
- 出力に色を付ける
## [TOMLファイルを出力する](serialize)
`toml::value`の値をフォーマットする方法と、可能なフォーマット指定について説明します。
以下の内容を含みます。
- `toml::value`の値ごとにフォーマットを指定する
- `toml::value`をフォーマットして文字列化する
## [`toml::value`の型を変更する](configure_types)
`toml::value`が格納する型（`integer_type`や`table_type`をカスタマイズする方法について説明します。
以下の内容を含みます。
- `type_config`の定義
- `ordered_type_config`を使用する
- コメントを保存しないようにする
- `std::deque`などの異なるコンテナを使用する
- `boost::multiprecision`などの異なる数値型を使用する
## [TOMLリテラル](literal)
C++内にTOMLファイルを埋め込むための`_toml`リテラルについて説明します。
以下の内容を含みます。
- TOMLリテラルを使用する
## [TOML言語バージョン](toml_spec)
toml11がサポートするTOML言語のバージョン、主にTOML-v1.1.0で追加された言語機能を制御する方法について説明します。
以下の内容を含みます。
- TOML言語の1.1.0を使用する
- TOML言語の1.1.0の一部の機能のみ使用する
## [TOML言語拡張](extension)
toml11独自のTOML言語拡張について説明します。
以下の内容を含みます。
- `null` をサポートする
- 浮動小数点数の16進数フォーマットをサポートする
- 数値に単位を付けられるようにする

213
docs/content.ja/docs/features/configure_types.md Normal file
View File

@@ -0,0 +1,213 @@
+++
title = "configuring types"
type = "docs"
weight = 50
+++
# 型をカスタマイズする
`toml::value` は `integer_type` として `std::int64_t` を、
`table_type` として `std::unordered_map<key_type, value_type>` を使用します。
しかし、場合によっては `boost::multiprecision::int128_t` や、 `std::map` を使用したい場合もあります。
そのため、 `toml::value` は `template` 引数を取って格納する型を変えられるように実装されています。
`std::string` が実際には `std::basic_string<char, std::char_traits<char>, std::allocator<char>>` の
エイリアスであるように、 `toml::value` は実際には `toml::basic_value<toml::type_config>` のエイリアスです。
ここでは、 `toml::type_config` が持つ型と、異なる `config` 型を定義する方法を説明します。
## `type_config`
`type_config` は、以下のメンバ型と`static`メンバ関数を持つクラスです。
```cpp
namespace toml
{
struct type_config
{
using comment_type = preserve_comments;
using boolean_type = bool;
using integer_type = std::int64_t;
using floating_type = double;
using string_type = std::string;
template<typename T>
using array_type = std::vector<T>;
template<typename K, typename T>
using table_type = std::unordered_map<K, T>;
static result<integer_type, error_info>
parse_int(const std::string& str, const source_location src, const std::uint8_t base);
static result<floating_type, error_info>
parse_float(const std::string& str, const source_location src, const bool is_hex);
};
}
```
`toml::basic_value<TypeConfig>` は、格納する `boolean_type` を `TypeConfig::boolean_type`、
格納する `integer_type` を `TypeConfig::integer_type` 、のようにして定義しています。
また、 `array_type` は `TypeConfig::array_type<toml::basic_value<TypeConfig>>` 、
`table_type` は `TypeConfig::table_type<key_type, toml::basic_value<TypeConfig>>` と
定義されます。
これらのメンバ型とメンバ関数を定義したクラスを `toml::basic_value` に
渡すことで、その `toml::basic_value` が持つ型を変更できます。
`parse_int` と `parse_float` は、数値型を独自実装のものに変更した際にパース方法を提供するための関数です。
これらの関数には `0x` などのprefixと桁区切りの `_` が取り除かれた文字列、
例えば `123456` や `DEADBEEF` が渡されます。
`base` には `10`, `16`, `8`, `2` のいずれかが渡されます。
これらを使って `integer_type` と `floating_type` をパース出来るような関数を渡してください。
デフォルト実装として、`toml::read_int` と `toml::read_float` が提供されています。
```cpp
static result<integer_type, error_info>
parse_int(const std::string& str, const source_location src, const std::uint8_t base)
{
return toml::read_int<integer_type>(str, src, base);
}
static result<floating_type, error_info>
parse_float(const std::string& str, const source_location src, const bool is_hex)
{
return toml::read_float<floating_type>(str, src, is_hex);
}
```
`read_int` は `istream` を使用し、16進と8進の場合は `std::hex` と
`std::oct` を使用します。2進の場合は掛け算と足し算で実装されています。
これらをサポートしている型であれば、 `read_int` をそのまま使用できます。
`read_float` は `istream` を使用します。
16進浮動小数点数は `double` と `float` の場合しかサポートされておらず、
それ以外の型のときに呼ばれると常にパースエラーを返す実装になっているので、
もし浮動小数点数型をこれら以外の型にし、かつ `hexfloat` を使用する場合は、
それを実装してください。 `hexfloat` を使用しないのであれば、実装する必要はありません。
## テーブル内の値の順序を維持する
デフォルトの `toml::type_config` の他に、 `toml::ordered_type_config` が提供されています。
これは、 `table_type` を [ordered_map]({{< ref "docs/reference/ordered_map" >}}) に変更したものです。
これを使用したものを `toml::ordered_value` 、その配列型とテーブル型のエイリアスを
`toml::ordered_array` と `toml::ordered_table` と定義しています。
`toml::parse(...)` を `toml::parse<toml::ordered_type_config>(...)` として呼び出すことで、
`toml::ordered_value` を使用することができます。
## コメントを保存しない
`type_config` は `comment_type` でコメントを保存するコンテナを定義しています。
コメントに特に情報がなく、パースせずに捨ててしまっていい場合は、 `comment_type` に
`toml::discard_comments` を指定してください。
```cpp
struct wo_comment_config
{
using comment_type = toml::discard_comments; // XXX
using boolean_type = bool;
using integer_type = std::int64_t;
using floating_type = double;
using string_type = std::string;
template<typename T>
using array_type = std::vector<T>;
template<typename K, typename T>
using table_type = std::unordered_map<K, T>;
static result<integer_type, error_info>
parse_int(const std::string& str, const source_location src, const std::uint8_t base)
{
return toml::read_int<integer_type>(str, src, base);
}
static result<floating_type, error_info>
parse_float(const std::string& str, const source_location src, const bool is_hex)
{
return toml::read_float<floating_type>(str, src, is_hex);
}
};
```
## 配列に`std::vector`以外のコンテナを使用する
TOML配列の実装に`vector`以外のコンテナ（例：`std::deque`）を使用するには、
`array_type` を以下のように変更してください。
また、テーブル型のコンテナに `unordered_map` 以外のコンテナ（例：`std::map`）を使用するには、
`table_type` を以下のように変更してください。
```cpp
struct deque_map_config
{
using comment_type = toml::preserve_comments;
using boolean_type = bool;
using integer_type = std::int64_t;
using floating_type = double;
using string_type = std::string;
template<typename T>
using array_type = std::deque<T>; // XXX
template<typename K, typename T>
using table_type = std::map<K, T>; // XXX
static result<integer_type, error_info>
parse_int(const std::string& str, const source_location src, const std::uint8_t base)
{
return toml::read_int<integer_type>(str, src, base);
}
static result<floating_type, error_info>
parse_float(const std::string& str, const source_location src, const bool is_hex)
{
return toml::read_float<floating_type>(str, src, is_hex);
}
};
```
## 数値型に `boost::multiprecision` を使用する
`boost::multiprecision::cpp_int` と `boost::multiprecision::cpp_bin_float_oct`
を使用することで、より幅の広い整数型とより精度の良い浮動小数点数型を使用することができます。
これらの型はストリーム演算子を実装しているため、デフォルト実装の `read_int` と
`read_float` をそのまま使用できます。
```cpp
struct large_num_config
{
using comment_type = toml::preserve_comments;
using boolean_type = bool;
using integer_type = boost::multiprecision::cpp_int;
using floating_type = boost::multiprecision::cpp_bin_float_oct;
using string_type = std::string;
template<typename T>
using array_type = std::vector<T>;
template<typename K, typename T>
using table_type = std::unordered_map<K, T>;
static toml::result<integer_type, toml::error_info>
parse_int(const std::string& str, const toml::source_location src, const std::uint8_t base)
{
return toml::read_int<integer_type>(str, src, base);
}
static toml::result<floating_type, toml::error_info>
parse_float(const std::string& str, const toml::source_location src, const bool is_hex)
{
return toml::read_float<floating_type>(str, src, is_hex);
}
};
```

237
docs/content.ja/docs/features/error_message.md Normal file
View File

@@ -0,0 +1,237 @@
+++
title = "error message"
type = "docs"
weight = 30
+++
# エラーメッセージを出力する
toml11は `toml::parse` や `toml::get<T>/find<T>`, `as_integer()` などから
ファイル内の位置情報を含んだエラーメッセージを出力します。
例えば、パース時に整数の文法エラーを発見した場合、
```
[error] bad integer: `_` must be surrounded by digits
--> internal string at line 64 in file main.cpp
|
1 | a = 123__456
| ^-- invalid underscore
Hint: valid : -42, 1_000, 1_2_3_4_5, 0xC0FFEE, 0b0010, 0o755
Hint: invalid: _42, 1__000, 0123
```
あるいは実際に格納されている型と異なる型を要求した場合
```
[error] toml::value::as_string(): bad_cast to string
--> input.toml
|
1 | a = 123_456
| ^^^^^^^-- the actual type is integer
```
toml11は `toml::value` からこのようなエラーメッセージを作成する方法を提供します。
この機能を利用することで、TOMLの文法エラーだけでなく、
例えば正の値でなければならないところに負数が現れた場合などの
アプリケーション固有のエラーメッセージを、TOMLファイル内の位置を指摘しながら
ユーザーに伝えられるということです。
## `toml::value` の位置情報からエラーメッセージを作成する
`toml::value` はそれがパースされた位置の情報を持っています。
その情報は `toml::source_location` にまとめられ、`toml::value::location()` で取得できます。
```cpp
const toml::value& a = input.at("a");
const toml::source_location src = a.location();
```
ファイルを `toml::parse` でパースした場合、そのTOMLファイル名と行数が保存されています。
`toml::parse_str` でパースした場合TOMLファイル名はありませんが、代わりに
`toml::parse_str` を呼び出したC++ソースコードのファイル名と行数がTOMLファイル名として保存されています。
このページの最初の例は `toml::parse_str` から出力された例でした。
ファイル名の部分に注目してください。
詳細は [reference]({{<ref "/docs/reference/source_location">}}) を参照してください。
`toml::source_location` または `toml::value` とそれに付随するエラーメッセージを
`toml::make_error_info` に渡すことで、エラー情報を構築できます。
これを`toml::format_error` に渡すと、エラーメッセージが `std::string` にフォーマットされます。
```cpp
const toml::value& a = input.at("a");
if(a.as_integer() < 0)
{
const toml::error_info err = toml::make_error_info(
"positive integer is required", // エラーのタイトル
a, "but got negative value" // 値の横に書くメッセージ
);
std::cerr << toml::format_error(err) << std::endl;
}
```
これは以下のようになります。
```
[error] positive integer is required
--> input.toml
|
1 | a = -123456
| ^^^^^^^-- but got negative value
```
最後に補足をつけ足すこともできます。これはインデントされません。
```cpp
const toml::value& a = input.at("a");
if(a.as_integer() < 0)
{
const toml::error_info err = toml::make_error_info(
"positive integer is required", // エラーのタイトル
a, "but got negative value", // 値の横に書くメッセージ
"Hint: `a` means length of the data" // 補足
);
std::cerr << toml::format_error(err) << std::endl;
}
```
```
[error] positive integer is required
--> input.toml
|
1 | a = -123456
| ^^^^^^^-- but got negative value
Hint: `a` means length of the data
```
{{<hint info>}}
`toml::value` からファイル内の行を出力できるのは、
パースしたファイルが文字列としてメモリの中に残されているからです。
パースした文字列はその全体が `std::shared_ptr` で `toml::value` に共有されています。
コピーしてもファイル文字列全体がコピーされることはありません。
また、そのファイルをパースして構築された `toml::value` が全てデストラクトされた時点で、
ファイル情報もメモリ上から解放されます。
ですので、アプリケーションで使用する際には、 `toml::value` を直接保存するのではなく
読み込み中に必要な値を全て取り出して、変換した値を保存した方がよいでしょう。
{{</hint>}}
## 文字列に色を付ける
エラーメッセージにはANSIエスケープコードを使って色を付けることができます。
`TOML11_COLORIZE_ERROR_MESSAGE` をコンパイル時に定義していれば、
toml11の出力するエラーメッセージはデフォルトで色が付くようになります。
そうでない場合は、 `toml::color::enable()` を呼び出すことにより、それ以降で出力される
エラーメッセージには色が付くようになります。
逆に出力先がコンソールではないなどの理由で色をつけたくない場合は、
`toml::color::disable()` を呼び出してください。
その時点で色が付くようになっているかどうかは、
`toml::color::should_color()` の返り値で判定できます。
詳細は [reference]({{<ref "docs/reference/color">}}) を参照してください。
また、エラーのタイトルやエラーメッセージ、補足にはデフォルトで色が付きませんが、
`toml::color` にあるマニピュレータを使って色を付けることも可能です。
```cpp
std::ostringstream oss;
oss << toml::color::red << "but got negative value";
const toml::error_info err = toml::make_error_info(
"positive integer is required", // Error title
a, oss.str(), // Message next to the value
"Hint: `a` means length of the data" // Supplementary message
);
```
こちらも、詳細は [reference]({{<ref "docs/reference/color">}}) を参照してください。
## エラーメッセージのprefixを`[error]`から変更する
エラーには種類があり、デフォルトの `[error]` ではよくない場合もあるでしょう。
`toml::format_error` では、 `toml::error_info` の前に `std::string` を取って、それを
`[error]` の代わりに出力することができます。
例えば、
```cpp
const toml::value& a = input.at("a");
if(a.as_integer() < 0)
{
const toml::error_info err = toml::make_error_info(
"positive integer is required", // エラーのタイトル
a, "but got negative value" // 値の横に書くメッセージ
);
std::ostringstream prefix;
prefix << toml::color::bold << toml::color::yellow << "[warn]";
std::cerr << toml::format_error(prefix.str(), err) << std::endl;
return 0;
}
else
{
return a.as_integer()
}
```
このようにすると、 `[warn]` から始まる警告を出力することができます。
他にも、`toml::format_error` に直接 `error_info` の構成要素を渡すことで、
`[error]` なしのエラーメッセージを作成できます。
```cpp
const toml::value& a = input.at("a");
if(a.as_integer() < 0)
{
std::cerr << toml::format_error(
"[warn] positive integer is required", // エラーのタイトル
a, "but got negative value" // 値の横に書くメッセージ
) << std::endl;
return 0;
}
else
{
return a.as_integer()
}
```
## 複数の `toml::value` を指すエラーメッセージを作成する
アプリケーションの設定では、先に読み込んだ値によって後に読み込んだ値が取れる範囲が変わることがあるでしょう。
そのような場合には、エラーの原因となる別の値を同時に出力したいはずです。
`toml::format_error` と `toml::make_error_info` は、 `toml::value` とそれに対応するエラーメッセージ `std::string` のペアを任意個取ることができます。
```cpp
std::cerr << toml::format_error(
"[error] invalid range",
a, "minimum value is defined here",
b, "maximum value is defined here",
c, "and it exceeds the range"
) << std::endl;
```
こちらも末尾に補足を追加することができます。
```cpp
std::cerr << toml::format_error(
"[error] invalid range",
a, "minimum value is defined here",
b, "maximum value is defined here",
c, "and it exceeds the range",
"Hint: all the value must be in the range, [a, b)"
) << std::endl;
```
`toml::value` または `toml::source_location` を渡した場合、必ずそれに関する
エラーメッセージが続く必要があります。
そうしない場合、非常にわかりにくいコンパイルエラーになります。

136
docs/content.ja/docs/features/extension.md Normal file
View File

@@ -0,0 +1,136 @@
+++
title = "extension"
type = "docs"
weight = 80
+++
# TOML言語拡張
TOML言語は現在 v1.0.0 が最新版ですが、その後もいくつかの新機能が議論の末マージされ、
v1.1.0に向けて議論が続いています。
そこで議論された機能の中には、有用なケースが少ないと考えられたものや、
提案された際の方向性では導入が難しいもの、導入がされなかったものも多くあります。
toml11では、そのような機能のなかからいくつかを選んで、実験的に実装を行っています。
これらはtoml11ではサポートされていますが、他のパーサではサポートされておらず、また
サポートされる予定もないことに注意してください。
また、これらの機能はデフォルトで使用されない設定になっており、
使用するためには機能フラグをそれぞれ `true` にしなければなりません。
非標準の機能なので、あえて明示的に書かなければ使えないように設計しています。
いくつかの機能は今後TOML言語自体に新機能としてマージされる可能性があります。
もし以下の拡張機能を完全に置き換えられる機能が導入された場合、拡張機能は
本来の機能の実装後にマイナーバージョンアップで削除される可能性があります。
## `null`
TOMLファイル内で値として`null`を使えるようになります。
```
a = null
b = [ 1, 2, 3, null, 5]
```
これを使用するには、 `toml::spec` の `ext_null_value` を `true` にします。
パースすると、デフォルト構築した場合と同様の `toml::value_t::empty` となります。
ただし、ファイル内の位置情報は設定されます。
`null` は値の文脈でのみパースされるので、キーに `null` を使用した際はこれまで通り
`"null"` という文字列のキーとして解釈されます。
```cpp
#include <toml.hpp>
int main()
{
toml::spec spec;
spec.ext_null_value = true;
const auto v = toml::parse_str("a = null", spec);
assert(v.at("a").is_empty());
assert(v.at("a").is(toml::value_t::empty));
return 0;
}
```
## 浮動小数点数の16進数フォーマット
TOMLファイル内で浮動小数点数に16進数フォーマットを使用できるようになります。
```
a = 0x1.91eb851eb851fp+1 # 3.14
```
これを使用するには、 `toml::spec` の `ext_hex_float` を `true` にします。
フォーマットは `printf` で `%a/%A` を指定した場合に準拠します。
```cpp
#include <toml.hpp>
int main()
{
toml::spec spec;
spec.ext_hex_float = true;
const auto v = toml::parse_str("a = 0x1.91eb851eb851fp+1", spec);
assert(v.at("a").is_floating());
assert(v.at("a").as_floating() == 3.14);
return 0;
}
```
## 整数・浮動小数点数のsuffix
TOMLファイル内で数値の後ろにsuffixをつけられるようになります。
10進数表記の整数と浮動小数点数で使用できます。
単位を表示するときなどに便利です。
```
a = 86_400_sec
b = 3.1416_rad
c = 10_μm
```
ですが、これらはあくまで単なる `suffix` であり、単位換算は行われません。
単位換算が必要な場合は、ユーザーが `suffix` を参照して実装してください。
これを使用するには、 `toml::spec` の `ext_num_suffix` を `true` にします。
数値と接尾辞の間は`_`で区切られている必要があります。
数値部分との区別のため、suffixは数値で始まることはできません。
```
distance = 100_m # valid
distance = 10_0m # invalid
distance = 10_0_m # valid
```
接尾辞は`std::string suffix`としてフォーマット情報に保持されます。
```cpp
#include <toml.hpp>
int main()
{
toml::spec spec;
spec.ext_hex_float = true;
const auto v = toml::parse_str("a = 86_400_sec", spec);
assert(v.at("a").is_integer());
assert(v.at("a").as_integer() == 86400);
assert(v.at("a").as_integer_fmt().suffix == "sec");
return 0;
}
```

93
docs/content.ja/docs/features/literal.md Normal file
View File

@@ -0,0 +1,93 @@
+++
title = "toml literal"
type = "docs"
weight = 60
+++
# `_toml`リテラル
`""_toml`リテラルによって、TOMLファイルをその場でフォーマットできます。
```cpp
#include <toml.hpp>
int main()
{
using namespace toml::literals::toml_literals;
const auto v = "a = 42"_toml;
assert(v.at("a").as_integer() == 42);
return 0;
}
```
改行を含む場合、生文字列リテラルが便利です。
```cpp
#include <toml.hpp>
int main()
{
using namespace toml::literals::toml_literals;
const auto v = R"(
a = 42
b = "foo"
)"_toml;
assert(v.at("a").as_integer() == 42);
assert(v.at("b").as_string() == "foo");
return 0;
}
```
値が単体で書かれていた場合、その値が返されます。
```cpp
#include <toml.hpp>
int main()
{
using namespace toml::literals::toml_literals;
const auto a = "42"_toml;
const auto b = "12:34:56"_toml;
assert(v.at("a").as_integer() == 42);
assert(v.at("b").as_local_time().hour == 12);
assert(v.at("b").as_local_time().minute == 34);
assert(v.at("b").as_local_time().second == 56);
return 0;
}
```
TOMLは数値のみからなるキーを許可しています。
よって、`[1]`はテーブル名として合法です。
`[1]`のようにテーブル定義と配列の区別がつかない場合、テーブル定義が優先されます。
配列として解釈させるには、trailing commaを使用してください。
```cpp
#include <toml.hpp>
int main()
{
using namespace toml::literals::toml_literals;
const auto t = "[1]"_toml; // {1 = {}}
const auto a = "[1,]"_toml; // [1,]
assert(t.is_table());
assert(t.at("1").is_table());
assert(a.is_array());
assert(a.at(0).as_integer() == 1);
return 0;
}
```

279
docs/content.ja/docs/features/parsing_files.md Normal file
View File

@@ -0,0 +1,279 @@
+++
title = "parsing files"
type = "docs"
weight = 10
+++
# ファイル・文字列をパースする
toml11では、`toml::parse` や `toml::try_parse` を使って、ファイルや文字列、バイト列をパースすることができます。
これらは成功時に `toml::value` を返します。
ファイルは常にテーブルになりますが、返り値が `toml::table` でないことに気を付けてください。
`toml::value` はファイルに関するメタデータを持っており、
`toml::table` は `std::unordered_map<std::stirng, toml::value>` のエイリアスでしかありません。
メタデータを返すために、 `toml::table` ではなく `toml::value` を返しています。
ファイルのルートに対応する `toml::value` は常に `table_type` を持ちます。
## ファイルをパースする
ファイルをパースする際は、
[`toml::parse`]({{< ref "docs/reference/parser#parse" >}})
または
[`toml::try_parse`]({{< ref "docs/reference/parser#try_parse" >}})
を使います。
### `toml::parse`
#### `std::string`でファイル名を指定する
[`toml::parse`]({{< ref "docs/reference/parser#parse" >}})
は、文字列でファイル名を受け取り、そのファイルを開いてパースします。
以下のサンプルは、`input.toml`というファイルをパースし、`title`という変数を文字列として取り出し、出力するコードです。
```cpp
#include <toml.hpp>
#include <iostream>
int main()
{
const toml::value input = toml::parse("input.toml");
std::cout << input.at("title").as_string() << std::endl;
return 0;
}
```
#### `std::istream`で入力ストリームを指定する
[`toml::parse`]({{< ref "docs/reference/parser#parse" >}})
には、`std::istream`を渡すことも可能です。
その際、ファイル名の情報がなくなるため、エラーメッセージ中では `"unknown file"` となります。
これを避けるため、 `std::istream` を取る場合は第二引数に `std::string` でファイル名を取ることもできます。
`std::ifstream` 以外にも、 `std::istringstream` 等の別の`istream`を受け取ることができます。
ただし、呼び出した時点で内容が全て読み込める必要があります。
```cpp
#include <toml.hpp>
#include <iostream>
int main()
{
std::string filename("input.toml");
std::ifstream ifs(filename);
const toml::value input = toml::parse(ifs, filename);
std::cout << input.at("title").as_string() << std::endl;
return 0;
}
```
#### `std::filesystem::path`でファイルを指定する
[`toml::parse`]({{< ref "docs/reference/parser#parse" >}})
には、`std::filesystem::path`を渡すことも可能です。
当然ですが、`<filesystem>`がサポートされるC++17以降でなければ使用できません。
#### `FILE*`でファイルを指定する
[`toml::parse`]({{< ref "docs/reference/parser#parse" >}})
には、`FILE*`を渡すことも可能です。
この場合も、`std::istream`のときと同様に、第二引数に文字列でファイル名を与える必要があります。
`FILE*`を渡した場合、ファイルの読み込みに失敗した際には`errno`が報告されます。
#### エラー時の挙動
[`toml::parse`]({{< ref "docs/reference/parser#parse" >}})
は、文法エラーを発見した場合
[`toml::syntax_error`]({{<ref "docs/reference/parser#syntax_error">}})
を送出します。
[`toml::syntax_error`]({{<ref "docs/reference/parser#syntax_error">}})
は、
[`toml::exception`]({{<ref "docs/reference/exception">}})
から派生しており、またそれは`std::exception`から派生します。
よって、
[`toml::syntax_error`]({{<ref "docs/reference/parser#syntax_error">}})
からは `what()` メンバ関数を使ってエラーメッセージを取り出すことができます。
また、
[`toml::syntax_error`]({{<ref "docs/reference/parser#syntax_error">}})
は
[`std::vector<toml::error_info>`]({{<ref "docs/reference/error_info">}})
を持っており、`errors()`メンバ関数を使ってそれにアクセスすることもできます。
`toml::parse` はごく簡単なエラーならスキップして復帰し、複数のエラーを報告しようと努めます。
数値のフォーマットエラー程度なら復帰できることが多いですが、
配列やテーブルの中のエラーは復帰できずに似たようなエラーを複数回報告することもあります。
冗長であると感じた場合は、 `std::vector<toml::error_info>` の `front()` だけを使用するようにすると、
確実に問題のある個所に関するメッセージを得られます。
```cpp
#include <toml.hpp>
int main()
{
// parse
try {
const toml::value input = toml::parse("input.toml");
std::cout << input.at("title").as_string() << std::endl;
} catch(const toml::syntax_error& err) {
// 全てのエラーを報告
std::cerr << err.what() << std::endl;
// 最初のエラーのみ報告
std::cerr << err.errors().front() << std::endl;
}
}
```
### `toml::try_parse`
`toml::parse` は失敗時に例外を送出しますが、 `toml::try_parse` は失敗時に例外を投げません。
その代わり、返り値が `toml::value` ではなく [`toml::result<toml::value, std::vector<toml::error_info>>`]({{<ref "docs/reference/result#result">}}) になります。
[`result`]({{<ref "docs/reference/result#result">}}) 型は成功値または失敗値のどちらかを持つ型です。
Rustの `Result` やHaskellの `Either` に相当します。
```cpp
#include <toml.hpp>
int main()
{
const auto parse_result = toml::try_parse("input.toml");
if(parse_result.is_ok())
{
std::cout << parse_result.unwrap().at("title").as_string() << std::endl;
}
else
{
std::cerr << parse_result.unwrap_err().at(0) << std::endl;
}
return 0;
}
```
[`result`]({{<ref "docs/reference/result#result">}}) 型がどちらの値を保持しているかは
`is_ok()`, `is_err()` 関数を使って確認できます。
また、 `unwrap()`, `unwrap_err()` によって成功値、失敗値をそれぞれ取り出せます。
`unwrap` が失敗した場合は、 `bad_result_access` 例外が送出されます。
`as_ok()` と `as_err()` 関数を使用すると、失敗時には例外が送出されず、未定義動作となります。
{{<hint warning>}}
`try_parse` は `syntax_error` や `file_io_error` を投げず、同じ `toml::error_info` を
`result` の失敗型として返しますが、絶対に例外を投げないわけではありません。
標準ライブラリ内部でエラーが発生した場合、例えばメモリ不足の際に `vector` の
`allocate` が失敗した場合などには `std::bad_alloc` が送出されますが、
`toml::try_parse` はこれが送出された場合は `catch` せずに通します。
そのため、それらのような標準ライブラリの内部で発生する例外は送出される恐れがあります。
{{</hint>}}
## 文字列をパースする
### `toml::parse_str`
[`toml::parse_str`]({{<ref "docs/reference/parser#parse_str">}})
は、ファイル名ではなくパースする文字列そのものを受け取ります。
また、エラーメッセージのTOMLファイルの名前に相当する部分には、`std::source_location`
相当のコンパイラ拡張機能が使用できる場合、 `parse_str` を呼び出したC++ファイルの名前と行数が代わりに使用されます。
```cpp
#include <toml.hpp>
#include <iostream>
int main()
{
const toml::value input = toml::parse_str("title = \"parse_str\"");
std::cout << input.at("title").as_string() << std::endl;
return 0;
}
```
### `toml::try_parse_str`
[`toml::try_parse_str`]({{<ref "docs/reference/parser#try_parse_str">}})
は、 `parse_str` と同じくパースする文字列そのものを受け取り、
`try_parse` と同じくエラーの報告に
[`toml::result`]({{<ref "docs/reference/result#result">}})
を使用します。
```cpp
#include <toml.hpp>
#include <iostream>
int main()
{
const auto parse_result = toml::try_parse_str("title = \"parse_str\"");
if(parse_result.is_ok())
{
std::cout << parse_result.unwrap().at("title").as_string() << std::endl;
}
else
{
std::cerr << parse_result.unwrap_err().at(0) << std::endl;
}
return 0;
}
```
## バイト列をパースする
ファイルではなくバイト列をパースすることも可能です。
UTF-8でエンコードされている必要があるため、`unsigned char`を使っています。
### `toml::parse(std::vector<unsigned char>)`
挙動は [`toml::parse`]({{<ref "docs/reference/parser#parse">}}) と同一です。
バイト列をパースする際は、 `filename` を要求します。
```cpp
#include <toml.hpp>
#include <iostream>
int main()
{
std::vector<unsigned char> bytes{/* ... */};
const toml::value input = toml::parse(bytes, "internal bytes");
std::cout << input.at("title").as_string() << std::endl;
return 0;
}
```
### `toml::try_parse(std::vector<unsigned char>)`
挙動は [`toml::try_parse`]({{<ref "docs/reference/parser#try_parse">}}) と同一です。
バイト列をパースする際は、 `filename` を要求します。
```cpp
#include <toml.hpp>
#include <iostream>
int main()
{
std::vector<unsigned char> bytes{/* ... */};
const auto parse_result = toml::try_parse(bytes, "internal bytes");
if(parse_result.is_ok())
{
std::cout << parse_result.unwrap().at("title").as_string() << std::endl;
}
else
{
std::cerr << parse_result.unwrap_err().at(0) << std::endl;
}
return 0;
}
```

234
docs/content.ja/docs/features/serialize.md Normal file
View File

@@ -0,0 +1,234 @@
+++
title = "serializing values"
type = "docs"
weight = 40
+++
# TOMLファイルを出力する
`toml::format` を使うと、 `toml::value` を文字列にすることができます。
```cpp
#include <toml.hpp>
#include <cassert>
int main()
{
const toml::value v(toml::table{
{"a", 42},
{"b", "foo"},
});
const std::string s = toml::format(v);
const toml::value u = toml::parse_str(s);
assert(u.at("a").as_integer() == 42);
assert(u.at("b").as_string() == "foo");
return 0;
}
```
`table_type` を格納している `toml::value` が渡されると、それがファイルのルートテーブルとして解釈されます。
もし `table_type` 以外を格納している `toml::value` が渡されると、その値だけがフォーマットされます。
一部のフォーマット指定では、キーが渡されていないとフォーマットできないことがあります。
例えば、 `toml::array_format::array_of_tables` は `[[array.of.tables]]` の形でフォーマットするので、
キーへのアクセスを要求します。
キーを要求するフォーマット指定の値がキーなしで渡された場合、 `toml::serialization_error` が送出されます。
他にも、フォーマット指定と矛盾する値が含まれる場合には、 `toml::serialization_error` が送出されます。
例えば、 `integer_format::hex` が指定された整数が負の値を持っている場合や、
`string_format::literal` が指定された文字列が改行を含んでいる場合などです。
フォーマットの指定方法は後述します。
## キーを渡して出力する
`toml::format` には `std::string` としてキーを渡すことが可能です。
その場合、ルートテーブルの下にそのキーがあり、渡した値はそのキーに対応すると解釈されます。
キーが複数段になる場合、 `std::vector<std::string>` を渡すことができます。
```cpp
#include <toml.hpp>
#include <cassert>
int main()
{
const toml::value v(toml::table{
{"a", 42},
{"b", "foo"},
});
const std::string s = toml::format("bar", v);
const toml::value u = toml::parse_str(s);
assert(u.at("bar").at("a").as_integer() == 42);
assert(u.at("bar").at("b").as_string() == "foo");
return 0;
}
```
## フォーマットを指定する
`toml::value` のそれぞれの型には、対応するフォーマット情報型があります。
`toml::value::integer_type` には `toml::integer_format_info` が、
`toml::value::table_type` には `toml::table_format_info` があります。
これらは、パースした際に設定され、型が変わらない限り値を変更しても引き継がれます。
また、 `as_integer_fmt()` や `as_table_fmt()` といったメンバ関数によってアクセスすることができ、
直接編集することが可能です。
以下ではいくつかの例を挙げて使い方を説明します。
フォーマットへのアクセス方法は
[`toml::value`のリファレンス]({{< ref "/docs/reference/value" >}})を、
フォーマット情報クラスの完全なリストと詳細は
[formatのリファレンス]({{< ref "/docs/reference/format" >}})を
参照してください。
### 整数のフォーマットを指定する
整数は、基数と幅、そして `_` の位置を指定することができます。
`hex`, `oct`, `bin` のとき、指定された幅に達するまでゼロで埋められます。
`dec` の場合は幅指定はスペースを追加しますが、これはパースされません。
```cpp
#include <toml.hpp>
int main()
{
toml::value v(0x00C0'FFEE);
v.as_integer_fmt().fmt = toml::integer_format::hex;
v.as_integer_fmt().width = 8;
v.as_integer_fmt().spacer = 4;
const std::stirng s = toml::format(v);
assert(s == "0x00C0_FFEE");
return 0;
}
```
詳細は、[reference]({{< ref "/docs/reference/format#integer_format" >}}) を参照してください。
### 配列を単一行・複数行にする
配列には、 `toml::array_format::oneline` や `toml::array_format::multiline` を指定できます。
```toml
# oneline
a = [1, 2, 3, 4, 5]
# multiline
a = [
1,
2,
3,
4,
5
]
```
`multiline` のときは、インデントを指定できます。
各要素は `body_indent` の分だけインデントされ、閉じ括弧 `]` は `closing_indent` の分だけインデントされます。
文字種は `indent_type` で指定され、 `toml::indent_char::space` または `toml::indent_char::tab` が選択できます。
{{<hint warning>}}
インデントに使用する文字種は統一してください。
一つのファイル内でインデントに異なる文字種が指定された場合、結果は未規定になります。
何らかのインデントがされますが、全ての箇所で文字種やインデントの深さは不定となります。
{{</hint>}}
また、 `array` の要素が全て `table_type` を持つ場合、
`toml::array_format::array_of_tables` が指定できます。
`array_of_tables` を指定せずに `multiline` にした場合、テーブルはインラインテーブルになります。
```toml
# multiline
a = [
{foo = 42},
{bar = "hoge"},
]
# array_of_tables
[[a]]
foo = 42
[[a]]
bar = "hoge"
```
デフォルトでは、 `toml::array_format::default_format` が指定されます。
これは適したフォーマットを自動的に選択します。
例えば、 `default_format` で全要素が `table_type` だった場合、 `array_of_tables` が選択されます。
また、十分短い配列は `oneline` に、長い配列またはネストされた配列などの複雑な配列は `multiline` になります。
詳細は、[reference]({{< ref "/docs/reference/format#array_format" >}}) を参照してください。
### テーブルをインラインテーブルにする
テーブルをインラインテーブルにする際は `toml::table_format::oneline` を指定します。
通常のテーブルにする際は、 `toml::table_format::multiline` を指定します。
```toml
oneline = {a = 42, b = "foo"}
[multiline]
a = 42
b = "foo"
```
TOML v1.1.0ではインラインテーブル内での改行が許可されますが、その場合は
`toml::table_format::multiline_oneline` とします。
これは、後述するTOMLバージョン指定で対応する機能フラグが`true`になっていない限り無視されます。
```toml
multiline_oneline = {
a = 42,
b = "foo"
}
```
詳細は、[reference]({{< ref "/docs/reference/format#table_format" >}}) を参照してください。
## TOML言語バージョンを指定して出力する
TOML v1.1.0で許可されたインラインテーブル内の改行や`\x`エスケープシーケンスのように、
TOMLバージョンによって使用できない言語機能があります。
`toml::format` は最後の引数に `toml::spec` を取ることができます。
これにより、シリアライズ時に使用するTOMLのバージョンを指定することができます。
特に、 `toml::parse` で `toml::spec` を使用して新機能を使用した場合は、
パースした値がそのバージョンでしか使えないフォーマット情報を持つ場合があるので、
`toml::format` にも同じ `toml::spec` を渡すことを忘れないようにしてください。
```cpp
#include <toml.hpp>
#include <iostream>
int main()
{
const auto spec = toml::spec::v(1, 1, 0)
const toml::value v = toml::parse("input.toml", spec);
std::cout << toml::format(v, spec);
return 0;
}
```

116
docs/content.ja/docs/features/toml_spec.md Normal file
View File

@@ -0,0 +1,116 @@
+++
title = "toml spec"
type = "docs"
weight = 70
+++
# TOML言語バージョン
[`toml::spec`]({{< ref "docs/reference/spec#tomlspec" >}})
によって、 `toml::parse` や `toml::format` で使用するTOML言語のバージョンや、個別の機能フラグを指定することができます。
## TOMLのバージョンを指定する
[`toml::spec`]({{< ref "docs/reference/spec#tomlspec" >}})
は
[`toml::semantic_version`]({{< ref "docs/reference/spec#tomlsemantic_version" >}})
から構築できます。
```cpp
#include <toml.hpp>
int main()
{
toml::spec spec(toml::semantic_version(1, 1, 0));
return 0;
}
```
ですがこれは長いので、`toml::spec::v()`関数が用意されています。
```cpp
#include <toml.hpp>
int main()
{
toml::spec spec = toml::spec::v(1, 1, 0);
return 0;
}
```
特に指定しない場合、デフォルトの値で構築する `toml::spec::default_version()` が使用されます。
デフォルトの値はtoml11のバージョンによって変わりますが、その時点でリリースされているTOML言語の最新バージョンに追従します。
v4.0.0現在、TOML v1.1.0はまだリリースされていないため、デフォルトのTOMLバージョンはv1.0.0です。
{{<hint warning>}}
TOML v1.1.0の一部の機能にはかなり長い議論が続いており、まだ差し戻される可能性があります。
実際に差し戻された場合、toml11はマイナーバージョンアップでそれらの機能を削除、もしくは対応するそれ以降のバージョンに移動します。
そのような意味で、将来のバージョンに関する機能は全て不安定なものと考えてください。
{{</hint>}}
### バージョン指定でパースする
[`toml::parse`]({{< ref "docs/reference/parser" >}})
のオーバーロードは、ファイル名に続いて`toml::spec`を受け取ります。
これによって、使用するTOMLバージョンを変更できます。
```cpp
#include <toml.hpp>
int main()
{
toml::value input = toml::parse("input.toml", toml::spec::v(1, 1, 0));
return 0;
}
```
### バージョン指定でシリアライズする
[`toml::format`]({{< ref "docs/reference/serializer" >}})
のオーバーロードは、 `toml::value` に続いて `toml::spec` を受け取ります。
これによって、使用するTOMLバージョンを変更できます。
```cpp
#include <toml.hpp>
int main()
{
toml::value v = toml::parse("input.toml", toml::spec::v(1, 1, 0));
std::cout << toml::format(v, toml::spec::v(1, 1, 0)) << std::endl;
return 0;
}
```
もしフォーマット変数などによって指定されているフォーマットが渡された `toml::spec`
では許可されていないものだった場合、指定は無視されて他のフォーマットにフォールバックされます。
## TOMLに追加された新機能を個別に指定する
TOMLのバージョンアップで追加された機能は複数あり、そのうちの一部だけを有効にすることが可能です。
```cpp
#include <toml.hpp>
int main()
{
toml::spec spec = toml::spec::v(1, 0, 0);
// インラインテーブル内での改行を許可
spec.v1_1_0_allow_newlines_in_inline_tables = true;
toml::value input = toml::parse("input.toml", spec);
return 0;
}
```
全てのフラグのリストは、
[`toml::spec`]({{< ref "docs/reference/spec#tomlspec" >}})
を参照してください。

828
docs/content.ja/docs/features/value.md Normal file
View File

@@ -0,0 +1,828 @@
+++
title = "getting values"
type = "docs"
weight = 20
+++
# 値を取り出す
ここでは、 `toml::value` が格納している値にアクセスする方法を説明します。
## メンバ関数を使って値にアクセスする
### `is_something` と `as_something`
`toml::value` は `is_boolean()` や `is_integer()` などのメンバ関数を持っており、
これらを使うと持っている型を調べることができます。
また、 `as_boolean()`, `as_integer()` などのメンバ関数も持っており、
これらを使ってその型にアクセスすることができます。
完全なリストは [`toml::value` のリファレンス]({{<ref "docs/reference/value#is_xxx">}}) を参照してください。
```cpp
toml::value v = /* ... */;
if(v.is_integer())
{
std::cout << v.as_integer() << std::endl;
}
```
指定された値と異なる型が格納されていた場合、 [`toml::type_error`]({{<ref "docs/reference/value#tomltype_error">}}) が送出されます。
その `what()` は以下のようなメッセージを含みます。
```
[error] toml::value::as_string(): bad_cast to string
--> input.toml
|
1 | a = 123_456
| ^^^^^^^-- the actual type is integer
```
### `toml::value_t`
型情報は [`enum class toml::value_t`]({{<ref "docs/reference/value_t">}}) で識別できます。
[`type()`]({{<ref "docs/reference/value#type">}}) メンバ関数は、現時点で格納している値の型情報を返します。
```cpp
toml::value v = /* ... */;
switch(v.type())
{
case toml:value_t::empty : { /*...*/ break; }
case toml:value_t::boolean : { /*...*/ break; }
case toml:value_t::integer : { /*...*/ break; }
case toml:value_t::floating : { /*...*/ break; }
case toml:value_t::string : { /*...*/ break; }
case toml:value_t::offset_datetime: { /*...*/ break; }
case toml:value_t::local_datetime : { /*...*/ break; }
case toml:value_t::local_date : { /*...*/ break; }
case toml:value_t::local_time : { /*...*/ break; }
case toml:value_t::array : { /*...*/ break; }
case toml:value_t::table : { /*...*/ break; }
default: {break;}
}
```
[`is(toml::value_t)`]({{<ref "docs/reference/value#istomlvalue_t">}}) メンバ関数は、渡された `value_t` と同じ型の値を格納している場合 `true` を、
それ以外の場合 `false` を返します。
```cpp
toml::value v = /* ... */;
if(v.is(toml::value_t::integer))
{
std::cout << v.as_integer() << std::endl;
}
```
### `at`, `[]`, `contains`, `size`, `push_back`, `emplace_back`
標準ライブラリコンテナが持つメンバ関数の一部は、 `toml::value` も提供しています。
これらは、内部で `toml::value` を対応する型に変換し、そのメンバ関数を呼び出します。
#### `at(std::size_t i)`, `operator[](std::size_t i)`
`as_array().at(i)`, `as_array()[i]` と同等です。
`toml::value` はデフォルトで `std::vector<toml::value>` を `array_type` に使うので、
エラーが発生した際には `at` は `std::out_of_range` を送出し、`operator[]` は未定義動作となります。
```cpp
toml::value v(toml::array{1,2,3});
std::cout << v.at(1);
```
格納している型が `array_type` ではなかった場合、 `type_error` を送出します。
#### `at(std::string key)`, `operator[](std::string key)`
`as_table().at(key)`, `as_table()[key]` と同等です。
`toml::value` はデフォルトで `std::unordered_map<std::string, toml::value>` を `table_type` に使うので、
対応する値が存在しない場合は `at` は `std::out_of_range` を送出し、 `operator[]` は新しく `toml::value` を構築してそれへの参照を返します。
そのため、`operator[]` に `const` 版はありません。
```cpp
toml::value v(toml::table{});
v["a"] = 42;
```
格納している型が `table_type` ではなかった場合、 `type_error` を送出します。
#### `size()`
長さを返します。
`array_type` または `table_type` の場合は要素数、 `string_type` の場合は文字数を返します。
格納している型がどれでもなかった場合、 `type_error` を送出します。
#### `push_back()`, `emplace_back()`
`as_array().push_back()`, `as_array().emplace_back()` と同一です。
格納している型が `array_type` ではなかった場合、 `type_error` を送出します。
## コメントにアクセスする
toml11では、デフォルトでコメントがパースされ、対応する値に行ごとに保存されます。
対応する値は、連続するコメント行の直後に来る値か、もしくはそのコメントと同じ行に描かれている値です。
直前または直後に値がなければ、そのコメントはどこにも紐づけられず、無視されます。
```toml
# input.toml
# これはaに関するコメントです。
a = 42
b = 3.14 # これはbに関するコメントです。
# このコメントには対応する値がないため無視されます。
# これは1番目のcに関するコメントです。
# これは2番目のcに関するコメントです。
c = "foo" # これは最後のcに関するコメントです。
```
値に対応するコメントには、`toml::value` の `comments()` メンバ関数を使ってアクセスします。
`comments()` は `std::vector<std::string>` と同じメンバ関数を持つコンテナを返します。
```cpp
const auto v = toml::parse("input.toml");
const auto& a = v.at("a");
const auto& b = v.at("b");
const auto& c = v.at("c");
assert(a.comments().size() == 1);
assert(a.comments().at(0) == "# これはaに関するコメントです。");
assert(b.comments().size() == 1);
assert(b.comments().at(0) == "# これはbに関するコメントです。");
assert(c.comments().size() == 3);
assert(c.comments().at(0) == "# これは1番目のcに関するコメントです。");
assert(c.comments().at(1) == "# これは2番目のcに関するコメントです。");
assert(c.comments().at(2) == "# これは最後のcに関するコメントです。");
```
ファイル全体に対応するルートテーブルに関するコメントは、ファイルの先頭に書きます。
```toml
# ルートテーブルに関するコメントです。
# これもルートテーブルに関するコメントです。
# これはaに関するコメントです。
a = 42
```
ただし、もしファイルの先頭のコメントの直後に値が来た場合、
そのコメントはその値に関するコメントと解釈され、ルートテーブルのコメントはなくなります。
```toml
# これはaに関するコメントです。
# これもaに関するコメントです。
a = 42
```
## インラインテーブル・ドットキーの取り扱い
インラインテーブルは単にテーブルで、C++コード上で他のテーブルと異なる点はありません。
```toml
a = {b = 42, c = "foo"}
```
ドットキーも単にテーブルで、C++コード上で他のテーブルと異なる点はありません。
```toml
a.b = 42
a.c = "foo"
```
これらは以下のファイルと全く同じ構造を持ちます。
```toml
[a]
b = 42
c = "foo"
```
なので、どの記法でも以下の全く同一のコードで処理できます。
```cpp
const auto input = toml::parse("input.toml");
assert(input.at("a").at("b").as_integer() == 42);
assert(input.at("a").at("c").as_string() == "foo");
```
ただし、フォーマット情報によって区別することは可能です。
```cpp
const auto input = toml::parse("input.toml");
switch(input.at("a").as_table_fmt().fmt)
{
case toml::table_format::oneline:
{
std::cout << "inline table" << std::endl;
break;
}
case toml::table_format::multiline:
{
std::cout << "normal table" << std::endl;
break;
}
case toml::table_format::dotted:
{
std::cout << "dotted keys" << std::endl;
break;
}
}
```
このフォーマット情報は後述するシリアライズの際も考慮されます。
## 日付情報の取り扱い
[`local_date`]({{<ref "docs/reference/datetime#local_date">}}),
[`local_time`]({{<ref "docs/reference/datetime#local_time">}}),
[`local_datetime`]({{<ref "docs/reference/datetime#local_datetime">}}), そして
[`offset_datetime`]({{<ref "docs/reference/datetime#offset_datetime">}}) は、
toml11では対応するメンバ変数を持つ専用の構造体にパースされます。
使用する際は、直接値を取り出す他にも、後述する `toml::get` や `toml::find` を使用して、
`std::chrono::system_clock::time_point` や `std::tm` 等の型に変換することができます。
## `toml::get<T>`を使って変換する
`toml::get<T>` は、 `toml::value` の持つ値を変換して取り出す関数です。
`T` に変換先に指定したい型を指定します。
```cpp
const toml::value v = /*...*/;
std::cout << toml::get<int>(v) << std::endl;
```
後述する `toml::find<T>` も、型変換の部分は同一の機能を持ちます。
格納されている型のそれぞれについて、
変換ができない型が指定された場合、 `toml::type_error` が送出されます。
### 単純な変換
#### boolean_type
`boolean_type` から変換が可能なのは、 `bool` のみです。
#### integer_type
`bool` 以外で `std::is_integral<T>` が `true` になる型は、 `integer_type` から変換できます。
```cpp
toml::value v(42);
const auto u32 = toml::get<std::uint32_t>(v);
const auto i16 = toml::get<short>(v);
```
#### floating_type
`std::is_floating_point<T>` が `true` になる型は、`floating_type` から変換できます。
```cpp
toml::value v(3.14);
const auto f64 = toml::get<double>(v);
const auto f32 = toml::get<float >(v);
```
#### string_type
`string_type` からは `std::string` へ変換できます。
また、C++17以降では、`std::string_view` へも変換できます。
```cpp
toml::value v("foo");
const auto s = toml::get<std::string>(v);
// C++17以降
const auto sv = toml::get<std::string_view>(v);
```
#### datetime variants
[`local_date`]({{<ref "docs/reference/datetime#local_date">}}),
[`local_datetime`]({{<ref "docs/reference/datetime#local_datetime">}}),
[`offset_datetime`]({{<ref "docs/reference/datetime#offset_datetime">}}) は
ある日付と時刻を指しているため、
`std::chrono::system_clock::time_point` への変換が可能です。
ただし、[`local_time`]({{<ref "docs/reference/datetime#local_time">}}) は
日付の情報がないため、0時0分からの経過時刻として `std::chrono::duration` への
変換をサポートします。
また、 `local_date` と `local_datetime` は実行中のマシンのタイムゾーンを取得して変換を行います。
```toml
date = 2024-01-23
time = 12:30:00
l_dt = 2024-01-23T12:30:00
o_dt = 2024-01-23T12:30:00+09:00
```
```cpp
const auto input = toml::parse("input.toml");
const auto date = toml::get<std::chrono::system_clock::time_point>(input.at("date"));
const auto l_dt = toml::get<std::chrono::system_clock::time_point>(input.at("l_dt"));
const auto o_dt = toml::get<std::chrono::system_clock::time_point>(input.at("o_dt"));
const auto time = toml::get<std::chrono::minutes>(input.at("time")); // 12 * 60 + 30 min
```
### 参照を取得できる条件
`toml::get<T>` は、 `T` が `toml::value` が格納する型そのものだった場合、参照を返すことができます。
逆に、変換が必要な場合（ `std::int64_t` で格納されている整数を `std::uint32_t` で取り出そうとした場合）は、
変換後の型への参照を返すことは不可能です。
変換が必要ない型の場合、返された参照を経由して値を書き換えることも可能です。
```cpp
toml::value v(42);
toml::get<toml::value::integer_type>(v) = 6 * 9;
assert(v.as_integer() == 54);
```
### 配列をSTLコンテナに
配列の要素型が全て同じ場合、要素型が `T` に変換可能であれば、 `std::vector<T>` に変換可能です。
```toml
a = [1, 2, 3, 4, 5]
```
```cpp
const auto a = toml::get<std::vector<int>>(input.at("a"));
```
他のSTLコンテナにも変換可能です。
```cpp
const auto a1 = toml::get<std::deque<int>>(input.at("a"));
const auto a2 = toml::get<std::list <int>>(input.at("a"));
const auto a3 = toml::get<std::array<int, 5>>(input.at("a"));
```
`std::array` に変換する場合、要素数が一致している必要があります。
もし要素数が一致しなかった場合、 `std::out_of_range` が送出されます。
STL以外のコンテナであっても、デフォルトコンストラクタと `push_back` を持っている場合、
`toml::get` で変換が可能です。
```cpp
const auto a = toml::get<boost::container::small_vector<int, 8>>(input.at("a"));
```
### 配列を `std::pair`, `std::tuple` に
配列の要素型が異なる場合、 `std::pair` や `std::tuple` に変換が可能です。
```toml
a = [true, 3.14]
b = [42, 2.718, "foo"]
```
```cpp
const auto a = toml::get<std::pair<bool, double>>(input.at("a"));
const auto b = toml::get<std::tuple<int, double, std::string>>(input.at("b"));
```
`std::array` の場合と同様に、配列の長さは `std::pair`, `std::tuple` の要素数と一致している必要があります。
もし要素数が一致しなかった場合、 `std::out_of_range` が送出されます。
また、各要素は対応する要素に変換できる必要があります。
変換できない場合、 `toml::type_error` が送出されます。
### ネストされた配列の変換
ネストされた配列は、ネストされたコンテナに変換可能です。
```toml
a = [ [1, 2, 3], [4, 5, 6] ]
```
```cpp
const auto a = toml::get<std::vector<std::vector<int>>>(input.at("a"));
```
型が異なる場合には、 `std::pair/tuple` が便利です。
```toml
a = [ [1, 2, 3], ["foo", "bar"] ]
```
```cpp
const auto a = toml::get<
std::pair<std::vector<int>, std::vector<std::string>>
>(input.at("a"));
```
### テーブルを `std::map` に変換
テーブルに含まれる値の型が全て同じであれば、 `std::map` や `std::unordered_map` に変換が可能です。
```toml
t = {a = 1, b = 2}
```
```cpp
const auto t = toml::get<std::map<std::string, int>>(input.at("t"));
```
STL以外のコンテナであっても、デフォルトコンストラクタと `emplace(key, mapped)` を持っている場合、
`toml::get` で変換が可能です。
```cpp
const auto t = toml::get<boost::container::flat_map<std::string, int>>(input.at("t"));
```
要素型の変換に失敗した場合は `toml::type_error` が送出されます。
## `toml::get_or`を使って失敗時の値を指定する
`toml::get` は変換に失敗した際に `toml::type_error` 例外を送出します。
`toml::get_or` を使用することで、変換に失敗した際に例外ではなくデフォルト値を返せるようになります。
`toml::get<T>` とは異なり、 `get_or` は引数から変換先の型を推論するため、 `<T>` の指定は不要です。
```cpp
const auto a = toml::get_or(input.at("a"), 42);
```
変換可能な型は `toml::get` と同様です。
`toml::value::xxx_type`を指定した場合は、参照を取り出すことも可能ですが、その場合は引数も参照である必要があります。
```cpp
toml::value::integer_type a_default = 42;
auto a& = toml::get_or(input.at("a"), a_default);
```
## `toml::find<T>`を使って検索と変換を同時に行う
`toml::find<T>` は、テーブルを持つ `toml::value` から値を検索し、同時に
`toml::get` と同じ型変換を行って取り出す関数です。
```cpp
const auto a = toml::find<int>(input, "a");
// const auto a = toml::get<int>(input.at("a")); と同じ
```
`toml::find<T>` は配列にも使用できます。
```cpp
const auto a = input.at("a");
const auto a2 = toml::find<int>(a, 2);
// const auto a2 = toml::get<int>(input.at("a").at(2)); と同じ
```
型変換の際にエラーが起きた場合、 `toml::get` と同じ `toml::type_error` を
送出します。
キーが見つからなかった場合またはインデックスが存在しない場合は、
`std::out_of_range` を送出します。
型を指定しなかった場合、型変換を行わず `toml::value` を取り出します。
```cpp
const auto a = toml::find(input, "a");
// const auto a = input.at("a"); と同じ
```
`toml::find<T>` は再帰的に値にアクセスることもできます。
```toml
a = {b = {c = 42}}
```
```cpp
const auto a_b_c = toml::find<int>(input, "a", "b", "c");
// const auto a = toml::get<int>(input.at("a").at("b").at("c")); と同じ
```
このとき、キーとインデックスを混ぜることができます。
```toml
a = [ {b = 1}, {b = 2}, {b = 3} ]
```
```cpp
const auto a_2_b = toml::find<int>(input, "a", 2, "b");
// const auto a = toml::get<int>(input.at("a").at(2).at("c")); と同じ
```
{{<hint info>}}
TOMLはquoted keyという機能を持っています。
これは、 `""` や `''` を使うことで通常許可されない文字をキーに使えるというもので、
この中では `.` はテーブルを導入**しません**。
```toml
"127.0.0.1" = "value"
site."google.com" = true
```
このTOMLファイルは以下のようにして読みます。
```cpp
const auto input = toml::parse("input.toml");
assert(input.at("127.0.0.1").as_string() == "value");
assert(input.at("site").at("google.com").as_boolean());
```
このような場合にも違和感なく対応するため、toml11ではキーに `.` が含まれていても
自動で分割はしません。
テーブルの階層構造を陽に指定することが、適切な入力ファイルの構造化に資すると考えているからです。
参考: [toml.io キー](https://toml.io/ja/v1.0.0#%E3%82%AD%E3%83%BC)
{{</hint>}}
## `toml::find_or`を使って失敗時の値を指定する
`toml::find_or` は、 `toml::get_or` と同様に、失敗時のデフォルト値を渡します。
```cpp
const auto a = toml::find_or(input, "a", 42);
```
型変換の失敗だけでなく、キーが見つからなかった場合もデフォルト値を返します。
## ユーザー定義型との変換を定義する
`toml::get` や `toml::find` では、以下のどれかの方法を使うことで
ユーザー定義型を使用することができます。
### `toml::from` の定義
toml11には `toml::from` という型があり、以下のように特殊化することでユーザー定義型からの
変換をサポートできます。
```cpp
namespace extlib
{
struct foo
{
int a;
std::string b;
};
} // extlib
namespace toml
{
template<>
struct from<extlib::foo>
{
static extlib::foo from_toml(const toml::value& v)
{
return extlib::foo{
toml::find<int>(v, "a"),
toml::find<std::string>(v, "b")
};
}
};
} // toml
```
後述する型設定を変更した `toml::value` もサポートする場合、以下のようにしてください。
```cpp
namespace extlib
{
struct foo
{
int a;
std::string b;
};
} // extlib
namespace toml
{
template<>
struct from<extlib::foo>
{
template<typename <TC>
static extlib::foo from_toml(const toml::basic_value<TC>& v)
{
return extlib::foo{
toml::find<int>(v, "a"),
toml::find<std::string>(v, "b")
};
}
};
} // toml
```
この定義は、 `TOML11_DEFINE_CONVERSION_NON_INTRUSIVE` によって自動的に定義できます。
```cpp
namespace extlib
{
struct foo
{
int a;
std::string b;
};
} // extlib
TOML11_DEFINE_CONVERSION_NON_INTRUSIVE(extlib::foo, a, b)
```
あるいは、リフレクションライブラリを使用することもできます。
`example` の `boost-ext/reflect` を使用したサンプルも参照してください。
### `from_toml` メンバ関数の定義
`from_toml` メンバ関数を定義することによっても変換を定義することができます。
これを使用する場合、デフォルトコンストラクタが必要です。
```cpp
struct bar
{
int a;
std::string b;
void from_toml(const toml::value& v)
{
this->a = toml::find<int>(v, "a");
this->b = toml::find<std::string>(v, "b");
return ;
}
};
```
両方が定義されていた場合、 `toml::from` が優先されます。
### `toml::value` を受け取るコンストラクタ
`toml::value` を受け取るコンストラクタがあれば、 `toml::get` による変換ができます。
```cpp
struct baz
{
explicit baz(const toml::value& v)
: a(toml::find<int>(v, "a")), b(toml::find<std::string>(v, "b"))
{}
int a;
std::string b;
};
```
両方が定義されていた場合、`toml::from` と `from_toml` が優先されます。
## `toml::visit`で関数を適用する
`toml::value` が格納する型すべてに適用できる関数オブジェクトがあれば、
`toml::visit` によって型変換を経ずに直接その関数を呼ぶことができます。
```cpp
struct type_name_of
{
std::string operator()(const toml::value::boolean_type &) const {return "boolean";}
std::string operator()(const toml::value::integer_type &) const {return "integer";}
std::string operator()(const toml::value::floating_type &) const {return "floating";}
std::string operator()(const toml::value::string_type &) const {return "string";}
std::string operator()(const toml::value::local_time_type &) const {return "local_time";}
std::string operator()(const toml::value::local_date_type &) const {return "local_date";}
std::string operator()(const toml::value::local_datetime_type &) const {return "local_datetime";}
std::string operator()(const toml::value::offset_datetime_type&) const {return "offset_datetime";}
std::string operator()(const toml::value::array_type &) const {return "array";}
std::string operator()(const toml::value::table_type &) const {return "table";}
};
toml::value v(3.14);
std::cout << toml::visit(type_name_of{}, v) << std::endl; // floating
```
## `toml::value` を構築する
`toml::value` はパーサの内部だけでなく、ユーザーコードで構築することも可能です。
`toml::value` が格納する型と同じか変換可能な型を渡しての構築が可能です。
```cpp
toml::value v1(true);
toml::value v2(42);
toml::value v3(3.14);
```
配列の場合、 `toml::array` を使うか、
```cpp
toml::value v(toml::array{1, 2, 3});
```
配列の場合、 `std::vector` などのコンテナを直接渡すことが可能です。
```cpp
const std::vector<toml::value> a{1,2,3};
toml::value v(a);
```
このコンテナには、 `toml::get` で変換可能なコンテナが使用できます。
テーブルの場合も同様に、 `toml::table` を使うか、
```cpp
toml::value v(toml::table{{"foo", 1}, {"bar", 2}, {"baz", 3}});
```
`std::map` などのコンテナを直接渡します。
```cpp
const std::map<std::string, toml::value> t{
{"foo", 1}, {"bar", 2}, {"baz", 3}
}
toml::value v(t);
```
コンストラクタには、 `format_info` と コメントを渡すことができます。
コメントの型は `std::vector<std::string>` です。
各要素が一行分に相当します。
```cpp
toml::integer_format_info fmt;
fmt.fmt = toml::integer_format::hex;
fmt.spacer = 4;
toml::value v1(0xDEADBEEF, fmt);
toml::value v2(0xC0FFEE, fmt, {"hex value!"});
```
## `toml::value` に変換する
ユーザー定義型から `toml::value` を構築する際に、 `toml::into` や `into_toml` を
定義することで、その挙動をカスタマイズできます。
特に、別のライブラリの型などを変換する際に `toml::into` が便利です。
### `toml::into`を定義する
`toml::into` を特殊化することで `toml::value` への変換が可能になります。
`toml::value` への変換が用意されていない外部ライブラリの型などに対して有効です。
`toml::value` が変換時に `type_config` を渡すため、`basic_value` の `template` 引数を受け取る必要があります。
```cpp
namespace extlib
{
struct foo
{
int a;
std::string b;
};
} // extlib
template<>
struct into<extlib::foo>
{
template<typename TC>
static toml::basic_value<TC> into_toml(const extlib::foo& f)
{
return toml::basic_value<TC>(typename toml::basic_value<TC>::table_type{{"a", f.a}, {"b", f.b}});
}
};
```
### `into_toml` メンバ関数を定義する
`from_toml` と同様、メンバ関数によっても変換を定義することができます。
`toml::into` が定義されていた場合、そちらが優先されます。
```cpp
struct bar
{
int a;
std::string b;
toml::value into_toml() const
{
return toml::value(toml::table{{"a", this->a}, {"b", this->b}});
}
};
```

104
docs/content.ja/docs/installation/_index.md Normal file
View File

@@ -0,0 +1,104 @@
+++
title = "installation"
type = "docs"
weight = 1
+++
# installation
## `single_include`を使用する
`single_include/toml.hpp`は、`toml11`が持つ全ての機能を単一のファイルにまとめたシングルファイル・ヘッダオンリーライブラリです。
これを`INCLUDE_PATH`が通っている箇所にコピーして`#include <toml.hpp>`とするのが最も単純な使用方法です。
MITライセンスの許諾表示はコメントと`toml:license_notice()`関数の両方に含まれます。
ソースコードを公開せずに再頒布する場合は、toml11のライセンスファイルをコピーして同梱するか、この関数を呼び出せるようにしておいてください。
## toml11をクローンし、`cmake`を使って使用する
`toml11`を`git submodule`などによって自身のレポジトリ下に配置した場合、`cmake`を使用している場合は`add_subdirectory(toml11)`のようにすることで使用可能になります。
```cmake
add_subdirectory(toml11)
add_executable(main main.cpp)
target_link_libraries(main PUBLIC toml11::toml11)
```
`toml11`は自身がルートプロジェクトのときのみ、テストとインストールを行います。
## `cmake`を使用してインストールする
`toml11`をクローンしたのち、`cmake`を使ってインストールすることができます。
```console
$ cmake -B ./build/ -DTOML11_BUILD_TESTS=ON
$ cmake --install ./build/ --prefix=/opt/toml11
```
インストールの前にテストプログラムを実行する際は、最初に`-DTOML11_BUILD_TESTS=ON`を設定してください。
インストールが完了すれば、以下のようにして使用できます。
```cmake
find_package(toml11)
add_executable(main main.cpp)
target_link_libraries(main PRIVATE toml11::toml11)
```
## `cmake`を使用してコンパイルし、静的ライブラリを作成する
`cmake`の実行時に`-DTOML11_PRECOMPILE=ON`を定義することで、`toml11`の関数のうちコンパイルできるものを先にコンパイルして、全体のコンパイル時間を短縮することができます。
```console
$ cmake -B ./build/ -DTOML11_PRECOMPILE=ON
```
ただし、toml11は複数のC++バージョンに対応するため、`__cplusplus`の値などによって型を切り替えることがあります。
そのため、ビルドした際のバージョンと使用時のバージョンが異なる場合、リンクに失敗する可能性があります。
問題が生じた場合は`CMAKE_CXX_STANDARD`によって必要なバージョンを設定してコンパイルしてください。
それが難しい場合は、通常通りヘッダオンリーライブラリとして使用してください。
`find_package(toml11)`によって`TOML11_INCLUDE_DIR`が定義されます。
コンパイル済みライブラリとしてインストールした場合でも、 `TOML11_INCLUDE_DIR` を
`include_directories` に追加した上で `target_link_libraries` を
使用しないようにすれば、ヘッダオンリーライブラリとして使用可能です。
```cmake
find_package(toml11)
add_executable(main main.cpp)
# インクルードのみ可能にし、リンクを行わない
target_include_directories(main PRIVATE ${TOML11_INCLUDE_DIR})
```
## examplesをコンパイルする
`-DTOML11_BUILD_EXAMPLES=ON`とすることで、`examples/`をコンパイルできます。
```console
$ cmake -B ./build/ -DTOML11_BUILD_EXAMPLES=ON
$ cmake --build ./build/
```
`examples`の実行バイナリは`examples/`に生成されます。
## テストを実行する
テストをビルドするためには、`-DTOML11_BUILD_TESTS=ON`とします。
```console
$ git submodule update --init --recursive
$ cmake -B ./build/ -DTOML11_BUILD_TESTS=ON
$ cmake --build ./build/
$ ctest --test_dir ./build/
```
toml-lang/toml-testsを実行するには、`-DTOML11_BUILD_TOML_TESTS=ON`とします。
すると、`tests/`に`toml11_decoder`と`toml11_encoder`がビルドされます。
```console
$ git submodule update --init --recursive
$ cmake -B ./build/ -DTOML11_BUILD_TOML_TESTS=ON
$ cmake --build ./build/
$ ctest --test_dir ./build/
```

124
docs/content.ja/docs/reference/_index.md Normal file
View File

@@ -0,0 +1,124 @@
+++
title = "reference"
type = "docs"
weight = 3
bookCollapseSection = true
+++
# Reference
以下では、toml11が公開するクラスと関数の効果を説明します。
## ディレクトリ構造
`toml.hpp` と `toml_fwd.hpp` は `${TOML11_INCLUDE_DIR}` にあります。
他のファイルは、`${TOML11_INCLUDE_DIR}/toml11` にあります。
もし各機能のファイルを個別に `#include` したい場合は、 `#include <toml11/color.hpp>` としてください。
全てを一度に `#include` する場合は、 `#include <toml.hpp>` としてください。
## [color.hpp](color)
エラーメッセージの色付けに関する関数を定義します。
## [comments.hpp](comments)
コメントを持つ`preserve_comment`型と`discard_comment`型を定義します。
## [conversion.hpp](conversion)
`toml::value`とユーザー定義クラスを自動的に変換するマクロを定義します。
## [datetime.hpp](datetime)
日時情報を持つクラスを定義します。
## [error_info.hpp](error_info)
エラー情報を持つクラスを定義します。
## [exception.hpp](exception)
toml11で使用される例外の基底クラス、`toml::exception`を定義します。
## [find.hpp](find)
値を探し変換する`toml::find`関数を定義します。
## [format.hpp](format)
値のフォーマット情報を持つクラスを定義します。
## [from.hpp](from)
ユーザー定義型を変換するための`from<T>`型の前方宣言です。
## [get.hpp](get)
`toml::value`の値を取り出し変換する`toml::get<T>`関数を定義します。
## [into.hpp](into)
ユーザー定義型を変換するための`into<T>`型の前方宣言です。
## [literal.hpp](literal)
`operator"" _toml`リテラルを定義します。
## [ordered_map.hpp](ordered_map)
`toml::ordered_map`を定義します。
## [parser.hpp](parser)
ファイルまたは文字列をパースする関数を定義します。
## [result.hpp](result)
他の関数の返り値として使われる、成功値または失敗値を持つ`result<T, E>`型を定義します。
## [serializer.hpp](serializer)
シリアライズに用いる`toml::format`関数と`toml::serializer`を定義します。
## [source_location.hpp](source_location)
エラー情報に用いられる、ファイル内のある領域を指す`source_location`型を定義します。
## [spec.hpp](spec)
TOML言語のバージョン情報と機能フラグを制御する、`toml::semantic_version`型と`toml::spec`型を定義します。
## [toml.hpp](toml)
`toml.hpp`は、他の全てのヘッダを `include` します。
toml11の全機能が使用可能になります。
## [toml_fwd.hpp](toml_fwd)
`toml_fwd.hpp`は、toml11で定義される構造体の前方宣言と、マクロ定義を持ちます。
## [types.hpp](types)
`toml::value`の持つ型を制御するための`toml::type_config`型を定義します。
## [value.hpp](value)
`toml::value`型を定義します。
## [value_t.hpp](value_t)
列挙型`toml::value_t`を定義します。
## [version.hpp](version)
toml11のバージョン情報を定義します。
## [visit.hpp](visit)
`toml::value`の持つ値に関数を適用する`toml::visit`関数を定義します。
## 備考
ここで明記されない関数（主に`namespace toml::detail`や`namespace toml::cxx`以下に定義されるもの）は、
ソースコードを見ることで利用可能ではあるものの、そのインターフェースは今後のいかなるバージョンアップでも（パッチバージョンアップを含む）維持される保証はありません。

141
docs/content.ja/docs/reference/color.md Normal file
View File

@@ -0,0 +1,141 @@
+++
title = "color.hpp"
type = "docs"
+++
# color.hpp
`color.hpp`では、エラーメッセージの色付けに関する関数が定義されます。
色はANSIエスケープシーケンスによって指定されます。
ANSIエスケープシーケンスをサポートしていないターミナルやその他の出力先では、読みにくくなる可能性があります。
## マクロ
```cpp
TOML11_COLORIZE_ERROR_MESSAGE
```
コンパイル時にこのマクロが定義されていた場合（`-DTOML11_COLORIZE_ERROR_MESASGE`）、
デフォルトでエラーメッセージに色が付きます。
定義されていなかった場合、デフォルトでは色は付きません。以下の `toml::color::enable()` を
使用して指定する必要があります。
## 関数
### `enable()`
```cpp
namespace toml {
namespace color {
void enable();
} // color
} // toml
```
ANSIエスケープシーケンスによる色付けを行うよう設定します。
#### 例
```cpp
#include <toml.hpp>
int main()
{
toml::color::enable(); // この後の全てのエラーがカラーになります。
const auto input = toml::parse("input.toml");
return 0;
}
```
### `disable()`
```cpp
namespace toml {
namespace color {
void disable();
} // color
} // toml
```
ANSIエスケープシーケンスによる色付けを行わないよう設定します。
#### 例
```cpp
#include <toml.hpp>
int main()
{
toml::color::enable(); // この後の全てのエラーがカラーになります。
const auto input = toml::parse("input.toml");
return 0;
}
```
### `should_color()`
```cpp
namespace toml {
namespace color {
bool should_color();
} // color
} // toml
```
色付けを行う設定になっている場合`true`が、そうでない場合`false`が返されます。
#### 例
```cpp
#include <toml.hpp>
#include <iomanip>
#include <iostream>
int main()
{
std::cout << "colorized? : " << std::boolalpha << toml::color::should_color() << std::endl;
return 0;
}
```
## マニピュレータ
```cpp
namespace toml {
namespace color {
std::ostream& reset (std::ostream&);
std::ostream& bold (std::ostream&);
std::ostream& grey (std::ostream&);
std::ostream& gray (std::ostream&);
std::ostream& red (std::ostream&);
std::ostream& green (std::ostream&);
std::ostream& yellow (std::ostream&);
std::ostream& blue (std::ostream&);
std::ostream& magenta(std::ostream&);
std::ostream& cyan (std::ostream&);
std::ostream& white (std::ostream&);
} // color
} // toml
```
ANSIエスケープシーケンスによって、`fg`を色付けします。
#### 例
```cpp
#include <toml.hpp>
#include <iostream>
int main()
{
std::cout << toml::color::red << "red!" << std::endl;
return 0;
}
```
# 関連項目
- [error_info.hpp]({{<ref "error_info.md">}})

773
docs/content.ja/docs/reference/comments.md Normal file
View File

@@ -0,0 +1,773 @@
+++
title = "comments.hpp"
type = "docs"
+++
# comments.hpp
`color.hpp`では、コメントを保持するクラスが提供されます。
# `toml::preserve_comments`
`preserve_comments`は、コメントを保持するコンテナです。
`std::vector<std::string>`が持つメンバ関数を全て持っています。
コメントは`std::string`として保持されます。
先頭が`#`でない場合、出力時に`#`が補われます。コンテナに要素として追加する段階では補われません。
スペースは補われないため、`#`の直後にスペースを入れたい場合、コメントをスペースから始めるか、`#`を含めたコメントを渡す必要があります。
```cpp
namespace toml
{
class preserve_comments;
bool operator==(const preserve_comments&, const preserve_comments&);
bool operator!=(const preserve_comments&, const preserve_comments&);
bool operator< (const preserve_comments&, const preserve_comments&);
bool operator<=(const preserve_comments&, const preserve_comments&);
bool operator> (const preserve_comments&, const preserve_comments&);
bool operator>=(const preserve_comments&, const preserve_comments&);
void swap(preserve_comments&, preserve_comments&);
void swap(preserve_comments&, std::vector<std::string>&);
void swap(std::vector<std::string>&, preserve_comments&);
std::ostream& operator<<(std::ostream&, const preserve_comments&);
} //toml
```
## メンバ型
```cpp
using container_type = std::vector<std::string>;
using size_type = container_type::size_type;
using difference_type = container_type::difference_type;
using value_type = container_type::value_type;
using reference = container_type::reference;
using const_reference = container_type::const_reference;
using pointer = container_type::pointer;
using const_pointer = container_type::const_pointer;
using iterator = container_type::iterator;
using const_iterator = container_type::const_iterator;
using reverse_iterator = container_type::reverse_iterator;
using const_reverse_iterator = container_type::const_reverse_iterator;
```
## メンバ関数
### デフォルトコンストラクタ
```cpp
preserve_comments() = default;
```
空の`preserve_comments`を構築します。
### コピー・ムーブコンストラクタ
```cpp
preserve_comments(preserve_comments const&) = default;
preserve_comments(preserve_comments &&) = default;
```
`preserve_comments`をコピー・ムーブ構築します。
### コンストラクタ(`std::vector<std::string>`)
```cpp
explicit preserve_comments(const std::vector<std::string>& c);
explicit preserve_comments(std::vector<std::string>&& c);
```
`std::vector<std::string>`の内容を持つ`preserve_comments`を構築します。
### コンストラクタ(`discard_comments`)
```cpp
explicit preserve_comments(const discard_comments&);
```
空の`preserve_comments`を構築します。
### コンストラクタ(`Iterator`)
```cpp
template<typename InputIterator>
preserve_comments(InputIterator first, InputIterator last);
```
`std::string`を指す`InputIterator`が表す範囲から`preserve_comments`を構築します。
### コンストラクタ(`std::initializer_list`)
```cpp
preserve_comments(std::initializer_list<std::string> x);
```
`std::initializer_list<std::string>`が表す範囲から`preserve_comments`を構築します。
### コンストラクタ(サイズ指定)
```cpp
explicit preserve_comments(size_type n);
preserve_comments(size_type n, const std::string& x);
```
`n`個のコメントを持つ`preserve_comments`を構築します。
`std::string`を渡した場合、そのコメントを`n`個に複製します。
### デストラクタ
```cpp
~preserve_comments() = default;
```
`preserve_comments`を破棄します。
### `operator=(preserve_comments)`
```cpp
preserve_comments& operator=(preserve_comments const&) = default;
preserve_comments& operator=(preserve_comments &&) = default;
```
`preserve_comments`をコピー・ムーブ代入します。
### `operator=(std::vector<std::string>)`
```cpp
preserve_comments& operator=(const std::vector<std::string>& c);
preserve_comments& operator=(std::vector<std::string>&& c);
```
`std::vector<std::string>`をコピー・ムーブ代入します。
### `assign`
```cpp
template<typename InputIterator>
void assign(InputIterator first, InputIterator last);
void assign(std::initializer_list<std::string> ini);
void assign(size_type n, const std::string& val);
```
`std::vector<std::string>::assign`と同等の効果を持ちます。
### `insert`
```cpp
iterator insert(const_iterator p, const std::string& x);
iterator insert(const_iterator p, std::string&& x);
iterator insert(const_iterator p, size_type n, const std::string& x);
template<typename InputIterator>
iterator insert(const_iterator p, InputIterator first, InputIterator last);
iterator insert(const_iterator p, std::initializer_list<std::string> ini);
```
`std::vector<std::string>::insert`と同等の効果を持ちます。
### `emplace`
```cpp
template<typename ... Ts>
iterator emplace(const_iterator p, Ts&& ... args);
```
`std::vector<std::string>::insert`と同等の効果を持ちます。
### `erase`
```cpp
iterator erase(const_iterator pos);
iterator erase(const_iterator first, const_iterator last);
```
`std::vector<std::string>::insert`と同等の効果を持ちます。
### `swap`
```cpp
void swap(preserve_comments& other);
```
他の`preserve_comments`と内容を交換します。
### `push_back`
```cpp
void push_back(const std::string& v);
void push_back(std::string&& v);
```
`std::vector<std::string>::push_back`と同等の効果を持ちます。
### `pop_back`
```cpp
void pop_back();
```
`std::vector<std::string>::pop_back`と同等の効果を持ちます。
### `emplace_back`
```cpp
template<typename ... Ts>
void emplace_back(Ts&& ... args);
```
`std::vector<std::string>::emplace_back`と同等の効果を持ちます。
### `clear`
```cpp
void clear();
```
`std::vector<std::string>::clear`と同等の効果を持ちます。
### `size`
```cpp
size_type size() const noexcept;
```
`std::vector<std::string>::size`と同等の効果を持ちます。
### `max_size`
```cpp
size_type max_size() const noexcept;
```
`std::vector<std::string>::max_size`と同等の効果を持ちます。
### `capacity`
```cpp
size_type capacity() const noexcept;
```
`std::vector<std::string>::capacity`と同等の効果を持ちます。
### `empty`
```cpp
bool empty() const noexcept;
```
`std::vector<std::string>::empty`と同等の効果を持ちます。
### `reserve`
```cpp
void reserve(size_type n);
```
`std::vector<std::string>::reserve`と同等の効果を持ちます。
### `resize`
```cpp
void resize(size_type n);
void resize(size_type n, const std::string& c);
```
`std::vector<std::string>::resize`と同等の効果を持ちます。
### `shrink_to_fit`
```cpp
void shrink_to_fit();
```
`std::vector<std::string>::shrink_to_fit`と同等の効果を持ちます。
### `operator[]`
```cpp
reference operator[](const size_type n) noexcept;
const_reference operator[](const size_type n) const noexcept;
```
`std::vector<std::string>::operator[]`と同等の効果を持ちます。
### `at`
```cpp
reference at(const size_type n) ;
const_reference at(const size_type n) const;
```
`std::vector<std::string>::at`と同等の効果を持ちます。
### `front`
```cpp
reference front() noexcept;
const_reference front() const noexcept;
```
`std::vector<std::string>::front`と同等の効果を持ちます。
### `back`
```cpp
reference back() noexcept;
const_reference back() const noexcept;
```
`std::vector<std::string>::back`と同等の効果を持ちます。
### `data`
```cpp
pointer data() noexcept;
const_pointer data() const noexcept;
```
`std::vector<std::string>::data`と同等の効果を持ちます。
### `begin/end`
```cpp
iterator begin() noexcept;
iterator end() noexcept;
const_iterator begin() const noexcept;
const_iterator end() const noexcept;
const_iterator cbegin() const noexcept;
const_iterator cend() const noexcept;
```
`std::vector<std::string>::begin/end`と同等の効果を持ちます。
### `rbegin/rend`
```cpp
reverse_iterator rbegin() noexcept;
reverse_iterator rend() noexcept;
const_reverse_iterator rbegin() const noexcept;
const_reverse_iterator rend() const noexcept;
const_reverse_iterator crbegin() const noexcept;
const_reverse_iterator crend() const noexcept;
```
`std::vector<std::string>::rbegin/rend`と同等の効果を持ちます。
## 非メンバ関数
### 比較演算子
```cpp
bool operator==(const preserve_comments&, const preserve_comments&);
bool operator!=(const preserve_comments&, const preserve_comments&);
bool operator< (const preserve_comments&, const preserve_comments&);
bool operator<=(const preserve_comments&, const preserve_comments&);
bool operator> (const preserve_comments&, const preserve_comments&);
bool operator>=(const preserve_comments&, const preserve_comments&);
```
`std::vector<std::string>`と同様に比較を行います。
### `swap`
```cpp
void swap(preserve_comments&, preserve_comments&);
void swap(preserve_comments&, std::vector<std::string>&);
void swap(std::vector<std::string>&, preserve_comments&);
```
### ストリーム演算子
```cpp
std::ostream& operator<<(std::ostream&, const preserve_comments&);
```
コメントとして出力します。
先頭が`#`でない場合、`#`が補われます。
# `toml::discard_comments`
`discard_comments`は、コメントを破棄するコンテナです。
`std::vector<std::string>`が持つメンバ関数を全て持っていますが、内容を変更する関数を呼び出しても何も効果はなく、常に空になります。
```cpp
namespace toml
{
class discard_comments;
bool operator==(const discard_comments&, const discard_comments&);
bool operator!=(const discard_comments&, const discard_comments&);
bool operator< (const discard_comments&, const discard_comments&);
bool operator<=(const discard_comments&, const discard_comments&);
bool operator> (const discard_comments&, const discard_comments&);
bool operator>=(const discard_comments&, const discard_comments&);
void swap(discard_comments&, discard_comments&);
std::ostream& operator<<(std::ostream&, const discard_comments&);
} //toml
```
## メンバ型
```cpp
// container_type is not defined
using size_type = std::size_t;
using difference_type = std::ptrdiff_t;
using value_type = std::string;
using reference = std::string&;
using const_reference = std::string const&;
using pointer = std::string*;
using const_pointer = std::string const*;
using iterator = /* internal type: empty-iterator */
using const_iterator = /* internal type: empty-iterator */
using reverse_iterator = /* internal type: empty-iterator */
using const_reverse_iterator = /* internal type: empty-iterator */
```
### デフォルトコンストラクタ
```cpp
discard_comments() = default;
```
空の`discard_comments`を構築します。
### コピー・ムーブコンストラクタ
```cpp
discard_comments(discard_comments const&) = default;
discard_comments(discard_comments &&) = default;
```
`discard_comments`をコピー・ムーブ構築します。
### コンストラクタ(`std::vector<std::string>`)
```cpp
explicit discard_comments(const std::vector<std::string>& c);
explicit discard_comments(std::vector<std::string>&& c);
```
空の`discard_comments`を構築します。引数の内容は無視されます。
### コンストラクタ(`preserve_comments`)
```cpp
explicit discard_comments(const preserve_comments&);
```
空の`discard_comments`を構築します。引数の内容は無視されます。
### コンストラクタ(`Iterator`)
```cpp
template<typename InputIterator>
discard_comments(InputIterator first, InputIterator last);
```
空の`discard_comments`を構築します。引数の内容は無視されます。
### コンストラクタ(`std::initializer_list`)
```cpp
discard_comments(std::initializer_list<std::string> x);
```
空の`discard_comments`を構築します。引数の内容は無視されます。
### コンストラクタ(サイズ指定)
```cpp
explicit discard_comments(size_type n);
discard_comments(size_type n, const std::string& x);
```
空の`discard_comments`を構築します。引数の内容は無視されます。
### デストラクタ
```cpp
~discard_comments() = default;
```
`discard_comments`を破棄します。
### `operator=(discard_comments)`
```cpp
discard_comments& operator=(discard_comments const&) = default;
discard_comments& operator=(discard_comments &&) = default;
```
`discard_comments`をコピー・ムーブ代入します。
### `operator=(std::vector<std::string>)`
```cpp
discard_comments& operator=(const std::vector<std::string>& c);
discard_comments& operator=(std::vector<std::string>&& c);
```
何もしません。引数の内容は無視されます。
### `assign`
```cpp
template<typename InputIterator>
void assign(InputIterator first, InputIterator last);
void assign(std::initializer_list<std::string> ini);
void assign(size_type n, const std::string& val);
```
何もしません。引数の内容は無視されます。
### `insert`
```cpp
iterator insert(const_iterator p, const std::string& x);
iterator insert(const_iterator p, std::string&& x);
iterator insert(const_iterator p, size_type n, const std::string& x);
template<typename InputIterator>
iterator insert(const_iterator p, InputIterator first, InputIterator last);
iterator insert(const_iterator p, std::initializer_list<std::string> ini);
```
何もしません。引数の内容は無視されます。
### `emplace`
```cpp
template<typename ... Ts>
iterator emplace(const_iterator p, Ts&& ... args);
```
何もしません。引数の内容は無視されます。
### `erase`
```cpp
iterator erase(const_iterator pos);
iterator erase(const_iterator first, const_iterator last);
```
何もしません。引数の内容は無視されます。
### `swap`
```cpp
void swap(discard_comments& other);
```
他の`discard_comments`と内容を交換します。
### `push_back`
```cpp
void push_back(const std::string& v);
void push_back(std::string&& v);
```
何もしません。引数の内容は無視されます。
### `pop_back`
```cpp
void pop_back();
```
何もしません。引数の内容は無視されます。
### `emplace_back`
```cpp
template<typename ... Ts>
void emplace_back(Ts&& ... args);
```
何もしません。引数の内容は無視されます。
### `clear`
```cpp
void clear();
```
何もしません。引数の内容は無視されます。
### `size`
```cpp
size_type size() const noexcept;
```
常に`0`を返します。
### `max_size`
```cpp
size_type max_size() const noexcept;
```
常に`0`を返します。
### `capacity`
```cpp
size_type capacity() const noexcept;
```
常に`0`を返します。
### `empty`
```cpp
bool empty() const noexcept;
```
常に`true`を返します。
### `reserve`
```cpp
void reserve(size_type n);
```
何もしません。引数の内容は無視されます。
### `resize`
```cpp
void resize(size_type n);
void resize(size_type n, const std::string& c);
```
何もしません。引数の内容は無視されます。
### `shrink_to_fit`
```cpp
void shrink_to_fit();
```
何もしません。引数の内容は無視されます。
### `operator[]`
```cpp
reference operator[](const size_type n) noexcept;
const_reference operator[](const size_type n) const noexcept;
```
未定義動作です。
### `at`
```cpp
reference at(const size_type n) ;
const_reference at(const size_type n) const;
```
`std::out_of_range`を送出します。
### `front`
```cpp
reference front() noexcept;
const_reference front() const noexcept;
```
未定義動作です。
### `back`
```cpp
reference back() noexcept;
const_reference back() const noexcept;
```
未定義動作です。
### `data`
```cpp
pointer data() noexcept;
const_pointer data() const noexcept;
```
常に`nullptr`を返します。
### `begin/end`
```cpp
iterator begin() noexcept;
iterator end() noexcept;
const_iterator begin() const noexcept;
const_iterator end() const noexcept;
const_iterator cbegin() const noexcept;
const_iterator cend() const noexcept;
```
内部で定義された`empty-iterator`を返します。
`empty-iterator`はインクリメントやデクリメントしても同じ値でとどまり、全ての値が同値です。
`empty-iterator`が指す先にアクセスすると常に`std::terminate`が呼び出されます。
### `rbegin/rend`
```cpp
reverse_iterator rbegin() noexcept;
reverse_iterator rend() noexcept;
const_reverse_iterator rbegin() const noexcept;
const_reverse_iterator rend() const noexcept;
const_reverse_iterator crbegin() const noexcept;
const_reverse_iterator crend() const noexcept;
```
内部で定義された`empty-iterator`を返します。
`empty-iterator`はインクリメントやデクリメントしても同じ値でとどまり、全ての値が同値です。
`empty-iterator`が指す先にアクセスすると常に`std::terminate`が呼び出されます。
## 非メンバ関数
### 比較演算子
```cpp
bool operator==(const discard_comments&, const discard_comments&);
bool operator!=(const discard_comments&, const discard_comments&);
bool operator< (const discard_comments&, const discard_comments&);
bool operator<=(const discard_comments&, const discard_comments&);
bool operator> (const discard_comments&, const discard_comments&);
bool operator>=(const discard_comments&, const discard_comments&);
```
`discard_comments`は全て同じ値です。`==`には常に`true`を、`!=`には常に`false`を返します。
### `swap`
```cpp
void swap(discard_comments&, discard_comments&);
```
二つの`discard_comments`を交換します。
### ストリーム演算子
```cpp
std::ostream& operator<<(std::ostream&, const discard_comments&);
```
何も出力しません。
# 関連項目
- [value.hpp]({{<ref "value.md">}})

33
docs/content.ja/docs/reference/conversion.md Normal file
View File

@@ -0,0 +1,33 @@
+++
title = "conversion.hpp"
type = "docs"
+++
# conversion.hpp
`toml::get`や`toml::find`でユーザー定義型をサポートするための変換関数を自動定義するマクロを提供します。
```cpp
TOML11_DEFINE_CONVERSION_NON_INTRUSIVE(NAME, ...)
```
## 例
```cpp
namespace foo
{
struct Foo
{
std::string s;
double d;
int i;
};
} // foo
TOML11_DEFINE_CONVERSION_NON_INTRUSIVE(foo::Foo, s, d, i)
```
# 関連項目
- [from.hpp]({{<ref "from.md">}})
- [into.hpp]({{<ref "into.md">}})

779
docs/content.ja/docs/reference/datetime.md Normal file
View File

@@ -0,0 +1,779 @@
+++
title = "datetime.hpp"
type = "docs"
+++
# datetime.hpp
TOMLの`datetime`で使用される、日時情報を保存するクラスを定義します。
# `enum class month_t`
月を指定する`enum class`です。
`std::tm`との関係で、`local_date`は1月を`0`としています。
混乱を避けるため、月の名前で指定できるよう`month_t`が用意されています。
```cpp
namespace toml
{
enum class month_t : std::uint8_t
{
Jan = 0,
Feb = 1,
Mar = 2,
Apr = 3,
May = 4,
Jun = 5,
Jul = 6,
Aug = 7,
Sep = 8,
Oct = 9,
Nov = 10,
Dec = 11
};
}
```
# `local_date`
日付を保持する構造体です。
`year`は西暦を、`month`は`std::tm`との対応のため1月を`0`として、`day`は日付を保持します。
```cpp
namespace toml
{
struct local_date
{
std::int16_t year;
std::uint8_t month;
std::uint8_t day;
local_date() = default;
~local_date() = default;
local_date(local_date const&) = default;
local_date(local_date&&) = default;
local_date& operator=(local_date const&) = default;
local_date& operator=(local_date&&) = default;
local_date(int y, month_t m, int d);
explicit local_date(const std::tm& t);
explicit local_date(const std::chrono::system_clock::time_point& tp);
explicit local_date(const std::time_t t);
operator std::chrono::system_clock::time_point() const;
operator std::time_t() const;
};
bool operator==(const local_date&, const local_date&);
bool operator!=(const local_date&, const local_date&);
bool operator< (const local_date&, const local_date&);
bool operator<=(const local_date&, const local_date&);
bool operator> (const local_date&, const local_date&);
bool operator>=(const local_date&, const local_date&);
std::ostream& operator<<(std::ostream& os, const local_date& date);
std::string to_string(const local_date& date);
}
```
## メンバ変数
### `year`
```cpp
std::int16_t year;
```
西暦です。オフセットはありません。`2024`年は`2024`です。
### `month`
```cpp
std::uint8_t month;
```
月を表します。`std::tm`との対応のため、1月は`0`, 2月は`1`と続きます。
混乱を避けるため、構築の際は`month_t`を使用します。
### `day`
```cpp
std::uint8_t day;
```
日付を表します。1日は`1`です。
## メンバ関数
### コンストラクタ
```cpp
local_date() = default;
```
デフォルト実装を使用します。
### デストラクタ
```cpp
~local_date() = default;
```
デフォルト実装を使用します。
### コピー・ムーブコンストラクタ
```cpp
local_date(local_date const&) = default;
local_date(local_date&&) = default;
```
デフォルト実装を使用します。
### コピー・ムーブ代入演算子
```cpp
local_date& operator=(local_date const&) = default;
local_date& operator=(local_date&&) = default;
```
デフォルト実装を使用します。
### コンストラクタ(`int year, month_t month, int day`)
```cpp
local_date(int y, month_t m, int d);
```
指定した値から`local_date`を構築します。
境界チェックなどは行いません。
### コンストラクタ(`std::tm`)
```cpp
local_date(const std::tm&);
```
指定した値から`local_date`を構築します。
### コンストラクタ(`std::chrono::system_clock::time_point`)
```cpp
local_date(const std::chrono::system_clock::time_point&);
```
指定した値から`local_date`を構築します。
タイムゾーンは実行環境でのものが選択されます。
### コンストラクタ(`std::time_t`)
```cpp
local_date(const std::time_t);
```
指定した値から`local_date`を構築します。
タイムゾーンは実行環境でのものが選択されます。
### `operator std::chrono::system_clock::time_point`
```cpp
operator std::chrono::system_clock::time_point() const;
```
`std::chrono::system_clock::time_point`に変換します。
タイムゾーンは実行環境でのものが選択されます。
時刻は0時00分とします。
### `operator std::time_t`
```cpp
operator std::time_t() const;
```
`std::time_t`に変換します。
タイムゾーンは実行環境でのものが選択されます。
時刻は0時00分とします。
## 非メンバ関数
### 比較演算子
```cpp
bool operator==(const local_date&, const local_date&);
bool operator!=(const local_date&, const local_date&);
bool operator< (const local_date&, const local_date&);
bool operator<=(const local_date&, const local_date&);
bool operator> (const local_date&, const local_date&);
bool operator>=(const local_date&, const local_date&);
```
日付の順序によって比較します。
### ストリーム出力演算子
```cpp
std::ostream& operator<<(std::ostream& os, const local_date& date);
```
TOMLのデフォルトのフォーマットで出力を行います。
### `to_string`
```cpp
std::string to_string(const local_date& date);
```
TOMLのデフォルトのフォーマットで文字列化します。
# `local_time`
```cpp
namespace toml
{
struct local_time
{
std::uint8_t hour; // [0, 23]
std::uint8_t minute; // [0, 59]
std::uint8_t second; // [0, 60]
std::uint16_t millisecond; // [0, 999]
std::uint16_t microsecond; // [0, 999]
std::uint16_t nanosecond; // [0, 999]
local_time(int h, int m, int s, int ms = 0, int us = 0, int ns = 0);
explicit local_time(const std::tm& t);
template<typename Rep, typename Period>
explicit local_time(const std::chrono::duration<Rep, Period>& t);
operator std::chrono::nanoseconds() const;
local_time() = default;
~local_time() = default;
local_time(local_time const&) = default;
local_time(local_time&&) = default;
local_time& operator=(local_time const&) = default;
local_time& operator=(local_time&&) = default;
};
bool operator==(const local_time& lhs, const local_time& rhs);
bool operator!=(const local_time& lhs, const local_time& rhs);
bool operator< (const local_time& lhs, const local_time& rhs);
bool operator<=(const local_time& lhs, const local_time& rhs);
bool operator> (const local_time& lhs, const local_time& rhs);
bool operator>=(const local_time& lhs, const local_time& rhs);
std::ostream& operator<<(std::ostream& os, const local_time& time);
std::string to_string(const local_time& time);
}
```
## メンバ変数
### `hour`
```cpp
std::uint8_t hour;
```
時間を表します。`0`から`23`の値を取ります。
### `minute`
```cpp
std::uint8_t minute; // [0, 59]
```
分を表します。`0`から`59`の値を取ります。
### `second`
```cpp
std::uint8_t second; // [0, 60]
```
秒を表します。`0`から`60`の値を取ります。
### `millisecond`
```cpp
std::uint16_t millisecond; // [0, 999]
```
ミリ秒を表します。`0`から`999`の値を取ります。
### `microsecond`
```cpp
std::uint16_t microsecond; // [0, 999]
```
マイクロ秒を表します。`0`から`999`の値を取ります。
### `nanosecond`
```cpp
std::uint16_t nanosecond; // [0, 999]
```
ナノ秒を表します。`0`から`999`の値を取ります。
## メンバ関数
### デフォルトコンストラクタ
```cpp
local_time() = default;
```
全ての値を`0`で初期化します。
### コンストラクタ(h, m, s, ms = 0, us = 0, ns = 0)
```cpp
local_time(int h, int m, int s, int ms = 0, int us = 0, int ns = 0);
```
指定された時刻を使って構築します。
境界チェックは行われません。
### コンストラクタ(`std::tm`)
```cpp
explicit local_time(const std::tm& t);
```
`std::tm`の`tm_hour`, `tm_min`, `tm_sec`を使って構築します。
サブセコンドは全て`0`で初期化されます。
### コンストラクタ(`std::chrono::duration`)
```cpp
template<typename Rep, typename Period>
explicit local_time(const std::chrono::duration<Rep, Period>& t);
```
`duration`をその日の0時からの時間として構築します。
### `operator std::chrono::nanoseconds`
```cpp
operator std::chrono::nanoseconds() const;
```
`std::chrono::nanoseconds`へ変換します。
## 非メンバ関数
### 比較演算子
```cpp
bool operator==(const local_time& lhs, const local_time& rhs);
bool operator!=(const local_time& lhs, const local_time& rhs);
bool operator< (const local_time& lhs, const local_time& rhs);
bool operator<=(const local_time& lhs, const local_time& rhs);
bool operator> (const local_time& lhs, const local_time& rhs);
bool operator>=(const local_time& lhs, const local_time& rhs);
```
時刻の値によって比較を行います。
### ストリーム演算子
```cpp
std::ostream& operator<<(std::ostream& os, const local_time& time);
```
TOMLのデフォルトのフォーマットで出力を行います。
### `to_string`
```cpp
std::string to_string(const local_time& time);
```
TOMLのデフォルトのフォーマットで文字列化します。
# `time_offset`
```cpp
namespace toml
{
struct time_offset
{
std::int8_t hour{0}; // [-12, 12]
std::int8_t minute{0}; // [-59, 59]
time_offset(int h, int m);
operator std::chrono::minutes() const;
time_offset() = default;
~time_offset() = default;
time_offset(time_offset const&) = default;
time_offset(time_offset&&) = default;
time_offset& operator=(time_offset const&) = default;
time_offset& operator=(time_offset&&) = default;
};
bool operator==(const time_offset&, const time_offset&);
bool operator!=(const time_offset&, const time_offset&);
bool operator< (const time_offset&, const time_offset&);
bool operator<=(const time_offset&, const time_offset&);
bool operator> (const time_offset&, const time_offset&);
bool operator>=(const time_offset&, const time_offset&);
std::ostream& operator<<(std::ostream& os, const time_offset& offset);
std::string to_string(const time_offset& offset);
}
```
## メンバ変数
### `hour`
```cpp
std::int8_t hour{0}; // [-12, 12]
```
時間のオフセットです。-12から+12の範囲の値を取ります。
### `minute`
```cpp
std::int8_t minute{0}; // [-59, 59]
```
分のオフセットです。-59から+59の範囲の値を取ります。
## メンバ関数
### コンストラクタ
```cpp
time_offset(int h, int m);
```
時間と分を取って構築します。
境界チェックは行いません。
### `operator std::chrono::minutes`
```cpp
operator std::chrono::minutes() const;
```
`std::chrono::minutes`への変換を行います。
## 非メンバ関数
### 比較演算子
```cpp
bool operator==(const time_offset&, const time_offset&);
bool operator!=(const time_offset&, const time_offset&);
bool operator< (const time_offset&, const time_offset&);
bool operator<=(const time_offset&, const time_offset&);
bool operator> (const time_offset&, const time_offset&);
bool operator>=(const time_offset&, const time_offset&);
```
時刻の長さで比較します。
### ストリーム出力演算子
```cpp
std::ostream& operator<<(std::ostream& os, const time_offset&);
```
TOMLのデフォルトのフォーマットで出力を行います。
### `to_string`
```cpp
std::string to_string(const time_offset&);
```
TOMLのデフォルトのフォーマットで文字列化します。
# `local_datetime`
```cpp
namespace toml
{
struct local_datetime
{
local_date date;
local_time time;
local_datetime(local_date d, local_time t);
explicit local_datetime(const std::tm& t);
explicit local_datetime(const std::chrono::system_clock::time_point& tp);
explicit local_datetime(const std::time_t t);
operator std::chrono::system_clock::time_point() const;
operator std::time_t() const;
local_datetime() = default;
~local_datetime() = default;
local_datetime(local_datetime const&) = default;
local_datetime(local_datetime&&) = default;
local_datetime& operator=(local_datetime const&) = default;
local_datetime& operator=(local_datetime&&) = default;
};
bool operator==(const local_datetime&, const local_datetime&);
bool operator!=(const local_datetime&, const local_datetime&);
bool operator< (const local_datetime&, const local_datetime&);
bool operator<=(const local_datetime&, const local_datetime&);
bool operator> (const local_datetime&, const local_datetime&);
bool operator>=(const local_datetime&, const local_datetime&);
std::ostream& operator<<(std::ostream& os, const local_datetime& dt);
std::string to_string(const local_datetime& dt);
}
```
## メンバ変数
### `local_date date`
```cpp
local_date date;
```
日付部分のデータを保持します。
### `local_time time`
```cpp
local_time time;
```
時刻部分のデータを保持します。
## メンバ関数
### デフォルトコンストラクタ
`date`, `time`の双方をデフォルト構築します。
### コンストラクタ(`local_date, local_time`)
指定された`date`と`time`で構築します。
### コンストラクタ(`std::tm`)
`std::tm`から構築します。
タイムゾーンは実行環境でのものが選択されます。
### コンストラクタ(`std::chrono::system_clock::time_point`)
`std::chrono::system_clock::time_point`から構築します。
タイムゾーンは実行環境でのものが選択されます。
### コンストラクタ(`std::time_t`)
`std::time_t`から構築します。
タイムゾーンは実行環境でのものが選択されます。
### `operator std::chrono::system_clock::time_point`
`std::chrono::system_clock::time_point`へ変換します。
### `operator std::time_t`
`std::time_t`へ変換します。
## 非メンバ関数
### 比較演算子
```cpp
bool operator==(const local_datetime&, const local_datetime&);
bool operator!=(const local_datetime&, const local_datetime&);
bool operator< (const local_datetime&, const local_datetime&);
bool operator<=(const local_datetime&, const local_datetime&);
bool operator> (const local_datetime&, const local_datetime&);
bool operator>=(const local_datetime&, const local_datetime&);
```
日付順で比較します。
### ストリーム出力演算子
```cpp
std::ostream& operator<<(std::ostream& os, const local_datetime&);
```
TOMLのデフォルトのフォーマットで出力を行います。
### `to_string`
```cpp
std::string to_string(const local_datetime&);
```
TOMLのデフォルトのフォーマットで文字列化します。
# `offset_datetime`
```cpp
namespace toml
{
struct offset_datetime
{
local_date date;
local_time time;
time_offset offset;
offset_datetime(local_date d, local_time t, time_offset o);
offset_datetime(const local_datetime& dt, time_offset o);
explicit offset_datetime(const local_datetime& ld);
explicit offset_datetime(const std::chrono::system_clock::time_point& tp);
explicit offset_datetime(const std::time_t& t);
explicit offset_datetime(const std::tm& t);
operator std::chrono::system_clock::time_point() const;
operator std::time_t() const;
offset_datetime() = default;
~offset_datetime() = default;
offset_datetime(offset_datetime const&) = default;
offset_datetime(offset_datetime&&) = default;
offset_datetime& operator=(offset_datetime const&) = default;
offset_datetime& operator=(offset_datetime&&) = default;
};
bool operator==(const offset_datetime&, const offset_datetime&);
bool operator!=(const offset_datetime&, const offset_datetime&);
bool operator< (const offset_datetime&, const offset_datetime&);
bool operator<=(const offset_datetime&, const offset_datetime&);
bool operator> (const offset_datetime&, const offset_datetime&);
bool operator>=(const offset_datetime&, const offset_datetime&);
std::ostream& operator<<(std::ostream& os, const offset_datetime& dt);
std::string to_string(const offset_datetime& dt);
}
```
## メンバ変数
### `date`
```cpp
local_date date;
```
日付部分のデータを保持します。
### `time`
```cpp
local_time time;
```
時刻部分のデータを保持します。
### `offset`
```cpp
time_offset offset;
```
オフセット部分のデータを保持します。
## メンバ関数
### デフォルトコンストラクタ
`date`, `time`, `offset`を全てデフォルト構築します。
### コンストラクタ(`local_date, local_time, time_offset`)
指定された`date`, `time`, `offset`で構築します。
### コンストラクタ(`local_datetime, time_offset`)
`local_datetime`と`offset`から構築します。
### コンストラクタ(`std::tm`)
`std::tm`から構築します。
タイムゾーンはUTC(00:00)になります。
### コンストラクタ(`std::chrono::system_clock::time_point`)
`std::chrono::system_clock::time_point`から構築します。
タイムゾーンはUTC(00:00)になります。
### コンストラクタ(`std::time_t`)
`std::time_t`から構築します。
タイムゾーンはUTC(00:00)になります。
### `operator std::chrono::system_clock::time_point`
`std::chrono::system_clock::time_point`へ変換します。
タイムゾーンはUTC(00:00)になります。
### `operator std::time_t`
`std::time_t`へ変換します。
タイムゾーンはUTC(00:00)になります。
## 非メンバ関数
### 比較演算子
```cpp
bool operator==(const offset_datetime&, const offset_datetime&);
bool operator!=(const offset_datetime&, const offset_datetime&);
bool operator< (const offset_datetime&, const offset_datetime&);
bool operator<=(const offset_datetime&, const offset_datetime&);
bool operator> (const offset_datetime&, const offset_datetime&);
bool operator>=(const offset_datetime&, const offset_datetime&);
```
日付順で比較します。
同じ日付の場合、タイムゾーン順で比較されます。
### ストリーム出力演算子
```cpp
std::ostream& operator<<(std::ostream& os, const offset_datetime&);
```
TOMLのデフォルトのフォーマットで出力を行います。
### `to_string`
```cpp
std::string to_string(const offset_datetime&);
```
TOMLのデフォルトのフォーマットで文字列化します。

151
docs/content.ja/docs/reference/error_info.md Normal file
View File

@@ -0,0 +1,151 @@
+++
title = "error_info.hpp"
type = "docs"
+++
# error_info.hpp
`error_info.hpp`では、`error_info`と、それをフォーマットする関数が定義されます。
# `toml::error_info`
```cpp
namespace toml
{
struct error_info
{
error_info(std::string t, source_location l, std::string m, std::string s = "");
error_info(std::string t, std::vector<std::pair<source_location, std::string>> l, std::string s = "");
std::string const& title() const noexcept;
std::string & title() noexcept;
std::vector<std::pair<source_location, std::string>> const& locations() const noexcept;
void add_locations(source_location loc, std::string msg) noexcept;
std::string const& suffix() const noexcept;
std::string & suffix() noexcept;
};
template<typename ... Ts>
error_info make_error_info(
std::string title, source_location loc, std::string msg, Ts&& ... tail);
std::string format_error(const std::string& errkind, const error_info& err);
std::string format_error(const error_info& err);
template<typename ... Ts>
std::string format_error(std::string title,
source_location loc, std::string msg, Ts&& ... tail);
std::ostream& operator<<(std::ostream& os, const error_info& e);
}
```
## メンバ関数
### コンストラクタ(`title, loc, msg, suffix`)
指定されたタイトル、位置情報、メッセージ、suffixから`error_info`を構築します。
`suffix`はデフォルトで空です。
### コンストラクタ(`title, [{loc, msg}, ...], suffix`)
指定されたタイトル、位置情報とメッセージの配列、そして`suffix`から`error_info`を構築します。
`suffix`はデフォルトで空です。
## メンバ関数
### `std::string title()`
エラーメッセージのタイトルです。
### `std::vector<std::pair<source_location, std::string>> locations()`
エラーの発生した位置とそれに関するメッセージです。
複数指定可能です。
### `std::string suffix()`
最後に表示するメッセージです。ヒントや補足を表示します。
## 非メンバ関数
### `make_error_info`
```cpp
template<typename ... Ts>
error_info make_error_info(
std::string title, source_location loc, std::string msg, Ts&& ... tail);
```
新しく`error_info`を構築します。
`source_location`または`basic_value`の後には、それに関する`msg`が続かなければなりません。
[`value.hpp`]({{<ref "docs/reference/value#tomlmake_error_info">}})
では、 `source_location` の代わりに `toml::basic_value` を渡した際のオーバーロードが追加されます。
末尾には`suffix`を渡すことが可能です。
### `format_error`
`error_info` を以下のようにフォーマットします。
```
{title}
--> {locations().at(0).first.file_name()}
|
1 | {locations().at(0).first.line()}
| ^-- {locations().at(0).second}
|
2 | {locations().at(1).first.line()}
| ^-- {locations().at(1).second}
{suffix}
```
二つの `source_location` のファイル名が異なる場合は、ファイル名が再度表示されます。
```cpp
std::string format_error(const std::string& errkind, const error_info& err);
std::string format_error(const error_info& err);
```
`error_info`をフォーマットします。
`errkind`が与えられなかった場合、赤色太字の`[error]`が`title`の前につけ足されます。
`errkind`が与えられた場合（空文字列の場合も含みます）、それが`[error]`の代わりに表示されます。
```cpp
namespace toml
{
template<typename ... Ts>
std::string format_error(std::string title,
source_location loc, std::string msg, Ts&& ... tail);
} // toml
```
`make_error_info` を使って作成した `error_info` を `format_error` でフォーマットした文字列を返します。
[`value.hpp`]({{<ref "docs/reference/value#tomlformat_error">}})
では、 `source_location` の代わりに `toml::basic_value` を渡した際のオーバーロードが追加されます。
### ストリーム演算子
```cpp
std::ostream& operator<<(std::ostream& os, const error_info& e);
```
`format_error(e)`を呼び出し、それを出力します。
# 関連項目
- [color.hpp]({{<ref "color.md">}})
- [parser.hpp]({{<ref "parser.md">}})
- [source_location.hpp]({{<ref "source_location.md">}})

41
docs/content.ja/docs/reference/exception.md Normal file
View File

@@ -0,0 +1,41 @@
+++
title = "exception.hpp"
type = "docs"
+++
# exception.hpp
# `toml::exception`
toml11で定義される例外型の基底クラスです。
```cpp
namespace toml
{
struct exception : public std::exception
{
public:
virtual ~exception() noexcept override = default;
virtual const char* what() const noexcept override {return "";}
};
} // toml
```
## メンバ関数
### デストラクタ
```cpp
virtual ~exception() noexcept override = default;
```
派生する際に上書きします。
### `what`
```cpp
virtual const char* what() const noexcept override {return "";}
```
エラーメッセージを返します。派生する際に上書きします。

251
docs/content.ja/docs/reference/find.md Normal file
View File

@@ -0,0 +1,251 @@
+++
title = "find.hpp"
type = "docs"
+++
# find.hpp
`toml::value`から値を検索し、同時に（必要な場合）型変換を行う関数です。
{{< hint info >}}
`toml::value` は格納する型を変更でき、`toml::find`はそれらに対応しているので、
厳密には全て `toml::basic_value<TC>` が使われています。ただしこれでは冗長なので、
関数の宣言と特に区別しなければならない場合を除いて、簡単のため説明文では `toml::value` と書きます。
説明文では、テンプレートパラメータ`TC`を変更して型が変更されていれば
`toml::value::integer_type` などの型は追従して変更されると解釈してください。
{{< /hint >}}
# `toml::find`
## 概要
`toml::find`には、取り出したい型をテンプレート引数で、検索したい値のキーを引数で与えます。
```cpp
template<typename T, typename TC, typename ... Keys>
T find(const basic_value<TC>& v, Keys ... keys);
```
サポートされている `T` の種類と変換の挙動に関しては、 `toml::get` と同様です。
`T` が指定されなかった場合、 `toml::value` が返されます。
キーは、 `toml::value::key_type` または `std::size_t` です。
複数個のキーが与えられた場合は、サブテーブルや配列に対して再帰的に検索が行われます。
`toml::value::key_type` が与えられた場合は `toml::table` として、 `std::size_t` が与えられた場合は `toml::array` として解釈されます。
### 再帰的な検索に関しての注意
TOMLには通常の bare key の他に、 `"` や `'` で囲まれた quoted key というものがあります。
quoted key を使うと、 `"foo.bar" = "baz"` というようなキーを書くことができ、この場合はサブテーブルは構築されず、キーは `foo.bar`となります。
このようなパターンに対応するため、toml11ではキーの中に`.`が含まれていても分割は行わず、そのままの文字列で検索を行います。
以下のTOMLファイルを考えます。
```toml
[foo]
[foo.bar]
baz = "hoge"
["foo.bar"]
baz = "fuga"
```
これに対応する`toml::find`の書き方は以下の通りです。
```cpp
const auto input = toml::parse("input.toml");
const auto baz1 = toml::find<std::string>(input, "foo", "bar", "baz"); // hoge
const auto baz2 = toml::find<std::string>(input, "foo.bar", "baz"); // fuga
```
参考：[toml.io/ja/v1.0.0#キー](https://toml.io/ja/v1.0.0#%E3%82%AD%E3%83%BC)
## `toml::find(value, key)`
`value` を `toml::table` として `key` を検索したあと、 `toml::get` で変換を行います。
```cpp
template<typename T, typename TC>
/* toml::get<T>(const value&) と同等 */ find(
const basic_value<TC>& v, const typename basic_value<TC>::key_type& ky);
template<typename T, typename TC>
/* toml::get<T>(value&) と同等 */ find(
basic_value<TC>& v, const typename basic_value<TC>::key_type& ky);
template<typename T, typename TC>
/* toml::get<T>(value&&) と同等 */ find(
basic_value<TC>&& v, const typename basic_value<TC>::key_type& ky);
```
`T`が指定されない場合は、変換を行わず`toml::value`を返します。
```cpp
template<typename TC>
basic_value<TC> const& find(
basic_value<TC> const& v, const typename basic_value<TC>::key_type& ky);
template<typename TC>
basic_value<TC>& find(
basic_value<TC>& v, const typename basic_value<TC>::key_type& ky);
template<typename TC>
basic_value<TC> find(
basic_value<TC>&& v, const typename basic_value<TC>::key_type& ky);
```
### 例外
`toml::value` が `table` を保持していなかった場合、 `toml::type_error` が送出されます。
格納している `table` が指定された要素を持っていなかった場合、 `std::out_of_range` が送出されます。
指定された要素が `T` に変換できない場合 （ `toml::get` が変換に失敗する場合） 、
`toml::type_error` が送出されます。
## `toml::find(value, index)`
`value` を `toml::array` として `index` 番目にアクセスし、 `toml::get` で変換を行います。
```cpp
template<typename T, typename TC>
/* toml::get<T>(const value&) と同等 */ find(
const basic_value<TC>& v, const std::size_t index);
template<typename T, typename TC>
/* toml::get<T>(value&) と同等 */ find(
basic_value<TC>& v, const std::size_t index);
template<typename T, typename TC>
/* toml::get<T>(value&&) と同等 */ find(
basic_value<TC>&& v, const std::size_t index);
```
`T`が指定されない場合は、変換を行わず`toml::value`を返します。
```cpp
template<typename TC>
basic_value<TC> const& find(basic_value<TC> const& v, const std::size_t ky);
template<typename TC>
basic_value<TC>& find(basic_value<TC>& v, const std::size_t ky);
template<typename TC>
basic_value<TC> find(basic_value<TC>&& v, const std::size_t ky);
```
### 例外
`toml::value` が `array` を保持していなかった場合、 `toml::type_error` が送出されます。
格納している `array` が指定された数の要素を持っていなかった場合、`std::out_of_range`が送出されます。
指定された要素が `T` に変換できない場合 （ `toml::get` が変換に失敗する場合） 、
`toml::type_error` が送出されます。
## `toml::find(value, keys...)`
```cpp
template<typename T, typename TC, typename K1, typename K2, typename ... Ks>
/* toml::get<T>(const value&) と同等 */ find(
const basic_value<TC>& v, const K1& k1, const K2& k2, const Ks& ... ks);
template<typename T, typename TC, typename K1, typename K2, typename ... Ks>
/* toml::get<T>(value&) と同等 */ find(
basic_value<TC>& v, const K1& k1, const K2& k2, const Ks& ... ks);
template<typename T, typename TC, typename K1, typename K2, typename ... Ks>
/* toml::get<T>(value&&) と同等 */ find(
basic_value<TC>&& v, const K1& k1, const K2& k2, const Ks& ... ks);
```
再帰的に`toml::find`が呼び出されます。
失敗する条件とその際に送出される例外は `toml::find` と同じです。
# `toml::find_or(value, key, fallback)`
```cpp
template<typename T, typename TC, typename Key>
T find_or(const basic_value<TC>& v, const Key& key, T&& opt);
```
`find_or` は失敗した際のためのデフォルト値を受け取ることで、失敗時に例外を投げないようにします。
このデフォルト値は受け取る型`T`と同じ型でなければなりません。
よって、 `toml::find<T>` とは違って、 `find_or` では `T` を指定せずとも推論されます。
`find_or<T>`のように `T` を指定することもできますが、その場合は常に新規な値が返されます。
参照を取得したい場合は、 `T` を指定しないでください。
## `T`が`basic_value`である場合
```cpp
template<typename TC, typename K>
basic_value<TC>& find_or(basic_value<TC>& v, const K& key, basic_value<TC>& opt) noexcept
template<typename TC, typename K>
basic_value<TC> const& find_or(const basic_value<TC>& v, const K& key, const basic_value<TC>& opt) noexcept
```
対応する値を検索し、変換せずに返します。変換が必要ないため、参照を返すことができます。
値が見つからなかった場合、デフォルト値を返します。
## `T`が`toml::value::{some_type}`である場合
```cpp
template<typename T, typename TC, typename K>
T& find_or(basic_value<TC>& v, const K& key, T& opt) noexcept
template<typename T, typename TC, typename K>
T const& find_or(const basic_value<TC>& v, const K& key, const T& opt) noexcept
```
対応する値を検索し、変換せずに返します。変換が必要ないため、参照を返すことができます。
値が見つからなかった場合、あるいは異なる型が格納されていた場合、デフォルト値を返します。
## `T`が`const char*`である場合
```cpp
template<typename TC, typename K>
std::string find_or(const basic_value<TC>& v, const K& k, const char* opt)
```
対応する値を検索し、 `std::string` として返します。
失敗時に `const char*` から `std::string` を構築するため、参照を返すことはできません。
## `T`がその他の型である場合
```cpp
template<typename T, typename TC, typename K>
T find_or(const basic_value<TC>& v, const K& key, T opt)
```
対応する値を検索し、 `T` に変換して返します。
変換を行うため、参照を返すことはできません。
## 複数のキーが与えられた場合
```cpp
template<typename Value, typename K1, typename K2, typename K3, typename ... Ks>
auto find_or(Value&& v, const K1& k1, const K2& k2, K3&& k3, Ks&& ... keys) noexcept
-> decltype(find_or(v, k2, std::forward<K3>(k3), std::forward<Ks>(keys)...))
```
キーの列の最後の要素がデフォルト値であると解釈して、再帰的に`find_or`を適用します。
`T` の推論結果が `toml::value` または `toml::value::some_type` になる場合、参照を返すことができます。
`T` を明示的に指定した場合、常に変換を行います。
# 関連項目
- [get.hpp]({{<ref "get.md">}})
- [value.hpp]({{<ref "value.md">}})

448
docs/content.ja/docs/reference/format.md Normal file
View File

@@ -0,0 +1,448 @@
+++
title = "format.hpp"
type = "docs"
+++
# format.hpp
`toml::value`のフォーマット情報を持つ構造体と列挙型を定義します。
# `indent_char`
インデント情報を表す列挙体です。
```cpp
enum class indent_char : std::uint8_t
{
space, // use space
tab, // use tab
none // no indent
};
std::ostream& operator<<(std::ostream& os, const indent_char& c);
std::string to_string(const indent_char);
```
`none`を選んだ場合、super tableでの値によらず、インデントは使用されません。
シリアライズ対象の値のなかに`space`と`tab`を指定する値が同時に存在していた場合、その動作は未規定で、指定していない方の文字が出現する可能性があります。
# `boolean_format_info`
`boolean`のフォーマット情報です。
```cpp
struct boolean_format_info {};
bool operator==(const boolean_format_info&, const boolean_format_info&) noexcept;
bool operator!=(const boolean_format_info&, const boolean_format_info&) noexcept;
```
`boolean`のフォーマット方法は一通りしかないため、設定できる値を持ちません。
# `integer_format`
```cpp
enum class integer_format : std::uint8_t
{
dec = 0,
bin = 1,
oct = 2,
hex = 3,
};
std::ostream& operator<<(std::ostream& os, const integer_format f);
std::string to_string(const integer_format);
```
`integer`の基数を指定します。
# `integer_format_info`
```cpp
struct integer_format_info
{
integer_format fmt = integer_format::dec;
std::size_t width = 0; // minimal width (may exceed)
std::size_t spacer = 0; // position of `_` (if 0, no spacer)
std::string suffix = ""; // _suffix (library extension)
};
bool operator==(const integer_format_info&, const integer_format_info&) noexcept;
bool operator!=(const integer_format_info&, const integer_format_info&) noexcept;
```
## メンバ変数
### `integer_format fmt`
基数を指定します。
### `std::size_t width`
最小の幅を指定します。値によってはこの幅を超えることがあります。
フォーマットした値がこの幅よりも小さい場合、`integer_format::dec`の場合は効果はありませんが、それ以外の場合は先頭にリーディング`0`が追加されます。
### `std::size_t spacer`
アンダースコア`_`を追加する幅を指定します。
`3`の場合`1_234_567`のように、`4`の場合`0xdead_beef`のようにフォーマットされます。
`0`の場合、アンダースコアは挿入されません。
不規則な幅を指定することはできません。
### `std::string suffix`
toml11拡張の`spec::ext_num_suffix`を`true`にしている場合、その`suffix`がここに保存されます。
参考：[spec.hpp]({{<ref "spec.md">}})
# `floating_format`
```cpp
enum class floating_format : std::uint8_t
{
defaultfloat = 0,
fixed = 1, // does not include exponential part
scientific = 2, // always include exponential part
hex = 3 // hexfloat extension
};
std::ostream& operator<<(std::ostream& os, const floating_format f);
std::string to_string(const floating_format);
```
`floating`のフォーマット形式を指定します。
それぞれ、`std::defaultfloat`, `std::fixed`, `std::scientific`, `std::hexfloat`に対応します。
`hexfloat`は、`toml::spec::ext_hex_float`が`true`の場合のみ使用可能です。
参考：[spec.hpp]({{<ref "spec.md">}})
# `floating_format_info`
```cpp
struct floating_format_info
{
floating_format fmt = floating_format::defaultfloat;
std::size_t prec = 0; // precision (if 0, use the default)
std::string suffix = ""; // 1.0e+2_suffix (library extension)
};
bool operator==(const floating_format_info&, const floating_format_info&) noexcept;
bool operator!=(const floating_format_info&, const floating_format_info&) noexcept;
```
## メンバ変数
### `floating_format fmt`
フォーマット形式を指定します。
### `std::size_t prec`
小数点以下の精度を指定します。
### `std::string suffix`
toml11拡張の`spec::ext_num_suffix`を`true`にしている場合、その`suffix`がここに保存されます。
参考：[spec.hpp]({{<ref "spec.md">}})
# `string_format`
```cpp
enum class string_format : std::uint8_t
{
basic = 0,
literal = 1,
multiline_basic = 2,
multiline_literal = 3
};
std::ostream& operator<<(std::ostream& os, const string_format f);
std::string to_string(const string_format);
```
文字列のフォーマット形式を指定します。
# `string_format_info`
```cpp
struct string_format_info
{
string_format fmt = string_format::basic;
bool start_with_newline = false;
};
bool operator==(const string_format_info&, const string_format_info&) noexcept;
bool operator!=(const string_format_info&, const string_format_info&) noexcept;
```
## メンバ変数
### `string_format fmt`
文字列のフォーマット情報を指定します。
### `bool start_with_newline`
`multiline_basic`または`multiline_literal`の場合、最初の`"""`や`'''`の後に改行を入れるかどうかを指定します。
# `datetime_delimiter_kind`
```cpp
enum class datetime_delimiter_kind : std::uint8_t
{
upper_T = 0,
lower_t = 1,
space = 2,
};
std::ostream& operator<<(std::ostream& os, const datetime_delimiter_kind d);
std::string to_string(const datetime_delimiter_kind);
```
`datetime`で日付と時刻の間のデリミタにどの文字を使うかを指定します。
`T`, `t`, ` `が使用可能です。
# `offset_datetime_format_info`
```cpp
struct offset_datetime_format_info
{
datetime_delimiter_kind delimiter = datetime_delimiter_kind::upper_T;
bool has_seconds = true;
std::size_t subsecond_precision = 6; // [us]
};
bool operator==(const offset_datetime_format_info&, const offset_datetime_format_info&) noexcept;
bool operator!=(const offset_datetime_format_info&, const offset_datetime_format_info&) noexcept;
```
## メンバ変数
### `datetime_delimiter_kind delimiter`
使用するデリミタを指定します。
### `bool has_seconds`
秒数を省略するかどうかを指定します。
### `std::size_t subsecond_precision`
秒以下の精度を何桁出力するかを指定します。
# `local_datetime_format_info`
```cpp
struct local_datetime_format_info
{
datetime_delimiter_kind delimiter = datetime_delimiter_kind::upper_T;
bool has_seconds = true;
std::size_t subsecond_precision = 6; // [us]
};
bool operator==(const local_datetime_format_info&, const local_datetime_format_info&) noexcept;
bool operator!=(const local_datetime_format_info&, const local_datetime_format_info&) noexcept;
```
## メンバ変数
### `datetime_delimiter_kind delimiter`
使用するデリミタを指定します。
### `bool has_seconds`
秒数を省略するかどうかを指定します。
### `std::size_t subsecond_precision`
秒以下の精度を何桁出力するかを指定します。
# `local_date_format_info`
```cpp
struct local_date_format_info
{
// nothing, for now
};
bool operator==(const local_date_format_info&, const local_date_format_info&) noexcept;
bool operator!=(const local_date_format_info&, const local_date_format_info&) noexcept;
```
`local_datetime`にはフォーマット指定するパラメータはありません。
# `local_time_format_info`
```cpp
struct local_time_format_info
{
bool has_seconds = true;
std::size_t subsecond_precision = 6; // [us]
};
bool operator==(const local_time_format_info&, const local_time_format_info&) noexcept;
bool operator!=(const local_time_format_info&, const local_time_format_info&) noexcept;
```
## メンバ変数
### `bool has_seconds`
秒数を省略するかどうかを指定します。
### `std::size_t subsecond_precision`
秒以下の精度を何桁出力するかを指定します。
# `array_format`
```cpp
enum class array_format : std::uint8_t
{
default_format = 0,
oneline = 1,
multiline = 2,
array_of_tables = 3 // [[format.in.this.way]]
};
std::ostream& operator<<(std::ostream& os, const array_format f);
std::string to_string(const array_format);
```
- `default_format`
- 適したフォーマットを自動的に選択します。ある程度長い配列は複数行になります。
- `oneline`
- 全ての要素を一行でフォーマットします。
- `multiline`
- 一行ごとに一つの要素を出力します。
- `array_of_tables`
- `[[array.of.tables]]`の形式でフォーマットします。`table`以外の要素を含むことはできません。
# `array_format_info`
```cpp
struct array_format_info
{
array_format fmt = array_format::default_format;
indent_char indent_type = indent_char::space;
std::int32_t body_indent = 4; // indent in case of multiline
std::int32_t closing_indent = 0; // indent of `]`
};
bool operator==(const array_format_info&, const array_format_info&) noexcept;
bool operator!=(const array_format_info&, const array_format_info&) noexcept;
```
## メンバ変数
### `array_format fmt`
フォーマット形式を指定します。
### `indent_char indent_type`
インデントに使用する文字の種類を選択します。
### `std::int32_t body_indent`
`array_format::multiline`の場合、要素の前に出力するインデントの文字数を指定します。
### `std::int32_t closing_indent`
`array_format::multiline`の場合、閉じ括弧`]`の前に出力するインデントの文字数を指定します。
# `table_format`
```cpp
enum class table_format : std::uint8_t
{
multiline = 0, // [foo] \n bar = "baz"
oneline = 1, // foo = {bar = "baz"}
dotted = 2, // foo.bar = "baz"
multiline_oneline = 3, // foo = { \n bar = "baz" \n }
implicit = 4 // [x] defined by [x.y.z]. skip in serializer.
};
std::ostream& operator<<(std::ostream& os, const table_format f);
std::string to_string(const table_format);
```
- `multiline`
- 複数行の通常のテーブルとしてフォーマットします。
- `oneline`
- インラインテーブルとしてフォーマットします。
- `dotted`
- `a.b.c = "d"`の形式でフォーマットします。
- `multiline_oneline`
- 改行を含むインラインテーブルとしてフォーマットします。TOML v1.1.0以降で使用可能です。
- 参考：[spec.hpp]({{<ref "spec.md">}})
- `implicit`
- `[x.y.z.w]`だけが定義されている際の`[x]`, `[x.y]`, `[x.y.z]`のように、暗黙定義としてスキップします。
{{< hint warning >}}
TOMLの文法上、`dotted`はサブテーブルを持つことができます。
```toml
[fruit]
apple.color = "red"
apple.taste.sweet = true
# [fruit.apple] # INVALID
# [fruit.apple.taste] # INVALID
[fruit.apple.texture] # you can add sub-tables
smooth = true
```
toml11は現時点ではこのフォーマットに対応していません。
`dotted`テーブルの下にあるテーブルは全て`dotted`になり、テーブルは強制的にインラインテーブルになります。
{{< /hint >}}
# `table_format_info`
```cpp
struct table_format_info
{
table_format fmt = table_format::multiline;
indent_char indent_type = indent_char::space;
std::int32_t body_indent = 0; // indent of values
std::int32_t name_indent = 0; // indent of [table]
std::int32_t closing_indent = 0; // in case of {inline-table}
};
bool operator==(const table_format_info&, const table_format_info&) noexcept;
bool operator!=(const table_format_info&, const table_format_info&) noexcept;
```
## メンバ変数
### `table_format fmt`
フォーマット方法を指定します。
### `indent_char indent_type`
インデントに使用する文字を指定します。
### `std::int32_t body_indent`
キーの前に出力するインデントの幅を指定します。
スーパーテーブルのインデント幅は加算されません。
### `std::int32_t name_indent`
`[table]`形式のキーのインデントを指定します。
スーパーテーブルのインデント幅は加算されません。
### `std::int32_t closing_indent`
`multiline_oneline`の場合に、閉じ括弧`}`の前のインデント幅を指定します。

55
docs/content.ja/docs/reference/from.md Normal file
View File

@@ -0,0 +1,55 @@
+++
title = "from.hpp"
type = "docs"
+++
# from.hpp
`toml::get`や`toml::find`で使用する、`toml::value`からの変換を定義する構造体です。
メンバ関数に`from_toml`を追加することによっても同じ機能を追加できますが、メンバ関数を追加できないクラスに対しては`from<T>`を使用してください。
このファイルでは特定の実装は提供しません。使用する際に、この構造体を特殊化してください。
```cpp
namespace toml
{
template<typename T>
struct from;
} // toml
```
## 例
```cpp
namespace extlib
{
struct foo
{
int a;
std::string b;
};
} // extlib
#include <toml11/from.hpp>
namespace toml
{
template<>
struct from<extlib::foo>
{
template<typename TC>
static extlib::foo from_toml(const toml::basic_value<TC>& v)
{
return extlib::foo{toml::find<int>(v, "a"), toml::find<std::string>(v, "b")};
}
};
} // toml
```
# 関連項目
- [conversion.hpp]({{<ref "conversion.md">}})
- [into.hpp]({{<ref "into.md">}})

444
docs/content.ja/docs/reference/get.md Normal file
View File

@@ -0,0 +1,444 @@
+++
title = "get.hpp"
type = "docs"
+++
# get.hpp
`toml::value`から値を取り出し、同時に（必要な場合）型変換を行う関数です。
{{< hint info >}}
`toml::value` は格納する型を変更でき、`toml::get`はそれらに対応しているので、
厳密には全て `toml::basic_value<TC>` が使われています。ただしこれでは冗長なので、
関数の宣言と特に区別しなければならない場合を除いて、簡単のため説明文では `toml::value` と書きます。
説明文では、テンプレートパラメータ`TC`を変更して型が変更されていれば
`toml::value::integer_type` などの型は追従して変更されると解釈してください。
{{< /hint >}}
# `toml::get<T>`
## 概要
基本的に、`toml::get`は以下のような関数として振る舞います。
`T`は`toml::get<int>(v)`のようにして与えます。
```cpp
template<typename T, typename TC>
T get(const basic_value<TC>& v);
```
ただし、`T`がどのような型であるかによって、`toml::get`は異なる挙動をします。
`T`の型の種類は、
1. 変換が必要ない型
2. 変換する必要がある型
に分けられます。
細かい条件と、特別にサポートしている具体的な型については後述します。
### 変換が必要ない型
変換が必要ないのは、渡された `toml::value` が格納している型です。
例えば、 `toml::value::integer_type` は `std::int64_t` のエイリアスなので、
`toml::get<std::int64_t>(v)` は変換を必要としません。
この場合、 `toml:get` は `integer` の値を `toml::value` から取り出し、その参照を返します。
渡された`toml::value`が可変参照(`&`)である場合、返す値も可変参照(`&`)です。
不変参照(`const&`)の場合、返す値も不変参照(`const&`)となります。
可変参照を返した場合、その参照を通して`toml::value`に格納されている値に上書きできます。
### 変換が必要な型
上記の型以外については変換が必要です。
例えば、`toml::value::integer_type`は`std::int64_t`のエイリアスなので、`toml::get<std::size_t>(toml::value&)`は変換が必要です。
この場合、`toml:get`は`integer`の値を`toml::value`から取り出し、それをキャストして返します。
toml11は簡単なキャストだけでなく、
`toml::array`からや`std::tuple<int, double, std::string>`や`std::array<double, 4>`、
`toml::table`から`std::map<std::string, int>`などの複雑な型変換をサポートします。
具体的には、続くセクションを参照してください。
### 失敗した場合
期待した型変換を行えない場合があります。例えば、`table`を持っている`toml::value`に`toml::get<int>(v)`を適用した場合などです。
このような場合は、取り出そうとした型に最も似ている型への変換（今回は`int`なので、`as_integer`）が失敗したとして、`toml::type_error`が送出されます。
ファイルからパースした場合、以下のようなエラーメッセージが出力されます。
```
terminate called after throwing an instance of 'toml::type_error'
what(): toml::value::as_integer(): bad_cast to integer
--> input.toml
|
6 | [fruit]
| ^^^^^^^-- the actual type is table
```
## `T`が`toml::value`と同一のとき
```cpp
template< T, typename TC>
T& get(basic_value<TC>& v);
template<typename T, typename TC>
T const& get(const basic_value<TC>& v);
template<typename T, typename TC>
T get(basic_value<TC>&& v);
```
条件：
- `std::is_same<T, basic_value<TC>>` を満たす
`toml::value`から`toml::value`なので、変換は行われず、そのままの値が返されます。
他の関数の実装を一般化するためだけに存在しています。
失敗しません。
## `T`が`toml::value::{some_type}`のいずれかのとき
```cpp
template<typename T, typename TC>
T& get(basic_value<TC>& v);
template<typename T, typename TC>
T const& get(const basic_value<TC>& v);
template<typename T, typename TC>
T get(basic_value<TC>&& v);
```
条件：
- `T`が`toml::value`が格納できる型（`toml::value::boolean_type`など）のどれかと同一であること
`toml::value` が格納している型と同じ型、例えば `toml::value::integer_type` が
`toml::get<T>` の `T` として指定されたとき、型変換の必要がないため参照を返すことが可能です。
異なる型が格納されていた場合、`toml::type_error` が送出されます。
## `T`が異なる`TypeConfig`を持つ`basic_value<OtherTC>`のとき
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
条件：
- `T`が`toml::basic_value<TC>`ではない
- `T`が`toml::basic_value<OtherTC>`である
異なる型を格納し得る`basic_value`が指定された場合、変換が行われます。
型変換が発生するので、返す値は新規な値であり、参照ではありません。
失敗しません（メモリ枯渇などの場合を除く）。
## `T`が整数型の場合
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
条件：
- `std::is_integral<T>` を満たす
- `std::is_same<T, bool>` ではない
- `toml::value::integer_type` ではない
`toml::value` を `integer_type` を保持しているとしてその値を取得し、それを `T` に変換して返します。
`toml::value::integer_type` 以外の型が格納されていた場合、 `toml::type_error` が送出されます。
## `T`が浮動小数点数型の場合
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
条件：
- `std::is_floating_point<T>` を満たす
- `toml::value::floating_type` ではない
`toml::value`を`floating_type`を保持しているとしてその値を取得し、それを`T`に変換して返します。
`toml::value::floating_type` 以外の型が格納されていた場合、 `toml::type_error` が送出されます。
## `T`が`std::string_view`の場合
C++17以降でのみ使用可能です。
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
条件：
- `std::is_same<std::string_view, T>` を満たす
`toml::value`を`string_type`を保持しているとしてその値を取得し、それから`std::string_view`を構築して返します。
`toml::value::string_type` 以外の型が格納されていた場合、 `toml::type_error` が送出されます。
## `T`が`std::chrono::duration`の場合
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
条件：
- `T`が`std::chrono::duration<Rep, Period>`である
`toml::value`を`local_time`を保持しているとしてその値を取得し、それを`std::chrono::duration`に変換して返します。
`toml::value::local_time` 以外の型が格納されていた場合、 `toml::type_error` が送出されます。
## `T`が`std::chrono::system_clock::time_point`の場合
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
条件：
- `std::is_same<T, std::chrono::system_clock::time_point>`を満たす
`toml::value` を `local_date`, `local_datetime`, `offset_datetime`のどれかを保持しているとしてその値を取得し、それを`std::chrono::system_clock::time_point`に変換して返します。
`local_date`, `local_datetime`, `offset_datetime` 以外の型が格納されていた場合、 `toml::type_error` が送出されます。
## `T`が`array-like`である場合
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
条件：
- `T`は`T::iterator`を持つ
- `T`は`T::value_type`を持つ
- `T`は`T::push_back(x)`を持つ
- `T`は`toml::value::array_type`ではない
- `T`は`std::string`ではない
- `T`は`std::string_view`ではない
- `T`は`map-like`ではない
- `T`は`from_toml()`メンバ関数を持たない
- `toml::from<T>`が定義されていない
- `toml::basic_value<TC>`からのコンストラクタが定義されていない
`std::vector<int>`や`std::deque<std::string>`などが該当します。
`toml::value`を`array`を保持しているとしてその値を取得し、それを指定されたコンテナに変換して返します。
`toml::value::array_type` 以外の型が格納されていた場合、 `toml::type_error` が送出されます。
## `T`が`std::array`である場合
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
条件：
- `T`は`std::array<U, N>`である
`toml::value`を`array`を保持しているとしてその値を取得し、それを指定されたコンテナに変換して返します。
`toml::value::array_type` 以外の型が格納されていた場合、 `toml::type_error` が送出されます。
`toml::value` が持つ `array` が十分な数の要素を持っていなかった場合、`std::out_of_range`が送出されます。
## `T`が`std::forward_list`である場合
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
条件：
- `T`は`std::forward_list<U>`である
`toml::value`を`array`を保持しているとしてその値を取得し、それを`std::forward_list`に変換して返します。
`toml::value::array_type` 以外の型が格納されていた場合、 `toml::type_error` が送出されます。
`forward_list`は`push_back`を持たないので、別に実装されています。
## `T`が`std::pair`である場合
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
条件：
- `T`は`std::pair<T1, T2>`である
`toml::value`を`array`を保持しているとしてその値を取得し、それを`std::pair<T1, T2>`に変換して返します。
`first` と `second` はそれぞれ再帰的に変換されます。
`toml::value::array_type` 以外の型が格納されていた場合、 `toml::type_error` が送出されます。
`toml::value` が持つ `array` の要素数がちょうど2個でなかった場合、`std::out_of_range`が送出されます。
## `T`が`std::tuple`である場合
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
条件：
- `T`は`std::tuple<T1, T2, ... TN>`である
`toml::value`を`array`を保持しているとしてその値を取得し、それを`std::tuple<T1, T2, ...TN>`に変換して返します。
各要素はそれぞれ再帰的に変換されます。
`toml::value::array_type` 以外の型が格納されていた場合、 `toml::type_error` が送出されます。
`toml::value` が持つ `array` の要素数がちょうど `std::tuple_size<T>::value` 個でなかった場合、`std::out_of_range`が送出されます。
## `T`が`map-like`である場合
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
条件：
- `T`は`T::iterator`を持つ
- `T`は`T::key_type`を持つ
- `T`は`T::value_type`を持つ
- `T`は`T::mapped_type`を持つ
- `T`は`toml::value::table_type`ではない
- `T`は`from_toml()`メンバ関数を持たない
- `toml::from<T>`が定義されていない
- `toml::basic_value<TC>`からのコンストラクタが定義されていない
`std::map<std::string, int>`や`std::unordered_map<std::string, float>`などが該当します。
`toml::value`を`table`を保持しているとしてその値を取得し、それを `T` に変換して返します。
各要素はそれぞれ再帰的に変換されます。
`basic_value::table_type` 以外の型が格納されていた場合、 `toml::type_error` が送出されます。
## `T`が`toml::from<T>`の特殊化を持つユーザー定義型である場合
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
条件：
- `toml::from<T>`が定義されている
`toml::from` の `T` に対する特殊化が定義されていた場合、それを使用した型変換が行われます。
個別にサポートされる型（ `std::array`, `std::pair`, `std::tuple` ）と衝突しないようにしてください。
## `T`が`T::from_toml`メンバ関数を持つユーザー定義型である場合
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
条件：
- `toml::from<T>`が定義されていない
- `T`は`from_toml()`メンバ関数を持つ
`T` に `from_toml(toml::basic_value<TC>)` メンバ関数が定義されていた場合、それを使用した型変換が行われます。
`toml::from<T>` が定義されていると、そちらが優先されます。
## `T`が`toml::basic_value<TC>`を取るコンストラクタを持つユーザー定義型である場合
```cpp
template<typename T, typename TC>
T get(basic_value<TC>& v);
```
条件：
- `toml::from<T>`が定義されていない
- `T`は`from_toml()`メンバ関数を持たない
- `T`は`toml::basic_value<TC>`を取るコンストラクタを持つ
`T` に `toml::basic_value<TC>` を取るコンストラクタが定義されていた場合、それを使用した型変換が行われます。
`toml::from<T>` または `T::from_toml` が定義されていると、そちらが優先されます。
# `toml::get_or<T>`
`get_or` は失敗した際のためのデフォルト値を受け取ることで、失敗時に例外を投げないようにします。
このデフォルト値は受け取る型`T`と同じ型でなければなりません。
よって、 `toml::get<T>` とは違って、 `get_or` では `T` を指定せずとも推論されます。
## `T`が`basic_value<TC>`である場合
```cpp
template<typename TC>
basic_value<TC> const& get_or(const basic_value<TC>& v, const basic_value<TC>& opt)
template<typename TC>
basic_value<TC> & get_or(basic_value<TC>& v, basic_value<TC>& opt)
template<typename TC>
basic_value<TC> get_or(basic_value<TC>&& v, basic_value<TC>&& opt)
```
変換先は同一の`toml::value`なので、失敗しません。
他の関数の実装を一般化するためだけに存在しています。
## `T`が`basic_value<TC>::{some_type}`である場合
```cpp
template<typename T, typename TC>
T const& get_or(const basic_value<TC>& v, const T& opt) noexcept
template<typename T, typename TC>
T & get_or(basic_value<TC>& v, T& opt) noexcept
template<typename T, typename TC>
T get_or(basic_value<TC>&& v, T&& opt) noexcept
```
`toml::get<T>`と同様の変換を行います。失敗した場合は第二引数が返されます。
## `T`が`const char*`である場合
```cpp
template<typename TC>
typename basic_value<TC>::string_type
get_or(const basic_value<TC>& v,
const typename basic_value<TC>::string_type::value_type* opt);
```
`const char*` が渡された場合、変換先は `std::string` として解釈されます。
## `T`がその他の場合
```cpp
template<typename TC>
typename std::remove_cv<typename std::remove_reference<T>::type>::type
get_or(const basic_value<TC>& v, T&& opt);
```
`toml::get<T>`と同様の変換を行います。失敗した場合は第二引数が返されます。
# 関連項目
- [find.hpp]({{<ref "find.md">}})
- [from.hpp]({{<ref "from.md">}})
- [value.hpp]({{<ref "value.md">}})

57
docs/content.ja/docs/reference/into.md Normal file
View File

@@ -0,0 +1,57 @@
+++
title = "into.hpp"
type = "docs"
+++
# into.hpp
`toml::value`のコンストラクタで使用する、ユーザー定義型からの変換を定義する構造体です。
メンバ関数に`into_toml`を追加することによっても同じ機能を追加できますが、メンバ関数を追加できないクラスに対しては`into<T>`を使用してください。
このファイルでは特定の実装は提供しません。使用する際に、この構造体を特殊化してください。
```cpp
namespace toml
{
template<typename T>
struct into;
} // toml
```
## 例
```cpp
namespace extlib
{
struct foo
{
int a;
std::string b;
};
} // extlib
#include <toml11/into.hpp>
namespace toml
{
template<>
struct into<extlib::foo>
{
template<typename TC>
static toml::basic_value<TC> into_toml(const extlib::foo& f)
{
using value_type = toml::basic_value<TC>;
using table_type = typename value_type::table_type;
return value_type(table_type{{"a", f.a}, {"b", f.b}});
}
};
} // toml
```
# 関連項目
- [conversion.hpp]({{<ref "conversion.md">}})
- [from.hpp]({{<ref "from.md">}})

83
docs/content.ja/docs/reference/literal.md Normal file
View File

@@ -0,0 +1,83 @@
+++
title = "literal.hpp"
type = "docs"
+++
# literal.hpp
`literal.hpp`では、`_toml`リテラルが定義されます。
`_toml`リテラルは、文字列リテラルをパースして`toml::value`に変換します。
```cpp
namespace toml
{
inline namespace literals
{
inline namespace toml_literals
{
toml::value operator"" _toml(const char* str, std::size_t len);
toml::value operator"" _toml(const char8_t* str, std::size_t len); // C++20以降
} // toml_literals
} // literals
} // toml
```
## 自由関数
### `operator"" _toml(char)`
```cpp
toml::value operator"" _toml(const char* str, std::size_t len);
```
文字列リテラルをパースして`toml::value`に変換します。
通常のTOMLファイルの場合、`toml::parse`と同等の処理が行われます。
```cpp
const auto v1 = "a = 'foo'"_toml; // v1: {a = 'foo'}
```
改行を含む場合、生文字列リテラルが便利です。
```cpp
const auto v1 = R"(
a = 42
b = "foo"
)"_toml;
```
値が単体で書かれていた場合、その値になります。
```cpp
const auto v2 = "'foo'"_toml; // v2: 'foo'
```
TOMLは数値のみからなるキーを許可しています。
`[1]`のように、テーブル定義と配列の区別がつかない場合、テーブル定義が優先されます。
配列として解釈させるには、trailing commaを使用してください。
```cpp
const auto v3 = "[1]"_toml; // v3: {1 = {}}
const auto v4 = "[1,]"_toml; // v4: [1,]
```
### `operator"" _toml(char8_t)`
`char8_t`が利用可能な場合に定義されます。引数の型のほかに違いはありません。
# 例
```cpp
#include <toml.hpp>
int main()
{
using namespace toml::literals::toml_literals;
const auto v = "a = \"foo\""_toml;
assert(v.at("a").as_string() == "foo");
return 0;
}
```

359
docs/content.ja/docs/reference/ordered_map.md Normal file
View File

@@ -0,0 +1,359 @@
+++
title = "ordered_map.hpp"
type = "docs"
+++
# ordered_map.hpp
ファイル中の値の順番を維持するために使用する`toml::ordered_map`を定義します。
# `class ordered_map`
```cpp
namespace toml
{
template<typename Key, typename Val, typename Cmp = std::equal_to<Key>,
typename Allocator = std::allocator<std::pair<Key, Val>>>
class ordered_map;
}
```
`ordered_map`は、値を追加した順序を保ったまま値を保持し、その順でイテレートできる `map` 型です。
線形コンテナなので、検索には要素数に対して `O(n)` の時間がかかります。
検索を行う機会が少なく、値の順序を守る必要がある場合に使用してください。
## 非メンバ型
```cpp
namespace toml
{
struct ordered_type_config;
using ordered_value = basic_value<ordered_type_config>;
using ordered_table = typename ordered_value::table_type;
using ordered_array = typename ordered_value::array_type;
}
```
`toml::type_config` と `toml::value` の代わりに使用します。
{{< hint info >}}
`toml::parse` はデフォルトで `type_config` を使用するので、パースする際に
```cpp
const auto input = toml::parse<toml::ordered_type_config>("input.toml");
```
としてください。
{{< /hint >}}
## メンバ型
```cpp
using key_type = Key;
using mapped_type = Val;
using value_type = std::pair<Key, Val>;
using key_compare = Cmp;
using allocator_type = Allocator;
using container_type = std::vector<value_type, Allocator>;
using reference = typename container_type::reference;
using pointer = typename container_type::pointer;
using const_reference = typename container_type::const_reference;
using const_pointer = typename container_type::const_pointer;
using iterator = typename container_type::iterator;
using const_iterator = typename container_type::const_iterator;
using size_type = typename container_type::size_type;
using difference_type = typename container_type::difference_type;
```
## メンバ関数
### コンストラクタ
```cpp
ordered_map() = default;
```
空の `ordered_map` を構築します。
### コンストラクタ（コンパレータ、アロケータ）
```cpp
explicit ordered_map(const Cmp& cmp, const Allocator& alloc = Allocator());
explicit ordered_map(const Allocator& alloc);
```
キーの比較に使用するコンパレータや、コンテナのメモリ確保に使用するアロケータを指定して構築します。
### コピー・ムーブコンストラクタ
```cpp
ordered_map(const ordered_map&) = default;
ordered_map(ordered_map&&) = default;
ordered_map(const ordered_map& other, const Allocator& alloc);
ordered_map(ordered_map&& other, const Allocator& alloc);
```
別の `ordered_map` の内容をコピー・ムーブして構築します。
コンテナのメモリ確保に使用するアロケータを指定することも可能です。
### コンストラクタ（`Iterator`）
```cpp
template<typename InputIterator>
ordered_map(InputIterator first, InputIterator last, const Cmp& cmp = Cmp(), const Allocator& alloc = Allocator());
template<typename InputIterator>
ordered_map(InputIterator first, InputIterator last, const Allocator& alloc = Allocator());
```
イテレータ範囲を受け取って構築します。
順序は、イテレータの順序に従います。
### コンストラクタ（`std::initializer_list`）
```cpp
ordered_map(std::initializer_list<value_type> v, const Cmp& cmp = Cmp(), const Allocator& alloc = Allocator());
ordered_map(std::initializer_list<value_type> v, const Allocator& alloc);
```
`ordered_map{...}`の形式で初期化します。
### コピー・ムーブ代入演算子
```cpp
ordered_map& operator=(const ordered_map&) = default;
ordered_map& operator=(ordered_map&&) = default;
```
別の `ordered_map` の内容をコピー・ムーブ代入します。
### 代入演算子（`std::initializer_list`）
```cpp
ordered_map& operator=(std::initializer_list<value_type> v);
```
`std::initializer_list` の内容を代入します。
### デストラクタ
```cpp
~ordered_map() = default;
```
`ordered_map` を破棄します。
### `begin()`, `end()`
```cpp
iterator begin() noexcept;
iterator end() noexcept;
const_iterator begin() const noexcept;
const_iterator end() const noexcept;
const_iterator cbegin() const noexcept;
const_iterator cend() const noexcept;
```
コンテナの内容を順序通りにイテレートします。
### `empty()`
```cpp
bool empty() const noexcept;
```
`ordered_map` が空の場合 `true` を、そうでない場合 `false` を返します。
### `size()`
```cpp
std::size_t size() const noexcept;
```
`ordered_map` の要素数を返します。
### `max_size()`
```cpp
std::size_t max_size() const noexcept;
```
`ordered_map` が持つことのできる最大の要素数を返します。
### `clear()`
```cpp
void clear();
```
内容を消去します。
### `push_back(kv)`
```cpp
void push_back(const value_type&);
void push_back(value_type&&);
```
キーと値のペアを末尾に追加します。
### `emplace_back(k, v)`
```cpp
void emplace_back(key_type, mapped_type);
```
キーと値のペアを末尾に追加します。
### `pop_back()`
```cpp
void pop_back();
```
末尾の値を削除します。
### `insert(kv)`
```cpp
void insert(value_type);
```
キーと値のペアを末尾に追加します。
### `emplace(k, v)`
```cpp
void emplace(key_type, mapped_type);
```
キーと値のペアを末尾に追加します。
### `count(k)`
```cpp
std::size_t count(const key_type&) const noexcept;
```
キーに対応する値の数を返します。
同じキーに複数の値を代入することはできないので、値が存在する場合は `1`, そうでない場合は `0` を返します。
### `contains(k)`
```cpp
bool contains(const key_type&) const noexcept;
```
キーに対応する値が存在するなら `true` を、そうでないなら `false` を返します。
### `find(k)`
```cpp
iterator find(const key_type& key) noexcept;
const_iterator find(const key_type& key) const noexcept;
```
キーに対応する値を検索し、それを指すイテレータを返します。
存在しなかった場合、`end()`を返します。
### `at(k)`
```cpp
mapped_type& at(const key_type& k);
mapped_type const& at(const key_type& k) const;
```
キーに対応する値を検索して返します。
存在しなかった場合、`std::out_of_range`を送出します。
### `operator[](k)`
```cpp
mapped_type& operator[](const key_type& k);
mapped_type const& operator[](const key_type& k) const;
```
キーに対応する値を検索して返します。
存在しなかった場合、新規な値を構築して返します。
`ordered_map` が `const` の場合は新規な値を構築できないので、 `std::out_of_range` を送出します。
### `key_comp()`
```cpp
key_compare key_comp() const;
```
比較に使用するコンパレータを返します。
## 使用上の注意
### キーの書き換え
{{< hint warning >}}
`ordered_map` は `value_type` に `std::pair<Key, Val>` を使用しているので、イテレータを介してキーを書き換えることが可能になってしまっています。
この方法でキーを書き換えることは推奨されません。
キーを書き換えて既存のキーと衝突した場合、衝突したうちの片方が検索できなくなります。
`operator[]` や `push_back`, `insert` による書き込みの場合は、既存のキーとの衝突が検出されます。
{{< /hint >}}
### 保たれる順序の詳細
{{< hint warning >}}
`ordered_map` はキーの順序を保ちますが、ここで保たれる順序は同じテーブルで定義されたキーの順序のみです。
よって、テーブルをまたいだ順序は保たれないことに注意してください。
例えば、以下のファイルの順序は保たれます。
```cpp
apple.type = "fruit"
apple.skin = "thin"
apple.color = "red"
orange.type = "fruit"
orange.skin = "thick"
orange.color = "orange"
```
対して以下のファイルの順序は保たれません。
```cpp
apple.type = "fruit"
orange.type = "fruit"
apple.skin = "thin"
orange.skin = "thick"
apple.color = "red"
orange.color = "orange"
```
`ordered_map` が保つ順序は、rootテーブルに定義された `apple` と `orange` の順序と、
`apple` 内で定義された `type`, `skin`, `color` の順序、
また `orange` 内で定義された `type`, `skin`, `color` の順序のみです。
{{< /hint >}}
## 関連項目
- [parser.hpp]({{<ref "parser.md">}})
- [types.hpp]({{<ref "types.md">}})
- [value.hpp]({{<ref "value.md">}})

381
docs/content.ja/docs/reference/parser.md Normal file
View File

@@ -0,0 +1,381 @@
+++
title = "parser.hpp"
type = "docs"
+++
# parser.hpp
ファイルまたは文字列をパースする関数と、それが用いる例外を定義します。
`parse`は失敗した場合に例外を送出しますが、`try_parse`はエラー情報を返します。
# `parse`
与えられたファイルの内容をパースし、`toml::basic_value`を返します。
失敗した場合は`toml::syntax_error`が送出されます。
`basic_value`の持つ型情報は`template`で、TOML言語のバージョンは`toml::spec`で指定します。
### `parse(std::istream&, std::string filename, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config>
basic_value<TC>
parse(std::istream& is,
std::string fname = "unknown file",
spec s = spec::default_version());
}
```
`std::istream&`を受け取ってその内容をパースします。
ファイル名の情報は第三引数で受け取ります。ファイル名が渡されなかった場合、`"unknown file"`になります。
### `parse(std::string filename, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config>
basic_value<TC>
parse(std::string fname,
spec s = spec::default_version());
}
```
ファイル名を受け取って、その内容をパースします。
ファイルの読み込みに失敗した場合、`file_io_error`が送出されます。
パースに失敗した場合、`syntax_error`が送出されます。
### `parse(const char (&)[N] filename, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config, std::size_t N>
basic_value<TC>
parse(const char (&fname)[N],
spec s = spec::default_version());
}
```
文字列リテラルを受け取って、そのファイルの内容をパースします。
ファイルの読み込みに失敗した場合、`file_io_error`が送出されます。
パースに失敗した場合、`syntax_error`が送出されます。
### `parse(std::filesystem::path, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config>
basic_value<TC>
parse(const std::filesystem::path& fpath,
spec s = spec::default_version());
}
```
`<filesystem>`が利用可能な場合のみ定義されます。
ファイルパスを受け取って、そのファイルの内容をパースします。
ファイルの読み込みに失敗した場合、`file_io_error`が送出されます。
パースに失敗した場合、`syntax_error`が送出されます。
### `parse(FILE*, std::string filename, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config>
result<basic_value<TC>, std::vector<error_info>>
parse(FILE* fp,
std::string filename,
spec s = spec::default_version());
}
```
`FILE*`が指すファイルを読み込んでパースします。
ファイルの読み込みに失敗した場合、`errno`が含まれた`file_io_error`が送出されます。
パースに失敗した場合、`syntax_error`が送出されます。
### `parse(std::vector<unsigned char>, std::string filename, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config>
basic_value<TC>
parse(std::vector<unsigned char> content,
std::string filename,
spec s = spec::default_version());
}
```
バイト列をTOMLファイルとしてパースします。
パースに失敗した場合、`syntax_error`が送出されます。
# `parse_str`
### `parse_str(std::string, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config>
basic_value<TC>
parse_str(std::string content,
spec s = spec::default_version(),
cxx::source_location loc = cxx::source_location::current());
}
```
文字列をTOMLファイルとしてパースします。
失敗した場合は`toml::syntax_error`が送出されます。
`basic_value`の持つ型情報は`template`で、TOML言語のバージョンは`toml::spec`で指定します。
第三引数の`cxx::source_location`を手動で設定する必要は通常ありません。
`std::source_location`, `std::experimental::source_location`, `__builtin_FILE`のいずれかが利用可能な場合、
`parse_str`が呼ばれた地点の情報が位置情報として保存されます。
# `try_parse`
与えられたファイルの内容をパースし、成功した場合は`toml::basic_value`を、失敗した場合は`std::vector<toml::error_info>`を返します。
`basic_value`の持つ型情報は`template`で、TOML言語のバージョンは`toml::spec`で指定します。
{{< hint warning >}}
`try_parse`は`parse`と異なり`syntax_error`などのtoml11で定義された例外は投げませんが、
標準ライブラリから送出される例外はそのまま送出されることに注意してください。
例えば、`std::ifstream`の内部で起きたエラーや、`std::vector`でのメモリ枯渇などは例外を送出します。
{{< /hint >}}
### `try_parse(std::istream&, std::string filename, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config>
result<basic_value<TC>, std::vector<error_info>>
try_parse(std::istream& is,
std::string fname = "unknown file",
spec s = spec::default_version());
}
```
`std::istream&`を受け取ってその内容をパースします。
ファイル名の情報は第二引数で受け取ります。ファイル名が渡されなかった場合、`"unknown file"`になります。
パースに失敗した場合、エラー型である`std::vector<error_info>`を持つ`result`が返されます。
成功した場合、`basic_value`を持つ`result`が返されます。
### `try_parse(std::string filename, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config>
result<basic_value<TC>, std::vector<error_info>>
try_parse(std::string fname,
spec s = spec::default_version());
}
```
ファイル名を受け取って、その内容をパースします。
パースに失敗した場合、エラー型である`std::vector<error_info>`を持つ`result`が返されます。
成功した場合、`basic_value`を持つ`result`が返されます。
### `try_parse(const char (&)[N] filename, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config, std::size_t N>
result<basic_value<TC>, std::vector<error_info>>
try_parse(const char (&fname)[N],
spec s = spec::default_version());
}
```
文字列リテラルをファイル名として受け取って、その内容をパースします。
パースに失敗した場合、エラー型である`std::vector<error_info>`を持つ`result`が返されます。
成功した場合、`basic_value`を持つ`result`が返されます。
### `try_parse(std::filesystem::path, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config>
result<basic_value<TC>, std::vector<error_info>>
try_parse(const std::filesystem::path& fpath,
spec s = spec::default_version());
}
```
ファイルパスを受け取って、その内容をパースします。
パースに失敗した場合、エラー型である`std::vector<error_info>`を持つ`result`が返されます。
成功した場合、`basic_value`を持つ`result`が返されます。
### `try_parse(FILE*, std::string filename, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config>
result<basic_value<TC>, std::vector<error_info>>
try_parse(FILE* fp,
std::string filename,
spec s = spec::default_version());
}
```
`FILE*`を受け取って、そのファイルの内容をパースします。
パースに失敗した場合、エラー型である`std::vector<error_info>`を持つ`result`が返されます。
成功した場合、`basic_value`を持つ`result`が返されます。
### `try_parse(std::vector<unsigned char>, std::string filename, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config>
result<basic_value<TC>, std::vector<error_info>>
try_parse(std::vector<unsigned char> content,
std::string filename,
spec s = spec::default_version());
}
```
バイト列を受け取って、その内容をTOMLファイルとしてパースします。
パースに失敗した場合、エラー型である`std::vector<error_info>`を持つ`result`が返されます。
成功した場合、`basic_value`を持つ`result`が返されます。
# `try_parse_str`
### `try_parse_str(std::string, toml::spec)`
```cpp
namespace toml
{
template<typename TC = type_config>
result<basic_value<TC>, std::vector<error_info>>
try_parse_str(std::string content,
spec s = spec::default_version(),
cxx::source_location loc = cxx::source_location::current());
}
```
文字列をTOMLファイルとしてパースし、成功した場合は`toml::basic_value`を、失敗した場合は`std::vector<toml::error_info>`を返します。
`parse_str`と異なり、`syntax_error`を送出せず、エラー情報を`result`の失敗型として返します。
`std::source_location`, `std::experimental::source_location`, `__builtin_FILE`のどれかが利用可能な場合、それを位置情報に記録します。
第三引数の`cxx::source_location`を手動で設定する必要は通常ありません。
`std::source_location`, `std::experimental::source_location`, `__builtin_FILE`のいずれかが利用可能な場合、
`parse_str`が呼ばれた地点の情報が位置情報として保存されます。
{{< hint warning >}}
`try_parse`は`parse`と異なり`syntax_error`などのtoml11で定義された例外は投げませんが、
標準ライブラリから送出される例外はそのまま送出されることに注意してください。
例えば、`std::ifstream`の内部で起きたエラーや、`std::vector`でのメモリ枯渇などは例外を送出します。
{{< /hint >}}
# `syntax_error`
```cpp
namespace toml
{
struct syntax_error final : public ::toml::exception
{
public:
syntax_error(std::string what_arg, std::vector<error_info> err);
~syntax_error() noexcept override = default;
const char* what() const noexcept override;
std::vector<error_info> const& errors() const noexcept
};
}
```
TOML言語の文法エラーが発見された場合に送出される例外です。
`parse`からは送出されますが、`try_parse`からは送出されません。
# `file_io_error`
```cpp
namespace toml
{
struct file_io_error final : public ::toml::exception
{
public:
file_io_error(const std::string& msg, const std::string& fname);
file_io_error(int errnum, const std::string& msg, const std::string& fname);
~file_io_error() noexcept override = default;
const char* what() const noexcept override;
bool has_errno() const noexcept;
int get_errno() const noexcept;
};
}
```
ファイルの内容を読むのに失敗した場合に送出される例外です。
`FILE*`を使ってファイルを読み込んだ場合は`errno`が設定されます。
### `has_errno`
`std::ifstream`が失敗した場合は`errno`は設定されません。
このとき、`has_errno`は`false`になります。
### `get_errno`
特に`FILE*`を渡していた場合に、`errno`の値を取得します。
`has_errno`が`false`の場合は`0`となります。
# 関連項目
- [error_info.hpp]({{<ref "error_info.md">}})
- [result.hpp]({{<ref "result.md">}})
- [spec.hpp]({{<ref "spec.md">}})
- [value.hpp]({{<ref "value.md">}})

529
docs/content.ja/docs/reference/result.md Normal file
View File

@@ -0,0 +1,529 @@
+++
title = "result.hpp"
type = "docs"
+++
# result.hpp
`result.hpp`は、成功値か失敗値かのどちらかを持つ`result`型を定義します。
これは、例外を投げない`toml::try_parse`の返り値として使用されます。
# success
成功値を持つ型です。
```cpp
namespace toml
{
template<typename T>
struct success
{
using value_type = T;
explicit success(value_type v);
~success() = default;
success(const success&) = default;
success(success&&) = default;
success& operator=(const success&) = default;
success& operator=(success&&) = default;
template<typename U>
explicit success(U&& v);
template<typename U>
explicit success(success<U> v);
value_type& get() noexcept;
value_type const& get() const noexcept;
};
template<typename T>
success<typename std::decay<T>::type> ok(T&& v);
template<std::size_t N>
success<std::string> ok(const char (&literal)[N])
}
```
## メンバ型
```cpp
using value_type = T;
```
成功値の型です。
## メンバ関数
### コンストラクタ
```cpp
explicit success(value_type v);
```
`value_type`を受け取って構築します。
```cpp
template<typename U>
explicit success(U&& v);
```
`value_type`に変換可能な他の型を受け取って構築します。
```cpp
template<typename U>
explicit success(success<U> v);
```
`value_type`に変換可能な他の型を持つ`success`型を受け取って構築します。
### `get()`
```cpp
value_type& get() noexcept;
value_type const& get() const noexcept;
```
値にアクセスします。
## 非メンバ関数
### `ok(T)`
```cpp
template<typename T>
success<typename std::decay<T>::type> ok(T&& v);
template<std::size_t N>
success<std::string> ok(const char (&literal)[N])
```
成功値から`success`型を構築して返します。
文字列リテラルを与えた場合は、`std::string`にして返します。
# `success<reference_wrapper<T>>`
`success`の特殊化。成功値が参照であるときに使用されます。
```cpp
namespace toml
{
template<typename T>
struct success<std::reference_wrapper<T>>
{
using value_type = T;
explicit success(std::reference_wrapper<value_type> v) noexcept;
value_type& get() noexcept;
value_type const& get() const noexcept;
};
}
```
## メンバ型
```cpp
using value_type = T;
```
成功値の型です。参照ではなく、`std::reference_wrapper<T>`の`T`です。
### `get()`
```cpp
value_type& get() noexcept;
value_type const& get() const noexcept;
```
値にアクセスします。
# failure
失敗値を持つ型です。
```cpp
namespace toml
{
template<typename T>
struct failure
{
using value_type = T;
explicit failure(value_type v);
~failure() = default;
failure(const failure&) = default;
failure(failure&&) = default;
failure& operator=(const failure&) = default;
failure& operator=(failure&&) = default;
template<typename U>
explicit failure(U&& v);
template<typename U>
explicit failure(failure<U> v);
value_type& get() noexcept;
value_type const& get() const noexcept;
};
template<typename T>
failure<typename std::decay<T>::type> err(T&& v);
template<std::size_t N>
failure<std::string> err(const char (&literal)[N]);
}
```
## メンバ型
```cpp
using value_type = T;
```
失敗値の型です。
## メンバ関数
### コンストラクタ
```cpp
explicit failure(value_type v);
```
`value_type`を受け取って構築します。
```cpp
template<typename U>
explicit failure(U&& v);
```
`value_type`に変換可能な他の型を受け取って構築します。
```cpp
template<typename U>
explicit failure(failure<U> v);
```
`value_type`に変換可能な他の型を持つ`failure`型を受け取って構築します。
### `get()`
```cpp
value_type& get() noexcept;
value_type const& get() const noexcept;
```
値にアクセスします。
## 非メンバ関数
### `err(T)`
```cpp
template<typename T>
failure<typename std::decay<T>::type> err(T&& v);
template<std::size_t N>
failure<std::string> err(const char (&literal)[N]);
```
失敗値から`failure`型を構築して返します。
文字列リテラルを与えた場合は、`std::string`にして返します。
# `failure<reference_wrapper<T>>`
`failure`の特殊化。失敗値が参照であるときに使用されます。
```cpp
namespace toml
{
template<typename T>
struct failure<std::reference_wrapper<T>>
{
using value_type = T;
explicit failure(std::reference_wrapper<value_type> v) noexcept;
value_type& get() noexcept {return value.get();}
value_type const& get() const noexcept {return value.get();}
};
}
```
## メンバ型
```cpp
using value_type = T;
```
失敗値の型です。参照ではなく、`std::reference_wrapper<T>`の`T`です。
### `get()`
```cpp
value_type& get() noexcept
value_type const& get() const noexcept
```
値にアクセスします。
# result
成功値か失敗値かのどちらかを持つ型です。
```cpp
namespace toml
{
template<typename T, typename E>
struct result
{
using success_type = success<T>;
using failure_type = failure<E>;
using value_type = typename success_type::value_type;
using error_type = typename failure_type::value_type;
result(success_type s);
result(failure_type f);
template<typename U>
result(success<U> s);
template<typename U>
result(failure<U> f);
result& operator=(success_type s);
result& operator=(failure_type f);
template<typename U>
result& operator=(success<U> s);
template<typename U>
result& operator=(failure<U> f);
~result() noexcept;
result(const result& other);
result(result&& other);
result& operator=(const result& other);
result& operator=(result&& other);
template<typename U, typename F>
result(result<U, F> other);
template<typename U, typename F>
result& operator=(result<U, F> other);
bool is_ok() const noexcept;
bool is_err() const noexcept;
explicit operator bool() const noexcept;
value_type& unwrap(cxx::source_location loc = cxx::source_location::current());
value_type const& unwrap(cxx::source_location loc = cxx::source_location::current()) const;
value_type& unwrap_or(value_type& opt) noexcept;
value_type const& unwrap_or(value_type const& opt) const noexcept;
error_type& unwrap_err(cxx::source_location loc = cxx::source_location::current());
error_type const& unwrap_err(cxx::source_location loc = cxx::source_location::current()) const;
value_type& as_ok() noexcept;
value_type const& as_ok() const noexcept;
error_type& as_err() noexcept;
error_type const& as_err() const noexcept;
};
}
```
## メンバ型
### `success_type`
`success<T>`です。
### `failure_type`
`failure<E>`です。
### `value_type`
成功型`T`です。`success_type::value_type`のエイリアスです。
成功型`T`として`std::reference_wrapper<U>`が渡された場合、その引数型の`U`になります。
### `error_type`
失敗型`E`です。`failure_type::value_type`のエイリアスです。
失敗型`E`として`std::reference_wrapper<F>`が渡された場合、その引数型の`F`になります。
## メンバ関数
### コンストラクタ
```cpp
result() = delete;
```
`result`型はデフォルトでは構築できません。
成功型か失敗型を与える必要があります。
```cpp
result(success_type s);
result(failure_type f);
```
成功型、失敗型を受け取って構築します。
```cpp
template<typename U>
result(success<U> s);
template<typename U>
result(failure<U> f);
```
`value_type`と`error_type`に変換可能な成功型、失敗型を受け取って構築します。
```cpp
template<typename U, typename F>
result(result<U, F> other);
template<typename U, typename F>
result& operator=(result<U, F> other);
```
変換可能な成功型、失敗型を持つ`result`から構築します。
### コピー・ムーブコンストラクタ
```cpp
result(const result& other);
result(result&& other);
```
コピー・ムーブ構築可能です。
### `operator=`
```cpp
result& operator=(const result& other);
result& operator=(result&& other);
```
コピー・ムーブ代入可能です。
```cpp
template<typename U>
result& operator=(success<U> s);
template<typename U>
result& operator=(failure<U> f);
```
変換可能な型を持つ成功型、失敗型は代入可能です。
### `is_ok()`
```cpp
bool is_ok() const noexcept;
```
成功値を持っている場合`true`を、そうでない場合`false`を返します。
### `is_err()`
```cpp
bool is_err() const noexcept;
```
失敗値を持っている場合`true`を、そうでない場合`false`を返します。
### `operator bool()`
```cpp
explicit operator bool() const noexcept;
```
成功値を持っている場合`true`を、そうでない場合`false`を返します。
### `unwrap()`
```cpp
value_type& unwrap(cxx::source_location loc = cxx::source_location::current());
value_type const& unwrap(cxx::source_location loc = cxx::source_location::current()) const;
```
成功値を取り出します。
成功値を持っていない場合、`toml::bad_result_access`が送出されます。
`std::source_location`または`std::experimental::source_location`が利用可能か、
あるいはコンパイラ拡張によって同等の情報が利用可能な場合、`what()`文字列に
`unwrap()`が発生したソースコードのファイル名と行数が表示されます。
利用可能でない場合、位置情報は表示されません。
### `unwrap_or()`
```cpp
value_type& unwrap_or(value_type& opt) noexcept;
value_type const& unwrap_or(value_type const& opt) const noexcept;
```
成功値を持っていた場合それを、持っていなかった場合は引数で与えられた値を返します。
### `unwrap_err()`
```cpp
error_type& unwrap_err(cxx::source_location loc = cxx::source_location::current());
error_type const& unwrap_err(cxx::source_location loc = cxx::source_location::current()) const;
```
失敗値を取り出します。
失敗値を持っていない場合、`toml::bad_result_access`が送出されます。
`std::source_location`または`std::experimental::source_location`が利用可能か、
あるいはコンパイラ拡張によって同等の情報が利用可能な場合、`what()`文字列に
`unwrap()`が発生したソースコードのファイル名と行数が表示されます。
利用可能でない場合、位置情報は表示されません。
### `as_ok()`
```cpp
value_type& as_ok() noexcept;
value_type const& as_ok() const noexcept;
```
チェックなしで成功値を返します。
成功値を持っていなかった場合、その動作は未定義となります。
### `as_err()`
```cpp
error_type& as_err() noexcept;
error_type const& as_err() const noexcept;
```
チェックなしで失敗値を返します。
失敗値を持っていなかった場合、その動作は未定義となります。
# bad_result_access
`result`の`unwrap`または`unwrap_err`で失敗した際に送出される例外です。
```cpp
namespace toml
{
struct bad_result_access : public ::toml::exception
{
public:
explicit bad_result_access(const std::string& what_arg);
virtual ~bad_result_access() noexcept override = default;
virtual const char* what() const noexcept override;
protected:
std::string what_;
};
}
```

66
docs/content.ja/docs/reference/serializer.md Normal file
View File

@@ -0,0 +1,66 @@
+++
title = "serializer.hpp"
type = "docs"
+++
# serializer.hpp
# `format`
シリアライズを行います。
```cpp
namespace toml
{
template<typename TC>
std::string format(const basic_value<TC>& v,
const spec s = spec::default_version());
template<typename TC>
std::string format(const typename basic_value<TC>::key_type& k,
const basic_value<TC>& v,
const spec s = spec::default_version());
template<typename TC>
std::string format(const std::vector<typename basic_value<TC>::key_type>& ks,
const basic_value<TC>& v,
const spec s = spec::default_version());
}
```
フォーマット情報と`spec`が矛盾する場合、例えば`v1.0.0`で`table_format::multiline_oneline`が指定されているときなどは、`spec`が優先されます。
### `format(v, spec)`
`toml::value`を、それが持つフォーマット情報と`spec`に従ってフォーマットします。
`table_type`だった場合、それがルートであるとしてフォーマットします。
それ以外の値だった場合、値のみをフォーマットします。
### `format(k, v, spec)`
`toml::value`を、与えられたキーと同時にフォーマットします。
`v`はそのキー以下に定義されていると解釈されます。
### `format([k,...], v, spec)`
`v`はそのキー以下に定義されていると解釈されます。
キーが複数与えられた場合、再帰的に定義されたテーブルとして解釈されます。
# `serialization_error`
シリアライズ中に発生したエラーを報告します。
```cpp
namespace toml
{
struct serialization_error final : public ::toml::exception
{
public:
explicit serialization_error(std::string what_arg, source_location loc);
~serialization_error() noexcept override = default;
const char* what() const noexcept override;
source_location const& location() const noexcept;
};
}
```

233
docs/content.ja/docs/reference/source_location.md Normal file
View File

@@ -0,0 +1,233 @@
+++
title = "source_location.hpp"
type = "docs"
+++
# source_location.hpp
`source_location.hpp`では、TOMLファイル内のある領域を指すクラスが定義されます。
このクラスは、エラーメッセージで問題の箇所を指摘するために使われます。
# `toml::source_location`
`source_location`は、TOMLファイル内のある領域を指すクラスです。
```cpp
namespace toml
{
struct source_location
{
public:
explicit source_location(/* implementation-defined */);
~source_location() = default;
source_location(source_location const&) = default;
source_location(source_location &&) = default;
source_location& operator=(source_location const&) = default;
source_location& operator=(source_location &&) = default;
bool is_ok() const noexcept;
std::size_t length() const noexcept;
std::size_t first_line_number() const noexcept;
std::size_t first_column_number() const noexcept;
std::size_t last_line_number() const noexcept;
std::size_t last_column_number() const noexcept;
std::string const& file_name() const noexcept;
std::size_t num_lines() const noexcept;
std::string const& first_line() const;
std::string const& last_line() const;
std::vector<std::string> const& lines() const noexcept;
};
template<typename ... Ts>
std::string format_location(const source_location& loc, const std::string& msg, const Ts& ... locs_and_msgs);
} //toml
```
## メンバ関数
### コンストラクタ
```cpp
explicit source_location(/* implementation-defined */);
```
`toml::source_location`を`toml::parse`または`_toml`リテラル以外で構築することはできません。
### `is_ok()`
```cpp
bool is_ok() const noexcept;
```
`source_location`が有効な値を保持している場合、`true`を、そうでない場合`false`を返します。
`toml::parse`や`_toml`リテラル以外から構築した`toml::value`の`location()`の結果は、指す対象がないため、`is_ok`は`false`を返します。
### `length()`
```cpp
std::size_t length() const noexcept;
```
`source_location`が指す領域の長さを返します。
有効な値を保持していない場合、`0`を返します。
### `first_line_number()`
```cpp
std::size_t first_line_number() const noexcept;
```
`source_location`が指す領域の最初の行の行番号を返します。
有効な値を保持していない場合、`1`を返します。
### `first_column_number()`
```cpp
std::size_t first_column_number() const noexcept;
```
`source_location`が指す領域の最初の列の列番号を返します。
有効な値を保持していない場合、`1`を返します。
### `last_line_number()`
```cpp
std::size_t last_line_number() const noexcept;
```
`source_location`が指す領域の最後の行の行番号を返します。
有効な値を保持していない場合、`1`を返します。
### `last_column_number()`
```cpp
std::size_t last_column_number() const noexcept;
```
`source_location`が指す領域の最後の列の列番号を返します。
有効な値を保持していない場合、`1`を返します。
### `file_name()`
```cpp
std::string const& file_name() const noexcept;
```
`source_location`が指す領域を含むファイルのファイル名を返します。
有効な値を保持していない場合、`"unknown file"`を返します。
### `num_lines()`
```cpp
std::size_t num_lines() const noexcept;
```
`source_location`が指す領域の行数を返します。
有効な値を保持していない場合、`0`を返します。
### `first_line()`
```cpp
std::string const& first_line() const;
```
`source_location`が指す領域の最初の行を返します。
有効な値を保持していない場合、`std::out_of_range`例外が送出されます。
### `last_line()`
```cpp
std::string const& last_line() const;
```
`source_location`が指す領域の最後の行を返します。
有効な値を保持していない場合、`std::out_of_range`例外が送出されます。
### `lines()`
```cpp
std::vector<std::string> const& lines() const noexcept;
```
`source_location`が指す領域の全ての行を返します。
有効な値を保持していない場合、空の`std::vector`への参照を返します。
## 非メンバ関数
### `format_location`
```cpp
template<typename ... Ts>
std::string format_location(const source_location& loc, const std::string& msg, const Ts& ... locs_and_msgs);
```
`source_location`が指す箇所と、それについてのメッセージを以下のようにフォーマットします。
```
-> {filename.toml}
|
1 | a = 42
| ^-- {message}
```
この時、色付けがONになっている場合、ANSIエスケープシーケンスによって色情報が追加されます。
locs_and_msgsが複数個ある場合、それらは`const source_location&`と`const std::string&`の順である必要があります。
#### 例：複数の`source_location`と`std::string`
複数の`source_location`と`std::string`を渡した場合、以下のようにフォーマットされます。
```cpp
source_location& loc0;
source_location& loc1;
source_location& loc2;
std::string msg0;
std::string msg1;
std::string msg2;
format_location(loc0, msg0,
loc1, msg1,
loc2, msg2);
```
```
-> {filename0.toml}
|
1 | a = 42
| ^-- {message0}
|
-> {filename1.toml}
|
2 | b = 3.14
| ^-- {message1}
|
-> {filename2.toml}
|
3 | c = "foo"
| ^-- {message2}
```
# 関連項目
- [error_info.hpp]({{<ref "error_info.md">}})
- [value.hpp]({{<ref "value.md">}})

314
docs/content.ja/docs/reference/spec.md Normal file
View File

@@ -0,0 +1,314 @@
+++
title = "spec.hpp"
type = "docs"
+++
# spec.hpp
`spec.hpp`では、TOMLのバージョンを指定するためのクラスが定義されます。
# `toml::semantic_version`
`semantic_version`は、バージョン情報を格納するクラスです。
```cpp
namespace toml
{
struct semantic_version
{
constexpr semantic_version(std::uint32_t mjr, std::uint32_t mnr, std::uint32_t p) noexcept;
std::uint32_t major;
std::uint32_t minor;
std::uint32_t patch;
};
constexpr semantic_version
make_semver(std::uint32_t major, std::uint32_t minor, std::uint32_t patch) noexcept;
constexpr bool operator==(const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator!=(const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator< (const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator<=(const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator> (const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator>=(const semantic_version&, const semantic_version&) noexcept;
std::ostream& operator<<(std::ostream& os, const semantic_version& ver);
} //toml
```
## メンバ関数
### コンストラクタ
```cpp
constexpr semantic_version(std::uint32_t mjr, std::uint32_t mnr, std::uint32_t p) noexcept;
```
`major`, `minor`, `patch`バージョンを指定して構築します。
## 非メンバ関数
### 比較演算子
```cpp
constexpr bool operator==(const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator!=(const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator< (const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator<=(const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator> (const semantic_version&, const semantic_version&) noexcept;
constexpr bool operator>=(const semantic_version&, const semantic_version&) noexcept;
```
semantic versioningに従って比較します。
### ストリーム演算子
```cpp
std::ostream& operator<<(std::ostream& os, const semantic_version& ver);
```
`{major}.{minor}.{patch}`の形式で出力します。
### `to_string`
```cpp
std::string to_string(const semantic_version& ver);
```
`{major}.{minor}.{patch}`の形式で文字列化します。
# `toml::spec`
`spec`は、TOMLのバージョン情報を格納するクラスです。
```cpp
struct spec
{
constexpr static spec default_version() noexcept;
constexpr static spec v(std::uint32_t mjr, std::uint32_t mnr, std::uint32_t p) noexcept;
constexpr explicit spec(const semantic_version& semver) noexcept;
semantic_version version; // toml version
// diff from v1.0.0 -> v1.1.0
bool v1_1_0_allow_control_characters_in_comments;
bool v1_1_0_allow_newlines_in_inline_tables;
bool v1_1_0_allow_trailing_comma_in_inline_tables;
bool v1_1_0_allow_non_english_in_bare_keys;
bool v1_1_0_add_escape_sequence_e;
bool v1_1_0_add_escape_sequence_x;
bool v1_1_0_make_seconds_optional;
// library extensions
bool ext_hex_float; // allow hex float
bool ext_num_suffix; // allow number suffix
bool ext_null_value; // allow null value
};
```
## メンバ関数
### コンストラクタ
```cpp
constexpr explicit spec(const semantic_version& semver) noexcept;
```
指定されたTOMLバージョンで`spec`を構築します。
TOML v1.0.0と、TOML v1.1.0に対応しています。
### `default_version()`
```cpp
constexpr static spec default_version() noexcept;
```
デフォルトのバージョンで`spec`を構築します。
`toml::parse`、`toml::format`でのデフォルト値として使われます。
toml11 v4.0.0での値は、v1.0.0です。
### `v(major, minor, patch)`
```cpp
constexpr static spec v(std::uint32_t mjr, std::uint32_t mnr, std::uint32_t p) noexcept;
```
指定されたバージョンで`spec`を構築します。
## メンバ変数
各フラグは機能追加がされたバージョンを指定されたとき、自動的に`true`になります。
変更して渡すことで、`toml::parse`、`toml::format`の挙動を変更できます。
{{<hint warning>}}
TOML v1.1.0の一部の機能にはかなり長い議論が続いており、まだ差し戻される可能性があります。
実際に差し戻された場合、toml11はマイナーバージョンアップでそれらの機能を削除、もしくは対応するそれ以降のバージョンに移動します。
そのような意味で、将来のバージョンに関する機能は全て不安定なものと考えてください。
{{</hint>}}
### 例
```cpp
auto spec = toml::spec::v(1, 0, 0);
// v1.0.0の機能に追加して、inline table内の改行を許可する。
// それ以外のv1.1.0の機能は有効化されない。
spec.v1_1_0_allow_newlines_in_inline_tables = true;
auto input = toml::parse("input_file.toml", spec);
```
### `v1_1_0_allow_control_characters_in_comments`
```cpp
bool v1_1_0_allow_control_characters_in_comments;
```
ほとんどの制御文字をコメントに含むことを許可します。
toml v1.1.0で追加。
### `v1_1_0_allow_newlines_in_inline_tables`
```cpp
bool v1_1_0_allow_newlines_in_inline_tables;
```
inline table内で改行することを許可します。
toml v1.1.0で追加。
### `v1_1_0_allow_trailing_comma_in_inline_tables`
```cpp
bool v1_1_0_allow_trailing_comma_in_inline_tables;
```
inline table内での末尾コンマを許可します。
toml v1.1.0で追加。
### `v1_1_0_add_escape_sequence_e`
```cpp
bool v1_1_0_add_escape_sequence_e;
```
`\e`でESC文字を指定できるようになります。
toml v1.1.0で追加。
### `v1_1_0_add_escape_sequence_x`
```cpp
bool v1_1_0_add_escape_sequence_x;
```
`\xHH`で1バイトの文字を指定できるようになります。
toml v1.1.0で追加。
### `v1_1_0_make_seconds_optional`
```cpp
bool v1_1_0_make_seconds_optional;
```
時刻での秒数指定を省略可能にします。
指定されなかった秒数は`0`で初期化されます。
toml v1.1.0で追加。
### `ext_hex_float`
```cpp
bool ext_hex_float;
```
toml11限定の言語拡張です。
どのバージョンを指定しても、`false`で初期化されます。
使用する際は個別に`true`にしてください。
浮動小数点数の16進数表記を許可します。
16進数表記は`printf`で`%a/%A`を指定した場合に準拠します。
```
hexf = 0xC0FFEEp-10
```
`toml::format` は、渡された `toml::spec` で `ext_hex_format` が `true` の場合のみ
16進表記でフォーマットします。
フォーマット情報で `hex` が指定されているにも関わらず `toml::format` に渡された
`toml::spec` の `ext_hex_float` が `false` だった場合、16進数指定は無視され、
10進表記で最大の精度で出力されます。
### `ext_num_suffix`
```cpp
bool ext_num_suffix;
```
toml11限定の言語拡張です。
どのバージョンを指定しても、`false`で初期化されます。
使用する際は個別に`true`にしてください。
10進数の整数と浮動小数点数に接尾辞を追加します。型を問わず、16進や8進、2進表記には適用されません。
数値と接尾辞の間は`_`で区切られている必要があります。
数値部分との区別のため、接尾辞は数値で始まることはできません。
```
distance = 10_m # valid
distance = 10_2m # invalid
distance = 10_2_m # valid
```
接尾辞は `std::string suffix` としてフォーマット情報に保持されます。
数値部分とを分ける `_` は `suffix` に含まれません。
```cpp
toml::value distance = toml::find(input, "distance");
assert(distance.as_integer_fmt().suffix == std::string("m"));
```
`toml::format` は、渡された `toml::spec` の `ext_num_suffix` が `true` の場合のみ
これをフォーマットします。
`suffix`は以下のような文法を持ちます。
```abnf
non-digit-graph = ALPHA / non-ascii
graph = ALPHA / DIGIT / non-ascii
suffix = _ non-digit-graph *( graph / ( _ graph ) )
```
### `ext_null_value`
```cpp
bool ext_null_value;
```
toml11限定の言語拡張です。
値として `null` を許可します。
`null` を指定された `toml::value` は値を持たず、 `is_empty()` が `true` になります。
`toml::format` は、渡された `toml::spec` で `ext_null_value` が `true` の場合のみ
`null` としてフォーマットします。
そうでない場合、 `toml::format` がエラーで終了します。

14
docs/content.ja/docs/reference/toml.md Normal file
View File

@@ -0,0 +1,14 @@
+++
title = "toml.hpp"
type = "docs"
+++
# toml.hpp
`toml.hpp`は、他の全てのヘッダを `include` します。
これによって、toml11の全機能が使用可能になります。
このヘッダファイルと `toml_fwd.hpp` は `${TOML11_INCLUDE_DIR}/` 以下に、
他のヘッダファイルは `${toml11_include_dir}/toml11/` 以下にあります。

24
docs/content.ja/docs/reference/toml_fwd.md Normal file
View File

@@ -0,0 +1,24 @@
+++
title = "toml_fwd.hpp"
type = "docs"
+++
# toml_fwd.hpp
`toml_fwd.hpp`は、toml11で定義される構造体の前方宣言と、マクロ定義を持ちます。
toml11の構造体についての前方宣言しか必要なく実装が必要ない場合、
`toml.hpp` のかわりにこちらを `include` することでコンパイル時間を短縮できます。
{{<hint warning>}}
このファイルには前方宣言しか含まれていないため、
`toml::basic_value<toml::type_config>::table_type` として定義される
`toml::table` と、同様に定義される `toml::array` は使用できません。
それらには `basic_value` の実装が必要だからです。
{{</hint>}}
このヘッダファイルと `toml.hpp` は `${TOML11_INCLUDE_DIR}/` 以下に、
他のヘッダファイルは `${TOML11_INCLUDE_DIR}/toml11/` 以下にあります。

154
docs/content.ja/docs/reference/types.md Normal file
View File

@@ -0,0 +1,154 @@
+++
title = "types.hpp"
type = "docs"
+++
# types.hpp
型情報を与えるクラスが定義されます。
# `type_config`
`type_config`は、`toml::basic_value`に与えられるパラメータをまとめた型です。
`toml::basic_value<T>`内で異なる型を使用する場合、これを別に定義して渡します。
記載のある要素は全て必須の要素です。
通常のストリーム演算子を使用できない数値型を使用する場合、`read_int`、`read_float`に相当するものを定義し、置き換えてください。
```cpp
namespace toml
{
struct type_config
{
using comment_type = preserve_comments;
using boolean_type = bool;
using integer_type = std::int64_t;
using floating_type = double;
using string_type = std::string;
template<typename T>
using array_type = std::vector<T>;
template<typename K, typename T>
using table_type = std::unordered_map<K, T>;
static result<integer_type, error_info>
parse_int(const std::string& str, const source_location src, const std::uint8_t base);
static result<floating_type, error_info>
parse_float(const std::string& str, const source_location src, const bool is_hex);
};
using value = basic_value<type_config>;
using table = typename value::table_type;
using array = typename value::array_type;
} // toml
```
## `static` メンバ関数
### `parse_int(str, src, base)`
```cpp
static result<integer_type, error_info>
parse_int(const std::string& str, const source_location src, const std::uint8_t base);
```
通常のストリーム演算子などを使用できない型を`integer_type`として使用する場合、この関数を実装してください。
`str`には、prefix、（`0x`などの場合）leading zero、underscoreが取り除かれた文字列が渡されます。
`src`には、その文字列が定義されていた箇所を指す`source_location`が渡されます。
`base`には、`10`, `2`, `8`, `16`のいずれかが渡されます。
### `parse_float(str, src, is_hex)`
```cpp
static result<floating_type, error_info>
parse_float(const std::string& str, const source_location src, const bool is_hex);
```
通常のストリーム演算子などを使用できない型を`floating_type`として使用する場合、この関数を実装してください。
`str`には、prefix、leading zero、underscoreが取り除かれた文字列が渡されます。
`src`には、その文字列が定義されていた箇所を指す`source_location`が渡されます。
`is_hex`には、フォーマットが`hexfloat`であるかどうかが渡されます。`hexfloat`拡張を使用しない場合は使われないので、実装する必要はありません。
`hexfloat`拡張に関しては、[spec.hpp]({{<ref "spec.md">}})を参照してください。
## 非メンバ関数
### `read_int`
```cpp
template<typename T>
result<T, error_info>
read_int(const std::string& str, const source_location src, const std::uint8_t base);
```
デフォルトで使用される関数です。`std::istringstream`を使用してパースします。
`operator>>`と`std::hex`等のマニピュレータ、`std::numeric_limits<T>`が定義されている場合（`boost::multiprecision`など）、特に変更なしにこれを使用できます。
### `read_float`
```cpp
template<typename T>
result<T, error_info>
read_float(const std::string& str, const source_location src, const bool is_hex);
```
デフォルトで使用される関数です。decimalの場合は`std::istringstream`を、hexfloatの場合は`sscanf()`を使用してパースします。
`double`、`float`に対応しています。
それ以外の型の場合、`operator>>`が定義されていて、かつ`hex`を使用しないなら、これを使用できます。
# `ordered_type_config`
`ordered_type_config`は、`toml::type_config`のテーブル型を`toml::ordered_map`に変更したものです。
また、`toml::ordered_value`エイリアスを定義します。
そのほかに`type_config`との違いはありません。
```cpp
namespace toml
{
struct ordered_type_config
{
using comment_type = preserve_comments;
using boolean_type = bool;
using integer_type = std::int64_t;
using floating_type = double;
using string_type = std::string;
template<typename T>
using array_type = std::vector<T>;
template<typename K, typename T>
using table_type = ordered_map<K, T>;
static result<integer_type, error_info>
parse_int(const std::string& str, const source_location src, const std::uint8_t base)
{
return read_int<integer_type>(str, src, base);
}
static result<floating_type, error_info>
parse_float(const std::string& str, const source_location src, const bool is_hex)
{
return read_float<floating_type>(str, src, is_hex);
}
};
using ordered_value = basic_value<ordered_type_config>;
using ordered_table = typename ordered_value::table_type;
using ordered_array = typename ordered_value::array_type;
} // toml
```

896
docs/content.ja/docs/reference/value.md Normal file
View File

@@ -0,0 +1,896 @@
+++
title = "value.hpp"
type = "docs"
+++
# value.hpp
`value.hpp`では、`basic_value`が定義されます。
# `toml::basic_value`
`basic_value`は、TOMLの値を格納するクラスです。
```cpp
namespace toml
{
template <class TypeConfig>
class basic_value;
// 以下はtypes.hppで定義される
// using value = basic_value<type_config>;
// using table = typename basic_value<type_config>::table_type;
// using array = typename basic_value<type_config>::array_type;
template<typename TC>
bool operator==(const basic_value<TC>&, const basic_value<TC>&);
template<typename TC>
bool operator!=(const basic_value<TC>&, const basic_value<TC>&);
template<typename TC>
bool operator< (const basic_value<TC>&, const basic_value<TC>&);
template<typename TC>
bool operator<=(const basic_value<TC>&, const basic_value<TC>&);
template<typename TC>
bool operator> (const basic_value<TC>&, const basic_value<TC>&);
template<typename TC>
bool operator>=(const basic_value<TC>&, const basic_value<TC>&);
} //toml
```
## メンバ型
以下のメンバ型が定義されます。
`TypeConfig`を使って、メンバ型を変更することができます。
参考： [types.hpp]({{<ref "types.md">}})
| 名前 | 定義 |
|:-----------------------|:-------------------------------------|
| `char_type` | `typename TypeConfig::char_type` |
| `key_type` | `typename TypeConfig::string_type` |
| `value_type` | `basic_value<TypeConfig>` |
| `boolean_type` | `typename TypeConfig::boolean_type` |
| `integer_type` | `typename TypeConfig::integer_type` |
| `floating_type` | `typename TypeConfig::floating_type` |
| `string_type` | `typename TypeConfig::string_type` |
| `local_time_type` | `toml::local_time` |
| `local_date_type` | `toml::local_date` |
| `local_datetime_type` | `toml::local_datetime` |
| `offset_datetime_type` | `toml::offset_datetime` |
| `array_type` | `typename TypeConfig::template array_type<value_type>`|
| `table_type` | `typename TypeConfig::template table_type<key_type, value_type>`|
| `comment_type` | `typename TypeConfig::comment_type` |
## メンバ関数
### デフォルトコンストラクタ
```cpp
basic_value() noexcept
```
空の`toml::value`を構築します。
構築された`toml::value`は空になります。
### コピー・ムーブコンストラクタ
```cpp
basic_value(const basic_value& v)
basic_value(basic_value&& v)
```
値、フォーマット情報、コメント、ファイル領域の全ての情報をコピー・ムーブします。
### コピー・ムーブコンストラクタ（コメント指定）
```cpp
basic_value(basic_value v, std::vector<std::string> com)
```
コメントを上書きしながらコピー・ムーブします。
### 変換コンストラクタ
```cpp
template<typename TI>
basic_value(basic_value<TI> other)
template<typename TI>
basic_value(basic_value<TI> other, std::vector<std::string> com)
```
異なる`type_config`を持つ`basic_value`からコピー・ムーブします。
### コンストラクタ (boolean)
```cpp
basic_value(boolean_type x)
basic_value(boolean_type x, boolean_format_info fmt)
basic_value(boolean_type x, std::vector<std::string> com)
basic_value(boolean_type x, boolean_format_info fmt, std::vector<std::string> com)
```
`bool`と、そのフォーマット情報、コメントを受け取って構築します。
### コンストラクタ (integer)
```cpp
basic_value(integer_type x)
basic_value(integer_type x, integer_format_info fmt)
basic_value(integer_type x, std::vector<std::string> com)
basic_value(integer_type x, integer_format_info fmt, std::vector<std::string> com)
```
`integer`と、そのフォーマット情報、コメントを受け取って構築します。
### コンストラクタ(floating)
```cpp
template<typename T, /* T は std::is_floating_point<T> を満たす */>
basic_value(T x)
template<typename T, /* T は std::is_floating_point<T> を満たす */>
basic_value(T x, floating_format_info fmt)
template<typename T, /* T は std::is_floating_point<T> を満たす */>
basic_value(T x, std::vector<std::string> com)
template<typename T, /* T は std::is_floating_point<T> を満たす */>
basic_value(T x, floating_format_info fmt, std::vector<std::string> com)
```
`floating`と、そのフォーマット情報、コメントを受け取って構築します。
### コンストラクタ(string)
```cpp
basic_value(string_type x)
basic_value(string_type x, string_format_info fmt)
basic_value(string_type x, std::vector<std::string> com)
basic_value(string_type x, string_format_info fmt, std::vector<std::string> com)
basic_value(const string_type::value_type* x)
basic_value(const string_type::value_type* x, string_format_info fmt)
basic_value(const string_type::value_type* x, std::vector<std::string> com)
basic_value(const string_type::value_type* x, string_format_info fmt, std::vector<std::string> com)
// C++17以降
basic_value(string_view_type x)
basic_value(string_view_type x, string_format_info fmt)
basic_value(string_view_type x, std::vector<std::string> com)
basic_value(string_view_type x, string_format_info fmt, std::vector<std::string> com)
```
`string`と、そのフォーマット情報、コメントを受け取って構築します。
`string_view_type`は、`string_type`と同じ`value_type`と`traits_type`を持ちます。
### コンストラクタ(local_date)
```cpp
basic_value(local_date_type x)
basic_value(local_date_type x, local_date_format_info fmt)
basic_value(local_date_type x, std::vector<std::string> com)
basic_value(local_date_type x, local_date_format_info fmt, std::vector<std::string> com)
```
`local_date_type`と、そのフォーマット情報、コメントを受け取って構築します。
### コンストラクタ(local_time)
```cpp
basic_value(local_time_type x)
basic_value(local_time_type x, local_time_format_info fmt)
basic_value(local_time_type x, std::vector<std::string> com)
basic_value(local_time_type x, local_time_format_info fmt, std::vector<std::string> com)
template<typename Rep, typename Period>
basic_value(const std::chrono::duration<Rep, Period>& x)
template<typename Rep, typename Period>
basic_value(const std::chrono::duration<Rep, Period>& x, local_time_format_info fmt)
template<typename Rep, typename Period>
basic_value(const std::chrono::duration<Rep, Period>& x, std::vector<std::string> com)
template<typename Rep, typename Period>
basic_value(const std::chrono::duration<Rep, Period>& x, local_time_format_info fmt, std::vector<std::string> com)
```
`local_time_type`と、そのフォーマット情報、コメントを受け取って構築します。
`std::chrono::duration`は、`00:00:00`からの時間幅として構築します。
### コンストラクタ(local_datetime)
```cpp
basic_value(local_datetime_type x)
basic_value(local_datetime_type x, local_date_format_info fmt)
basic_value(local_datetime_type x, std::vector<std::string> com)
basic_value(local_datetime_type x, local_date_format_info fmt, std::vector<std::string> com)
```
`local_datetime_type`と、そのフォーマット情報、コメントを受け取って構築します。
### コンストラクタ(offset_datetime)
```cpp
basic_value(offset_datetime_type x)
basic_value(offset_datetime_type x, offset_date_format_info fmt)
basic_value(offset_datetime_type x, std::vector<std::string> com)
basic_value(offset_datetime_type x, offset_date_format_info fmt, std::vector<std::string> com)
basic_value(std::chrono::system_clock::time_point x)
basic_value(std::chrono::system_clock::time_point x, offset_date_format_info fmt)
basic_value(std::chrono::system_clock::time_point x, std::vector<std::string> com)
basic_value(std::chrono::system_clock::time_point x, offset_date_format_info fmt, std::vector<std::string> com)
```
`offset_datetime_type`と、そのフォーマット情報、コメントを受け取って構築します。
`std::chrono::system_clock::time_point`の場合、それが指す時点として構築します。
### コンストラクタ(array)
```cpp
basic_value(array_type x)
basic_value(array_type x, integer_format_info fmt)
basic_value(array_type x, std::vector<std::string> com)
basic_value(array_type x, integer_format_info fmt, std::vector<std::string> com)
template<typename T, /* T is array-like */>
basic_value(T x)
template<typename T, /* T is array-like */>
basic_value(T x, array_format_info fmt)
template<typename T, /* T is array-like */>
basic_value(T x, std::vector<std::string> com)
template<typename T, /* T is array-like */>
basic_value(T x, array_format_info fmt, std::vector<std::string> com)
```
`array`と、そのフォーマット情報、コメントを受け取って構築します。
`array-like`は、以下の条件を満たす型です。
- `T::iterator` を持つ。
- `T::value_type` を持つ。
- `T::key_type` を持た**ない**。
- `T::mapped_type` を持た**ない**。
- `std::string` では**ない**。
- `std::string_view` では**ない**。(C++17以降)
### コンストラクタ(table)
```cpp
basic_value(table_type x)
basic_value(table_type x, integer_format_info fmt)
basic_value(table_type x, std::vector<std::string> com)
basic_value(table_type x, integer_format_info fmt, std::vector<std::string> com)
template<typename T, /* T is table-like */>
basic_value(T x)
template<typename T, /* T is table-like */>
basic_value(T x, table_format_info fmt)
template<typename T, /* T is table-like */>
basic_value(T x, std::vector<std::string> com)
template<typename T, /* T is table-like */>
basic_value(T x, table_format_info fmt, std::vector<std::string> com)
```
`table`と、そのフォーマット情報、コメントを受け取って構築します。
`table-like`は、以下の条件を満たす型です。
- `T::iterator` を持つ。
- `T::value_type` を持つ。
- `T::key_type` を持つ。
- `T::mapped_type` を持つ。
### コンストラクタ(user-defined)
```cpp
template<typename T /* toml::into<T>が定義されていること */>
basic_value(const T& ud);
template<typename T /* toml::into<T>が定義されていること */>
basic_value(const T& ud, std::vector<std::string> com);
template<typename T /* into<T>は定義されておらず、T{}.into_toml()が存在すること */>
basic_value(const T& ud);
template<typename T /* into<T>は定義されておらず、T{}.into_toml()が存在すること */>
basic_value(const T& ud, std::vector<std::string> com);
```
`toml::into<T>` が定義されていた場合、 `toml::into<T>(ud)` の結果から構築します。
`toml::into<T>` が定義されておらず、 `T` に `into_toml()` メンバ関数が定義されていた場合、
`ud.into_toml()`の結果から構築します。
-----
### `operator=(basic_value)`
```cpp
basic_value& operator=(const basic_value& v)
basic_value& operator=(basic_value&& v)
template<typename TI>
basic_value& operator=(basic_value<TI> other)
```
右辺の`basic_value`を代入します。
### `operator=(T)`
```cpp
template<typename T>
basic_value& operator=(T x)
```
Tに対応する値を代入します。
`source_location`の指す内容は破棄されます。
もし同じ型の値を持っていたなら、元のフォーマット情報が保持されます。
-----
### `is<T>()`
```cpp
bool is<T>() const noexcept
```
#### 条件
`T`は厳密にTOML型であること。つまり、値に対応する`toml::value::xxx_type`のいずれかであること。
#### 戻り値
格納している型が`T`と一致した場合`true`を、そうでない場合は`false`を返します。
-----
### `is(toml::value_t)`
```cpp
bool is(toml::value_t t) const noexcept
```
#### 戻り値
格納している型のタグが`t`と一致した場合`true`を、そうでない場合は`false`を返します。
-----
### `is_xxx()`
```cpp
bool is_boolean() const noexcept;
bool is_integer() const noexcept;
bool is_floating() const noexcept;
bool is_string() const noexcept;
bool is_offset_datetime() const noexcept;
bool is_local_datetime() const noexcept;
bool is_local_date() const noexcept;
bool is_local_time() const noexcept;
bool is_array() const noexcept;
bool is_table() const noexcept;
```
#### 戻り値
格納している型がその型である場合`true`を、そうでない場合は`false`を返します。
-----
### `is_empty()`
```cpp
bool is_empty() const noexcept;
```
#### 戻り値
デフォルト構築され値が代入されていない場合`true`を、そうでない場合は`false`を返します。
### `is_array_of_tables()`
```cpp
bool is_array_of_tables() const noexcept;
```
#### 戻り値
格納している型が配列であり、空ではなく、全要素がテーブルの場合は`true`を、そうでない場合は`false`を返します。
-----
### `type()`
```cpp
toml::value_t type() const noexcept
```
#### 戻り値
格納している型に対応するタグを返します。
-----
### `as_xxx()`
```cpp
boolean_type const& as_boolean () const;
integer_type const& as_integer () const;
floating_type const& as_floating () const;
string_type const& as_string () const;
offset_datetime_type const& as_offset_datetime() const;
local_datetime_type const& as_local_datetime () const;
local_date_type const& as_local_date () const;
local_time_type const& as_local_time () const;
array_type const& as_array () const;
table_type const& as_table () const;
boolean_type & as_boolean ();
integer_type & as_integer ();
floating_type & as_floating ();
string_type & as_string ();
offset_datetime_type& as_offset_datetime();
local_datetime_type & as_local_datetime ();
local_date_type & as_local_date ();
local_time_type & as_local_time ();
array_type & as_array ();
table_type & as_table ();
```
#### 戻り値
指定された型への参照を返します。
#### 例外
格納されている値の型が指定と異なる場合、`toml::type_error`を送出します。
-----
### `as_xxx(std::nothrow)`
`std::nothrow`オブジェクトを渡して呼び出します。
```cpp
boolean_type const& as_boolean (const std::nothrow_t&) const noexcept;
integer_type const& as_integer (const std::nothrow_t&) const noexcept;
floating_type const& as_floating (const std::nothrow_t&) const noexcept;
string_type const& as_string (const std::nothrow_t&) const noexcept;
offset_datetime_type const& as_offset_datetime(const std::nothrow_t&) const noexcept;
local_datetime_type const& as_local_datetime (const std::nothrow_t&) const noexcept;
local_date_type const& as_local_date (const std::nothrow_t&) const noexcept;
local_time_type const& as_local_time (const std::nothrow_t&) const noexcept;
array_type const& as_array (const std::nothrow_t&) const noexcept;
table_type const& as_table (const std::nothrow_t&) const noexcept;
boolean_type & as_boolean (const std::nothrow_t&) noexcept;
integer_type & as_integer (const std::nothrow_t&) noexcept;
floating_type & as_floating (const std::nothrow_t&) noexcept;
string_type & as_string (const std::nothrow_t&) noexcept;
offset_datetime_type& as_offset_datetime(const std::nothrow_t&) noexcept;
local_datetime_type & as_local_datetime (const std::nothrow_t&) noexcept;
local_date_type & as_local_date (const std::nothrow_t&) noexcept;
local_time_type & as_local_time (const std::nothrow_t&) noexcept;
array_type & as_array (const std::nothrow_t&) noexcept;
table_type & as_table (const std::nothrow_t&) noexcept;
```
#### 戻り値
指定された型への参照を返します。
#### 備考
格納されている値の型が指定と異なる場合、未定義動作となります。
-----
### `as_xxx_fmt()`
フォーマット情報にアクセスします。
```cpp
boolean_format_info & as_boolean_fmt ();
integer_format_info & as_integer_fmt ();
floating_format_info & as_floating_fmt ();
string_format_info & as_string_fmt ();
offset_datetime_format_info& as_offset_datetime_fmt();
local_datetime_format_info & as_local_datetime_fmt ();
local_date_format_info & as_local_date_fmt ();
local_time_format_info & as_local_time_fmt ();
array_format_info & as_array_fmt ();
table_format_info & as_table_fmt ();
boolean_format_info const& as_boolean_fmt () const;
integer_format_info const& as_integer_fmt () const;
floating_format_info const& as_floating_fmt () const;
string_format_info const& as_string_fmt () const;
offset_datetime_format_info const& as_offset_datetime_fmt() const;
local_datetime_format_info const& as_local_datetime_fmt () const;
local_date_format_info const& as_local_date_fmt () const;
local_time_format_info const& as_local_time_fmt () const;
array_format_info const& as_array_fmt () const;
table_format_info const& as_table_fmt () const;
```
#### 戻り値
指定された型のフォーマット情報を持つ構造体への参照を返します。
#### 例外
格納されている値の型が指定と異なる場合、`toml::type_error`を送出します。
-----
### `as_xxx_fmt(std::nothrow)`
`std::nothrow`オブジェクトを渡して呼び出します。
```cpp
boolean_format_info & as_boolean_fmt (const std::nothrow_t&) noexcept;
integer_format_info & as_integer_fmt (const std::nothrow_t&) noexcept;
floating_format_info & as_floating_fmt (const std::nothrow_t&) noexcept;
string_format_info & as_string_fmt (const std::nothrow_t&) noexcept;
offset_datetime_format_info& as_offset_datetime_fmt(const std::nothrow_t&) noexcept;
local_datetime_format_info & as_local_datetime_fmt (const std::nothrow_t&) noexcept;
local_date_format_info & as_local_date_fmt (const std::nothrow_t&) noexcept;
local_time_format_info & as_local_time_fmt (const std::nothrow_t&) noexcept;
array_format_info & as_array_fmt (const std::nothrow_t&) noexcept;
table_format_info & as_table_fmt (const std::nothrow_t&) noexcept;
boolean_format_info const& as_boolean_fmt (const std::nothrow_t&) const noexcept;
integer_format_info const& as_integer_fmt (const std::nothrow_t&) const noexcept;
floating_format_info const& as_floating_fmt (const std::nothrow_t&) const noexcept;
string_format_info const& as_string_fmt (const std::nothrow_t&) const noexcept;
offset_datetime_format_info const& as_offset_datetime_fmt(const std::nothrow_t&) const noexcept;
local_datetime_format_info const& as_local_datetime_fmt (const std::nothrow_t&) const noexcept;
local_date_format_info const& as_local_date_fmt (const std::nothrow_t&) const noexcept;
local_time_format_info const& as_local_time_fmt (const std::nothrow_t&) const noexcept;
array_format_info const& as_array_fmt (const std::nothrow_t&) const noexcept;
table_format_info const& as_table_fmt (const std::nothrow_t&) const noexcept;
```
#### 戻り値
指定された型のフォーマット情報を持つ構造体への参照を返します。
#### 備考
格納されている値の型が指定と異なる場合、未定義動作となります。
-----
### `at(key)`
```cpp
value_type& at(const key_type& key);
value_type const& at(const key_type& key) const;
```
#### 戻り値
今の`value`を`table`にキャストしたあと、`key`によって指定される要素を返します。
#### 例外
もし格納している値が`table`ではなかった場合、`toml::type_error`を送出します。
もし格納している`table`が指定された要素を持っていなかった場合、`std::out_of_range`を送出します。
-----
#### `operator[](key)`
```cpp
value_type& operator[](const key_type& k);
```
##### 戻り値
今の`value`を`table`にキャストしたあと、`key`によって指定される要素への参照です。
もし`key`によって指定される要素が存在しない場合、デフォルト構築されます。
##### 例外
もし格納している値が`table`ではなかった場合、`toml::type_error`を送出します。
-----
### `count(key)`
```cpp
std::size_t count(const key_type& key) const;
```
#### 戻り値
今の`value`を`table`にキャストしたあと、`key`に対応する要素が含まれていれば`1`、そうでなければ`0`を返します。
#### 例外
もし格納している値が`table`ではなかった場合、`toml::type_error`を送出します。
-----
### `contains(key)`
```cpp
bool contains(const key_type& key) const;
```
#### 戻り値
今の`value`を`table`にキャストしたあと、`key`に対応する要素が含まれていれば`true`、そうでなければ`false`を返します。
#### 例外
もし格納している値が`table`ではなかった場合、`toml::type_error`を送出します。
-----
### `at(idx)`
```cpp
value_type& at(const std::size_t idx);
value_type const& at(const std::size_t idx) const;
```
#### 戻り値
今の`value`を`array`にキャストしたあと、`idx`によって指定される要素を返します。
#### 例外
もし格納している値が`array`ではなかった場合、`toml::type_error`を送出します。
もし格納している`array`が指定された要素を持っていなかった場合、`std::out_of_range`を送出します。
-----
### `operator[](idx)`
```cpp
value_type& operator[](const std::size_t idx) noexcept;
value_type const& operator[](const std::size_t idx) const noexcept;
```
#### 戻り値
今の`value`を`array`にキャストしたあと、`idx`によって指定される要素への参照を返します。
#### 備考
一切のチェックを行いません。
もし格納している値が`array`ではなかった場合、あるいは`idx`によって指定される要素が存在しない場合、未定義動作となります。
-----
### `push_back(value)`
```cpp
void push_back(const value_type& x);
void push_back(value_type&& x);
```
`value`を`array`にキャストしたのち、その`array`に対して`push_back`を実行します。
#### 戻り値
なし。
#### 例外
格納している値が`array`ではなかった場合、`toml::type_error`を送出します。
-----
### `emplace_back(args...)`
```cpp
template<typename ... Ts>
value_type& emplace_back(Ts&& ... args)
```
`value`を`array`にキャストしたのち、その`array`に対して`emplace_back`を実行します。
#### 戻り値
構築した値への参照。
#### 例外
格納している値が`array`ではなかった場合、`toml::type_error`を送出します。
-----
### `size()`
```cpp
std::size_t size() const;
```
#### 戻り値
今の`value`を`array`、`string`、`table`のどれかにキャストしたあと、その要素数を返します。
`string`の場合、文字数を返します。
#### 例外
格納している値が`array`, `string`, `table`のどれでもなかった場合、`toml::type_error`を送出します。
-----
### `location()`
```cpp
source_location location() const;
```
#### 戻り値
その`value`が定義されたTOML文書内の位置を表す`source_location`オブジェクトを返します。
もしTOML文書のパースによって構築されたものでない場合、どこも指示さない`source_location`を返します。
-----
### `comments()`
```cpp
comment_type const& comments() const noexcept;
comment_type& comments() noexcept;
```
#### 戻り値
コメント用コンテナへの参照を返します。
## 非メンバ関数
### `operator==`
```cpp
template<typename TC>
bool operator==(const basic_value<TC>&, const basic_value<TC>&);
```
以下を満たすとき、2つの`basic_value<T>`は同値となります。
- TOML型が同一
- 含む値が同一
- コメントがバイト単位で同一
### `operator!=`
```cpp
template<typename TC>
bool operator!=(const basic_value<TC>& lhs, const basic_value<TC>& rhs)
{
return !(lhs == rhs);
}
```
### `operator<`
`array_type`と`table_type`が`operator<`を持っている場合のみ定義されます。
```cpp
template<typename TC>
bool operator<(const basic_value<TC>&, const basic_value<TC>&);
```
以下の順番で比較されます。
1. TOML型
2. TOML型が同一の場合、その値
3. TOML型とその値が同一の場合、コメント
TOML型は、以下の順に小さい値を持ちます。
1. `toml::value_t::empty`
2. `toml::value_t::boolean`
3. `toml::value_t::integer`
4. `toml::value_t::floating`
5. `toml::value_t::string`
6. `toml::value_t::offset_datetime`
7. `toml::value_t::local_datetime`
8. `toml::value_t::local_date`
9. `toml::value_t::local_time`
10. `toml::value_t::array`
11. `toml::value_t::table`
### `operator<=`
`array_type`と`table_type`が`operator<`を持っている場合のみ定義されます。
```cpp
template<typename TC>
bool operator<=(const basic_value<TC>& lhs, const basic_value<TC>& rhs)
{
return (lhs < rhs) || (lhs == rhs);
}
```
### `operator>`
`array_type`と`table_type`が`operator<`を持っている場合のみ定義されます。
```cpp
template<typename TC>
bool operator>(const basic_value<TC>& lhs, const basic_value<TC>& rhs)
{
return !(lhs <= rhs);
}
```
### `operator>=`
`array_type`と`table_type`が`operator<`を持っている場合のみ定義されます。
```cpp
template<typename TC>
bool operator>=(const basic_value<TC>& lhs, const basic_value<TC>& rhs)
{
return !(lhs < rhs);
}
```
# `toml::type_error`
型エラーの際に送出される例外です。
型エラーが生じた値の位置情報が格納されています。
```cpp
struct type_error final : public ::toml::exception
{
public:
type_error(std::string what_arg, source_location loc);
~type_error() noexcept override = default;
const char* what() const noexcept override;
source_location const& location() const noexcept;
};
```
# `toml::make_error_info`
```cpp
template<typename TC, typename ... Ts>
error_info make_error_info(
std::string title, const basic_value<TC>& v, std::string msg, Ts&& ... tail);
```
`basic_value` の `location()` を呼び出して、その `source_location` を
[`make_error_info`]({{<ref "docs/reference/error_info#make_error_info">}})
に渡して `error_info` を作成します。
詳しくは [`error_info`]({{<ref "docs/reference/error_info">}}) を参照してください。
# `toml::format_error`
```cpp
template<typename TC, typename ... Ts>
std::string format_error(std::string title,
const basic_value<TC>& v, std::string msg, Ts&& ... tail);
```
`basic_value` の `location()` を呼び出して、その `source_location` を
[`format_error`]({{<ref "docs/reference/error_info#format_error">}})
に渡して `error_info` を作成し、それを文字列化して返します。
詳しくは [`error_info`]({{<ref "docs/reference/error_info">}}) を参照してください。
# 関連項目
- [comments.hpp]({{<ref "comments.md">}})
- [source_location.hpp]({{<ref "source_location.md">}})
- [types.hpp]({{<ref "types.md">}})
- [visit.hpp]({{<ref "visit.md">}})

54
docs/content.ja/docs/reference/value_t.md Normal file
View File

@@ -0,0 +1,54 @@
+++
title = "value_t.hpp"
type = "docs"
+++
# value_t.hpp
型情報を表す列挙型です。
# `value_t`
`value_t`は、`toml::value`が持つ型情報を扱う際に使用します。
```cpp
namespace toml
{
enum class value_t : std::uint8_t
{
empty = 0,
boolean = 1,
integer = 2,
floating = 3,
string = 4,
offset_datetime = 5,
local_datetime = 6,
local_date = 7,
local_time = 8,
array = 9,
table = 10
};
std::ostream& operator<<(std::ostream& os, value_t t);
std::string to_string(value_t t);
} // toml
```
## 非メンバ関数
### ストリーム演算子
```cpp
std::ostream& operator<<(std::ostream& os, value_t t);
```
`value_t`の値を文字列化してストリームへ出力します。
### `to_string`
```cpp
std::string to_string(value_t t);
```
`value_t`の値を文字列化して返します。

37
docs/content.ja/docs/reference/version.md Normal file
View File

@@ -0,0 +1,37 @@
+++
title = "version.hpp"
type = "docs"
+++
# version.hpp
`version.hpp`では、toml11とC++のバージョン情報に関係するマクロが定義されます。
## マクロ
### `TOML11_VERSION_MAJOR`
toml11のメジャーバージョンです。
### `TOML11_VERSION_MINOR`
toml11のマイナーバージョンです。
### `TOML11_VERSION_PATCH`
toml11のパッチバージョンです。
## 関数
### `license_notice`
```cpp
namespace toml
{
const char* license_notice() noexcept;
}
```
ライセンス条項を返します。
ソースコードを公開せずに頒布する際の利便性のために用意されています。

69
docs/content.ja/docs/reference/visit.md Normal file
View File

@@ -0,0 +1,69 @@
+++
title = "visit.hpp"
type = "docs"
+++
# visit.hpp
`visit.hpp`では、`toml::visit`が定義されます。
# `toml::visit`
## 関数
```cpp
namespace toml
{
template<typename Visitor, typename TC>
/* Visitor を basic_value<TC>の値で呼び出した際の返り値 */
visit(Visitor&& visitor, const basic_value<TC>& v);
template<typename Visitor, typename TC>
/* Visitor を basic_value<TC>の値で呼び出した際の返り値 */
visit(Visitor&& visitor, basic_value<TC>& v)
template<typename Visitor, typename TC>
/* Visitor を basic_value<TC>の値で呼び出した際の返り値 */
visit(Visitor&& visitor, basic_value<TC>&& v)
}
```
`basic_value<TC>`が保持している型に対応する`Visitor`のオーバーロードを呼び出し、その結果を返します。
#### 条件
`Visitor`は、`basic_value<TC>`が保持している型のどれに対しても呼び出し可能な関数または関数オブジェクトでなければなりません。
また、それぞれのオーバーロードで返り値は同じであることが要求されます。
#### 例
```cpp
#include <toml.hpp>
#include <iostream>
struct type_name_of
{
std::string operator()(const toml::value::boolean_type &) const {return "boolean";}
std::string operator()(const toml::value::integer_type &) const {return "integer";}
std::string operator()(const toml::value::floating_type &) const {return "floating";}
std::string operator()(const toml::value::string_type &) const {return "string";}
std::string operator()(const toml::value::local_time_type &) const {return "local_time";}
std::string operator()(const toml::value::local_date_type &) const {return "local_date";}
std::string operator()(const toml::value::local_datetime_type &) const {return "local_datetime";}
std::string operator()(const toml::value::offset_datetime_type&) const {return "offset_datetime";}
std::string operator()(const toml::value::array_type &) const {return "array";}
std::string operator()(const toml::value::table_type &) const {return "table";}
};
int main()
{
toml::value v(3.14);
std::cout << toml::visit(type_name_of{}, v) << std::endl; // floating
return 0;
}
```
# 関連項目
- [value.hpp]({{<ref "value.md">}})