From 117d5e17261250378645a10a04843486d722e75d Mon Sep 17 00:00:00 2001
From: Tom Ryder <tom@sanctum.geek.nz>
Date: Thu, 5 Oct 2017 10:30:33 +1300
Subject: Add "records" example and accompanying test

Tweak last paragraph of second example so it flows.
---
 MANIFEST              |  1 +
 lib/List/Breakdown.pm | 55 ++++++++++++++++++++++++++++++++++++++++++++++++---
 t/records.t           | 42 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 95 insertions(+), 3 deletions(-)
 create mode 100644 t/records.t

diff --git a/MANIFEST b/MANIFEST
index e28fb15..8bab15f 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -5,6 +5,7 @@ MANIFEST
 README
 t/errors.t
 t/monitoring.t
+t/records.t
 t/words.t
 xt/manifest.t
 xt/pod-coverage.t
diff --git a/lib/List/Breakdown.pm b/lib/List/Breakdown.pm
index 96104b7..5d33486 100644
--- a/lib/List/Breakdown.pm
+++ b/lib/List/Breakdown.pm
@@ -137,6 +137,57 @@ This puts the following structure in C<%filtered>:
 
 =head1 EXAMPLES
 
+=head2 
+
+Suppose you have a list of strings from a very legacy system that you need to
+regularly check for problematic characters, alerting you to problems with an
+imperfect Perl parser:
+
+    my @records = (
+        "NEW CUSTOMER John O''Connor\r 2017-01-01",
+        "RETURNING CUSTOMER\tXah Zhang 2016-01-01",
+        "CHECK ACCOUNT Pierre d'Alun 2016-12-01",
+        "RETURNING CUSTOMER Aaron Carter 2016-05-01"
+    );
+
+You could have a bucket structure like this, which catches certain error types
+you've seen before for review:
+
+    my %buckets = (
+        bad_whitespace     => qr/ [\r\t] /msx,
+        apostrophes        => qr/ ' /msx,
+        double_apostrophes => qr/ '' /msx,
+        not_ascii          => qr/ [^[:ascii:]] /msx
+    );
+
+Notice that you don't have to wrap a quoted regular expression to match in a
+`sub` subroutine reference, as a convenience shortcut.
+
+Applying the bucket structure like so:
+
+    my %results = breakdown \%buckets, @records;
+
+The result set would look like this:
+
+    my %expected = (
+        bad_whitespace => [
+            "NEW CUSTOMER John O''Connor\r 2017-01-01",
+            "RETURNING CUSTOMER\tXah Lee 2016-01-01"
+        ],
+        apostrophes => [
+            "NEW CUSTOMER John O''Connor\r 2017-01-01",
+            'CHECK ACCOUNT Pierre d\'Alun 2016-12-01'
+        ],
+        double_apostrophes => [
+            "NEW CUSTOMER John O''Connor\r 2017-01-01"
+        ],
+        not_ascii => [
+        ]
+    );
+
+Notice that some of the lines appear in more than one list, and that the
+C<not_ascii> bucket is empty because none of the items matched it.
+
 =head2 Monitoring system check results
 
 Suppose you ran a list of checks with your monitoring system, and you have a
@@ -208,9 +259,7 @@ C<%results>:
         }
     )
 
-Notice that some of the check results appear in more than one list, and the
-hash buckets are arranged the same way they were in the spec, including an
-extra level of hash references.
+Note the extra level of hash referencing beneath the C<problem> key.
 
 =head1 SUBROUTINES/METHODS
 
diff --git a/t/records.t b/t/records.t
new file mode 100644
index 0000000..8af3e1a
--- /dev/null
+++ b/t/records.t
@@ -0,0 +1,42 @@
+#!perl -T
+
+use strict;
+use warnings;
+use utf8;
+
+use Test::More tests => 1;
+
+use List::Breakdown 'breakdown';
+
+our $VERSION = '0.11';
+
+my @records = (
+    "NEW CUSTOMER John O''Connor\r 2017-01-01",
+    "RETURNING CUSTOMER\tXah Lee 2016-01-01",
+    "CHECK ACCOUNT Pierre d'Alun 2016-12-01",
+    "RETURNING CUSTOMER Aaron Carter 2016-05-01"
+);
+
+my %buckets = (
+    bad_whitespace     => qr/ [\r\t] /msx,
+    apostrophes        => qr/ ' /msx,
+    double_apostrophes => qr/ '' /msx,
+    not_ascii          => qr/ [^[:ascii:]] /msx
+);
+
+my %results = breakdown \%buckets, @records;
+
+my %expected = (
+    apostrophes => [
+        "NEW CUSTOMER John O''Connor\r 2017-01-01",
+        'CHECK ACCOUNT Pierre d\'Alun 2016-12-01'
+    ],
+    bad_whitespace => [
+        "NEW CUSTOMER John O''Connor\r 2017-01-01",
+        "RETURNING CUSTOMER\tXah Lee 2016-01-01"
+    ],
+    double_apostrophes => ["NEW CUSTOMER John O''Connor\r 2017-01-01"],
+    not_ascii          => [],
+);
+
+is_deeply( \%results, \%expected, 'records' );
-- 
cgit v1.2.3