prep for 0.02

Changes

@@ -3,6 +3,9 @@ Revision history for Perl extension TOML::XS:
 0.02
 - Fix https://github.com/cktan/tomlc99/issues/52
   (Large TOML documents now decode MUCH faster!)
+- Improved test coverage
+- Documentation tweaks
+- Added benchmarks
 
 0.01 Sat 10 Apr 2021
 - Initial release

MANIFEST

@@ -4,6 +4,9 @@ MANIFEST
 Makefile.PL
 README.md
 XS.xs
+examples/assets/large.toml.gz
+examples/assets/small.toml
+examples/benchmark.pl
 lib/TOML/XS.pm
 lib/TOML/XS/Document.pm
 lib/TOML/XS/Timestamp.pm

README.md

@@ -1,8 +1,10 @@
 # NAME
 
-TOML::XS - Parse [TOML](https://toml.io) with XS
+TOML::XS - Turbo-charged [TOML](https://toml.io) parsing!
 
-<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>
+<div>
+    <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>
+</div>
 
 # SYNOPSIS
 
@@ -14,7 +16,7 @@ TOML::XS - Parse [TOML](https://toml.io) with XS
 # DESCRIPTION
 
 This module facilitates parsing of TOML documents in Perl via XS,
-which can yield significant performance gains relative to pure-Perl TOML
+which can yield dramatic performance gains relative to pure-Perl TOML
 libraries.
 
 It is currently implemented as a wrapper around the
@@ -40,15 +42,28 @@ which are namespace aliases for the relevant constants from
 
 # NOTE ON CHARACTER DECODING
 
-This library mimics the default configuration of popular JSON modules:
+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
 
-For small- and medium-sized files this should be quite a bit faster
-than pure-Perl TOML parsers. With larger files the speed gains are more
-muted or even (??) reversed. (That’s an underlying issue with tomlc99.)
+On my system the included (_very_ simple!) benchmark outputs:
+
+    Including TOML::Tiny …
+
+    small …
+                (warning: too few iterations for a reliable count)
+                Rate toml_tiny   toml_xs
+    toml_tiny   978/s        --      -95%
+    toml_xs   21739/s     2122%        --
+
+    large …
+                (warning: too few iterations for a reliable count)
+                (warning: too few iterations for a reliable count)
+            s/iter toml_tiny   toml_xs
+    toml_tiny   1.71        --      -94%
+    toml_xs    0.110     1455%        --
 
 # COPYRIGHT & LICENSE
 

examples/assets/small.toml

@@ -0,0 +1,26 @@
+# This is a TOML document
+
+title = "TOML Example"
+
+[owner]
+name = "Tom Preston-Werner"
+dob = 1979-05-27T07:32:00-08:00
+
+[database]
+enabled = true
+ports = [ 8000, 8001, 8002 ]
+data = [ ["delta", "phi"], [3.14] ]
+temp_targets = { cpu = 79.5, case = 72.0 }
+
+[servers]
+
+[servers.alpha]
+ip = "10.0.0.1"
+role = "frontend"
+
+[servers.beta]
+ip = "10.0.0.2"
+role = "backend"
+
+[checkwide]
+fluff = "épée"

examples/benchmark.pl

@@ -0,0 +1,66 @@
+#!/usr/bin/env perl
+
+use strict;
+use warnings;
+
+use Benchmark;
+use FindBin;
+
+use TOML::XS;
+
+my $has_toml_tiny = eval { require TOML::Tiny };
+print "Including TOML::Tiny …$/" if $has_toml_tiny;
+
+my @t = (
+    [ small => 5000 ],
+    [ large => 3 ],
+);
+
+for my $t_ar (@t) {
+    my ($name, $numruns) = @$t_ar;
+
+    my $toml_path = "$FindBin::Bin/assets/$name.toml";
+
+    my $toml = slurp($toml_path) || do {
+        require IO::Uncompress::Gunzip;
+
+        my $gz = slurp("$toml_path.gz") or die "$toml_path.gz: $!";
+
+        my $out;
+        IO::Uncompress::Gunzip::gunzip(\$gz, \$out);
+
+        $out;
+    };
+
+    my %benchmarks = (
+        toml_xs => sub {
+            my $struct = TOML::XS::from_toml($toml)->to_struct();
+        },
+    );
+
+    if ($has_toml_tiny) {
+
+        $benchmarks{'toml_tiny'} = sub {
+            TOML::Tiny::from_toml($toml);
+        };
+    }
+
+    print "$/$name …$/";
+
+    Benchmark::cmpthese(
+        $numruns,
+        \%benchmarks,
+    );
+}
+
+sub slurp {
+    my $path = shift;
+
+    if (open my $rfh, '<', $path) {
+        return scalar do { local $/; <$rfh> };
+    }
+
+    return undef;
+}
+
+1;

lib/TOML/XS.pm

@@ -72,6 +72,25 @@ 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<very> simple!) benchmark outputs:
+
+    Including TOML::Tiny …
+
+    small …
+                (warning: too few iterations for a reliable count)
+                Rate toml_tiny   toml_xs
+    toml_tiny   978/s        --      -95%
+    toml_xs   21739/s     2122%        --
+
+    large …
+                (warning: too few iterations for a reliable count)
+                (warning: too few iterations for a reliable count)
+            s/iter toml_tiny   toml_xs
+    toml_tiny   1.71        --      -94%
+    toml_xs    0.110     1455%        --
+
 =cut
 
 #----------------------------------------------------------------------

t/basic.t

@@ -36,14 +36,37 @@ role = "frontend"
 ip = "10.0.0.2"
 role = "backend"
 
-[checkwide]
+[checkextra]
 fluff = "épée"
+alltypes = [ "a string", true, false, 123, 34.5, 1979-05-27T07:32:00-08:00, {} ]
+boolean = false
+integer = 123
+double = 34.5
+timestamp = 1979-05-27T07:32:00-08:00
 END
 
 my $struct = TOML::XS::from_toml($doc)->to_struct();
 
 my $round_floats = $Config{'uselongdouble'} || $Config{'usequadmath'};
 
+my $the_timestamp_cmp = all(
+    Isa('TOML::XS::Timestamp'),
+    methods(
+        to_string => '1979-05-27T07:32:00-08:00',
+        year => 1979,
+        month => 5,
+        day => 27,
+        date => 27,
+        hour => 7,
+        hours => 7,
+        minute => 32,
+        second => 0,
+        millisecond => undef,
+        milliseconds => undef,
+        timezone => '-08:00',
+    ),
+);
+
 cmp_deeply(
     $struct,
     {
@@ -68,23 +91,7 @@ cmp_deeply(
         },
         'owner' => {
             'name' => 'Tom Preston-Werner',
-            'dob'  => all(
-                Isa('TOML::XS::Timestamp'),
-                methods(
-                    to_string => '1979-05-27T07:32:00-08:00',
-                    year => 1979,
-                    month => 5,
-                    day => 27,
-                    date => 27,
-                    hour => 7,
-                    hours => 7,
-                    minute => 32,
-                    second => 0,
-                    millisecond => undef,
-                    milliseconds => undef,
-                    timezone => '-08:00',
-                ),
-            ),
+            'dob'  => $the_timestamp_cmp,
         },
         'servers' => {
             'alpha' => {
@@ -97,8 +104,21 @@ cmp_deeply(
             }
         },
         'title' => 'TOML Example',
-   'checkwide' => {
-     'fluff' => "\x{e9}p\x{e9}e"
+   'checkextra' => {
+     'fluff' => "\x{e9}p\x{e9}e",
+     'alltypes' => [
+       'a string',
+       TOML::XS::true,
+       TOML::XS::false,
+       123,
+       '34.5',
+       $the_timestamp_cmp,
+       {},
+     ],
+     boolean => TOML::XS::false,
+     integer => 123,
+     double => 34.5,
+     timestamp => $the_timestamp_cmp,
    },
     },
     'struct as expected',