From 1bfee940dee1eec591700877318b4caadc3c9502 Mon Sep 17 00:00:00 2001
From: Tom Ryder <tom@sanctum.geek.nz>
Date: Thu, 5 Oct 2017 09:03:52 +1300
Subject: Add another example

Needs to be tested
---
 lib/List/Breakdown.pm | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)

diff --git a/lib/List/Breakdown.pm b/lib/List/Breakdown.pm
index 5814a9c..aab5afb 100644
--- a/lib/List/Breakdown.pm
+++ b/lib/List/Breakdown.pm
@@ -134,6 +134,83 @@ This puts the following structure in C<%filtered>:
         has_ba => ['bar', 'baz'],
     )
 
+=head1 EXAMPLES
+
+=head2 Monitoring system check results
+
+Suppose you ran a list of checks with your monitoring system, and you have a
+list of hashrefs describing each check and its outcome:
+
+    my @checks = (
+        {
+            hostname => 'webserver1',
+            status   => 'OK',
+        },
+        {
+            hostname => 'webserver2',
+            status   => 'CRITICAL',
+        },
+        {
+            hostname => 'webserver3',
+            status   => 'WARNING',
+        },
+        {
+            hostname => 'webserver4',
+            status   => 'OK',
+        }
+    );
+
+You would like to break the list down by status. Using C<List::Breakdown>, you
+would lay out your buckets like so:
+
+    my %buckets = (
+        ok       => sub { $_->{status} eq 'OK' },
+        problem  => {
+            warning  => sub { $_->{status} eq 'WARNING' },
+            critical => sub { $_->{status} eq 'CRITICAL' },
+            unknown  => sub { $_->{status} eq 'UNKNOWN' },
+        },
+    );
+
+And apply them like so:
+
+    my %results = breakdown \%buckets, $checks;
+
+For our sample data above, this would yield the following structure in
+C<%results>:
+
+    (
+        ok => [
+            {
+                hostname => 'webserver1',
+                status   => 'OK'
+            },
+            {
+                hostname => 'webserver4',
+                status   => 'OK'
+            }
+        ],
+        problem => {
+            warning => [
+                {
+                    hostname => 'webserver3',
+                    status   => 'WARNING'
+                }
+            ],
+            critical => [
+                {
+                    hostname => 'webserver2',
+                    status   => 'CRITICAL'
+                }
+            },
+            unknown => []
+        }
+    )
+
+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.
+
 =head1 SUBROUTINES/METHODS
 
 =head2 B<breakdown(\%spec, @items)>
-- 
cgit v1.2.3