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.