NAME

Badger::Class::Vars - class module for defining package variables

SYNOPSIS

    package My::Module;
    
    # simple pre-declaration of variables
    use Badger::Class::Vars '$FOO @BAR %BAZ';
    
    # pre-declaration with values
    use Badger::Class::Vars 
        '$FOO' => 10,
        '@BAR' => [20, 30, 40],
        '%BAZ' => { x => 100, y => 200 };
    
    # via Badger::Class
    use Badger::Class
        vars => '$FOO @BAR %BAZ';
    
    # via Badger::Class with values
    use Badger::Class
        vars => { 
            '$FOO' => 10,
            '@BAR' => [20, 30, 40],
            '%BAZ' => { x => 100, y => 200 },
        };

DESCRIPTION

This module allows you to pre-declare and optionally, define values for package variables. It can be used directly, or via the vars export hook in Badger::Class.

    # using the module directly
    use Badger::Class::Vars 
        '$FOO @BAR %BAZ';

    # using it via Badger::Class
    use Badger::Class
        vars => '$FOO @BAR %BAZ';   

In the simple case, it works just like the vars.pm module in pre-declaring the variables named.

Unlike vars.pm, this method will only define scalar, list and hash package variables (e.g. $SOMETHING, @SOMETHING or %SOMETHING).

If you want to define subroutines/methods then you can use the Badger::Class::Methods module, or the methods import hook or methods() method in Badger::Class. If you want to define a glob reference then you're already operating in Wizard Mode and you don't need our help.

If you don't specify a leading sigil (i.e. $, @ or %) then it will default to $ and create a scalar variable.

    use Badger::Class
        vars => 'FOO BAR BAZ';      # declares $FOO, $BAR and $BAZ

You can also use a reference to a hash array to define values for variables.

    use Badger::Class
        vars => {                           # Equivalent code:
            '$FOO' => 42,                   #   our $FOO = 25
            '@WIZ' => [100, 200, 300],      #   our @WIZ = (100, 200, 300)
            '%WOZ' => {ping => 'pong'},     #   our %QOZ = (ping => 'pong')
        };

Scalar package variables can be assigned any scalar value or a reference to some other data type. Again, the leading $ is optional on the variable names. Note the difference in the equivalent code - this time we end up with scalar variables and references exclusively.

    use Badger::Class
        vars => {                           # Equivalent code:
            FOO => 42,                      #   our $FOO = 42
            BAR => [100, 200, 300],         #   our $BAR = [100, 200, 300]
            BAZ => {ping => 'pong'},        #   our $BAZ = {ping => 'pong'}
            HAI => sub {                    #   our $HAI = sub { ... }
                'Hello ' . (shift || 'World') 
            },
        };

You can also assign any kind of data to a package list variable. If it's not already a list reference then the value will be treated as a single item list.

    use Badger::Class
        vars => {                           # Equivalent code:
            '@FOO' => 42,                   #   our @FOO = (42)
        };

METHODS

vars($target,$vars)

This method defines variable in the $target package. It is usually called automatically when the module is loaded via use.

The $vars can be specified as a single text string of whitespace delimited symbols or by reference to a list of individual symbols. The variables will be declared but undefined.

    # single string
    Badger::Class::Vars->vars(
        'My::Package',
        '$FOO, @BAR, %BAZ'
    );

    # list reference
    Badger::Class::Vars->vars(
        'My::Package',
        ['$FOO', '@BAR', '%BAZ']
    );

Use a reference to a hash array if you want to provide values for the variables.

    # hash reference
    Badger::Class::Vars->vars(
        'My::Package',
        {
            '$FOO'  => 10,
            '@BAR' => [20, 30, 40],
            '%BAZ' => { x => 100, y => 200 },
        }
    );

AUTHOR

Andy Wardley http://wardley.org/

COPYRIGHT

Copyright (C) 2008-2009 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.