# NAME TOML::XS - Turbo-charged [TOML](https://toml.io) parsing!
# 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 dramatic 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. Throws a suitable exception if the TOML document is unparseable. This doesn’t necessarily mean that _any_ malformed TOML content triggers such an error; for example, if an individual data item is malformed but the document is otherwise valid, this may return successful. # 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 behaviour 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 On my system the included (_very_ simple!) benchmark outputs: Including TOML::Tiny … small … Rate toml_tiny toml_xs toml_tiny 1009/s -- -95% toml_xs 21721/s 2053% -- large … (warning: too few iterations for a reliable count) s/iter toml_tiny toml_xs toml_tiny 1.65 -- -93% toml_xs 0.110 1400% -- # 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/).