1Sub::HandlesVia::HandleUrsLeirbrCaornyt:r:iAbrurtaeydS(u3Pb)e:r:lHaDnodcluemseVnitaa:t:iHoanndlerLibrary::Array(3)
2
6 Sub::HandlesVia::HandlerLibrary::Array - library of array-related
7 methods
8
10 package My::Class {
11 use Moo;
12 use Sub::HandlesVia;
13 use Types::Standard 'ArrayRef';
14 has attr => (
15 is => 'rwp',
16 isa => ArrayRef,
17 handles_via => 'Array',
18 handles => {
19 'my_accessor' => 'accessor',
20 'my_all' => 'all',
21 'my_all_true' => 'all_true',
22 'my_any' => 'any',
23 'my_apply' => 'apply',
24 'my_clear' => 'clear',
25 'my_count' => 'count',
26 'my_delete' => 'delete',
27 'my_elements' => 'elements',
28 'my_first' => 'first',
29 'my_first_index' => 'first_index',
30 'my_flatten' => 'flatten',
31 'my_flatten_deep' => 'flatten_deep',
32 'my_for_each' => 'for_each',
33 'my_for_each_pair' => 'for_each_pair',
34 'my_get' => 'get',
35 'my_grep' => 'grep',
36 'my_head' => 'head',
37 'my_insert' => 'insert',
38 'my_is_empty' => 'is_empty',
39 'my_join' => 'join',
40 'my_map' => 'map',
41 'my_max' => 'max',
42 'my_maxstr' => 'maxstr',
43 'my_min' => 'min',
44 'my_minstr' => 'minstr',
45 'my_natatime' => 'natatime',
46 'my_not_all_true' => 'not_all_true',
47 'my_pairfirst' => 'pairfirst',
48 'my_pairgrep' => 'pairgrep',
49 'my_pairkeys' => 'pairkeys',
50 'my_pairmap' => 'pairmap',
51 'my_pairs' => 'pairs',
52 'my_pairvalues' => 'pairvalues',
53 'my_pick_random' => 'pick_random',
54 'my_pop' => 'pop',
55 'my_print' => 'print',
56 'my_product' => 'product',
57 'my_push' => 'push',
58 'my_reduce' => 'reduce',
59 'my_reductions' => 'reductions',
60 'my_reset' => 'reset',
61 'my_reverse' => 'reverse',
62 'my_sample' => 'sample',
63 'my_set' => 'set',
64 'my_shallow_clone' => 'shallow_clone',
65 'my_shift' => 'shift',
66 'my_shuffle' => 'shuffle',
67 'my_shuffle_in_place' => 'shuffle_in_place',
68 'my_sort' => 'sort',
69 'my_sort_in_place' => 'sort_in_place',
70 'my_splice' => 'splice',
71 'my_sum' => 'sum',
72 'my_tail' => 'tail',
73 'my_uniq' => 'uniq',
74 'my_uniq_in_place' => 'uniq_in_place',
75 'my_uniqnum' => 'uniqnum',
76 'my_uniqnum_in_place' => 'uniqnum_in_place',
77 'my_uniqstr' => 'uniqstr',
78 'my_uniqstr_in_place' => 'uniqstr_in_place',
79 'my_unshift' => 'unshift',
80 },
81 );
82 }
83
85 This is a library of methods for Sub::HandlesVia.
86
88 "accessor( $index, $value? )"
89 Arguments: Int, Optional[Any].
90 Acts like "get" if given just an index, or "set" if given an index and
92 value.
93 my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
95 $object->my_accessor( 1, 'quux' );
96 say Dumper( $object->attr ); ## ==> [ 'foo', 'quux', 'baz' ]
97 say $object->my_accessor( 2 ); ## ==> 'baz'
98 "all()"
100 All elements in the array, in list context.
101 my $object = My::Class->new( attr => [ 'foo', 'bar' ] );
103 my @list = $object->my_all;
104 say Dumper( \@list ); ## ==> [ 'foo', 'bar' ]
105 "all_true( $coderef )"
107 Arguments: CodeRef.
108 Like "List::Util::all()".
110 "any( $coderef )"
112 Arguments: CodeRef.
113 Like "List::Util::any()".
115 my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
117 my $truth = $object->my_any( sub { /a/ } );
118 say $truth; ## ==> true
119 "apply( $coderef )"
121 Arguments: CodeRef.
122 Executes the coderef (which should modify $_) against each element of
124 the array; returns the resulting array in list context.
125 "clear()"
127 Empties the array.
128 my $object = My::Class->new( attr => [ 'foo' ] );
130 $object->my_clear;
131 say Dumper( $object->attr ); ## ==> []
132 "count()"
134 The number of elements in the referenced array.
135 my $object = My::Class->new( attr => [ 'foo', 'bar' ] );
137 say $object->my_count; ## ==> 2
138 "delete( $index )"
140 Arguments: Int.
141 Removes the indexed element from the array and returns it. Elements
143 after it will be "moved up".
144 "elements()"
146 All elements in the array, in list context. (Essentially the same as
147 "all".)
148 my $object = My::Class->new( attr => [ 'foo', 'bar' ] );
150 my @list = $object->my_elements;
151 say Dumper( \@list ); ## ==> [ 'foo', 'bar' ]
152 "first( $coderef )"
154 Arguments: CodeRef.
155 Like "List::Util::first()".
157 my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
159 my $found = $object->my_first( sub { /a/ } );
160 say $found; ## ==> 'bar'
161 "first_index( $coderef )"
163 Arguments: CodeRef.
164 Like "List::MoreUtils::first_index()".
166 my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
168 my $found = $object->my_first_index( sub { /z$/ } );
169 say $found; ## ==> 2
170 "flatten()"
172 All elements in the array, in list context. (Essentially the same as
173 "all".)
174 my $object = My::Class->new( attr => [ 'foo', 'bar' ] );
176 my @list = $object->my_flatten;
177 say Dumper( \@list ); ## ==> [ 'foo', 'bar' ]
178 "flatten_deep( $depth? )"
180 Arguments: Optional[Int].
181 Flattens the arrayref into a list, including any nested arrayrefs. (Has
183 the potential to loop infinitely.)
184 my $object = My::Class->new( attr => [ 'foo', [ 'bar', [ 'baz' ] ] ] );
186 say Dumper( [ $object->my_flatten_deep ] ); ## ==> [ 'foo', 'bar', 'baz' ]
187 my $object2 = My::Class->new( attr => [ 'foo', [ 'bar', [ 'baz' ] ] ] );
189 say Dumper( [ $object->my_flatten_deep(1) ] ); ## ==> [ 'foo', 'bar', [ 'baz' ] ]
190 "for_each( $coderef )"
192 Arguments: CodeRef.
193 Chainable method which executes the coderef on each element of the
195 array. The coderef will be passed two values: the element and its
196 index.
197 my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
199 $object->my_for_each( sub { say "Item $_[1] is $_[0]." } );
200 "for_each_pair( $coderef )"
202 Arguments: CodeRef.
203 Chainable method which executes the coderef on each pair of elements in
205 the array. The coderef will be passed the two elements.
206 "get( $index )"
208 Arguments: Int.
209 Returns a single element from the array by index.
211 my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
213 say $object->my_get( 0 ); ## ==> 'foo'
214 say $object->my_get( 1 ); ## ==> 'bar'
215 say $object->my_get( -1 ); ## ==> 'baz'
216 "grep( $coderef )"
218 Arguments: CodeRef.
219 Like "grep" from perlfunc.
221 "head( $count )"
223 Arguments: Int.
224 Returns the first $count elements of the array in list context.
226 "insert( $index, $value )"
228 Arguments: Int, Any.
229 Inserts a value into the array with the given index. Elements after it
231 will be "moved down".
232 my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
234 $object->my_insert( 1, 'quux' );
235 say Dumper( $object->attr ); ## ==> [ 'foo', 'quux', 'bar', 'baz' ]
236 "is_empty()"
238 Boolean indicating if the referenced array is empty.
239 my $object = My::Class->new( attr => [ 'foo', 'bar' ] );
241 say $object->my_is_empty; ## ==> false
242 $object->_set_attr( [] );
243 say $object->my_is_empty; ## ==> true
244 "join( $with? )"
246 Arguments: Optional[Str].
247 Returns a string joining all the elements in the array; if $with is
249 omitted, defaults to a comma.
250 my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
252 say $object->my_join; ## ==> 'foo,bar,baz'
253 say $object->my_join( '|' ); ## ==> 'foo|bar|baz'
254 "map( $coderef )"
256 Arguments: CodeRef.
257 Like "map" from perlfunc.
259 "max()"
261 Like "List::Util::max()".
262 "maxstr()"
264 Like "List::Util::maxstr()".
265 "min()"
267 Like "List::Util::min()".
268 "minstr()"
270 Like "List::Util::minstr()".
271 "natatime( $n, $callback? )"
273 Arguments: Int, Optional[CodeRef].
274 Given just a number, returns an iterator which reads that many elements
276 from the array at a time. If also given a callback, calls the callback
277 repeatedly with those values.
278 my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
280 my $iter = $object->my_natatime( 2 );
281 say Dumper( [ $iter->() ] ); ## ==> [ 'foo', 'bar' ]
282 say Dumper( [ $iter->() ] ); ## ==> [ 'baz' ]
283 "not_all_true( $coderef )"
285 Arguments: CodeRef.
286 Like "List::Util::notall()".
288 "pairfirst( $coderef )"
290 Arguments: CodeRef.
291 Like "List::Util::pairfirst()".
293 "pairgrep( $coderef )"
295 Arguments: CodeRef.
296 Like "List::Util::pairgrep()".
298 "pairkeys()"
300 Like "List::Util::pairkeys()".
301 "pairmap( $coderef )"
303 Arguments: CodeRef.
304 Like "List::Util::pairmap()".
306 "pairs()"
308 Like "List::Util::pairs()".
309 "pairvalues()"
311 Like "List::Util::pairvalues()".
312 "pick_random( $count )"
314 Arguments: Optional[Int].
315 If no $count is given, returns one element of the array at random. If
317 $count is given, creates a new array with that many random elements
318 from the original array (or fewer if the original array is not long
319 enough) and returns that as an arrayref or list depending on context
320 "pop()"
322 Removes the last element from the array and returns it.
323 my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
325 say $object->my_pop; ## ==> 'baz'
326 say $object->my_pop; ## ==> 'bar'
327 say Dumper( $object->attr ); ## ==> [ 'foo' ]
328 "print( $fh?, $with? )"
330 Arguments: Optional[FileHandle], Optional[Str].
331 Prints a string joining all the elements in the array; if $fh is
333 omitted, defaults to STDOUT; if $with is omitted, defaults to a comma.
334 "product()"
336 Like "List::Util::product()".
337 "push( @values )"
339 Adds elements to the end of the array.
340 my $object = My::Class->new( attr => [ 'foo' ] );
342 $object->my_push( 'bar', 'baz' );
343 say Dumper( $object->attr ); ## ==> [ 'foo', 'bar', 'baz' ]
344 "reduce( $coderef )"
346 Arguments: CodeRef.
347 Like "List::Util::reduce()".
349 "reductions( $coderef )"
351 Arguments: CodeRef.
352 Like "List::Util::reductions()".
354 "reset()"
356 Resets the attribute to its default value, or an empty arrayref if it
357 has no default.
358 my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
360 $object->my_reset;
361 say Dumper( $object->attr ); ## ==> []
362 "reverse()"
364 Returns the reversed array in list context.
365 "sample( $count )"
367 Arguments: Int.
368 Like "List::Util::sample()".
370 "set( $index, $value )"
372 Arguments: Int, Any.
373 Sets the element with the given index to the supplied value.
375 my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
377 $object->my_set( 1, 'quux' );
378 say Dumper( $object->attr ); ## ==> [ 'foo', 'quux', 'baz' ]
379 "shallow_clone()"
381 Creates a new arrayref with the same elements as the original.
382 "shift()"
384 Removes an element from the start of the array and returns it.
385 my $object = My::Class->new( attr => [ 'foo', 'bar', 'baz' ] );
387 say $object->my_shift; ## ==> 'foo'
388 say $object->my_shift; ## ==> 'bar'
389 say Dumper( $object->attr ); ## ==> [ 'baz' ]
390 "shuffle()"
392 Returns the array in a random order; can be called in list context or
393 scalar context and will return an arrayref in the latter case.
394 "shuffle_in_place()"
396 Rearranges the array in a random order, and changes the attribute to
397 point to the new order.
398 "sort( $coderef? )"
400 Arguments: Optional[CodeRef].
401 Like "sort" from perlfunc.
403 "sort_in_place( $coderef? )"
405 Arguments: Optional[CodeRef].
406 Like "sort" from perlfunc, but changes the attribute to point to the
408 newly sorted array.
409 "splice( $index, $length, @values )"
411 Like "splice" from perlfunc.
412 "sum()"
414 Like "List::Util::sum0()".
415 "tail( $count )"
417 Arguments: Int.
418 Returns the last $count elements of the array in list context.
420 "uniq()"
422 Returns the array filtered to remove duplicates; can be called in list
423 context or scalar context and will return an arrayref in the latter
424 case.
425 "uniq_in_place()"
427 Filters the array to remove duplicates, and changes the attribute to
428 point to the filtered array.
429 "uniqnum()"
431 Returns the array filtered to remove duplicates numerically; can be
432 called in list context or scalar context and will return an arrayref in
433 the latter case.
434 "uniqnum_in_place()"
436 Filters the array to remove duplicates numerically, and changes the
437 attribute to point to the filtered array.
438 "uniqstr()"
440 Returns the array filtered to remove duplicates stringwise; can be
441 called in list context or scalar context and will return an arrayref in
442 the latter case.
443 "uniqstr_in_place()"
445 Filters the array to remove duplicates stringwise, and changes the
446 attribute to point to the filtered array.
447 "unshift( @values )"
449 Adds an element to the start of the array.
450 my $object = My::Class->new( attr => [ 'foo' ] );
452 $object->my_unshift( 'bar', 'baz' );
453 say Dumper( $object->attr ); ## ==> [ 'bar', 'baz', 'foo' ]
454
456 This module provides some shortcut constants for indicating a list of
457 delegations.
458 package My::Class {
460 use Moo;
461 use Sub::HandlesVia;
462 use Sub::HandlesVia::HandlerLibrary::Array qw( HandleQueue );
463 has things => (
465 is => 'ro',
466 handles_via => 'Array',
467 handles => HandleQueue,
468 default => sub { [] },
469 );
470 }
471 These shortcuts can be combined using the " | " operator.
473 has things => (
475 is => 'ro',
476 handles_via => 'Array',
477 handles => HandleQueue | HandleStack,
478 default => sub { [] },
479 );
480 "HandleQueue"
482 Creates delegations named like "things_is_empty", "things_size",
483 "things_enqueue", "things_dequeue", and "things_peek".
484 "HandleStack"
486 Creates delegations named like "things_is_empty", "things_size",
487 "things_push", "things_pop", and "things_peek".
488
490 Using for_each
491 use strict;
492 use warnings;
493 package My::Plugin {
495 use Moo::Role;
496 sub initialize {}
497 sub finalize {}
498 }
499 package My::Processor {
501 use Moo;
502 use Sub::HandlesVia;
503 use Types::Standard qw( ArrayRef ConsumerOf );
504 has plugins => (
506 is => 'ro',
507 isa => ArrayRef[ ConsumerOf['My::Plugin'] ],
508 handles_via => 'Array',
509 handles => {
510 add_plugin => 'push',
511 plugin_do => 'for_each',
512 },
513 default => sub { [] },
514 );
515 sub _do_stuff {
517 return;
518 }
519 sub run_process {
521 my ( $self, @args ) = @_;
522 $self->plugin_do( sub {
523 my $plugin = shift;
524 $plugin->initialize( $self, @args );
525 } );
526 $self->_do_stuff( @args );
527 $self->plugin_do( sub {
528 my $plugin = shift;
529 $plugin->finalize( $self, @args );
530 } );
531 }
532 }
533 my $p = My::Processor->new();
535 package My::Plugin::Noisy {
537 use Moo; with 'My::Plugin';
538 sub initialize {
539 my ( $self, $processor, @args ) = @_;
540 say "initialize @args"; ## ==> 'initialize 1 2 3'
541 }
542 sub finalize {
543 my ( $self, $processor, @args ) = @_;
544 say "finalize @args"; ## ==> 'finalize 1 2 3'
545 }
546 }
547 $p->add_plugin( My::Plugin::Noisy->new );
549 $p->run_process( 1, 2, 3 );
551 Job queue using push and shift
553 use strict;
554 use warnings;
555 use Try::Tiny;
556 package My::JobQueue {
558 use Moo;
559 use Sub::HandlesVia;
560 use Types::Standard qw( Bool ArrayRef CodeRef HasMethods is_Object );
561 use Try::Tiny;
562 has auto_requeue => (
564 is => 'ro',
565 isa => Bool,
566 default => 0,
567 );
568 has jobs => (
570 is => 'ro',
571 isa => ArrayRef[ CodeRef | HasMethods['run'] ],
572 handles_via => 'Array',
573 handles => {
574 add_job => 'push',
575 _get_job => 'shift',
576 is_empty => 'is_empty',
577 },
578 default => sub { [] },
579 );
580 sub _handle_failed_job {
582 my ( $self, $job ) = @_;
583 $self->add_job( $job ) if $self->auto_requeue;
584 }
585 sub run_jobs {
587 my $self = shift;
588 while ( not $self->is_empty ) {
589 my $job = $self->_get_job;
590 try {
591 is_Object($job) ? $job->run() : $job->();
592 }
593 catch {
594 $self->_handle_failed_job( $job );
595 };
596 }
597 }
598 }
599 my $q = My::JobQueue->new();
601 my $str = '';
603 $q->add_job( sub { $str .= 'A' } );
604 $q->add_job( sub { $str .= 'B' } );
605 $q->add_job( sub { $str .= 'C' } );
606 $q->run_jobs;
608 say $str; ## ==> 'ABC'
610 # Attempt to push invalid value on the queue
612 #
613 try {
614 $q->add_job( "jobs cannot be strings" );
615 }
616 catch {
617 say $q->is_empty; ## ==> true
618 };
619
621 Please report any bugs to
622 <https://github.com/tobyink/p5-sub-handlesvia/issues>.
623
625 Sub::HandlesVia.
626
628 Toby Inkster <tobyink@cpan.org>.
629
631 This software is copyright (c) 2020, 2022 by Toby Inkster.
632 This is free software; you can redistribute it and/or modify it under
634 the same terms as the Perl 5 programming language system itself.
635
637 THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
638 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
639 MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
640perl v5.36.0 2022S-u1b2:-:1H7andlesVia::HandlerLibrary::Array(3)