Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

update and revamp documentation

  • Loading branch information...
commit 049ee8028d8938ad17d25a43eed6a4c2af1a4e62 1 parent 364bcea
Sawyer X authored December 28, 2012

Showing 1 changed file with 66 additions and 34 deletions. Show diff stats Hide diff stats

  1. 100  lib/Algorithm/Diff/Callback.pm
100  lib/Algorithm/Diff/Callback.pm
@@ -85,8 +85,8 @@ Use callbacks in your diff process to get better control over what will happen.
85 85
     diff_arrays(
86 86
         \@old_family_members,
87 87
         \@new_family_members,
88  
-        sub { print 'Happy to hear about ', shift },
89  
-        sub { print 'Sorry to hear about ', shift },
  88
+        added   => sub { say 'Happy to hear about ', shift },
  89
+        deleted => sub { say 'Sorry to hear about ', shift },
90 90
     );
91 91
 
92 92
 Or using hashes:
@@ -96,77 +96,109 @@ Or using hashes:
96 96
     diff_hashes(
97 97
         \%old_details,
98 98
         \%new_details,
99  
-        sub { print 'Lost ',   shift },
100  
-        sub { print 'Gained ', shift },
101  
-        sub {
  99
+        added   => sub { say 'Gained ', shift },
  100
+        deleted => sub { say 'Lost ',   shift },
  101
+        changed => sub {
102 102
             my ( $key, $before, $after ) = @_;
103  
-            print "$key changed from $before to $after\n";
  103
+            say "$key changed from $before to $after";
104 104
         },
105 105
     );
106 106
 
  107
+=head1 DESCRIPTION
  108
+
107 109
 One of the difficulties when using diff modules is that they assume they know
108 110
 what you want the information for. Some give you formatted output, some give you
109 111
 just the values that changes (but neglect to mention how each changed) and some
110 112
 (such as L<Algorithm::Diff>) give you way too much information that you now have
111 113
 to skim over and write long complex loops for.
112 114
 
113  
-L<Algorithm::Diff::Callback> let's you pick what you're going to diff (Arrays,
  115
+L<Algorithm::Diff::Callback> let's you pick what you're going to diff (Arrays or
114 116
 Hashes) and set callbacks for the diff process.
115 117
 
116 118
 =head1 EXPORT
117 119
 
  120
+You'll need to declare to explicitly export these functions.
  121
+
118 122
 =head2 diff_arrays
119 123
 
120 124
 =head2 diff_hashes
121 125
 
  126
+    use Algorithm::Diff::Callback qw<diff_arrays diff_hashes>;
  127
+
122 128
 =head1 SUBROUTINES/METHODS
123 129
 
124  
-=head2 diff_arrays(\@old, \@new, \&removed, \&added)
  130
+=head2 diff_arrays(\@old, \@new, %callbacks)
125 131
 
126 132
 The first two parameters are array references to compare.
127 133
 
128  
-The second two parameters are subroutine references which will be called and
129  
-given the value that was either removed or added during the diff process.
  134
+The rest of the parameters are keys for the type of callback you want and the
  135
+corresponding callback. You can provide multiple callbacks. Supported keys are:
130 136
 
131  
-The comparison is explicitly the second one B<against> the first one.
  137
+=over 4
132 138
 
133  
-That means that if you give a I<removed> subroutine, it really means that a
134  
-value that existed in the first arrayref does not exist in the second arrayref.
  139
+=item * added
  140
+
  141
+    diff_arrays(
  142
+        \@old, \@new,
  143
+        added => sub {
  144
+            my $value = shift;
  145
+            say "$value was added to the array";
  146
+        }
  147
+    );
135 148
 
136  
-If you gave a I<added> subroutine, it really means that a value that did B<not>
137  
-exist in the first arrayref now exists in the second one.
  149
+=item * deleted
138 150
 
139  
-B<Note:> if you do not wish to give a certain subroutine, you can simply provide
140  
-undef:
  151
+    diff_arrays(
  152
+        \@old, \@new,
  153
+        deleted => sub {
  154
+            my $value = shift;
  155
+            say "$value was deleted from the array";
  156
+        }
  157
+    );
141 158
 
142  
-    diff_arrays( \@old, \@new, undef, sub { 'added: ', $_[0], "\n" } );
  159
+=back
143 160
 
144  
-=head2 diff_hashes(\%old, \%new, \&removed, \&added, \&change)
  161
+=head2 diff_hashes(\%old, \%new, %callbacks)
145 162
 
146 163
 The first two parameters are hash references to compare.
147 164
 
148  
-The second two paramters are the subroutine references which will be called and
149  
-given the key and value that was either removed or added during the diff
150  
-process.
  165
+The rest of the parameters are keys for the type of callback you want and the
  166
+corresponding callback. You can provide multiple callbacks. Supported keys are:
151 167
 
152  
-The third parameter is a subroutine reference of information that changed
153  
-between the first and second hashes. It will be given the key that was changed,
154  
-the value it had before and the value it now has in the new reference.
  168
+=over 4
155 169
 
156  
-B<Note:> if you do not wish to give a certain subroutine, you can simply provide
157  
-undef:
  170
+=item * added
158 171
 
159 172
     diff_hashes(
160  
-        \%old,
161  
-        \%new,
162  
-        undef,
163  
-        undef,
164  
-        sub {
  173
+        \%old, \%new,
  174
+        added => sub {
  175
+            my ( $key, $value ) = @_;
  176
+            say "$key ($value) was added to the hash";
  177
+        }
  178
+    );
  179
+
  180
+=item * deleted
  181
+
  182
+    diff_hashes(
  183
+        \%old, \%new,
  184
+        deleted => sub {
  185
+            my ( $key, $value ) = @_;
  186
+            say "$key ($value) was deleted from the hash";
  187
+        }
  188
+    );
  189
+
  190
+=item * changed
  191
+
  192
+    diff_hashes(
  193
+        \%old, \%new,
  194
+        changed => sub {
165 195
             my ( $key, $before, $after ) = @_;
166  
-            print "$key changed from $before to $after\n";
167  
-        },
  196
+            say "$key in the hash was changed from $before to $after";
  197
+        }
168 198
     );
169 199
 
  200
+=back
  201
+
170 202
 =head1 BUGS
171 203
 
172 204
 Please report bugs on the Github issues page at

0 notes on commit 049ee80

Please sign in to comment.
Something went wrong with that request. Please try again.