# NAME TOML::XS - Parse [TOML](https://toml.io) with XS # SYNOPSIS # NB: Don’t read_text(), or stuff may break. my $toml = File::Slurper::read_binary('/path/to/toml/file'); my $struct = TOML::XS::from_toml($toml)->to_struct(); # DESCRIPTION This module facilitates parsing of TOML documents in Perl via XS, which can yield significant performance gains relative to pure-Perl TOML libraries. It is currently implemented as a wrapper around the [tomlc99](https://github.com/cktan/tomlc99) C library. # FUNCTIONS ## $doc = TOML::XS::from\_toml($byte\_string) Converts a byte string (i.e., raw, undecoded bytes) that contains a serialized TOML document to a [TOML::XS::Document](https://metacpan.org/pod/TOML::XS::Document) instance. # MAPPING TOML TO PERL Most TOML data items map naturally to Perl. The following details are relevant: - Strings are character-decoded. - Booleans are represented as [TOML::XS::true](https://metacpan.org/pod/TOML::XS::true) and [TOML::XS::false](https://metacpan.org/pod/TOML::XS::false), which are namespace aliases for the relevant constants from [Types::Serialiser](https://metacpan.org/pod/Types::Serialiser). - Timestamps are represented as [TOML::XS::Timestamp](https://metacpan.org/pod/TOML::XS::Timestamp) instances. # NOTE ON CHARACTER DECODING This library mimics the default configuration of popular JSON modules: the TOML input to the parser is expected to be a byte string, while the strings that the parser outputs are character strings. # PERFORMANCE For small- and medium-sized files this should be quite a bit faster than pure-Perl TOML parsers. With larger files the speed gains are more muted or even (??) reversed. (That’s an underlying issue with tomlc99.) # COPYRIGHT & LICENSE Copyright 2021 Gasper Software Consulting. All rights reserved. This library is licensed under the same license as Perl itself. [tomlc99](https://github.com/cktan/tomlc99) is licensed under the [MIT License](https://mit-license.org/).