1 package DOM::Tiny::Collection;
8 use Scalar::Util 'blessed';
10 our $VERSION = '0.001';
12 our @EXPORT_OK = ('c');
14 sub c { __PACKAGE__->new(@_) }
18 return bless [@_], ref $class || $class;
21 sub TO_JSON { [@{shift()}] }
25 return $self->new(grep { defined && (ref || length) } @$self);
30 return @$self unless $cb;
32 $_->$cb($i++) for @$self;
37 my ($self, $cb) = (shift, shift);
38 return $self->[0] unless $cb;
39 return List::Util::first { $_ =~ $cb } @$self if ref $cb eq 'Regexp';
40 return List::Util::first { $_->$cb(@_) } @$self;
43 sub flatten { $_[0]->new(_flatten(@{$_[0]})) }
46 my ($self, $cb) = (shift, shift);
47 return $self->new(grep { $_ =~ $cb } @$self) if ref $cb eq 'Regexp';
48 return $self->new(grep { $_->$cb(@_) } @$self);
52 join $_[1] // '', map {"$_"} @{$_[0]};
55 sub last { shift->[-1] }
58 my ($self, $cb) = (shift, shift);
59 return $self->new(map { $_->$cb(@_) } @$self);
65 goto &List::Util::reduce;
68 sub reverse { $_[0]->new(reverse @{$_[0]}) }
70 sub shuffle { $_[0]->new(List::Util::shuffle @{$_[0]}) }
72 sub size { scalar @{$_[0]} }
76 return $self->new(@$self[@_]);
82 return $self->new(sort @$self) unless $cb;
87 local (*{"${caller}::a"}, *{"${caller}::b"}) = (\$a, \$b);
90 return $self->new(@sorted);
94 my ($self, $cb) = (shift, shift);
95 $_->$cb(@_) for $self;
99 sub to_array { [@{shift()}] }
102 my ($self, $cb) = (shift, shift);
104 return $self->new(grep { !$seen{$_->$cb(@_)}++ } @$self) if $cb;
105 return $self->new(grep { !$seen{$_}++ } @$self);
109 map { _ref($_) ? _flatten(@$_) : $_ } @_;
112 sub _ref { ref $_[0] eq 'ARRAY' || blessed $_[0] && $_[0]->isa(__PACKAGE__) }
120 DOM::Tiny::Collection - Collection
124 use DOM::Tiny::Collection;
126 # Manipulate collection
127 my $collection = DOM::Tiny::Collection->new(qw(just works));
128 unshift @$collection, 'it';
129 say $collection->join("\n");
132 $collection->map(sub { ucfirst })->shuffle->each(sub {
133 my ($word, $num) = @_;
137 # Use the alternative constructor
138 use DOM::Tiny::Collection 'c';
139 c(qw(a b c))->join('/')->url_escape->say;
143 L<DOM::Tiny::Collection> is an array-based container for collections of
144 L<DOM::Tiny> nodes based on L<Mojo::Collection>.
146 # Access array directly to manipulate collection
147 my $collection = DOM::Tiny::Collection->new(1 .. 25);
148 $collection->[23] += 100;
149 say for @$collection;
153 L<DOM::Tiny::Collection> implements the following functions, which can be imported
158 my $collection = c(1, 2, 3);
160 Construct a new array-based L<DOM::Tiny::Collection> object.
164 L<DOM::Tiny::Collection> implements the following methods.
168 my $collection = DOM::Tiny::Collection->new(1, 2, 3);
170 Construct a new array-based L<DOM::Tiny::Collection> object.
174 my $array = $collection->TO_JSON;
176 Alias for L</"to_array">.
180 my $new = $collection->compact;
182 Create a new collection with all elements that are defined and not an empty
186 DOM::Tiny::Collection->new(0, 1, undef, 2, '', 3)->compact->join(', ');
190 my @elements = $collection->each;
191 $collection = $collection->each(sub {...});
193 Evaluate callback for each element in collection or return all elements as a
194 list if none has been provided. The element will be the first argument passed
195 to the callback and is also available as C<$_>.
197 # Make a numbered list
198 $collection->each(sub {
205 my $first = $collection->first;
206 my $first = $collection->first(qr/foo/);
207 my $first = $collection->first(sub {...});
208 my $first = $collection->first($method);
209 my $first = $collection->first($method, @args);
211 Evaluate regular expression/callback for, or call method on, each element in
212 collection and return the first one that matched the regular expression, or for
213 which the callback/method returned true. The element will be the first argument
214 passed to the callback and is also available as C<$_>.
217 my $first = $collection->first(sub { $_->$method(@args) });
219 # Find first value that contains the word "dom"
220 my $interesting = $collection->first(qr/dom/i);
222 # Find first value that is greater than 5
223 my $greater = $collection->first(sub { $_ > 5 });
227 my $new = $collection->flatten;
229 Flatten nested collections/arrays recursively and create a new collection with
232 # "1, 2, 3, 4, 5, 6, 7"
233 DOM::Tiny::Collection->new(1, [2, [3, 4], 5, [6]], 7)->flatten->join(', ');
237 my $new = $collection->grep(qr/foo/);
238 my $new = $collection->grep(sub {...});
239 my $new = $collection->grep($method);
240 my $new = $collection->grep($method, @args);
242 Evaluate regular expression/callback for, or call method on, each element in
243 collection and create a new collection with all elements that matched the
244 regular expression, or for which the callback/method returned true. The element
245 will be the first argument passed to the callback and is also available as
249 my $new = $collection->grep(sub { $_->$method(@args) });
251 # Find all values that contain the word "dom"
252 my $interesting = $collection->grep(qr/dom/i);
254 # Find all values that are greater than 5
255 my $greater = $collection->grep(sub { $_ > 5 });
259 my $stream = $collection->join;
260 my $stream = $collection->join("\n");
262 Turn collection into string.
264 # Join all values with commas
265 $collection->join(', ')->say;
269 my $last = $collection->last;
271 Return the last element in collection.
275 my $new = $collection->map(sub {...});
276 my $new = $collection->map($method);
277 my $new = $collection->map($method, @args);
279 Evaluate callback for, or call method on, each element in collection and create
280 a new collection from the results. The element will be the first argument
281 passed to the callback and is also available as C<$_>.
284 my $new = $collection->map(sub { $_->$method(@args) });
286 # Append the word "dom" to all values
287 my $domified = $collection->map(sub { $_ . 'dom' });
291 my $result = $collection->reduce(sub {...});
292 my $result = $collection->reduce(sub {...}, $initial);
294 Reduce elements in collection with callback, the first element will be used as
295 initial value if none has been provided.
297 # Calculate the sum of all values
298 my $sum = $collection->reduce(sub { $a + $b });
300 # Count how often each value occurs in collection
301 my $hash = $collection->reduce(sub { $a->{$b}++; $a }, {});
305 my $new = $collection->reverse;
307 Create a new collection with all elements in reverse order.
311 my $new = $collection->slice(4 .. 7);
313 Create a new collection with all selected elements.
316 DOM::Tiny::Collection->new('A', 'B', 'C', 'D', 'E')->slice(1, 2, 4)->join(' ');
320 my $new = $collection->shuffle;
322 Create a new collection with all elements in random order.
326 my $size = $collection->size;
328 Number of elements in collection.
332 my $new = $collection->sort;
333 my $new = $collection->sort(sub {...});
335 Sort elements based on return value of callback and create a new collection
338 # Sort values case-insensitive
339 my $case_insensitive = $collection->sort(sub { uc($a) cmp uc($b) });
343 $collection = $collection->tap(sub {...});
345 Equivalent to L<Mojo::Base/"tap">.
349 my $array = $collection->to_array;
351 Turn collection into array reference.
355 my $new = $collection->uniq;
356 my $new = $collection->uniq(sub {...});
357 my $new = $collection->uniq($method);
358 my $new = $collection->uniq($method, @args);
360 Create a new collection without duplicate elements, using the string
361 representation of either the elements or the return value of the
365 my $new = $collection->uniq(sub { $_->$method(@args) });
368 DOM::Tiny::Collection->new('foo', 'bar', 'bar', 'baz')->uniq->join(' ');
371 DOM::Tiny::Collection->new([1, 2], [2, 1], [3, 2])->uniq(sub{ $_->[1] })->to_array;
375 Report any issues on the public bugtracker.
379 Dan Book <dbook@cpan.org>
381 =head1 COPYRIGHT AND LICENSE
383 This software is Copyright (c) 2015 by Dan Book.
385 This is free software, licensed under:
387 The Artistic License 2.0 (GPL Compatible)