Improved CSAF::List

lib/CSAF/List.pm

@@ -32,9 +32,8 @@ sub each {
 
 sub to_array { [@{shift->items}] }
 
-sub item   { push @{shift->items}, shift }
-sub append { shift->item(@_) }
-sub add    { shift->item(@_) }
+sub item { push @{shift->items}, shift }
+sub add  { shift->item(@_) }
 
 sub first { shift->items->[0] }
 sub last  { shift->items->[-1] }
@@ -43,3 +42,120 @@ sub join  { join($_[1], $_[0]->items) }
 sub TO_JSON { [@{shift->items}] }
 
 1;
+
+__END__
+
+=head1 NAME
+
+CSAF::List - Collection utility
+
+=head1 SYNOPSIS
+
+    use CSAF::List;
+    my $collection = CSAF::List->new( qw[foo bar baz] );
+
+
+=head1 DESCRIPTION
+
+L<CSAF::List> is a collection utility.
+
+
+=head2 METHODS
+
+=over
+
+=item TO_JSON
+
+Alias for L</"to_array">.
+
+=item add
+
+Alias for L</"item">.
+
+=item each
+
+Evaluate callback for each element in collection.
+
+    foreach my $item ($c->each) {
+        [...]
+    }
+
+    my $collection = $c->each(sub {...});
+
+=item first
+
+Get the first element of collection.
+
+=item item
+
+Add a new item in collection.
+
+    $c->item('foo');
+    $c->item(sub {...});
+
+=item items
+
+Get the list of collection items.
+
+=item join
+
+Join elements in collection.
+
+    $c->join(', ');
+
+=item last
+
+Get the last element of collection.
+
+=item new
+
+Create a new collection.
+
+    my $c = CSAF::List->new( [foo bar baz] );
+
+=item size
+
+Number of item elements.
+
+=item to_array
+
+Return the collection array.
+
+=back
+
+
+=head1 SUPPORT
+
+=head2 Bugs / Feature Requests
+
+Please report any bugs or feature requests through the issue tracker
+at L<https://github.com/giterlizzi/perl-CSAF/issues>.
+You will be notified automatically of any progress on your issue.
+
+=head2 Source Code
+
+This is open source software.  The code repository is available for
+public review and contribution under the terms of the license.
+
+L<https://github.com/giterlizzi/perl-CSAF>
+
+    git clone https://github.com/giterlizzi/perl-CSAF.git
+
+
+=head1 AUTHOR
+
+=over 4
+
+=item * Giuseppe Di Terlizzi <[email protected]>
+
+=back
+
+
+=head1 LICENSE AND COPYRIGHT
+
+This software is copyright (c) 2023-2024 by Giuseppe Di Terlizzi.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+=cut