blib/lib/TOML/XS.pm

filter: Statementstmt 100% 23 / 23 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 6 / 6 Podpod n/a totaltotal 100% 29 / 29 CC 3 SCAR 5.6
CC
3
Cov
100%
_BUILD_JSON_POINTER
3.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.8
« blib/lib/TOML/XS/Timestamp.pm ↑ Summary easyxs/easyxs_numeric.h »
1 package TOML::XS;
2  
3 6 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 6 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 6 our ($VERSION);
7  
8 6 ▶use Types::Serialiser ();
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 6 ▶use XSLoader ();
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 6 ▶BEGIN {
Subroutine BEGIN: called CC=1 SCAR=0.0
13 6 $VERSION = '0.06';
14 6 XSLoader::load( __PACKAGE__, $VERSION );
15 }
16  
17 =encoding utf8
18  
19 =head1 NAME
20  
21 TOML::XS - Turbo-charged L<TOML|https://toml.io> parsing!
22  
23 =begin html
24  
25 <a href='https://coveralls.io/github/FGasper/p5-TOML-XS?branch=master'><img src='https://coveralls.io/repos/github/FGasper/p5-TOML-XS/badge.svg?branch=master' alt='Coverage Status' /></a>
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 # The top-level document is always a struct.
35 my $struct = TOML::XS::from_toml($toml)->get();
36  
37 # You can also fetch individual items from the document, e.g.:
38 my $last_name = TOML::XS::from_toml($toml)->get('info', 'last_name');
39  
40 =head1 DESCRIPTION
41  
42 This module facilitates parsing of TOML documents in Perl via XS,
43 which can yield dramatic performance gains relative to pure-Perl TOML
44 libraries.
45  
46 It is currently implemented atop the
47 L<tomlc17|https://github.com/cktan/tomlc17> C library. This distribution
48 embeds that library, so you don’t need to install it separately.
49  
50 This library is solely a parser; there is no logic here to serialize a parsed
51 TOML document.
52  
53 =head1 FUNCTIONS
54  
55 =head2 $doc = TOML::XS::from_toml($byte_string)
56  
57 Converts a byte string (i.e., raw, undecoded bytes) that contains a
58 serialized TOML document to a L<TOML::XS::Document> instance.
59  
60 Throws a suitable exception if the TOML document is unparseable. This
61 doesn’t necessarily mean that I<any> malformed TOML content triggers such
62 an error; for example, if an individual data item is malformed but the
63 document is otherwise valid, this may return successful.
64  
65 =head1 MAPPING TOML TO PERL
66  
67 Most TOML data items map naturally to Perl. The following details
68 are relevant:
69  
70 =over
71  
72 =item * Strings are character-decoded.
73  
74 =item * Booleans are represented as L<TOML::XS::true> and L<TOML::XS::false>,
75 which are namespace aliases for the relevant constants from
76 L<Types::Serialiser>.
77  
78 =item * Timestamps are represented as L<TOML::XS::Timestamp> instances.
79  
80 =back
81  
82 =head1 NOTE ON CHARACTER DECODING
83  
84 This library mimics the default behaviour of popular JSON modules:
85 the TOML input to the parser is expected to be a byte string, while the
86 strings that the parser outputs are character strings.
87  
88 =head1 PERFORMANCE
89  
90 On my system the included (I<very> simple!) benchmark outputs:
91  
92 Including TOML::Tiny …
93  
94 small …
95 Rate toml_tiny toml_xs
96 toml_tiny 1009/s -- -95%
97 toml_xs 21721/s 2053% --
98  
99 large …
100 (warning: too few iterations for a reliable count)
101 s/iter toml_tiny toml_xs
102 toml_tiny 1.65 -- -93%
103 toml_xs 0.110 1400% --
104  
105 =cut
106  
107 #----------------------------------------------------------------------
108  
109 6 *true = *Types::Serialiser::true;
110 6 *false = *Types::Serialiser::false;
111  
112 6 ▶sub _BUILD_JSON_POINTER {
Subroutine _BUILD_JSON_POINTER: called CC=3 SCAR=11.0
113 6 my $pieces_ar = shift;
114  
115 6 my @pieces = @$pieces_ar;
116  
117 6 s<~><~0>g for @pieces;
118 6 s</><~1>g for @pieces;
119  
120 6 return join('/', q<>, @pieces);
121 }
122  
123 #----------------------------------------------------------------------
124  
125 =head1 COPYRIGHT & LICENSE
126  
127 Copyright 2021 Gasper Software Consulting. All rights reserved.
128  
129 This library is licensed under the same license as Perl itself.
130  
131 L<tomlc17|https://github.com/cktan/tomlc17> is licensed under the
132 L<MIT License|https://mit-license.org/>.
133  
134 =cut
135  
136 6 1;
« blib/lib/TOML/XS/Timestamp.pm ↑ Summary easyxs/easyxs_numeric.h »