/ 
Badger-0.04
River stage one • 4 direct dependents • 7 total dependents
/ Badger::Utils

NAME

Badger::Utils - various utility functions

SYNOPSIS

use Badger::Utils 'blessed params';

sub example {
    my $self   = shift;
    my $params = params(@_);
    
    if (blessed $self) {
        print "self is blessed\n";
    }
}

DESCRIPTION

This module implements a number of utility functions. It also provides access to all of the utility functions in Scalar::Util, List::Util, List::MoreUtils, Hash::Util and Digest::MD5 as a convenience.

use Badger::Utils 'blessed reftype first max any all lock_hash md5_hex';

The single line of code shown here will import blessed and reftype from Scalar::Util, first and max from List::Util, any and all from List::Util, lock_hash from Hash::Util, and md5_hex from Digest::MD5.

These modules are loaded on demand so there's no overhead incurred if you don't use them (other than a lookup table so we know where to find them).

EXPORTABLE FUNCTIONS

The following exportable function are defined in addition to those that Badger::Utils can load from Scalar::Util, List::Util, List::MoreUtils, Hash::Util and Digest::MD5.

UTILS

Exports a UTILS constant which contains the name of the Badger::Utils class.

is_object($class,$object)

Returns true if the $object is a blessed reference which isa $class.

use Badger::Filesystem 'FS';
use Badger::Utils 'is_object';

if (is_object( FS => $object )) {       # FS == Badger::Filesystem
    print $object, ' isa ', FS, "\n";
}

textlike($item)

Returns true if $item is a non-reference scalar or an object that has an overloaded stringification operator.

use Badger::Filesystem 'File';
use Badger::Utils 'textlike';

# Badger::Filesystem::File objects have overloaded string operator
my $file = File('example.txt'); 
print $file;                                # example.txt
print textlike $file ? 'ok' : 'not ok';     # ok

params(@args)

Method to coerce a list of named paramters to a hash array reference. If the first argument is a reference to a hash array then it is returned. Otherwise the arguments are folded into a hash reference.

use Badger::Utils 'params';

params({ a => 10 });            # { a => 10 }
params( a => 10 );              # { a => 10 }

self_params(@args)

Similar to params() but also expects a $self reference at the start of the argument list.

use Badger::Utils 'self_params';

sub example {
    my ($self, $params) = self_params(@_);
    # do something...
}

plural($noun)

The function makes a very naive attempt at pluralising the singular noun word passed as an argument.

If the $noun word ends in ss, sh, ch or x then es will be added to the end of it.

print plural('class');      # classes
print plural('hash');       # hashes
print plural('patch');      # patches 
print plural('box');        # boxes

If it ends in y then it will be replaced with ies.

print plural('party');      # parties

In all other cases, s will be added to the end of the word.

print plural('device');     # devices

It will fail miserably on many common words.

print plural('woman');      # womans     FAIL!
print plural('child');      # childs     FAIL!
print plural('foot');       # foots      FAIL!

This function should only be used in cases where the singular noun is known in advance and has a regular form that can be pluralised correctly by the algorithm described above. For example, the Badger::Factory module allows you to specify $ITEM and $ITEMS package variable to provide the singular and plural names of the items that the factory manages.

our $ITEM  = 'person';
our $ITEMS = 'people';

If the singular noun is sufficiently regular then the $ITEMS can be omitted and the plural function will be used.

our $ITEM  = 'codec';       # $ITEMS defaults to 'codecs'

In this case we know that codec will pluralise correctly to codecs and can safely leave $ITEMS undefined.

For more robust pluralisation of English words, you should use the Lingua::EN::Inflect module by Damian Conway. For further information on the difficulties of correctly pluralising English, and details of the implementation of Lingua::EN::Inflect, see Damian's paper "An Algorithmic Approach to English Pluralization" at http://www.csse.monash.edu.au/~damian/papers/HTML/Plurals.html

module_file($name)

Returns the module name passed as an argument as a relative filesystem path suitable for feeding into require()

print module_file('My::Module');     # My/Module.pm

xprintf($format,@args)

A wrapper around sprintf() which provides some syntactic sugar for embedding positional parameters.

xprintf('The <2> sat on the <1>', 'mat', 'cat');
xprintf('The <1> costs <2:%.2f>', 'widget', 11.99);

AUTHOR

Andy Wardley http://wardley.org/

COPYRIGHT

Copyright (C) 1996-2008 Andy Wardley. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.