File Coverage

blib/lib/TOML/XS.pm

Criterion	Covered	Total	%
statement	23	25	92.0
branch			n/a
condition			n/a
subroutine	8	9	88.8
pod			n/a
total	31	34	91.1

package TOML::XS;

use strict;
use warnings;

our ($VERSION);

use Types::Serialiser ();

use XSLoader ();

BEGIN {
    $VERSION = '0.05_01';
    XSLoader::load( __PACKAGE__, $VERSION );
}

=encoding utf8

=head1 NAME

TOML::XS - Turbo-charged L parsing!

=begin html



=end html

=head1 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();

=head1 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
L C library.

=head1 FUNCTIONS

=head2 $doc = TOML::XS::from_toml($byte_string)

Converts a byte string (i.e., raw, undecoded bytes) that contains a
serialized TOML document to a L instance.

Throws a suitable exception if the TOML document is unparseable. This
doesn’t necessarily mean that I 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.

=head1 MAPPING TOML TO PERL

Most TOML data items map naturally to Perl. The following details
are relevant:

=over

=item * Strings are character-decoded.

=item * Booleans are represented as L and L,
which are namespace aliases for the relevant constants from
L.

=item * Timestamps are represented as L instances.

=back

=head1 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.

=head1 PERFORMANCE

On my system the included (I 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%        --

=cut

#----------------------------------------------------------------------

*true = *Types::Serialiser::true;
*false = *Types::Serialiser::false;

sub _croak_malformed_toml {
    my $path_ar = shift;

    return _croak_with_pointer('Malformed TOML value found!', $path_ar);
}

sub _croak_pointer_beyond_datum {
    my $path_ar = shift;

    return _croak_with_pointer('Can’t descend into non-container!', $path_ar);
}

sub _croak_with_pointer {
    my ($msg, $path_ar) = @_;

    die sprintf( "%s (JSON pointer: %s)", $msg, _BUILD_JSON_POINTER($path_ar) );
}

sub _BUILD_JSON_POINTER {
    my $pieces_ar = shift;

    my @pieces =  @$pieces_ar;

    s<~><~0>g for @pieces;
    s<~1>g for @pieces;

    return join('/', q<>, @pieces);
}

#----------------------------------------------------------------------

=head1 COPYRIGHT & LICENSE

Copyright 2021 Gasper Software Consulting. All rights reserved.

This library is licensed under the same license as Perl itself.

L is licensed under the
L.

=cut

1;