AuroraMiddleware/toml11

Fork 0

mirror of https://github.com/ToruNiina/toml11.git synced 2024-09-19 15:19:54 +00:00

ToruNiina d00c0c1b15 doc: explain a macro to link pre-built lib

2024-06-28 23:52:58 +09:00

17 KiB

Raw Permalink Blame History

toml11 v4

toml11は、C++11,14,17,20のための豊富な機能を持つTOML言語ライブラリです。

TOML言語の最新規格に準拠しています。
TOML言語標準のテストケースすべてにパスしています。
TOML言語の次期バージョン (v1.1.0) にマージされた新機能のそれぞれを試すことができます。
エラーが起きた位置を含めたわかりやすいエラーメッセージを出力します。
コメントもパースし、対応する値に保存します。
16進整数やクオートの種類などのフォーマット情報を保持し、シリアライズ時に考慮します。
例外を投げないバージョンをサポートします。
TOML値からの複雑な型変換をサポートします。
整数、浮動小数点数、コンテナ等の型を変更可能です。
TOML言語にない一部の拡張機能を試すことができます。

Example

#include <toml.hpp>
#include <iostream>

// ```toml
// title = "an example toml file"
// nums  = [3, 1, 4, 1, 5] # pi!
// ```

int main()
{
    // select TOML version at runtime (optional)
    auto data = toml::parse("example.toml", toml::spec::v(1,1,0));

    // find a value with the specified type from a table
    std::string title = toml::find<std::string>(data, "title");

    // convert the whole array into STL-like container automatically
    std::vector<int> nums = toml::find<std::vector<int>>(data, "nums");

    // access with STL-like manner
    if( ! data.contains("foo"))
    {
        data["foo"] = "bar";
    }
    if(data.at("nums").is_array())
    {
        data.push_back(9);
    }

    // check comments
    assert(data.at("nums").comments().at(0) == "# pi!");

    // pass a fallback
    std::string name = toml::find_or<std::string>(data, "name", "not found");

    // serialization considering format info
    data.at("nums").as_array_fmt().fmt = toml::array_format::multiline;
    data.at("nums").as_array_fmt().indent_type = toml::indent_char::space;
    data.at("nums").as_array_fmt().body_indent = 2;

    std::cout << toml::format(data) << std::endl;

    return 0;
}

詳細な機能とリファレンスに関しては、ドキュメントを参照してください。

Integration
Features
Breaking Changes from v3
Contributors
Licensing Terms

Integration

toml11を使うには複数の方法があります。

ここではそれぞれを短く紹介します。詳細は、ドキュメントを参照してください。

Single include file

single_include/toml.hppを好きなところにコピーして、インクルードパスを通してください。

git submodule

git submoduleなどでサブディレクトリにすれば、toml11/includeにインクルードパスを通すか、 add_subdirectory(toml11) とすることで使用できます。

Install using CMake

以下の手順で、CMakeを使ってインストールすることができます。

$ git clone https://github.com/ToruNiina/toml11
$ cd toml11
$ git submodule update --init --recursive
$ cmake -B ./build/
$ cmake --build ./build/
$ cmake --install ./build --prefix /path/to/toml11

Precompile library

-DTOML11_PRECOMPILE=ON とすることで、ライブラリの一部の関数をコンパイルできます。

この場合、C++バージョンによって使用できる標準ライブラリ機能が変化し、インターフェースの一部が変わるため、CMAKE_CXX_STANDARDを指定する必要があります。

$ cmake -B ./build/ -DTOML11_PRECOMPILE=ON -DCMAKE_CXX_STANDARD=11/14/17/20
$ cmake --build ./build/

ライブラリをリンクする場合は、CMakeで

target_link_libraries(your_target PUBLIC toml11::toml11)

とするか、コンパイラに-DTOML11_COMPILE_SOURCESを渡してください。

Building example

-DTOML11_BUILD_EXAMPLES=ONとすることで、examples/をコンパイルできます。

$ cmake -B ./build/ -DTOML11_BUILD_EXAMPLES=ON
$ cmake --build ./build/

Building example

-DTOML11_BUILD_TESTS=ONとすることで、ユニットテストをコンパイルできます。

また、-DTOML11_BUILD_TOML_TESTS=ONとすることで、toml-test用のencoderとdecoderをコンパイルできます。

$ cmake -B ./build/ -DTOML11_BUILD_EXAMPLES=ON
$ cmake --build ./build/

Features

ここでは、toml11の持つ機能を短く紹介します。

詳細についてはドキュメントを参照してください。

parsing a file

ファイルをパースする場合は、toml::parseを使います。

ファイル全体の型は常にテーブルですが、 toml::value はコメントやフォーマット情報などのメタデータを持つので、toml::parseからは toml::table ではなく toml::value が返ります。

const toml::value input = toml::parse("input.toml");

文字列そのものをパースする場合は、toml::parse_strを使います。

const toml::value input = toml::parse_str("a = 42");

toml::parseは文法エラーの際に toml::syntax_error 例外を投げます。これを避けるには、 toml::result を返す toml::try_parse を使います。

const auto input = toml::try_parse("input.toml");
if(input.is_ok())
{
    std::cout << input.unwrap().at("a").as_integer() << std::endl;
}

また、使用するTOML言語のバージョンを簡単に、かつ細かく変更できるようになりました。

TOML v1.0.0に加えて、v1.1.0の新機能を一部だけ使用するというような制御が可能です。

toml::spec s = toml::spec::v(1, 0, 0);
s.v1_1_0_allow_trailing_comma_in_inline_tables = true;

const toml::value input = toml::parse("input.toml");

また、TOML言語自体に含まれない言語拡張もいくつか用意しています。

toml::spec s = toml::spec::v(1, 0, 0);
s.ext_hex_float  = true; // 16進数浮動小数点数を許可
s.ext_null_value = true; // 空の値 `null` を許可
s.ext_num_suffix = true; // `100_msec`などのsuffixを許可

各機能の紹介とリファレンスは、ドキュメントを参照してください。

finding a value

toml::value はアクセス用のメンバ関数、at() や is_xxx(), as_xxx() を持ちます。

const toml::value input = toml::parse("input.toml");
if(input.contains("a") && input.at("a").is_integer())
{
    std::cout << input.at("a").as_integer() << std::endl;
}

toml::find を使うことで、型変換と検索が同時に行えます。

const toml::value input = toml::parse("input.toml");
std::cout << toml::find<int>(input, "a") << std::endl;

また、複雑なTOML値に対して、高度な型変換を行うことができます。

mixed_array = [
    42,
    3.14,
    {a = "foo", b = "bar"}
]

const toml::value input = toml::parse("input.toml");

const auto mixed = toml::find<
        std::tuple<int, double, std::map<std::string, std::string>>
    >(input, "mixed_array") << std::endl;

詳細についてはドキュメントを参照してください。

comments

toml11は、値に関するコメントを値に保存します。

値に関するコメントとは、ある値の直前に書かれた一連のコメントと、値の直後に改行を挟まず書かれたコメントです。

# これは a のコメントです。
# これも a のコメントです。
a = 42 # これも a のコメントです。

# これは改行で分かれているので、 b のコメントではありません。

# これは b のコメントです。
b = "foo"

これは std::vector<std::string> と同じインターフェースで toml::value に格納されます。

const toml::value input = toml::parse("input.toml");
std::cout << input.at("a").comments().size() << std::endl;
std::cout << input.at("a").comments().at(0) << std::endl;

詳細についてはドキュメントを参照してください。

error messages

toml11の目標の一つは、わかりやすいエラーメッセージを出力することです。

パースエラーに対しては以下のようなエラーメッセージが、

[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

このようなエラーメッセージを、TOMLの文法とは関係のないユーザー特有の処理に対しても出力することが可能です。

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

詳細はドキュメントを参照してください。

serialization

toml::format を使うことで、toml::value を std::string にフォーマットできます。

const toml::value input = toml::parse("input.toml");
std::cout << toml::format(input) << std::endl;

toml::format はフォーマット情報を参照します。なので、フォーマット方法を変更することが可能です。

toml::value output(toml::table{ {"a", 0xDEADBEEF} });
output.at("a").as_integer_fmt().fmt = toml::integer_format::hex;
output.at("a").as_integer_fmt().spacer = 4;

std::cout << toml::format(input) << std::endl;

どのような指定が可能かなどの詳細はドキュメントを参照してください。

configuring types

examplesディレクトリには、多倍長整数を使用する場合やユニコードを正規化する場合、外部のリフレクションライブラリと連携する場合などの複雑な使用例を用意しています。

そのような状況での実装例として参照してください。

Changes from v3

toml11 v3からは複数の破壊的変更が追加されています。

シンプルな使い方をしている場合にはほとんど変更せずに済むように努力はしていますが、高度な機能を利用していた場合は多少の変更が必要になります。

しかし、追加された機能や整理された機能は、その分の利便性を提供できると考えています。

破壊的な変更

ブランチを master から main に変更
toml::basic_value の template 引数を変更
フォーマット情報を陽に格納するためtoml::string を廃止
フォーマット情報を使用するためtoml::formatの引数を変更
TOMLバージョン情報を格納するtoml::specを追加するためtoml::parseのデフォルト引数を変更
toml::source_location のインターフェースを複数行を前提とした形に変更
toml::format_error の引数を変更
toml::format_underline の名称を toml::format_location に変更
toml::color の制御方法を toml::color::enable()に統一

破壊的でない変更

toml::parse_strの追加
toml::try_parseの追加
バイト列のパースをサポート
toml::value にフォーマット情報を追加
コメントをデフォルトで保存するよう変更
single_include/toml.hppの追加
コンパイル済みライブラリとしての使用を可能に

Contributors

このライブラリに新機能を追加、あるいはバグを修正してくださったコントリビュータの方々に感謝します。

Guillaume Fraux (@Luthaf)
- Windows support and CI on Appvayor
- Intel Compiler support
Quentin Khan (@xaxousis)
- Found & Fixed a bug around ODR
- Improved error messages for invalid keys to show the location where the parser fails
Petr Beneš (@wbenny)
- Fixed warnings on MSVC
Ivan Shynkarenka (@chronoxor)
- Fixed Visual Studio 2019 warnings
- Fix compilation error in <filesystem> with MinGW
Khoi Dinh Trinh (@khoitd1997)
- Fixed warnings while type conversion
@KerstinKeller
- Added installation script to CMake
J.C. Moyer (@jcmoyer)
- Fixed an example code in the documentation
Jt Freeman (@blockparty-sh)
- Fixed feature test macro around localtime_s
- Suppress warnings in Debug mode
OGAWA Kenichi (@kenichiice)
- Suppress warnings on intel compiler
- Fix include path in README
Jordan Williams (@jwillikers)
- Fixed clang range-loop-analysis warnings
- Fixed feature test macro to suppress -Wundef
- Use cache variables in CMakeLists.txt
- Automate test set fetching, update and refactor CMakeLists.txt
Scott McCaskill
- Parse 9 digits (nanoseconds) of fractional seconds in a local_time
Shu Wang (@halfelf)
- fix "Finding a value in an array" example in README
@maass-tv and @SeverinLeonhardt
- Fix MSVC warning C4866
Mohammed Alyousef (@MoAlyousef)
- Made testing optional in CMake
Alex Merry (@amerry)
- Add missing include files
sneakypete81 (@sneakypete81)
- Fix typo in error message
Oliver Kahrmann (@founderio)
- Fix missing filename in error message if parsed file is empty
Karl Nilsson (@karl-nilsson)
- Fix many spelling errors
ohdarling88 (@ohdarling)
- Fix a bug in a constructor of serializer
estshorter (@estshorter)
- Fix MSVC warning C26478
Philip Top (@phlptp)
- Improve checking standard library feature availability check
Louis Marascio (@marascio)
- Fix free-nonheap-object warning
Axel Huebl (@ax3l)
- Make installation optional if the library is embedded
Ken Matsui (@ken-matsui)
- Support user-defined error message prefix
- Support dynamic color mode
Giel van Schijndel (@muggenhor)
- Remove needless copy in parse function
Lukáš Hrázký (@lukash)
- Add a parse(FILE *) interface and improve file-related error messages
spiderman idog (@spiderman-idog)
- Fix typo in README
Jajauma's GitHub (@Jajauma)
- Avoid possible lexer truncation warnings
Moritz Klammler (@ctcmkl)
- Many patches in (#200) including:
- Improve CMake scripts, build process, and test file handling
- Detect error when discard_comments is accessed
- And more.
Chris White (@cxw42)
- Fix address-sanitizer error when parsing literal strings having invalid UTF-8 characters
- Fix function name in error messages
offa (@offa)
- Update checkout action to v3
- Update Required CMake version
- Cleanup old CI settings
Sergey Vidyuk (@VestniK)
- Fix for case when vector iterator is raw pointer
Kfir Gollan (@kfirgollan)
- Add installation example with checkinstall and cmake
Martin Tournoij (@arp242)
- Escape control characters in keys
@DavidKorczynski
- Add fuzzing test based on ClusterFuzzLite
Esonhugh Skyworship (@Esonhugh)
- Fix function signature of strerror_r on macos

Licensing terms

This product is licensed under the terms of the MIT License.

17 KiB Raw Permalink Blame History

toml11 v4

Example

Table of Contents

Integration

Single include file

git submodule

Install using CMake

Precompile library

Building example

Building example

Features

parsing a file

finding a value

comments

error messages

serialization

configuring types

Changes from v3

破壊的な変更

破壊的でない変更

Contributors

Licensing terms

17 KiB

Raw Permalink Blame History