Smart.pm

filter: Statementstmt 100% 34 / 34 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 9 / 9 Podpod 100% 5 / 5 totaltotal 100% 48 / 48 CC 1 SCAR 0.0
CC
1
Cov
100%
BEGIN
1.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« Smart/Renderer/JSON.pm ↑ Summary
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;
« Smart/Renderer/JSON.pm ↑ Summary