1 files changed, 52 insertions, 3 deletions
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