| 1 | package Data::Hash::Diff::Smart; | ||
| 2 | |||
| 3 | 16 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 4 | 16 | ▶ | use warnings; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 5 | |||
| 6 | 16 | ▶ | use Exporter 'import'; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 7 | 16 | ▶ | use Data::Hash::Diff::Smart::Engine (); |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 8 | |||
| 9 | 16 | our @EXPORT_OK = qw( | |
| 10 | diff | ||
| 11 | diff_text | ||
| 12 | diff_json | ||
| 13 | diff_yaml | ||
| 14 | diff_test2 | ||
| 15 | ); | ||
| 16 | |||
| 17 | =head1 NAME | ||
| 18 | |||
| 19 | Data::Hash::Diff::Smart - Smart structural diff for Perl data structures | ||
| 20 | |||
| 21 | =head1 VERSION | ||
| 22 | |||
| 23 | Version 0.02 | ||
| 24 | |||
| 25 | =cut | ||
| 26 | |||
| 27 | 16 | our $VERSION = '0.02'; | |
| 28 | |||
| 29 | =head1 SYNOPSIS | ||
| 30 | |||
| 31 | use Data::Hash::Diff::Smart qw(diff diff_text diff_json diff_yaml diff_test2); | ||
| 32 | |||
| 33 | my $changes = diff($old, $new); | ||
| 34 | |||
| 35 | print diff_text($old, $new); | ||
| 36 | |||
| 37 | my $json = diff_json($old, $new); | ||
| 38 | |||
| 39 | my $yaml = diff_yaml($old, $new); | ||
| 40 | |||
| 41 | diag diff_test2($old, $new); | ||
| 42 | |||
| 43 | =head1 DESCRIPTION | ||
| 44 | |||
| 45 | C<Data::Hash::Diff::Smart> provides a modern, recursive, configurable diff | ||
| 46 | engine for Perl data structures. It understands nested hashes, arrays, | ||
| 47 | scalars, objects, and supports ignore rules, custom comparators, and | ||
| 48 | multiple array diffing strategies. | ||
| 49 | |||
| 50 | The diff engine produces a stable, structured list of change operations, | ||
| 51 | which can be rendered as text, JSON, YAML, or Test2 diagnostics. | ||
| 52 | |||
| 53 | =head1 FUNCTIONS | ||
| 54 | |||
| 55 | =head2 diff($old, $new, %opts) | ||
| 56 | |||
| 57 | Compute a structural diff between two Perl data structures. | ||
| 58 | |||
| 59 | Returns an arrayref of change operations: | ||
| 60 | |||
| 61 | [ | ||
| 62 | { op => 'change', path => '/user/name', from => 'Nigel', to => 'N. Horne' }, | ||
| 63 | { op => 'add', path => '/tags/2', value => 'admin' }, | ||
| 64 | { op => 'remove', path => '/debug', from => 1 }, | ||
| 65 | ] | ||
| 66 | |||
| 67 | =head3 Options | ||
| 68 | |||
| 69 | =over 4 | ||
| 70 | |||
| 71 | =item * ignore => [ '/path', qr{^/debug}, '/foo/*/bar' ] | ||
| 72 | |||
| 73 | Ignore specific paths. Supports exact paths, regexes, and wildcard | ||
| 74 | segments. | ||
| 75 | |||
| 76 | =item * compare => { '/price' => sub { abs($_[0] - $_[1]) < 0.01 } } | ||
| 77 | |||
| 78 | Custom comparator callbacks for specific paths. | ||
| 79 | |||
| 80 | =item * array_mode => 'index' | 'lcs' | 'unordered' | ||
| 81 | |||
| 82 | Choose how arrays are diffed: | ||
| 83 | |||
| 84 | =over 4 | ||
| 85 | |||
| 86 | =item * index - compare by index (default) | ||
| 87 | |||
| 88 | =item * lcs - minimal diff using Longest Common Subsequence | ||
| 89 | |||
| 90 | =item * unordered - treat arrays as multisets (order ignored) | ||
| 91 | |||
| 92 | =back | ||
| 93 | |||
| 94 | =item * array_key => 'id' | ||
| 95 | |||
| 96 | When using unordered C<array_mode> with arrays of hashes, | ||
| 97 | nominate a field to use as the identity key for matching elements across the two arrays. | ||
| 98 | Without this, elements are compared as multisets by structure. | ||
| 99 | |||
| 100 | diff($old, $new, array_mode => 'unordered', array_key => 'id') | ||
| 101 | |||
| 102 | =back | ||
| 103 | |||
| 104 | =head2 diff_text($old, $new, %opts) | ||
| 105 | |||
| 106 | Render the diff as a human-readable text format. | ||
| 107 | |||
| 108 | =head2 diff_json($old, $new, %opts) | ||
| 109 | |||
| 110 | Render the diff as JSON using C<JSON::MaybeXS>. | ||
| 111 | |||
| 112 | =head2 diff_yaml($old, $new, %opts) | ||
| 113 | |||
| 114 | Render the diff as YAML using C<YAML::XS>. | ||
| 115 | |||
| 116 | =head2 diff_test2($old, $new, %opts) | ||
| 117 | |||
| 118 | Render the diff as Test2 diagnostics suitable for C<diag>. | ||
| 119 | |||
| 120 | =head1 INTERNALS | ||
| 121 | |||
| 122 | The diff engine lives in L<Data::Hash::Diff::Smart::Engine>. | ||
| 123 | |||
| 124 | =cut | ||
| 125 | |||
| 126 | # Core diff | ||
| 127 | 424 | ▶ | sub diff { |
|
Subroutine
diff: called CC=1 SCAR=0.0
Pod
documented
| |||
| 128 | 424 | my ($old, $new, %opts) = @_; | |
| 129 | 424 | return Data::Hash::Diff::Smart::Engine::diff($old, $new, %opts); | |
| 130 | } | ||
| 131 | |||
| 132 | # Text renderer (lazy-loaded) | ||
| 133 | 41 | ▶ | sub diff_text { |
|
Subroutine
diff_text: called CC=1 SCAR=0.0
Pod
documented
| |||
| 134 | 41 | my ($old, $new, %opts) = @_; | |
| 135 | 41 | require Data::Hash::Diff::Smart::Renderer::Text; | |
| 136 | 41 | my $changes = diff($old, $new, %opts); | |
| 137 | 41 | return Data::Hash::Diff::Smart::Renderer::Text::render($changes); | |
| 138 | } | ||
| 139 | |||
| 140 | # JSON renderer (lazy-loaded) | ||
| 141 | 41 | ▶ | sub diff_json { |
|
Subroutine
diff_json: called CC=1 SCAR=0.0
Pod
documented
| |||
| 142 | 41 | my ($old, $new, %opts) = @_; | |
| 143 | 41 | require Data::Hash::Diff::Smart::Renderer::JSON; | |
| 144 | 41 | my $changes = diff($old, $new, %opts); | |
| 145 | 41 | return Data::Hash::Diff::Smart::Renderer::JSON::render($changes); | |
| 146 | } | ||
| 147 | |||
| 148 | # YAML renderer (lazy-loaded) | ||
| 149 | 25 | ▶ | sub diff_yaml { |
|
Subroutine
diff_yaml: called CC=1 SCAR=0.0
Pod
documented
| |||
| 150 | 25 | my ($old, $new, %opts) = @_; | |
| 151 | 25 | require Data::Hash::Diff::Smart::Renderer::YAML; | |
| 152 | 25 | my $changes = diff($old, $new, %opts); | |
| 153 | 25 | return Data::Hash::Diff::Smart::Renderer::YAML::render($changes); | |
| 154 | } | ||
| 155 | |||
| 156 | 26 | ▶ | sub diff_test2 { |
|
Subroutine
diff_test2: called CC=1 SCAR=0.0
Pod
documented
| |||
| 157 | 26 | my ($old, $new, %opts) = @_; | |
| 158 | 26 | require Data::Hash::Diff::Smart::Renderer::Test2; | |
| 159 | 26 | my $changes = diff($old, $new, %opts); | |
| 160 | 26 | return Data::Hash::Diff::Smart::Renderer::Test2::render($changes); | |
| 161 | } | ||
| 162 | |||
| 163 | 16 | 1; | |
| 164 | |||
| 165 | =head1 BENCHMARKS | ||
| 166 | |||
| 167 | To run all benchmarks: | ||
| 168 | |||
| 169 | perl benchmarks/bench.pl | ||
| 170 | |||
| 171 | This will run diff operations on: | ||
| 172 | |||
| 173 | - small structures | ||
| 174 | - medium nested structures | ||
| 175 | - large 5000-element arrays | ||
| 176 | - cyclic structures (cycle detection) | ||
| 177 | - unordered array mode | ||
| 178 | - LCS array mode | ||
| 179 | |||
| 180 | Example output: | ||
| 181 | |||
| 182 | === Benchmark: medium === | ||
| 183 | Rate | ||
| 184 | diff 12000/s | ||
| 185 | |||
| 186 | =head1 AUTHOR | ||
| 187 | |||
| 188 | Nigel Horne, C<< <njh at nigelhorne.com> >> | ||
| 189 | |||
| 190 | =head1 SEE ALSO | ||
| 191 | |||
| 192 | L<Data::Hash::Patch::Smart> | ||
| 193 | |||
| 194 | =head1 REPOSITORY | ||
| 195 | |||
| 196 | L<https://github.com/nigelhorne/Data-Hash-Diff-Smart> | ||
| 197 | |||
| 198 | =head1 SUPPORT | ||
| 199 | |||
| 200 | This module is provided as-is without any warranty. | ||
| 201 | |||
| 202 | Please report any bugs or feature requests to C<bug-data-hash-diff-smart at rt.cpan.org>, | ||
| 203 | or through the web interface at | ||
| 204 | L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Data-Hash-Diff-Smart>. | ||
| 205 | I will be notified, and then you'll | ||
| 206 | automatically be notified of progress on your bug as I make changes. | ||
| 207 | |||
| 208 | You can find documentation for this module with the perldoc command. | ||
| 209 | |||
| 210 | perldoc Data::Hash::Diff::Smart | ||
| 211 | |||
| 212 | You can also look for information at: | ||
| 213 | |||
| 214 | =over 4 | ||
| 215 | |||
| 216 | =item * MetaCPAN | ||
| 217 | |||
| 218 | L<https://metacpan.org/dist/Data-Hash-Diff-Smart> | ||
| 219 | |||
| 220 | =item * RT: CPAN's request tracker | ||
| 221 | |||
| 222 | L<https://rt.cpan.org/NoAuth/Bugs.html?Dist=Data-Hash-Diff-Smart> | ||
| 223 | |||
| 224 | =item * CPAN Testers' Matrix | ||
| 225 | |||
| 226 | L<http://matrix.cpantesters.org/?dist=Data-Hash-Diff-Smart> | ||
| 227 | |||
| 228 | =item * CPAN Testers Dependencies | ||
| 229 | |||
| 230 | L<http://deps.cpantesters.org/?module=Data::Hash::Diff::Smart> | ||
| 231 | |||
| 232 | =back | ||
| 233 | |||
| 234 | =head1 LICENCE AND COPYRIGHT | ||
| 235 | |||
| 236 | Copyright 2026 Nigel Horne. | ||
| 237 | |||
| 238 | Usage is subject to licence terms. | ||
| 239 | |||
| 240 | The licence terms of this software are as follows: | ||
| 241 | |||
| 242 | =over 4 | ||
| 243 | |||
| 244 | =item * Personal single user, single computer use: GPL2 | ||
| 245 | |||
| 246 | =item * All other users (including Commercial, Charity, Educational, Government) | ||
| 247 | must apply in writing for a licence for use from Nigel Horne at the | ||
| 248 | above e-mail. | ||
| 249 | |||
| 250 | =back | ||
| 251 | |||
| 252 | =cut | ||
| 253 | |||
| 254 | 16 | 1; | |