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.