File Coverage

blib/lib/TOML/XS.pm
Criterion Covered Total %
statement 18 18 100.0
branch n/a
condition n/a
subroutine 6 6 100.0
pod n/a
total 24 24 100.0


line stmt bran cond sub pod time code
1             package TOML::XS;
2              
3 4     4   350313 use strict;
  4         35  
  4         124  
4 4     4   22 use warnings;
  4         8  
  4         168  
5              
6             our ($VERSION);
7              
8 4     4   2217 use Types::Serialiser ();
  4         6478  
  4         109  
9              
10 4     4   27 use XSLoader ();
  4         8  
  4         144  
11              
12             BEGIN {
13 4     4   12 $VERSION = '0.04';
14 4         3279 XSLoader::load( __PACKAGE__, $VERSION );
15             }
16              
17             =encoding utf8
18              
19             =head1 NAME
20              
21             TOML::XS - Turbo-charged L parsing!
22              
23             =begin html
24              
25             Coverage Status
26              
27             =end html
28              
29             =head1 SYNOPSIS
30              
31             # NB: Don’t read_text(), or stuff may break.
32             my $toml = File::Slurper::read_binary('/path/to/toml/file');
33              
34             my $struct = TOML::XS::from_toml($toml)->to_struct();
35              
36             =head1 DESCRIPTION
37              
38             This module facilitates parsing of TOML documents in Perl via XS,
39             which can yield dramatic performance gains relative to pure-Perl TOML
40             libraries.
41              
42             It is currently implemented as a wrapper around the
43             L C library.
44              
45             =head1 FUNCTIONS
46              
47             =head2 $doc = TOML::XS::from_toml($byte_string)
48              
49             Converts a byte string (i.e., raw, undecoded bytes) that contains a
50             serialized TOML document to a L instance.
51              
52             Throws a suitable exception if the TOML document is unparseable. This
53             doesn’t necessarily mean that I malformed TOML content triggers such
54             an error; for example, if an individual data item is malformed but the
55             document is otherwise valid, this may return successful.
56              
57             =head1 MAPPING TOML TO PERL
58              
59             Most TOML data items map naturally to Perl. The following details
60             are relevant:
61              
62             =over
63              
64             =item * Strings are character-decoded.
65              
66             =item * Booleans are represented as L and L,
67             which are namespace aliases for the relevant constants from
68             L.
69              
70             =item * Timestamps are represented as L instances.
71              
72             =back
73              
74             =head1 NOTE ON CHARACTER DECODING
75              
76             This library mimics the default behaviour of popular JSON modules:
77             the TOML input to the parser is expected to be a byte string, while the
78             strings that the parser outputs are character strings.
79              
80             =head1 PERFORMANCE
81              
82             On my system the included (I simple!) benchmark outputs:
83              
84             Including TOML::Tiny …
85              
86             small …
87             Rate toml_tiny toml_xs
88             toml_tiny 1009/s -- -95%
89             toml_xs 21721/s 2053% --
90              
91             large …
92             (warning: too few iterations for a reliable count)
93             s/iter toml_tiny toml_xs
94             toml_tiny 1.65 -- -93%
95             toml_xs 0.110 1400% --
96              
97             =cut
98              
99             #----------------------------------------------------------------------
100              
101             *true = *Types::Serialiser::true;
102             *false = *Types::Serialiser::false;
103              
104             sub _croak_err_message_from_pieces {
105 2     2   1861 my $path_ar = shift;
106              
107 2         15 s<~><~0>g for @$path_ar;
108 2         11 s<~1>g for @$path_ar;
109              
110 2         26 die sprintf "Malformed TOML value found! (JSON pointer: %s)", join('/', q<>, @$path_ar);
111             }
112              
113             #----------------------------------------------------------------------
114              
115             =head1 COPYRIGHT & LICENSE
116              
117             Copyright 2021 Gasper Software Consulting. All rights reserved.
118              
119             This library is licensed under the same license as Perl itself.
120              
121             L is licensed under the
122             L.
123              
124             =cut
125              
126             1;