Introduction on toml11

parsing files

Mon, 01 Jan 0001 00:00:00 +0000

ファイル・文字列をパースする #

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 または toml::try_parse を使います。

`toml::parse` #

`std::string`でファイル名を指定する #

toml::parse は、文字列でファイル名を受け取り、そのファイルを開いてパースします。

以下のサンプルは、input.tomlというファイルをパースし、titleという変数を文字列として取り出し、出力するコードです。

#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::filesystem::path`でファイルを指定する #

toml::parse には、std::filesystem::pathを渡すことも可能です。

当然ですが、<filesystem>がサポートされるC++17以降でなければ使用できません。

`std::istream`で入力ストリームを指定する #

toml::parse には、std::istreamを渡すことも可能です。

getting values

Mon, 01 Jan 0001 00:00:00 +0000

値を取り出す #

ここでは、 toml::value が格納している値にアクセスする方法を説明します。

メンバ関数を使って値にアクセスする #

`is_something` と `as_something` #

toml::value は is_boolean() や is_integer() などのメンバ関数を持っており、これらを使うと持っている型を調べることができます。

また、 as_boolean(), as_integer() などのメンバ関数も持っており、これらを使ってその型にアクセスすることができます。

完全なリストは toml::value のリファレンスを参照してください。

toml::value v = /* ... */;
if(v.is_integer())
{
 std::cout << v.as_integer() << std::endl;
}

指定された値と異なる型が格納されていた場合、 toml::type_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 で識別できます。

error message

Mon, 01 Jan 0001 00:00:00 +0000

エラーメッセージを出力する #

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 からこのようなエラーメッセージを作成する方法を提供します。

serializing values

Mon, 01 Jan 0001 00:00:00 +0000

TOMLファイルを出力する #

toml::format を使うと、 toml::value を文字列にすることができます。

#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 としてキーを渡すことが可能です。

configuring types

Mon, 01 Jan 0001 00:00:00 +0000

型をカスタマイズする #

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メンバ関数を持つクラスです。

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 、のようにして定義しています。

toml literal

Mon, 01 Jan 0001 00:00:00 +0000

`_toml`リテラル #

""_tomlリテラルによって、TOMLファイルをその場でフォーマットできます。

#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;
}

改行を含む場合、生文字列リテラルが便利です。

#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;
}

値が単体で書かれていた場合、その値が返されます。

#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]はテーブル名として合法です。

toml spec

Mon, 01 Jan 0001 00:00:00 +0000

TOML言語バージョン #

toml::spec によって、 toml::parse や toml::format で使用するTOML言語のバージョンや、個別の機能フラグを指定することができます。

TOMLのバージョンを指定する #

toml::spec は toml::semantic_version から構築できます。

#include <toml.hpp>

int main()
{
 toml::spec spec(toml::semantic_version(1, 1, 0));
 return 0;
}

ですがこれは長いので、toml::spec::v()関数が用意されています。

#include <toml.hpp>

int main()
{
 toml::spec spec = toml::spec::v(1, 1, 0);
 return 0;
}

特に指定しない場合、デフォルトの値で構築する toml::spec::default_version() が使用されます。

デフォルトの値はtoml11のバージョンによって変わりますが、その時点でリリースされているTOML言語の最新バージョンに追従します。

v4.4.0現在、TOML v1.1.0はまだリリースされていないため、デフォルトのTOMLバージョンはv1.0.0です。

TOML v1.1.0の一部の機能にはかなり長い議論が続いており、まだ差し戻される可能性があります。

実際に差し戻された場合、toml11はマイナーバージョンアップでそれらの機能を削除、もしくは対応するそれ以降のバージョンに移動します。

そのような意味で、将来のバージョンに関する機能は全て不安定なものと考えてください。

バージョン指定でパースする #

toml::parse のオーバーロードは、ファイル名に続いてtoml::specを受け取ります。

これによって、使用するTOMLバージョンを変更できます。

#include <toml.hpp>

int main()
{
 toml::value input = toml::parse("input.toml", toml::spec::v(1, 1, 0));
 return 0;
}

バージョン指定でシリアライズする #

toml::format のオーバーロードは、 toml::value に続いて toml::spec を受け取ります。

extension

Mon, 01 Jan 0001 00:00:00 +0000

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" という文字列のキーとして解釈されます。

#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進数フォーマットを使用できるようになります。

color.hpp

Mon, 01 Jan 0001 00:00:00 +0000

color.hpp #

color.hppでは、エラーメッセージの色付けに関する関数が定義されます。

色はANSIエスケープシーケンスによって指定されます。 ANSIエスケープシーケンスをサポートしていないターミナルやその他の出力先では、読みにくくなる可能性があります。

マクロ #

`TOML11_COLORIZE_ERROR_MESSAGE` #

コンパイル時にこのマクロが定義されていた場合（-DTOML11_COLORIZE_ERROR_MESASGE）、デフォルトでエラーメッセージに色が付きます。

定義されていなかった場合、デフォルトでは色は付きません。以下の toml::color::enable() を使用して指定する必要があります。

`TOML11_USE_THREAD_LOCAL_COLORIZATION` #

コンパイル時にこのマクロが定義されていた場合（-DTOML11_COLORIZE_ERROR_MESASGE）、 toml::color::enableの設定がthread_localになります。この場合、toml::color::enable()やtoml::color::disable()は、それを呼び出したスレッドでの設定しか変更しません。つまり、新しいスレッドを起動した際にデフォルトと異なる設定にしたい場合は、再度設定が必要になります。その代わり、toml::color::enable()やtoml::color::disable()はスレッドセーフになります。

デフォルトでは設定はグローバルです。グローバルの場合、一つのスレッドがtoml::color::enable()を実行した場合、すべてのスレッドで色が付きます。ただし、あるスレッドがenable()またはdisable()を実行している間に別のスレッドがenable()、disable()、should_color()を実行した場合、その結果は未定義です。

関数 #

`enable()` #

namespace toml {
namespace color {
void enable();
} // color
} // toml

ANSIエスケープシーケンスによる色付けを行うよう設定します。

例 #

#include <toml.hpp>

int main()
{
 toml::color::enable(); // この後の全てのエラーがカラーになります。
 const auto input = toml::parse("input.toml");
 return 0;
}

`disable()` #

namespace toml {
namespace color {
void disable();
} // color
} // toml

ANSIエスケープシーケンスによる色付けを行わないよう設定します。

comments.hpp

Mon, 01 Jan 0001 00:00:00 +0000

comments.hpp #

color.hppでは、コメントを保持するクラスが提供されます。

`toml::preserve_comments` #

preserve_commentsは、コメントを保持するコンテナです。

std::vector<std::string>が持つメンバ関数を全て持っています。

コメントはstd::stringとして保持されます。先頭が#でない場合、出力時に#が補われます。コンテナに要素として追加する段階では補われません。スペースは補われないため、#の直後にスペースを入れたい場合、コメントをスペースから始めるか、#を含めたコメントを渡す必要があります。

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

メンバ型 #

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;

メンバ関数 #

デフォルトコンストラクタ #

preserve_comments() = default;

空のpreserve_commentsを構築します。

conversion.hpp

Mon, 01 Jan 0001 00:00:00 +0000

conversion.hpp #

toml::getやtoml::findでユーザー定義型をサポートするための変換関数を自動定義するマクロを提供します。

TOML11_DEFINE_CONVERSION_NON_INTRUSIVE(NAME, ...)

例 #

namespace foo
{
struct Foo
{
 std::string s;
 double d;
 int i;
};
} // foo

TOML11_DEFINE_CONVERSION_NON_INTRUSIVE(foo::Foo, s, d, i)

datetime.hpp

Mon, 01 Jan 0001 00:00:00 +0000

datetime.hpp #

TOMLのdatetimeで使用される、日時情報を保存するクラスを定義します。

`enum class month_t` #

月を指定するenum classです。

std::tmとの関係で、local_dateは1月を0としています。混乱を避けるため、月の名前で指定できるようmonth_tが用意されています。

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は日付を保持します。

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` #

std::int16_t year;

西暦です。オフセットはありません。2024年は2024です。

error_info.hpp

Mon, 01 Jan 0001 00:00:00 +0000

error_info.hpp #

error_info.hppでは、error_infoと、それをフォーマットする関数が定義されます。

`toml::error_info` #

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を構築します。

exception.hpp

Mon, 01 Jan 0001 00:00:00 +0000

exception.hpp #

`toml::exception` #

toml11で定義される例外型の基底クラスです。

namespace toml
{
struct exception : public std::exception
{
 public:
 virtual ~exception() noexcept override = default;
 virtual const char* what() const noexcept override {return "";}
};
} // toml

メンバ関数 #

デストラクタ #

virtual ~exception() noexcept override = default;

派生する際に上書きします。

`what` #

virtual const char* what() const noexcept override {return "";}

エラーメッセージを返します。派生する際に上書きします。

find.hpp

Mon, 01 Jan 0001 00:00:00 +0000

find.hpp #

toml::valueから値を検索し、同時に（必要な場合）型変換を行う関数です。

toml::value は格納する型を変更でき、toml::findはそれらに対応しているので、厳密には全て toml::basic_value<TC> が使われています。ただしこれでは冗長なので、関数の宣言と特に区別しなければならない場合を除いて、簡単のため説明文では toml::value と書きます。説明文では、テンプレートパラメータTCを変更して型が変更されていれば toml::value::integer_type などの型は追従して変更されると解釈してください。

`toml::find` #

概要 #

toml::findには、取り出したい型をテンプレート引数で、検索したい値のキーを引数で与えます。

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ではキーの中に.が含まれていても分割は行わず、そのままの文字列で検索を行います。

format.hpp

Mon, 01 Jan 0001 00:00:00 +0000

format.hpp #

toml::valueのフォーマット情報を持つ構造体と列挙型を定義します。

`indent_char` #

インデント情報を表す列挙体です。

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のフォーマット情報です。

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` #

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の基数を指定します。

from.hpp

Mon, 01 Jan 0001 00:00:00 +0000

from.hpp #

toml::getやtoml::findで使用する、toml::valueからの変換を定義する構造体です。

メンバ関数にfrom_tomlを追加することによっても同じ機能を追加できますが、メンバ関数を追加できないクラスに対してはfrom<T>を使用してください。

このファイルでは特定の実装は提供しません。使用する際に、この構造体を特殊化してください。

namespace toml
{

template<typename T>
struct from;

} // toml

例 #

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

get.hpp

Mon, 01 Jan 0001 00:00:00 +0000

get.hpp #

toml::valueから値を取り出し、同時に（必要な場合）型変換を行う関数です。

toml::value は格納する型を変更でき、toml::getはそれらに対応しているので、厳密には全て toml::basic_value<TC> が使われています。ただしこれでは冗長なので、関数の宣言と特に区別しなければならない場合を除いて、簡単のため説明文では toml::value と書きます。説明文では、テンプレートパラメータTCを変更して型が変更されていれば toml::value::integer_type などの型は追従して変更されると解釈してください。

`toml::get<T>` #

概要 #

基本的に、toml::getは以下のような関数として振る舞います。 Tはtoml::get<int>(v)のようにして与えます。

template<typename T, typename TC>
T get(const basic_value<TC>& v);

ただし、Tがどのような型であるかによって、toml::getは異なる挙動をします。

Tの型の種類は、

変換が必要ない型
変換する必要がある型

に分けられます。

細かい条件と、特別にサポートしている具体的な型については後述します。

変換が必要ない型 #

変換が必要ないのは、渡された 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>などの複雑な型変換をサポートします。具体的には、続くセクションを参照してください。

into.hpp

Mon, 01 Jan 0001 00:00:00 +0000

into.hpp #

toml::valueのコンストラクタで使用する、ユーザー定義型からの変換を定義する構造体です。

メンバ関数にinto_tomlを追加することによっても同じ機能を追加できますが、メンバ関数を追加できないクラスに対してはinto<T>を使用してください。

このファイルでは特定の実装は提供しません。使用する際に、この構造体を特殊化してください。

namespace toml
{

template<typename T>
struct into;

} // toml

例 #

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

literal.hpp

Mon, 01 Jan 0001 00:00:00 +0000

literal.hpp #

literal.hppでは、_tomlリテラルが定義されます。

_tomlリテラルは、文字列リテラルをパースしてtoml::valueに変換します。

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)` #

toml::value operator"" _toml(const char* str, std::size_t len);

文字列リテラルをパースしてtoml::valueに変換します。

通常のTOMLファイルの場合、toml::parseと同等の処理が行われます。

const auto v1 = "a = 'foo'"_toml; // v1: {a = 'foo'}

改行を含む場合、生文字列リテラルが便利です。

const auto v1 = R"(
 a = 42
 b = "foo"
)"_toml;

値が単体で書かれていた場合、その値になります。

const auto v2 = "'foo'"_toml; // v2: 'foo'

TOMLは数値のみからなるキーを許可しています。 [1]のように、テーブル定義と配列の区別がつかない場合、テーブル定義が優先されます。

配列として解釈させるには、trailing commaを使用してください。

ordered_map.hpp

Mon, 01 Jan 0001 00:00:00 +0000

ordered_map.hpp #

ファイル中の値の順番を維持するために使用するtoml::ordered_mapを定義します。

`class ordered_map` #

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) の時間がかかります。検索を行う機会が少なく、値の順序を守る必要がある場合に使用してください。

非メンバ型 #

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 の代わりに使用します。

toml::parse はデフォルトで type_config を使用するので、パースする際に
const auto input = toml::parse<toml::ordered_type_config>("input.toml");
としてください。

メンバ型 #

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;

メンバ関数 #

コンストラクタ #

ordered_map() = default;

空の ordered_map を構築します。

parser.hpp

Mon, 01 Jan 0001 00:00:00 +0000

parser.hpp #

ファイルまたは文字列をパースする関数と、それが用いる例外を定義します。

parseは失敗した場合に例外を送出しますが、try_parseはエラー情報を返します。

`parse` #

与えられたファイルの内容をパースし、toml::basic_valueを返します。

失敗した場合はtoml::syntax_errorが送出されます。

basic_valueの持つ型情報はtemplateで、TOML言語のバージョンはtoml::specで指定します。

`parse(std::string filename, toml::spec)` #

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)` #

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)` #

namespace toml
{
template<typename TC = type_config>
basic_value<TC>
parse(const std::filesystem::path& fpath,
 spec s = spec::default_version());
}

<filesystem>が利用可能な場合のみ定義されます。

result.hpp

Mon, 01 Jan 0001 00:00:00 +0000

result.hpp #

result.hppは、成功値か失敗値かのどちらかを持つresult型を定義します。

これは、例外を投げないtoml::try_parseの返り値として使用されます。

success #

成功値を持つ型です。

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])
}

メンバ型 #

using value_type = T;

成功値の型です。

serializer.hpp

Mon, 01 Jan 0001 00:00:00 +0000

serializer.hpp #

`format` #

シリアライズを行います。

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はそのキー以下に定義されていると解釈されます。キーが複数与えられた場合、再帰的に定義されたテーブルとして解釈されます。

source_location.hpp

Mon, 01 Jan 0001 00:00:00 +0000

source_location.hpp #

source_location.hppでは、TOMLファイル内のある領域を指すクラスが定義されます。

このクラスは、エラーメッセージで問題の箇所を指摘するために使われます。

`toml::source_location` #

source_locationは、TOMLファイル内のある領域を指すクラスです。

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

メンバ関数 #

コンストラクタ #

explicit source_location(/* implementation-defined */);

toml::source_locationをtoml::parseまたは_tomlリテラル以外で構築することはできません。

spec.hpp

Mon, 01 Jan 0001 00:00:00 +0000

spec.hpp #

spec.hppでは、TOMLのバージョンを指定するためのクラスが定義されます。

`toml::semantic_version` #

semantic_versionは、バージョン情報を格納するクラスです。

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

メンバ関数 #

コンストラクタ #

constexpr semantic_version(std::uint32_t mjr, std::uint32_t mnr, std::uint32_t p) noexcept;

major, minor, patchバージョンを指定して構築します。

toml_fwd.hpp

Mon, 01 Jan 0001 00:00:00 +0000

toml_fwd.hpp #

toml_fwd.hppは、toml11で定義される構造体の前方宣言と、マクロ定義を持ちます。

toml11の構造体についての前方宣言しか必要なく実装が必要ない場合、 toml.hpp のかわりにこちらを include することでコンパイル時間を短縮できます。

このファイルには前方宣言しか含まれていないため、 toml::basic_value<toml::type_config>::table_type として定義される toml::table と、同様に定義される toml::array は使用できません。それらには basic_value の実装が必要だからです。

このヘッダファイルと toml.hpp は ${TOML11_INCLUDE_DIR}/ 以下に、他のヘッダファイルは ${TOML11_INCLUDE_DIR}/toml11/ 以下にあります。

toml.hpp

Mon, 01 Jan 0001 00:00:00 +0000

toml.hpp #

toml.hppは、他の全てのヘッダを include します。

これによって、toml11の全機能が使用可能になります。

このヘッダファイルと toml_fwd.hpp は ${TOML11_INCLUDE_DIR}/ 以下に、他のヘッダファイルは ${toml11_include_dir}/toml11/ 以下にあります。

types.hpp

Mon, 01 Jan 0001 00:00:00 +0000

types.hpp #

型情報を与えるクラスが定義されます。

`type_config` #

type_configは、toml::basic_valueに与えられるパラメータをまとめた型です。

toml::basic_value<T>内で異なる型を使用する場合、これを別に定義して渡します。記載のある要素は全て必須の要素です。

通常のストリーム演算子を使用できない数値型を使用する場合、read_int、read_floatに相当するものを定義し、置き換えてください。

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)` #

static result<integer_type, error_info>
parse_int(const std::string& str, const source_location src, const std::uint8_t base);

通常のストリーム演算子などを使用できない型をinteger_typeとして使用する場合、この関数を実装してください。

value_t.hpp

Mon, 01 Jan 0001 00:00:00 +0000

value_t.hpp #

型情報を表す列挙型です。

`value_t` #

value_tは、toml::valueが持つ型情報を扱う際に使用します。

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

非メンバ関数 #

ストリーム演算子 #

std::ostream& operator<<(std::ostream& os, value_t t);

value_tの値を文字列化してストリームへ出力します。

`to_string` #

std::string to_string(value_t t);

value_tの値を文字列化して返します。

value.hpp

Mon, 01 Jan 0001 00:00:00 +0000

value.hpp #

value.hppでは、basic_valueが定義されます。

`toml::basic_value` #

basic_valueは、TOMLの値を格納するクラスです。

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

メンバ型 #

以下のメンバ型が定義されます。

version.hpp

Mon, 01 Jan 0001 00:00:00 +0000

version.hpp #

version.hppでは、toml11とC++のバージョン情報に関係するマクロが定義されます。

マクロ #

`TOML11_VERSION_MAJOR` #

toml11のメジャーバージョンです。

`TOML11_VERSION_MINOR` #

toml11のマイナーバージョンです。

`TOML11_VERSION_PATCH` #

toml11のパッチバージョンです。

関数 #

`license_notice` #

namespace toml
{
const char* license_notice() noexcept;
}

ライセンス条項を返します。

ソースコードを公開せずに頒布する際の利便性のために用意されています。

visit.hpp

Mon, 01 Jan 0001 00:00:00 +0000

visit.hpp #

visit.hppでは、toml::visitが定義されます。

`toml::visit` #

関数 #

namespace toml
{

template<typename Visitor, typename ... Args>
/* visitor にArgsの中身を渡した際の返り値 */
visit(Visitor&& visitor, Args&& ... args);

} // toml

basic_value<TC>が保持している型に対応するVisitorのオーバーロードを呼び出し、その結果を返します。

条件 #

Visitorは、basic_value<TC>が保持している型のどれに対しても呼び出し可能な関数または関数オブジェクトでなければなりません。

また、それぞれのオーバーロードで返り値は同じであることが要求されます。

例 #

#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;
}

Introduction on toml11

parsing files

ファイル・文字列をパースする #

ファイルをパースする #

toml::parse #

std::stringでファイル名を指定する #

std::filesystem::pathでファイルを指定する #

std::istreamで入力ストリームを指定する #

getting values

値を取り出す #

メンバ関数を使って値にアクセスする #

is_something と as_something #

toml::value_t #

error message

エラーメッセージを出力する #

serializing values

TOMLファイルを出力する #

キーを渡して出力する #

configuring types

型をカスタマイズする #

type_config #

toml literal

_tomlリテラル #

toml spec

TOML言語バージョン #

TOMLのバージョンを指定する #

バージョン指定でパースする #

バージョン指定でシリアライズする #

extension

TOML言語拡張 #

null #

浮動小数点数の16進数フォーマット #

color.hpp

color.hpp #

マクロ #

TOML11_COLORIZE_ERROR_MESSAGE #

TOML11_USE_THREAD_LOCAL_COLORIZATION #

関数 #

enable() #

例 #

disable() #

comments.hpp

comments.hpp #

toml::preserve_comments #

メンバ型 #

メンバ関数 #

デフォルトコンストラクタ #

conversion.hpp

conversion.hpp #

例 #

関連項目 #

datetime.hpp

datetime.hpp #

enum class month_t #

local_date #

メンバ変数 #

year #

error_info.hpp

error_info.hpp #

toml::error_info #

メンバ関数 #

コンストラクタ(title, loc, msg, suffix) #

exception.hpp

exception.hpp #

toml::exception #

メンバ関数 #

デストラクタ #

what #

find.hpp

find.hpp #

toml::find #

概要 #

再帰的な検索に関しての注意 #

format.hpp

format.hpp #

indent_char #

boolean_format_info #

integer_format #

from.hpp

from.hpp #

`toml::parse` #

`std::string`でファイル名を指定する #

`std::filesystem::path`でファイルを指定する #

`std::istream`で入力ストリームを指定する #

`is_something` と `as_something` #

`toml::value_t` #

`type_config` #

`_toml`リテラル #

`null` #

`TOML11_COLORIZE_ERROR_MESSAGE` #

`TOML11_USE_THREAD_LOCAL_COLORIZATION` #

`enable()` #

`disable()` #

`toml::preserve_comments` #

`enum class month_t` #

`local_date` #

`year` #

`toml::error_info` #

コンストラクタ(`title, loc, msg, suffix`) #

`toml::exception` #

`what` #

`toml::find` #

`indent_char` #

`boolean_format_info` #

`integer_format` #

`toml::get<T>` #

`operator"" _toml(char)` #

`class ordered_map` #

`parse` #

`parse(std::string filename, toml::spec)` #

`parse(const char (&)[N] filename, toml::spec)` #

`parse(std::filesystem::path, toml::spec)` #

`format` #

`format(v, spec)` #

`format(k, v, spec)` #

`format([k,...], v, spec)` #

`toml::source_location` #

`toml::semantic_version` #

`type_config` #

`static` メンバ関数 #

`parse_int(str, src, base)` #

`value_t` #

`to_string` #

`toml::basic_value` #