Index
NAME 
Newcomen::Util::Traits - Moose related utility functions.
SYNOPSIS
package MyPackage;
use namespace::autoclean;
use Moose;
use Newcomen::Util::Traits;
has 'array' => (
'is' => 'ro',
'isa' => 'ArrayRef',
'default' => sub {[]},
'traits' => ['Array'],
'handles' => Newcomen::Util::Traits::std_array_handles (),
);
has 'hash' => (
'is' => 'ro',
'isa' => 'HashRef',
'default' => sub {{}},
'traits' => ['Hash'],
'handles' => Newcomen::Util::Traits::std_hash_handles (),
);
__PACKAGE__ -> meta () -> make_immutable ();
1;Using that package:
use MyPackage;
my $instance = MyPackage -> new ();
# Add a value to the array attribute:
$instance -> push ($value);
# Add an entry to the hash attribute:
$instance -> set ('key', $value);DESCRIPTION
This package provides utility functions for Moose classes. It is not a Moose class itself. Note that all functions may be imported into the package using Newcomen::Util::Traits:
use Newcomen::Util::Traits qw( std_array_handles std_hash_handles );
No function is exported by default.
If you followed a link from another module's documentation to this page and are looking for the array and/or hash methods, see INSTANCE METHODS below. In that case you may ignore the section FUNCTIONS. Keep in mind that these instance methods are directly available as instance methods of the class that led you here (any exceptions are mentioned in the class' documentation).
FUNCTIONS
std_array_handles, std_hash_handles
Toggle sources: std_array_handles std_hash_handles
sub std_array_handles {{
'clear' => 'clear',
'count' => 'count',
'empty' => 'is_empty',
'find' => 'first',
'first' => 'first_index',
'grep' => 'grep',
'insert' => 'insert',
'item' => 'get',
'items' => 'elements',
'map' => 'map',
'ordered' => 'sort',
'paginate' => 'natatime',
'push' => 'push',
'remove' => 'delete',
'sort' => 'sort_in_place',
'splice' => 'splice',
'unshift' => 'unshift',
}}sub std_hash_handles {{
'defined' => 'defined',
'delete' => 'delete',
'elements' => 'kv',
'exists' => 'exists',
'get' => 'get',
'keys' => 'keys',
'set' => 'set',
'total' => 'count',
'values' => 'values',
'void' => 'is_empty',
'wipe' => 'clear',
}}has 'array' => (
'is' => 'ro',
'isa' => 'ArrayRef',
'default' => sub {[]},
'traits' => ['Array'],
'handles' => std_array_handles (),
);
has 'hash' => (
'is' => 'ro',
'isa' => 'HashRef',
'default' => sub {{}},
'traits' => ['Hash'],
'handles' => std_hash_handles (),
);The two functions std_array_handles() and std_hash_handles() may be used to add a default set of handles to a Moose attribute (either an arrayref attribute or a hashref attribute, respectively). Both functions return a hashref containing the mapping of method names to Moose's native traits (see Moose::Meta::Attribute::Native::Trait::Array for array traits and Moose::Meta::Attribute::Native::Trait::Hash for hash traits). The handles are named in a way that allows a class to include one arrayref attribute using the array handles and one hashref attribute using the hash handles at the same time without clashing method names. See below for the list of methods that will be available to the classes.
INSTANCE METHODS
The following methods will be available in the classes using one of Newcomen::Util::Traits' functions, i.e. these are not Newcomen::Util::Traits' methods!
Array Methods
clear
$instance -> clear ();
Handle for the clear() native trait.
Removes all elements from the array. This method does not accept any parameters, the return value is not defined.
count
my $number = $instance -> count ();
Handle for the count() native trait.
Returns the number of elements in the array. This method does not accept any parameters.
empty
if ($instance -> empty ()) {
# do something...
}Handle for the is_empty() native trait.
Returns a true value if the array does not contain any elements, a false value if there is at least one element. This method does not accept any parameters.
find
my $element = $instance -> find (sub { ... });Handle for the first() native trait.
Returns the first matching element of the array. The parameter has to be a subroutine reference. It
will be called against each array element until one matches or all elements have been checked. If no
matching element can be found, the method will return undef.
first
my $index = $instance -> first (sub { ... });Handle for the first_index() native trait.
Like find() (see above), but instead of returning the matching element itself this method
returns the matching element's index in the array, or -1 if there is no match.
grep
my @matching = $instance -> grep (sub { ... });Handle for the grep() native trait.
Like Perl's grep() function, this method returns a list of all matching elements of the array. The parameter has to be a subroutine reference that will be called against each array element.
insert
$instance -> insert ($index, $value);
Handle for the insert() native trait.
Inserts a new element (second parameter) at the specified index (first parameter) into the array. Returns the new value at the specified index.
item
my $item = $instance -> item ($index);
Handle for the get() native trait.
Returns the element of the array at the specified index (the only parameter). A negative index may
be used, like in Perl's array handling. If the specified element does not exist, the method will
return undef.
items
my @items = $instance -> items ();
Handle for the elements() native trait.
Returns all the items in the array as a list. This method does not accept any parameters.
map
my @stuff = $instance -> map (sub { ... });Handle for the map() native trait.
Like Perl's map() function, this method applies the subroutine (the only parameter) to every element of the array and returns the new array.
ordered
my @ordered = $instance -> ordered (sub { ... });Handle for the sort() native trait.
Returns the elements of the array in sorted order. As an optional parameter a subroutine may be
specified to decide about item order (like Perl's sort() function). Unlike Perl's sort()
function, the two elements to be compared will be available as $_[0] and $_[1] inside the
subroutine. If no subroutine is specified, sorting defaults to ASCII order.
paginate
my $iterator = $instance -> paginate (5);
while (my @values = $iterator -> ()) {
# do something...
}Handle for the natatime() native trait.
Returns an array iterator, which itself returns a number of items (specified by the first parameter of the paginate() call) at each call. I.e. in the example above the first iteration will handle the first five array items, the second iteration the next five and so on until no more items are left. This works like natatime() from List::MoreUtils. As an optional second parameter, a coderef may be specified. It will be called for each group of items in the array, like described before.
push
my $size = $instance -> push ($value1, $value2);
Handle for the push() native trait.
Adds the new value or values at the end of the array. An arbitrary number of parameters may be specified (at least one). The method returns the number of elements in the array after the operation.
remove
my $value = $instance -> remove ($index);
Handle for the delete() native trait.
This method deletes the element at the specified index (the only parameter) from the array and
returns the deleted value. If there is no element at the specified index, it will return undef.
sort
$instance -> sort (sub { ... });Handle for the sort_in_place() native trait.
Works like the ordered() method (see above), but instead of returning the sorted array the array itself will be modified. This method accepts the same parameters as ordered(), but does not define a return value.
splice
my @removed = $instance -> splice ($index, $length, @values);
Handle for the splice() native trait.
This method works like Perl's splice() function. It will return the last element removed in
scalar context (undef if nothing was removed), or all elements removed in list context. At least
one parameter has to be specified.
unshift
my $size = $instance -> unshift ($value1, $value2);
Handle for the unshift() native trait.
Adds the new value or values at the beginning of the array. An arbitrary number of parameters may be specified. The method returns the number of elements in the array after the operation.
Hash Methods
defined
if ($instance -> defined ($key)) {
# do something...
}Handle for the defined() native trait.
Returns a true value if the value for the specified key (the only parameter) is defined, else a false value.
delete
my @deleted = $instance -> delete ($key1, $key2);
Handle for the delete() native trait.
Deletes the elements with the specified keys from the hash. In list context this method returns the list of values (not the keys!) that have been deleted. In scalar context it returns just the last value deleted. At least one key has to be specified as parameter, specifying more than one key is allowed.
elements
for ($instance -> elements ()) {
my $key = $_ -> [0];
my $value = $_ -> [1];
}Handle for the kv() native trait.
Returns a list of all key/value pairs in the hash. Every element of the returned list is itself an arrayref, with the first element in this arrayref being the key, the second element being the value. This method does not expect any parameters.
exists
if ($instance -> exists ($key)) {
# do something...
}Handle for the exists() native trait.
Returns a true value if the specified key (the only parameter) exists in the hash, else a false value.
get
my @values = $instance -> get ($key1, $key2);
Handle for the get() native trait.
At least one key has to be supplied as parameter. In list context, the method returns a list of all
values for the specified keys. In scalar context, only the value for the last key will be returned.
If a key does not exist, the value for that key will be undef.
keys
my @keys = $instance -> keys ();
Handle for the keys() native trait.
Returns a list containing all keys of the hash (the order is not defined). This method does not expect any parameters.
set
my @values = $instance -> set ($key1 => $value1, $key2 => $value2);
Handle for the set() native trait.
This method sets the specified values for the specified keys. At least one key/value pair has to be supplied, and the number of parameters must be even. The return value is a list of all values set, in the order they were specified.
total
my $number = $instance -> total ();
Handle for the count() native trait.
Returns the number of values in the hash. This method does not expect any parameters.
values
my @values = $instance -> values ();
Handle for the values() native trait.
Returns a list containing all values of the hash (the order is not defined). This method does not expect any parameters.
void
if ($instance -> void ()) {
# do something...
}Handle for the is_empty() native trait.
Returns a true value if there is no element in the hash, else a false value. This method does not expect any parameters.
wipe
$instance -> wipe ();
Handle for the clear() native trait.
Removes all content from the hash. This method does not expect any parameters, and does not define a return value.
SEE ALSO
List::Util, List::MoreUtils, Moose, Moose::Meta::Attribute::Native::Trait::Array, Moose::Meta::Attribute::Native::Trait::Hash
VERSION
This is version 2014052501.
AUTHOR
Stefan Goebel - newcomen {at} subtype {dot} de
COPYRIGHT AND LICENSE
Copyright 2013-2014 Stefan Goebel.
This file is part of Newcomen.
Newcomen is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the license, or (at your option) any later version.
Newcomen is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with Newcomen. If not, see <http://www.gnu.org/licenses/>.