File Coverage

blib/lib/Hydrogen/Topic/HashRef.pm
Criterion Covered Total %
statement 105 163 64.4
branch 35 98 35.7
condition 1 11 9.0
subroutine 22 30 73.3
pod 21 21 100.0
total 184 323 56.9


line stmt bran cond sub pod time code
1             # This file was autogenerated.
2 2     2   227522 use 5.008001;
  2         12  
3 2     2   14 use strict;
  2         6  
  2         39  
4 2     2   9 use warnings;
  2         4  
  2         50  
5 2     2   11 no warnings qw( void once );
  2         4  
  2         56  
6 2     2   390 use Hydrogen ();
  2         5  
  2         155  
7              
8             package Hydrogen::Topic::HashRef;
9              
10             our $AUTHORITY = 'cpan:TOBYINK';
11             our $VERSION = '0.020000';
12              
13             =head1 NAME
14              
15             Hydrogen::Topic::HashRef - functions from Hydrogen::HashRef applied to C<$_>
16              
17             =head1 VERSION
18              
19             This documentation is for Hydrogen::Topic::HashRef 0.020000,
20             which is based on Sub::HandlesVia::HandlerLibrary::Hash 0.046.
21              
22             =cut
23              
24             =head1 FUNCTIONS
25              
26             Each function implicitly operates on C<< $_ >>, expecting it to be a reference to a hash.
27              
28             =cut
29              
30 2         12 use Exporter::Shiny qw(
31             accessor
32             all
33             clear
34             count
35             defined
36             delete
37             delete_where
38             elements
39             exists
40             for_each_key
41             for_each_pair
42             for_each_value
43             get
44             is_empty
45             keys
46             kv
47             reset
48             set
49             shallow_clone
50             sorted_keys
51             values
52 2     2   13 );
  2         4  
53              
54             =head2 C<< accessor( $key, $value? ) >>
55              
56             Operates on C<< $_ >>, which must be a reference to a hash.
57              
58             Arguments: B<< Str >>, B<< Optional[Any] >>.
59              
60             Acts like C if given just a key, or C if given a key and a value.
61              
62             =cut
63              
64             {
65             my $__signature;
66              
67             sub accessor {
68              
69             package Hydrogen::HashRef::__SANDBOX__;
70             $__signature ||= sub {
71 0     0   0 my ( %tmp, $tmp );
72              
73 0 0 0     0 @_ >= 1 && @_ <= 2
74             or Hydrogen::croak(
75             "Wrong number of parameters in signature for %s: got %d, %s",
76             "accessor", scalar(@_), "expected exactly 1 parameters" );
77              
78             # Parameter $_[0] (type: Str)
79 0 0       0 do {
80              
81             package Hydrogen::HashRef::__SANDBOX__;
82 0 0       0 defined( $_[0] ) and do {
83 0 0       0 ref( \$_[0] ) eq 'SCALAR'
84             or ref( \( my $val = $_[0] ) ) eq 'SCALAR';
85             }
86             }
87             or Hydrogen::croak(
88             "Type check failed in signature for accessor: %s should be %s",
89             "\$_[0]", "Str"
90             );
91              
92             # Parameter $_[1] (type: Optional[Any])
93 0 0       0 $#_ >= 1
94             or return (@_);
95 0         0 ( !!1 )
96             or Hydrogen::croak(
97             "Type check failed in signature for accessor: %s should be %s",
98             "\$_[1]", "Optional[Any]"
99             );
100              
101 0         0 (@_);
102 0   0 0 1 0 };
103 0         0 @_ = &$__signature;
104 0         0 1;
105 0 0       0 ( ( 0 + @_ ) == 1 ) ? ($_)->{ $_[0] } : ( ($_)->{ $_[0] } = $_[1] );
106             }
107             }
108              
109             =head2 C<< all() >>
110              
111             Operates on C<< $_ >>, which must be a reference to a hash.
112              
113             Returns the hash in list context.
114              
115             =cut
116              
117             sub all {
118              
119             package Hydrogen::HashRef::__SANDBOX__;
120 1 50   1 1 9244 @_ == 0
121             or Hydrogen::croak( "Wrong number of parameters for all; usage: "
122             . "Hydrogen::Topic::HashRef::all()" );
123 1         2 %{$_};
  1         7  
124             }
125              
126             =head2 C<< clear() >>
127              
128             Operates on C<< $_ >>, which must be a reference to a hash.
129              
130             Empties the hash.
131              
132             =cut
133              
134             sub clear {
135              
136             package Hydrogen::HashRef::__SANDBOX__;
137 1 50   1 1 2503 @_ == 0
138             or Hydrogen::croak( "Wrong number of parameters for clear; usage: "
139             . "Hydrogen::Topic::HashRef::clear()" );
140 1         2 1;
141 1         4 %{$_} = ();
  1         3  
142             }
143              
144             =head2 C<< count() >>
145              
146             Operates on C<< $_ >>, which must be a reference to a hash.
147              
148             Returns the number of keys in the hash.
149              
150             =cut
151              
152             sub count {
153              
154             package Hydrogen::HashRef::__SANDBOX__;
155 1 50   1 1 2978 @_ == 0
156             or Hydrogen::croak( "Wrong number of parameters for count; usage: "
157             . "Hydrogen::Topic::HashRef::count()" );
158 1         3 scalar keys %{$_};
  1         7  
159             }
160              
161             =head2 C<< defined( $key ) >>
162              
163             Operates on C<< $_ >>, which must be a reference to a hash.
164              
165             Arguments: B<< Str >>.
166              
167             Indicates whether a value exists and is defined in the hashref by its key.
168              
169             =cut
170              
171             sub defined {
172              
173             package Hydrogen::HashRef::__SANDBOX__;
174 1     1 1 2882 @_ = do {
175 1         3 my ( %tmp, $tmp );
176              
177 1 50       5 @_ == 1
178             or Hydrogen::croak(
179             "Wrong number of parameters in signature for %s: got %d, %s",
180             "defined", scalar(@_), "expected exactly 1 parameters" );
181              
182             # Parameter $_[0] (type: Str)
183 1 50       2 do {
184              
185             package Hydrogen::HashRef::__SANDBOX__;
186 1 50       5 defined( $_[0] ) and do {
187 1 50       12 ref( \$_[0] ) eq 'SCALAR'
188             or ref( \( my $val = $_[0] ) ) eq 'SCALAR';
189             }
190             }
191             or Hydrogen::croak(
192             "Type check failed in signature for defined: %s should be %s",
193             "\$_[0]", "Str" );
194              
195 1         5 (@_);
196             };
197 1         6 defined( ($_)->{ $_[0] } );
198             }
199              
200             =head2 C<< delete( $key ) >>
201              
202             Operates on C<< $_ >>, which must be a reference to a hash.
203              
204             Removes a value from the hashref by its key.
205              
206             =cut
207              
208             sub delete {
209              
210             package Hydrogen::HashRef::__SANDBOX__;
211 1 50   1 1 2747 @_ >= 1
212             or Hydrogen::croak( "Wrong number of parameters for delete; usage: "
213             . "Hydrogen::Topic::HashRef::delete( \$key )" );
214 1         2 1;
215 1         2 delete( @{$_}{@_} );
  1         6  
216             }
217              
218             =head2 C<< delete_where( $match ) >>
219              
220             Operates on C<< $_ >>, which must be a reference to a hash.
221              
222             Arguments: B<< CodeRef|RegexpRef >>.
223              
224             Removes values from the hashref by matching keys against a coderef or regexp.
225              
226             =cut
227              
228             sub delete_where {
229              
230             package Hydrogen::HashRef::__SANDBOX__;
231 2     2 1 3322 @_ = do {
232 2         4 my ( %tmp, $tmp );
233              
234 2 50       8 @_ == 1
235             or Hydrogen::croak(
236             "Wrong number of parameters in signature for %s: got %d, %s",
237             "delete_where", scalar(@_), "expected exactly 1 parameters" );
238              
239             # Parameter $_[0] (type: CodeRef|RegexpRef)
240 2 50       5 do {
241              
242             package Hydrogen::HashRef::__SANDBOX__;
243             (
244             ( ref( $_[0] ) eq 'CODE' ) or (
245 2 100       10 do {
246              
247             package Hydrogen::HashRef::__SANDBOX__;
248 2     2   1531 use Scalar::Util ();
  2         24  
  2         49  
249 2     2   10 use re ();
  2         4  
  2         3179  
250 1 50 0     12 ref( $_[0] ) && !!re::is_regexp( $_[0] )
      33        
251             or Scalar::Util::blessed( $_[0] )
252             && $_[0]->isa('Regexp');
253             }
254             )
255             );
256             }
257             or Hydrogen::croak(
258             "Type check failed in signature for delete_where: %s should be %s",
259             "\$_[0]", "CodeRef|RegexpRef"
260             );
261              
262 2         7 (@_);
263             };
264 2         3 my %shv_tmp = %{$_};
  2         9  
265 2         4 my $shv_match = $_[0];
266 2 100       19 my @shv_keys =
267             ( "CODE" eq ref $shv_match )
268             ? grep( $shv_match->($_), keys %shv_tmp )
269             : grep( /$shv_match/, keys %shv_tmp );
270 2         15 my @shv_return = delete @shv_tmp{@shv_keys};
271             (
272 2         5 %{$_} = %{
273 2         4 +do {
  2         3  
274 2         4 my $shv_final_unchecked = \%shv_tmp;
275 2         3 do {
276 2 50       5 ( ref($shv_final_unchecked) eq 'HASH' )
277             or Hydrogen::croak(
278             "Type check failed for delete_where: expected %s, got value %s",
279             "HashRef", $shv_final_unchecked
280             );
281 2         6 $shv_final_unchecked;
282             };
283             }
284             }
285             );
286 2 50       8 wantarray ? @shv_return : $shv_return[-1];
287             }
288              
289             =head2 C<< elements() >>
290              
291             Operates on C<< $_ >>, which must be a reference to a hash.
292              
293             Returns the hash in list context.
294              
295             =cut
296              
297             sub elements {
298              
299             package Hydrogen::HashRef::__SANDBOX__;
300 1 50   1 1 3117 @_ == 0
301             or Hydrogen::croak( "Wrong number of parameters for elements; usage: "
302             . "Hydrogen::Topic::HashRef::elements()" );
303 1         2 %{$_};
  1         9  
304             }
305              
306             =head2 C<< exists( $key ) >>
307              
308             Operates on C<< $_ >>, which must be a reference to a hash.
309              
310             Arguments: B<< Str >>.
311              
312             Indicates whether a value exists in the hashref by its key.
313              
314             =cut
315              
316             sub exists {
317              
318             package Hydrogen::HashRef::__SANDBOX__;
319 2     2 1 2244 @_ = do {
320 2         5 my ( %tmp, $tmp );
321              
322 2 50       6 @_ == 1
323             or Hydrogen::croak(
324             "Wrong number of parameters in signature for %s: got %d, %s",
325             "exists", scalar(@_), "expected exactly 1 parameters" );
326              
327             # Parameter $_[0] (type: Str)
328 2 50       5 do {
329              
330             package Hydrogen::HashRef::__SANDBOX__;
331 2 50       7 defined( $_[0] ) and do {
332 2 50       12 ref( \$_[0] ) eq 'SCALAR'
333             or ref( \( my $val = $_[0] ) ) eq 'SCALAR';
334             }
335             }
336             or Hydrogen::croak(
337             "Type check failed in signature for exists: %s should be %s",
338             "\$_[0]", "Str" );
339              
340 2         8 (@_);
341             };
342 2         11 defined( ($_)->{ $_[0] } );
343             }
344              
345             =head2 C<< for_each_key( $coderef ) >>
346              
347             Operates on C<< $_ >>, which must be a reference to a hash.
348              
349             Arguments: B<< CodeRef >>.
350              
351             Function which calls the coderef for each key in the hash, passing just the key to the coderef.
352              
353             =cut
354              
355             sub for_each_key {
356              
357             package Hydrogen::HashRef::__SANDBOX__;
358 0     0 1 0 @_ = do {
359 0         0 my ( %tmp, $tmp );
360              
361 0 0       0 @_ == 1
362             or Hydrogen::croak(
363             "Wrong number of parameters in signature for %s: got %d, %s",
364             "for_each_key", scalar(@_), "expected exactly 1 parameters" );
365              
366             # Parameter $_[0] (type: CodeRef)
367 0 0       0 ( ref( $_[0] ) eq 'CODE' )
368             or Hydrogen::croak(
369             "Type check failed in signature for for_each_key: %s should be %s",
370             "\$_[0]", "CodeRef"
371             );
372              
373 0         0 (@_);
374             };
375 0         0 for my $shv_key ( keys %{$_} ) { &{ $_[0] }($shv_key) };
  0         0  
  0         0  
  0         0  
376 0         0 $_;
377             }
378              
379             =head2 C<< for_each_pair( $coderef ) >>
380              
381             Operates on C<< $_ >>, which must be a reference to a hash.
382              
383             Arguments: B<< CodeRef >>.
384              
385             Function which calls the coderef for each key in the hash, passing the key and value to the coderef.
386              
387             =cut
388              
389             sub for_each_pair {
390              
391             package Hydrogen::HashRef::__SANDBOX__;
392 0     0 1 0 @_ = do {
393 0         0 my ( %tmp, $tmp );
394              
395 0 0       0 @_ == 1
396             or Hydrogen::croak(
397             "Wrong number of parameters in signature for %s: got %d, %s",
398             "for_each_pair", scalar(@_), "expected exactly 1 parameters" );
399              
400             # Parameter $_[0] (type: CodeRef)
401 0 0       0 ( ref( $_[0] ) eq 'CODE' )
402             or Hydrogen::croak(
403             "Type check failed in signature for for_each_pair: %s should be %s",
404             "\$_[0]", "CodeRef"
405             );
406              
407 0         0 (@_);
408             };
409 0         0 while ( my ( $shv_key, $shv_value ) = each %{$_} ) {
  0         0  
410 0         0 &{ $_[0] }( $shv_key, $shv_value );
  0         0  
411             };
412 0         0 $_;
413             }
414              
415             =head2 C<< for_each_value( $coderef ) >>
416              
417             Operates on C<< $_ >>, which must be a reference to a hash.
418              
419             Arguments: B<< CodeRef >>.
420              
421             Function which calls the coderef for each value in the hash, passing just the value to the coderef.
422              
423             =cut
424              
425             sub for_each_value {
426              
427             package Hydrogen::HashRef::__SANDBOX__;
428 0     0 1 0 @_ = do {
429 0         0 my ( %tmp, $tmp );
430              
431 0 0       0 @_ == 1
432             or Hydrogen::croak(
433             "Wrong number of parameters in signature for %s: got %d, %s",
434             "for_each_value", scalar(@_), "expected exactly 1 parameters" );
435              
436             # Parameter $_[0] (type: CodeRef)
437 0 0       0 ( ref( $_[0] ) eq 'CODE' )
438             or Hydrogen::croak(
439             "Type check failed in signature for for_each_value: %s should be %s",
440             "\$_[0]", "CodeRef"
441             );
442              
443 0         0 (@_);
444             };
445 0         0 for my $shv_value ( values %{$_} ) { &{ $_[0] }($shv_value) };
  0         0  
  0         0  
  0         0  
446 0         0 $_;
447             }
448              
449             =head2 C<< get( $key ) >>
450              
451             Operates on C<< $_ >>, which must be a reference to a hash.
452              
453             Returns a value from the hashref by its key.
454              
455             =cut
456              
457             sub get {
458              
459             package Hydrogen::HashRef::__SANDBOX__;
460 1 50   1 1 8227 @_ >= 1
461             or Hydrogen::croak( "Wrong number of parameters for get; usage: "
462             . "Hydrogen::Topic::HashRef::get( \$key )" );
463 1 50       12 ( 0 + @_ ) > 1 ? @{$_}{@_} : ($_)->{ $_[0] };
  0         0  
464             }
465              
466             =head2 C<< is_empty() >>
467              
468             Operates on C<< $_ >>, which must be a reference to a hash.
469              
470             Returns true iff there are no keys in the hash.
471              
472             =cut
473              
474             sub is_empty {
475              
476             package Hydrogen::HashRef::__SANDBOX__;
477 2 50   2 1 2810 @_ == 0
478             or Hydrogen::croak( "Wrong number of parameters for is_empty; usage: "
479             . "Hydrogen::Topic::HashRef::is_empty()" );
480 2         4 !scalar keys %{$_};
  2         11  
481             }
482              
483             =head2 C<< keys() >>
484              
485             Operates on C<< $_ >>, which must be a reference to a hash.
486              
487             Returns the list of keys in the hash.
488              
489             =cut
490              
491             sub keys {
492              
493             package Hydrogen::HashRef::__SANDBOX__;
494 1 50   1 1 2827 @_ == 0
495             or Hydrogen::croak( "Wrong number of parameters for keys; usage: "
496             . "Hydrogen::Topic::HashRef::keys()" );
497 1         3 keys %{$_};
  1         6  
498             }
499              
500             =head2 C<< kv() >>
501              
502             Operates on C<< $_ >>, which must be a reference to a hash.
503              
504             Returns a list of arrayrefs, where each arrayref is a key-value pair.
505              
506             =cut
507              
508             sub kv {
509              
510             package Hydrogen::HashRef::__SANDBOX__;
511 0 0   0 1 0 @_ == 0
512             or Hydrogen::croak( "Wrong number of parameters for kv; usage: "
513             . "Hydrogen::Topic::HashRef::kv()" );
514 0         0 map [ $_ => ($_)->{$_} ], keys %{$_};
  0         0  
515             }
516              
517             =head2 C<< reset() >>
518              
519             Operates on C<< $_ >>, which must be a reference to a hash.
520              
521             Resets the original value to its default value, or an empty hashref if it has no default.
522              
523             =cut
524              
525             sub reset {
526              
527             package Hydrogen::HashRef::__SANDBOX__;
528 0 0   0 1 0 @_ == 0
529             or Hydrogen::croak( "Wrong number of parameters for reset; usage: "
530             . "Hydrogen::Topic::HashRef::reset()" );
531             (
532 0         0 %{$_} = %{
533 0         0 +do {
  0         0  
534 0         0 my $shv_final_unchecked = {};
535 0         0 do {
536 0 0       0 ( ref($shv_final_unchecked) eq 'HASH' )
537             or Hydrogen::croak(
538             "Type check failed for reset: expected %s, got value %s",
539             "HashRef", $shv_final_unchecked
540             );
541 0         0 $shv_final_unchecked;
542             };
543             }
544             }
545             );
546             }
547              
548             =head2 C<< set( $key, $value, ... ) >>
549              
550             Operates on C<< $_ >>, which must be a reference to a hash.
551              
552             Given a key and value, adds the key to the hashref with the given value.
553              
554             =cut
555              
556             sub set {
557              
558             package Hydrogen::HashRef::__SANDBOX__;
559 1 50   1 1 6869 @_ >= 2
560             or Hydrogen::croak( "Wrong number of parameters for set; usage: "
561             . "Hydrogen::Topic::HashRef::set( \$key, \$value, ... )" );
562 1         4 my (@shv_params) = @_;
563 1 50       7 scalar(@shv_params) % 2
564             and Hydrogen::croak(
565             "Wrong number of parameters; expected even-sized list of keys and values"
566             );
567 1         7 my (@shv_keys_idx) = grep( !( $_ % 2 ), 0 .. $#shv_params );
568 1         4 my (@shv_values_idx) = grep( ( $_ % 2 ), 0 .. $#shv_params );
569 1 50       8 grep( !defined, @shv_params[@shv_keys_idx] )
570             and Hydrogen::croak(
571             "Undef did not pass type constraint; keys must be defined");
572 1         4 for my $shv_tmp (@shv_keys_idx) {
573 2         2 do {
574 2 50       3 do {
575              
576             package Hydrogen::HashRef::__SANDBOX__;
577 2 50       6 defined( $shv_params[$shv_tmp] ) and do {
578 2 50       14 ref( \$shv_params[$shv_tmp] ) eq 'SCALAR'
579             or ref( \( my $val = $shv_params[$shv_tmp] ) ) eq 'SCALAR';
580             }
581             }
582             or Hydrogen::croak(
583             "Type check failed for set: expected %s, got value %s",
584             "Str", $shv_params[$shv_tmp] );
585 2         7 $shv_params[$shv_tmp];
586             };
587             };
588 1         5 @{$_}{ @shv_params[@shv_keys_idx] } = @shv_params[@shv_values_idx];
  1         3  
589             wantarray
590 0         0 ? @{$_}{ @shv_params[@shv_keys_idx] }
591 1 50       9 : ($_)->{ $shv_params[ $shv_keys_idx[0] ] };
592             }
593              
594             =head2 C<< shallow_clone() >>
595              
596             Operates on C<< $_ >>, which must be a reference to a hash.
597              
598             Creates a new hashref with the same keys and values as the original.
599              
600             =cut
601              
602             sub shallow_clone {
603              
604             package Hydrogen::HashRef::__SANDBOX__;
605 0 0   0 1 0 @_ == 0
606             or
607             Hydrogen::croak( "Wrong number of parameters for shallow_clone; usage: "
608             . "Hydrogen::Topic::HashRef::shallow_clone()" );
609 0         0 +{ %{$_} };
  0         0  
610             }
611              
612             =head2 C<< sorted_keys() >>
613              
614             Operates on C<< $_ >>, which must be a reference to a hash.
615              
616             Returns an alphabetically sorted list of keys in the hash.
617              
618             =cut
619              
620             sub sorted_keys {
621              
622             package Hydrogen::HashRef::__SANDBOX__;
623 1 50   1 1 5670 @_ == 0
624             or Hydrogen::croak( "Wrong number of parameters for sorted_keys; usage: "
625             . "Hydrogen::Topic::HashRef::sorted_keys()" );
626 1         4 sort( keys %{$_} );
  1         13  
627             }
628              
629             =head2 C<< values() >>
630              
631             Operates on C<< $_ >>, which must be a reference to a hash.
632              
633             Returns the list of values in the hash.
634              
635             =cut
636              
637             sub values {
638              
639             package Hydrogen::HashRef::__SANDBOX__;
640 1 50   1 1 3155 @_ == 0
641             or Hydrogen::croak( "Wrong number of parameters for values; usage: "
642             . "Hydrogen::Topic::HashRef::values()" );
643 1         3 values %{$_};
  1         6  
644             }
645              
646             1;
647              
648             =head1 EXPORT
649              
650             No functions are exported by this module by default. To import them all (this is usually a bad idea), use:
651              
652             use Hydrogen::Topic::HashRef -all;
653              
654             To import a particular function, use:
655              
656             use Hydrogen::Topic::HashRef 'clear';
657              
658             To rename functions:
659              
660             use Hydrogen::Topic::HashRef 'clear' => { -as => 'myfunc' };
661              
662             On Perl 5.37.2+ (or if L is installed) you can import lexically:
663              
664             use Hydrogen::Topic::HashRef -lexical, 'clear';
665              
666             See L for more hints on importing.
667              
668             =head1 BUGS
669              
670             Please report any bugs to
671             L.
672              
673             =head1 SEE ALSO
674              
675             L,
676             L,
677             L,
678             L,
679             L,
680             L.
681              
682             =head1 AUTHOR
683              
684             Toby Inkster Etobyink@cpan.orgE.
685              
686             =head1 COPYRIGHT AND LICENCE
687              
688             This software is copyright (c) 2022-2023 by Toby Inkster.
689              
690             This is free software; you can redistribute it and/or modify it under
691             the same terms as the Perl 5 programming language system itself.
692              
693             =head1 DISCLAIMER OF WARRANTIES
694              
695             THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
696             WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
697             MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
698