/ 
Class-Framework-1.228
River stage zero No dependents
/ Class::MethodVars

NAME

Class::MethodVars - Implicit access to the class instance variable and fields variables for methods

DESCRIPTION

Using this module will allow you to mark subs as "ClassMethod"s and "Method"s. The former will get the current class name in whatever is indicated by the -*class options ("__CLASS__" by default), both will get the current object in whatever is indicated by the -*this options ("this" by default). The "Method"s will also get fields mapped into ${^_*} (where "*" is the field name). The object MUST be a hash reference (or something that does a good impression of one), fields should be valid symbol names (ie match /^[_a-zA-Z]\w*$/).

SYNOPSIS

use Class::MethodVars qw( field1 myotherfield );

sub new :ClassMethod {
  return bless({@_},__CLASS__);
}

sub dual_fields :Method {
  @_ = @{shift()} if @_ == 1;
  if (@_) {
    ${^_field1} = shift;
    ${^_myotherfield} = shift;
  }
  return [ this->{field1},this->{myotherfield} ];
}

FIELDS AND OPTIONS

Fields and Options are defined on the use line in the following fashion:

use Class::MethodVars @fieldlist,@optionlist;

Either @fieldlist or @optionlist may be empty (in which case the separating comma may be dropped too).

Fields can also be specified via one of the -*fields options. @fieldlist can also be expressed as an array reference (eg [@fieldlist]).

OPTIONS WITH PARAMETERS

In the options below, "hatvar" refers to a variable named "${^_*}" with "*" replace with the name of the "hatvar" variable. These are variables which are global in scope (like "$_") and excluded from "use strict" requirements (like "$_") and are explicitly listed as being safe to use in programs (see perlvar). Note that the reserved "${^_}" will never get used because an empty field name is invalid.

-this=>"name"

Set the variable/constant/hatvar name for accessing the current object.

Default is "this".

-class=>"name"

Set the variable/constant/hatvar name for accessing the current class name.

Default is "__CLASS__"

-rwfields=>@list or -rwfield=>@list or -rwfields=>[@list] or -rwfield=>[@list] -fields=>@list or -field=>@list or -fields=>[@list] or -field=>[@list]

Set the list of read+write field names for the class. Each instance of the option will be merged with previous versions. Duplicate field names will be ignored. If using Class::Framework, accessors will be generated with ->mk_accessors for these fields

Default is no fields.

-rofields=>@list or -rofield=>@list or -rofields=>[@list] or -rofield=>[@list]

Set the list of read only field names for the class. Each instance of the option will be merged with previous versions. Duplicate field names will be ignored. If using Class::Framework, accessors will be generated with ->mk_ro_accessors for these fields

Default is no fields.

-wofields=>@list or -wofield=>@list or -wofields=>[@list] or -wofield=>[@list]

Set the list of write only field names for the class. Each instance of the option will be merged with previous versions. Duplicate field names will be ignored. If using Class::Framework, accessors will be generated with ->mk_wo_accessors for these fields

Default is no fields.

-hiddenfields=>@list or -hiddenfield=>@list or -hiddenfields=>[@list] or -hiddenfield=>[@list]

Set the list of hidden field names for the class. Each instance of the option will be merged with previous versions. Duplicate field names will be ignored. No accessor methods will be created for these fields if using Class::Framework, however variables will be (subject to -varfields and -hatfields).

Default is no fields.

-fieldvarprefix=>"prefix"

Set the prefix to prepend to variables for field named. Requires -varfields. For example -fieldvarprefix=>"this_" would create "$this_myfield" for a field called "myfield".

Default is "". (no prefix).

-fieldhatprefix=>"prefix"

Set the prefix to prepend to the hatvar ("${^_*}") style variables. Requires -hatfields. Given a prefix of "f", a field "stuff" would get a variable "${^_fstuff}".

Default is "". (no prefix).

BOOLEAN OPTIONS

All the options are described below as "-option", but they can be formed as:

-option
-option=>1
-option=>"ON"
-option=>"TRUE"
  All set the option ON.

+option
-option=>0
-option=>"OFF"
-option=>"FALSE"
  All set the option OFF.
'-^args' or '-hatargs'

Form ${^_*} variables for arguments. (See ":Method()" or ":ClassMethod()" below).

Default is ON.

'-varargs'

Create variables of the appropriate name for arguments (See ":Method()" or ":ClassMethod()"). NOTE: You may have difficulty using these variables with "use strict 'vars';" as they are not automatically added into "use vars ...". Simply predeclare them with "our $..." or "use vars ..." in the package. (Or if you feel invulnerable "no strict 'vars'").

Default is OFF.

'-^fields' or '-hatfields'

Create ${^_*} variables for fields. (Replacing "*" in each case with the field name). These variables will "write-through" to the actual fields such that ${^_field} = 7; this->{field} == 7 is true. This means you should be able to use the ${^_*} form fields anywhere you would use the this->{*} form.

Default is ON.

'-varfields'

Create variables of the appropriate name for fields. These variables "write-through" as above. A field this->{myfield} would be available in $myfield. These variables will be entered into "use vars ..." for your package, and so should work under "use strict 'vars'".

Default is OFF.

'-^this' or '-hatthis'

Create a variable ${^_this} (changing "this" for whatever -this is set to) that is the current object.

Default is OFF.

'-varthis'

Create a variable like "$this" (changing "this" for whatever -this is set to) that is the current object.

Default is OFF unless -this=>"_". (See ""_" for -this and -class" below)

'-subthis'

Create a subroutine / constant called "this" (or whatever -this is set to).

Default is ON unless -this=>"_". (See ""_" for -this and -class" below)

'-^class' or '-hatclass'

Create a ${^___CLASS__} variable (note *3* leading "_"! changing "__CLASS__" (2 leading "_"!) for whatever -class is set to) that is the current class. :ClassMethod only!

Default is OFF.

'-varclass'

Create a variable like "$__CLASS__" (changing "__CLASS__" for whatever -class is set to). :ClassMethod only!

Default is OFF unless -class=>"_". (See ""_" for -this and -class" below)

'-subclass'

Create a subroutine / constant called "__CLASS__" (or whatever -class is set to).

Default is ON unless -class=>"_". (See ""_" for -this and -class" below)

'-debug'

If present, displays the wrapper subroutines as they are created. You probably don't want to do this unless you are sure that Class::MethodVars is doing something wrong.

Default is OFF.

"_" for -this and -class

If -this is set to "_", then '$_' will be used as the variable for that this, and -subthis will be disabled ("_" is a magic file handle and cannot be a subroutine). Also if the first parameter is not a member of this class, then $_ is assumed to already hold the object. This allows method calls to the same class to skip the $_-> prefix. However watch your prototypes which should not include the "$" for the object variable. Because the default settings would assign nothing for "_" they are overridden to assign to "$_" unless -hatthis is set.

The same things apply for -class=>"_". If both -this and -class are set to "_", then "$_" will be the class name in a :ClassMethod, and the object in :Method.

:Method()

This has 2 main forms:

sub mymethod :Method { ... }
and
sub mymethod :Method(this argnames) { ... }

The first form simply marks "mymethod" as a method and ensures that configured items are available.

The second form allows you to redefine the -this option and define the names of ordered arguments. The values in the parentheses are a space or comma separated list of barewords. The first word is used to redefine the -this option and may be "." (a single dot) to indicate no change from the "use" line. Subsequent words define names of positional parameters. The last parameter name may start with a "@" or "%" sigil to mop up @_. If there are no parameter names or the last one is not an array or hash name then the remainder of @_ will be untouched.

Note that if there is a conflict of name between an argument and and field, the argument will win.

:ClassMethod()

This is the same as :Method(), except that in the second form the first name changes the -class option not the -this option.

EXAMPLES

See Class::Framework for examples.

SEE ALSO

Class::Framework - Combines this module with fields and Class::Accessor, adding a default new() :ClassMethod to fill out a class.

COPYRIGHT

Copyright 2006 Timothy Hinchcliffe.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. That means either (a) the GNU General Public License or (b) the Artistic License.