NAME
TOML::XS - Turbo-charged TOML 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 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 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 and TOML::XS::false, which are namespace aliases for the relevant constants from Types::Serialiser.
Timestamps are represented as 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 is licensed under the MIT License.