1 package DOM::Tiny::Collection;
8 use Scalar::Util 'blessed';
10 our $VERSION = '0.001';
12 our @EXPORT_OK = ('c');
14 sub TO_JSON { [@{shift()}] }
16 sub c { __PACKAGE__->new(@_) }
20 return $self->new(grep { defined && (ref || length) } @$self);
25 return @$self unless $cb;
27 $_->$cb($i++) for @$self;
32 my ($self, $cb) = (shift, shift);
33 return $self->[0] unless $cb;
34 return List::Util::first { $_ =~ $cb } @$self if ref $cb eq 'Regexp';
35 return List::Util::first { $_->$cb(@_) } @$self;
38 sub flatten { $_[0]->new(_flatten(@{$_[0]})) }
41 my ($self, $cb) = (shift, shift);
42 return $self->new(grep { $_ =~ $cb } @$self) if ref $cb eq 'Regexp';
43 return $self->new(grep { $_->$cb(@_) } @$self);
47 join +(defined $_[1] ? $_[1] : ''), map {"$_"} @{$_[0]};
50 sub last { shift->[-1] }
53 my ($self, $cb) = (shift, shift);
54 return $self->new(map { $_->$cb(@_) } @$self);
59 return bless [@_], ref $class || $class;
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 Mojo::Collection;
126 # Manipulate collection
127 my $collection = Mojo::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 Mojo::Collection 'c';
139 c(qw(a b c))->join('/')->url_escape->say;
143 L<Mojo::Collection> is an array-based container for collections.
145 # Access array directly to manipulate collection
146 my $collection = Mojo::Collection->new(1 .. 25);
147 $collection->[23] += 100;
148 say for @$collection;
152 L<Mojo::Collection> implements the following functions, which can be imported
157 my $collection = c(1, 2, 3);
159 Construct a new array-based L<Mojo::Collection> object.
163 L<Mojo::Collection> implements the following methods.
167 my $array = $collection->TO_JSON;
169 Alias for L</"to_array">.
173 my $new = $collection->compact;
175 Create a new collection with all elements that are defined and not an empty
179 Mojo::Collection->new(0, 1, undef, 2, '', 3)->compact->join(', ');
183 my @elements = $collection->each;
184 $collection = $collection->each(sub {...});
186 Evaluate callback for each element in collection or return all elements as a
187 list if none has been provided. The element will be the first argument passed
188 to the callback and is also available as C<$_>.
190 # Make a numbered list
191 $collection->each(sub {
198 my $first = $collection->first;
199 my $first = $collection->first(qr/foo/);
200 my $first = $collection->first(sub {...});
201 my $first = $collection->first($method);
202 my $first = $collection->first($method, @args);
204 Evaluate regular expression/callback for, or call method on, each element in
205 collection and return the first one that matched the regular expression, or for
206 which the callback/method returned true. The element will be the first argument
207 passed to the callback and is also available as C<$_>.
210 my $first = $collection->first(sub { $_->$method(@args) });
212 # Find first value that contains the word "mojo"
213 my $interesting = $collection->first(qr/mojo/i);
215 # Find first value that is greater than 5
216 my $greater = $collection->first(sub { $_ > 5 });
220 my $new = $collection->flatten;
222 Flatten nested collections/arrays recursively and create a new collection with
225 # "1, 2, 3, 4, 5, 6, 7"
226 Mojo::Collection->new(1, [2, [3, 4], 5, [6]], 7)->flatten->join(', ');
230 my $new = $collection->grep(qr/foo/);
231 my $new = $collection->grep(sub {...});
232 my $new = $collection->grep($method);
233 my $new = $collection->grep($method, @args);
235 Evaluate regular expression/callback for, or call method on, each element in
236 collection and create a new collection with all elements that matched the
237 regular expression, or for which the callback/method returned true. The element
238 will be the first argument passed to the callback and is also available as
242 my $new = $collection->grep(sub { $_->$method(@args) });
244 # Find all values that contain the word "mojo"
245 my $interesting = $collection->grep(qr/mojo/i);
247 # Find all values that are greater than 5
248 my $greater = $collection->grep(sub { $_ > 5 });
252 my $stream = $collection->join;
253 my $stream = $collection->join("\n");
255 Turn collection into string.
257 # Join all values with commas
258 $collection->join(', ')->say;
262 my $last = $collection->last;
264 Return the last element in collection.
268 my $new = $collection->map(sub {...});
269 my $new = $collection->map($method);
270 my $new = $collection->map($method, @args);
272 Evaluate callback for, or call method on, each element in collection and create
273 a new collection from the results. The element will be the first argument
274 passed to the callback and is also available as C<$_>.
277 my $new = $collection->map(sub { $_->$method(@args) });
279 # Append the word "mojo" to all values
280 my $mojoified = $collection->map(sub { $_ . 'mojo' });
284 my $collection = Mojo::Collection->new(1, 2, 3);
286 Construct a new array-based L<Mojo::Collection> object.
290 my $result = $collection->reduce(sub {...});
291 my $result = $collection->reduce(sub {...}, $initial);
293 Reduce elements in collection with callback, the first element will be used as
294 initial value if none has been provided.
296 # Calculate the sum of all values
297 my $sum = $collection->reduce(sub { $a + $b });
299 # Count how often each value occurs in collection
300 my $hash = $collection->reduce(sub { $a->{$b}++; $a }, {});
304 my $new = $collection->reverse;
306 Create a new collection with all elements in reverse order.
310 my $new = $collection->slice(4 .. 7);
312 Create a new collection with all selected elements.
315 Mojo::Collection->new('A', 'B', 'C', 'D', 'E')->slice(1, 2, 4)->join(' ');
319 my $new = $collection->shuffle;
321 Create a new collection with all elements in random order.
325 my $size = $collection->size;
327 Number of elements in collection.
331 my $new = $collection->sort;
332 my $new = $collection->sort(sub {...});
334 Sort elements based on return value of callback and create a new collection
337 # Sort values case-insensitive
338 my $case_insensitive = $collection->sort(sub { uc($a) cmp uc($b) });
342 $collection = $collection->tap(sub {...});
344 Alias for L<Mojo::Base/"tap">.
348 my $array = $collection->to_array;
350 Turn collection into array reference.
354 my $new = $collection->uniq;
355 my $new = $collection->uniq(sub {...});
356 my $new = $collection->uniq($method);
357 my $new = $collection->uniq($method, @args);
359 Create a new collection without duplicate elements, using the string
360 representation of either the elements or the return value of the
364 my $new = $collection->uniq(sub { $_->$method(@args) });
367 Mojo::Collection->new('foo', 'bar', 'bar', 'baz')->uniq->join(' ');
370 Mojo::Collection->new([1, 2], [2, 1], [3, 2])->uniq(sub{ $_->[1] })->to_array;
374 Report any issues on the public bugtracker.
378 Dan Book <dbook@cpan.org>
380 =head1 COPYRIGHT AND LICENSE
382 This software is Copyright (c) 2015 by Dan Book.
384 This is free software, licensed under:
386 The Artistic License 2.0 (GPL Compatible)