Smart.pm

filter: Statementstmt 100% 18 / 18 Branchbran 50.0% 1 / 2 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 5 / 5 Podpod 100% 1 / 1 totaltotal 96.1% 25 / 26 CC 2 SCAR 3.0
CC
2
Cov
95%
patch
2.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.3
« Smart/Engine.pm ↑ Summary
1 package Data::Hash::Patch::Smart;
2  
3 8 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 8 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 8 ▶use Exporter 'import';
Subroutine BEGIN: called CC=1 SCAR=0.0
7 8 ▶use Data::Hash::Patch::Smart::Engine ();
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 8 our @EXPORT_OK = qw(patch);
10  
11 =head1 NAME
12  
13 Data::Hash::Patch::Smart - Apply structural, wildcard, and array-aware patches to Perl data structures
14  
15 =head1 VERSION
16  
17 Version 0.01
18  
19 =cut
20  
21 8 our $VERSION = '0.01';
22  
23 =head1 SYNOPSIS
24  
25 use Data::Hash::Patch::Smart qw(patch);
26  
27 my $data = {
28 users => {
29 alice => { role => 'user' },
30 bob => { role => 'admin' },
31 }
32 };
33  
34 my $changes = [
35 { op => 'change', path => '/users/alice/role', to => 'admin' },
36 { op => 'add', path => '/users/bob/tags/0', value => 'active' },
37 { op => 'remove', path => '/users/*/deprecated' },
38 ];
39  
40 my $patched = patch($data, $changes, strict => 1);
41  
42 =head1 DESCRIPTION
43  
44 C<Data::Hash::Patch::Smart> applies structured patches to nested Perl
45 data structures. It is the companion to C<Data::Hash::Diff::Smart> and
46 supports:
47  
48 =over 4
49  
50 =item *
51  
52 Hash and array navigation via JSON-Pointer-like paths
53  
54 =item *
55  
56 Index arrays (ordered semantics)
57  
58 =item *
59  
60 Unordered arrays (push/remove semantics)
61  
62 =item *
63  
64 Structural wildcards (C</foo/*/bar>)
65  
66 =item *
67  
68 C<create_missing> mode for auto-creating intermediate containers
69  
70 =item *
71  
72 C<strict> mode for validating paths
73  
74 =item *
75  
76 Cycle-safe wildcard traversal
77  
78 =back
79  
80 The goal is to provide a predictable, expressive patch engine suitable
81 for configuration management, data migrations, and diff/patch
82 round-tripping.
83  
84 =head1 PATCH OPERATIONS
85  
86 Each change is a hashref with:
87  
88 =over 4
89  
90 =item C<op>
91  
92 One of C<add>, C<remove>, C<change>.
93  
94 =item C<path>
95  
96 Slash-separated path segments.
97 Numeric segments index arrays.
98  
99 =item C<value> / C<from> / C<to>
100  
101 Payload for the operation.
102  
103 =back
104  
105 =head2 Unordered array wildcard
106  
107 A leaf C<*> applies unordered semantics:
108  
109 { op => 'add', path => '/items/*', value => 'x' }
110 { op => 'remove', path => '/items/*', from => 'x' }
111  
112 =head2 Structural wildcard
113  
114 A C<*> in the parent path matches all children:
115  
116 /users/*/role
117 /servers/*/ports/*
118  
119 =head1 ERROR HANDLING
120  
121 =head2 Strict mode
122  
123 Strict mode enforces:
124  
125 =over 4
126  
127 =item *
128  
129 Missing hash keys
130  
131 =item *
132  
133 Out-of-bounds array indices
134  
135 =item *
136  
137 Invalid array indices
138  
139 =item *
140  
141 Unsupported operations
142  
143 =back
144  
145 Wildcard segments do B<not> trigger strict errors when no matches exist.
146  
147 =head1 CYCLE DETECTION
148  
149 Wildcard traversal detects cycles and throws an exception in strict mode.
150  
151 =head1 FUNCTIONS
152  
153 =head2 patch( $data, \@changes, %opts )
154  
155 Applies a list of changes to a data structure and returns a deep clone
156 with the modifications applied.
157  
158 =head3 Options
159  
160 =over 4
161  
162 =item C<strict =E<gt> 1>
163  
164 Die on invalid paths, missing keys,
165 or out-of-bounds array indices.
166  
167 =item C<create_missing =E<gt> 1>
168  
169 Auto-create intermediate hashes and arrays when walking a path.
170  
171 =item C<arrays =E<gt> 'unordered'>
172  
173 Enables unordered array semantics for leaf C<*> paths.
174  
175 =back
176  
177 =cut
178  
179 18 ▶sub patch {
Subroutine patch: called CC=2 SCAR=7.1
Pod documented
180 18 my ($data, $changes, %opts) = @_;
181  
182 18 ▶ die 'patch() expects an arrayref of changes' unless ref($changes) eq 'ARRAY';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $changes eq "ARRAY" 0 18 18
183  
184 18 return Data::Hash::Patch::Smart::Engine::patch($data, $changes, %opts);
185 }
186  
187 =head1 AUTHOR
188  
189 Nigel Horne, C<< <njh at nigelhorne.com> >>
190  
191 =head1 BUGS
192  
193 =head1 SEE ALSO
194  
195 L<Data::Hash::Diff::Smart>
196  
197 =head1 REPOSITORY
198  
199 L<https://github.com/nigelhorne/Data-Hash-Patch-Smart>
200  
201 =head1 SUPPORT
202  
203 This module is provided as-is without any warranty.
204  
205 Please report any bugs or feature requests to C<bug-data-hash-patch-smart at rt.cpan.org>,
206 or through the web interface at
207 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Data-Hash-Patch-Smart>.
208 I will be notified, and then you'll
209 automatically be notified of progress on your bug as I make changes.
210  
211 You can find documentation for this module with the perldoc command.
212  
213 perldoc Data::Hash::Patch::Smart
214  
215 You can also look for information at:
216  
217 =over 4
218  
219 =item * MetaCPAN
220  
221 L<https://metacpan.org/dist/Data-Hash-Patch-Smart>
222  
223 =item * RT: CPAN's request tracker
224  
225 L<https://rt.cpan.org/NoAuth/Bugs.html?Dist=Data-Hash-Patch-Smart>
226  
227 =item * CPAN Testers' Matrix
228  
229 L<http://matrix.cpantesters.org/?dist=Data-Hash-Patch-Smart>
230  
231 =item * CPAN Testers Dependencies
232  
233 L<http://deps.cpantesters.org/?module=Data::Hash::Patch::Smart>
234  
235 =back
236  
237 =head1 LICENCE AND COPYRIGHT
238  
239 Copyright 2026 Nigel Horne.
240  
241 Usage is subject to licence terms.
242  
243 The licence terms of this software are as follows:
244  
245 =over 4
246  
247 =item * Personal single user, single computer use: GPL2
248  
249 =item * All other users (including Commercial, Charity, Educational, Government)
250 must apply in writing for a licence for use from Nigel Horne at the
251 above e-mail.
252  
253 =back
254  
255 =cut
256  
257 8 1;
« Smart/Engine.pm ↑ Summary