GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  ROSE::CLASS::MAKEMETHODS::GENERIC (3)

.ds Aq ’

NAME

Rose::Class::MakeMethods::Generic - Create simple class methods.

CONTENTS

SYNOPSIS



  package MyClass;

  use Rose::Class::MakeMethods::Generic
  (
    scalar =>
    [
      error,
      type => { interface => get_set_init },
    ],

    inheritable_scalar => name,
  );

  sub init_type { special }
  ...

  package MySubClass;
  our @ISA = qw(MyClass);
  ...

  MyClass->error(123);

  print MyClass->type; # special

  MyClass->name(Fred);
  print MySubClass->name; # Fred

  MyClass->name(Wilma);
  print MySubClass->name; # Wilma

  MySubClass->name(Bam);
  print MyClass->name;    # Wilma
  print MySubClass->name; # Bam



DESCRIPTION

Rose::Class::MakeMethods::Generic is a method maker that inherits from Rose::Object::MakeMethods. See the Rose::Object::MakeMethods documentation to learn about the interface. The method types provided by this module are described below. All methods work only with classes, not objects.

METHODS TYPES

<B>scalarB> Create get/set methods for scalar class attributes.
Options
init_method The name of the class method to call when initializing the value of an undefined attribute. This option is only applicable when using the get_set_init interface. Defaults to the method name with the prefix init_ added.
interface Choose one of the two possible interfaces. Defaults to get_set.
Interfaces
get_set Creates a simple get/set accessor method for a class attribute. When called with an argument, the value of the attribute is set. The current value of the attribute is returned.
get_set_init Behaves like the get_set interface unless the value of the attribute is undefined. In that case, the class method specified by the init_method option is called and the attribute is set to the return value of that method.

Example:



    package MyClass;

    use Rose::Class::MakeMethods::Generic
    (
      scalar => power,
      scalar --get_set_init => name,
    );

    sub init_name { Fred }
    ...

    MyClass->power(99);    # returns 99
    MyClass->name;         # returns "Fred"
    MyClass->name(Bill); # returns "Bill"



<B>inheritable_booleanB> Create get/set methods for boolean class attributes that are inherited by subclasses until/unless their values are changed.
Options
interface Choose the interface. This is kind of pointless since there is only one interface right now. Defaults to get_set, obviously.
Interfaces
get_set Creates a get/set accessor method for a class attribute. When called with an argument, the value of the attribute is set to 1 if that argument is true or 0 if it is false. The value of the attribute is then returned.

If called with no arguments, and if the attribute was never set for this class, then a left-most, breadth-first search of the parent classes is initiated. The value returned is taken from first parent class encountered that has ever had this attribute set.

Example:



    package MyClass;

    use Rose::Class::MakeMethods::Generic
    (
      inheritable_boolean => enabled,
    );
    ...

    package MySubClass;
    our @ISA = qw(MyClass);
    ...

    package MySubSubClass;
    our @ISA = qw(MySubClass);
    ...

    $x = MyClass->enabled;       # undef
    $y = MySubClass->enabled;    # undef
    $z = MySubSubClass->enabled; # undef

    MyClass->enabled(1);
    $x = MyClass->enabled;       # 1
    $y = MySubClass->enabled;    # 1
    $z = MySubSubClass->enabled; # 1

    MyClass->enabled(0);
    $x = MyClass->enabled;       # 0
    $y = MySubClass->enabled;    # 0
    $z = MySubSubClass->enabled; # 0

    MySubClass->enabled(1);
    $x = MyClass->enabled;       # 0
    $y = MySubClass->enabled;    # 1
    $z = MySubSubClass->enabled; # 1

    MyClass->enabled(1);
    MySubClass->enabled(undef);
    $x = MyClass->enabled;       # 1
    $y = MySubClass->enabled;    # 0
    $z = MySubSubClass->enabled; # 0

    MySubSubClass->enabled(1);
    $x = MyClass->enabled;       # 1
    $y = MySubClass->enabled;    # 0
    $z = MySubSubClass->enabled; # 0



<B>inheritable_scalarB> Create get/set methods for scalar class attributes that are inherited by subclasses until/unless their values are changed.
Options
interface Choose the interface. This is kind of pointless since there is only one interface right now. Defaults to get_set, obviously.
Interfaces
get_set Creates a get/set accessor method for a class attribute. When called with an argument, the value of the attribute is set and then returned.

If called with no arguments, and if the attribute was never set for this class, then a left-most, breadth-first search of the parent classes is initiated. The value returned is taken from first parent class encountered that has ever had this attribute set.

Example:



    package MyClass;

    use Rose::Class::MakeMethods::Generic
    (
      inheritable_scalar => name,
    );
    ...

    package MySubClass;
    our @ISA = qw(MyClass);
    ...

    package MySubSubClass;
    our @ISA = qw(MySubClass);
    ...

    $x = MyClass->name;       # undef
    $y = MySubClass->name;    # undef
    $z = MySubSubClass->name; # undef

    MyClass->name(Fred);
    $x = MyClass->name;       # Fred
    $y = MySubClass->name;    # Fred
    $z = MySubSubClass->name; # Fred

    MyClass->name(Wilma);
    $x = MyClass->name;       # Wilma
    $y = MySubClass->name;    # Wilma
    $z = MySubSubClass->name; # Wilma

    MySubClass->name(Bam);
    $x = MyClass->name;       # Wilma
    $y = MySubClass->name;    # Bam
    $z = MySubSubClass->name; # Bam

    MyClass->name(Koop);
    MySubClass->name(undef);
    $x = MyClass->name;       # Koop
    $y = MySubClass->name;    # undef
    $z = MySubSubClass->name; # undef

    MySubSubClass->name(Sam);
    $x = MyClass->name;       # Koop
    $y = MySubClass->name;    # undef
    $z = MySubSubClass->name; # Sam



<B>hashB> Create methods to manipulate a hash of class attributes.
Options
hash_key The key to use for the storage of this attribute. Defaults to the name of the method.
interface Choose which interface to use. Defaults to get_set.
Interfaces
get_set If called with no arguments, returns a list of key/value pairs in list context or a reference to the actual hash used to store values in scalar context.

If called with one argument, and that argument is a reference to a hash, that hash reference is used as the new value for the attribute. Returns a list of key/value pairs in list context or a reference to the actual hash used to store values in scalar context.

If called with one argument, and that argument is a reference to an array, then a list of the hash values for each key in the array is returned.

If called with one argument, and it is not a reference to a hash or an array, then the hash value for that key is returned.

If called with an even number of arguments, they are taken as name/value pairs and are added to the hash. It then returns a list of key/value pairs in list context or a reference to the actual hash used to store values in scalar context.

Passing an odd number of arguments greater than 1 causes a fatal error.

get_set_all If called with no arguments, returns a list of key/value pairs in list context or a reference to the actual hash used to store values in scalar context.

If called with one argument, and that argument is a reference to a hash, that hash reference is used as the new value for the attribute. Returns a list of key/value pairs in list context or a reference to the actual hash used to store values in scalar context.

Otherwise, the hash is emptied and the arguments are taken as name/value pairs that are then added to the hash. It then returns a list of key/value pairs in list context or a reference to the actual hash used to store values in scalar context.

clear Sets the attribute to an empty hash.
reset Sets the attribute to undef.
delete Deletes the key(s) passed as arguments. Failure to pass any arguments causes a fatal error.
exists Returns true of the argument exists in the hash, false otherwise. Failure to pass an argument or passing more than one argument causes a fatal error.
keys Returns the keys of the hash in list context, or a reference to an array of the keys of the hash in scalar context. The keys are not sorted.
names An alias for the keys interface.
values Returns the values of the hash in list context, or a reference to an array of the values of the hash in scalar context. The values are not sorted.

Example:



    package MyClass;

    use Rose::Class::MakeMethods::Generic
    (
      hash =>
      [
        param        => { hash_key =>params },
        params       => { interface=>get_set_all },
        param_names  => { interface=>keys,   hash_key=>params },
        param_values => { interface=>values, hash_key=>params },
        param_exists => { interface=>exists, hash_key=>params },
        delete_param => { interface=>delete, hash_key=>params },

        clear_params => { interface=>clear, hash_key=>params },
        reset_params => { interface=>reset, hash_key=>params },
      ],
    );
    ...

    MyClass->params; # undef

    MyClass->params(a => 1, b => 2); # add pairs
    $val = MyClass->param(b); # 2

    %params = MyClass->params; # copy hash keys and values
    $params = MyClass->params; # get hash ref

    MyClass->params({ c => 3, d => 4 }); # replace contents

    MyClass->param_exists(a); # false

    $keys = join(,, sort MyClass->param_names);  # c,d
    $vals = join(,, sort MyClass->param_values); # 3,4

    MyClass->delete_param(c);
    MyClass->param(f => 7, g => 8);

    $vals = join(,, sort MyClass->param_values); # 4,7,8

    MyClass->clear_params;
    $params = MyClass->params; # empty hash

    MyClass->reset_params;
    $params = MyClass->params; # undef



<B>inheritable_hashB> Create methods to manipulate a hash of class attributes that can be inherited by subclasses.

The hash of attributes is inherited by subclasses using a one-time copy. Any subclass that accesses or manipulates the hash in any way will immediately get its own private copy of the hash as it exists in the superclass at the time of the access or manipulation.

The superclass from which the hash is copied is the closest (least super) class that has ever accessed or manipulated this hash. The copy is a shallow copy, duplicating only the keys and values. Reference values are not recursively copied.

Setting to hash to undef (using the ’reset’ interface) will cause it to be re-copied from a superclass the next time it is accessed.
Options
hash_key The key to use for the storage of this attribute. Defaults to the name of the method.
interface Choose which interface to use. Defaults to get_set.
Interfaces
get_set If called with no arguments, returns a list of key/value pairs in list context or a reference to the actual hash used to store values in scalar context.

If called with one argument, and that argument is a reference to a hash, that hash reference is used as the new value for the attribute. Returns a list of key/value pairs in list context or a reference to the actual hash used to store values in scalar context.

If called with one argument, and that argument is a reference to an array, then a list of the hash values for each key in the array is returned.

If called with one argument, and it is not a reference to a hash or an array, then the hash value for that key is returned.

If called with an even number of arguments, they are taken as name/value pairs and are added to the hash. It then returns a list of key/value pairs in list context or a reference to the actual hash used to store values in scalar context.

Passing an odd number of arguments greater than 1 causes a fatal error.

get_set_all If called with no arguments, returns a list of key/value pairs in list context or a reference to the actual hash used to store values in scalar context.

If called with one argument, and that argument is a reference to a hash, that hash reference is used as the new value for the attribute. Returns a list of key/value pairs in list context or a reference to the actual hash used to store values in scalar context.

Otherwise, the hash is emptied and the arguments are taken as name/value pairs that are then added to the hash. It then returns a list of key/value pairs in list context or a reference to the actual hash used to store values in scalar context.

clear Sets the attribute to an empty hash.
reset Sets the attribute to undef.
delete Deletes the key(s) passed as arguments. Failure to pass any arguments causes a fatal error.
exists Returns true of the argument exists in the hash, false otherwise. Failure to pass an argument or passing more than one argument causes a fatal error.
keys Returns the keys of the hash in list context, or a reference to an array of the keys of the hash in scalar context. The keys are not sorted.
names An alias for the keys interface.
values Returns the values of the hash in list context, or a reference to an array of the values of the hash in scalar context. The values are not sorted.

Example:



    package MyClass;

    use Rose::Class::MakeMethods::Generic
    (
      inheritable_hash =>
      [
        param        => { hash_key =>params },
        params       => { interface=>get_set_all },
        param_names  => { interface=>keys,   hash_key=>params },
        param_values => { interface=>values, hash_key=>params },
        param_exists => { interface=>exists, hash_key=>params },
        delete_param => { interface=>delete, hash_key=>params },

        clear_params => { interface=>clear, hash_key=>params },
        reset_params => { interface=>reset, hash_key=>params },
      ],
    );
    ...

    package MySubClass;
    our @ISA = qw(MyClass);
    ...

    MyClass->params; # undef

    MyClass->params(a => 1, b => 2); # add pairs
    $val = MyClass->param(b); # 2

    %params = MyClass->params; # copy hash keys and values
    $params = MyClass->params; # get hash ref

    # Inherit a copy of params from MyClass
    $params = MySubClass->params; # { a => 1, b => 2 }

    MyClass->params({ c => 3, d => 4 }); # replace contents

    # MySubClass params are still as the existed at the time
    # they were originally copied from MyClass
    $params = MySubClass->params; # { a => 1, b => 2 }

    # MySubClass can manipulate its own params as it wishes
    MySubClass->param(z => 9);

    $params = MySubClass->params; # { a => 1, b => 2, z => 9 }

    MyClass->param_exists(a); # false

    $keys = join(,, sort MyClass->param_names);  # c,d
    $vals = join(,, sort MyClass->param_values); # 3,4

    # Reset params (set to undef) so that they will be re-copied
    # from MyClass the next time theyre accessed
    MySubClass->reset_params;

    MyClass->delete_param(c);
    MyClass->param(f => 7, g => 8);

    $vals = join(,, sort MyClass->param_values); # 4,7,8

    # Inherit a copy of params from MyClass
    $params = MySubClass->params; # { d => 4, f => 7, g => 8 }



<B>inherited_hashB> Create a family of class methods for managing an inherited hash.

An inherited hash is made up of the union of the hashes of all superclasses, minus any keys that are explicitly deleted in the current class.
Options
add_implies A method name, or reference to a list of method names, to call when a key is added to the hash. Each added name/value pair is passed to each method in the add_implies list, one pair at a time.
add_method The name of the class method used to add a single name/value pair to the hash. Defaults to the method name with the prefix add_ added.
adds_method The name of the class method used to add one or more name/value pairs to the hash. Defaults to plural_name with the prefix add_ added.
cache_method The name of the class method used to retrieve (or generate, if it doesn’t exist) the internal cache for the hash. This should be considered a private method, but it is listed here because it does take up a spot in the method namespace. Defaults to plural_name with _cache added to the end.
clear_method The name of the class method used to clear the contents of the hash. Defaults to plural_name with a clear_ prefix added.
delete_implies A method name, or reference to a list of method names, to call when a key is removed from the hash. Each deleted key is passed as an argument to each method in the delete_implies list, one key per call.
delete_method The name of the class method used to remove a single key from the hash. Defaults to the method name with the prefix delete_ added.
deletes_method The name of the class method used to remove one or more keys from the hash. Defaults to plural_name with a delete_ prefix added.
exists_method The name of the class method that tests for the existence of a key in the hash. Defaults to the method name with the suffix _exists added.
get_set_all_method The name of the class method use to set or fetch the entire hash. The hash may be passed as a reference to a hash or as a list of name/value pairs. Returns the hash (in list context) or a reference to a hash (in scalar context). Defaults to plural_name.
hash_method This is an alias for the get_set_all_method parameter.
inherit_method The name of the class method used to indicate that an inherited key that was previously deleted from the hash should return to being inherited. Defaults to the method name with the prefix inherit_ added.
inherits_method The name of the class method used to indicate that one or more inherited keys that were previously deleted from the hash should return to being inherited. Defaults to the plural_name with the prefix inherit_ added.
interface Choose the interface. This is kind of pointless since there is only one interface right now. Defaults to all, obviously.
keys_method The name of the class method that returns a reference to a list of keys in scalar context, or a list of keys in list context. Defaults to plural_name with _keys added to the end.
plural_name The plural version of the method name, used to construct the default names for some other methods. Defaults to the method name with s added.
Interfaces
all Creates the entire family of methods described above. The example below illustrates their use.

Example:



    package MyClass;

    use Rose::Class::MakeMethods::Generic
    (
      inherited_hash =>
      [
        pet_color =>
        {
          keys_method     => pets,
          delete_implies  => delete_special_pet_color,
          inherit_implies => inherit_special_pet_color,
        },

        special_pet_color =>
        {
          keys_method     => special_pets,
          add_implies => add_pet_color,
        },
      ],
    );
    ...

    package MySubClass;
    our @ISA = qw(MyClass);
    ...


    MyClass->pet_colors(Fido => white,
                        Max  => black,
                        Spot => yellow);

    MyClass->special_pet_color(Toby => tan);

    MyClass->pets;              # Fido, Max, Spot, Toby
    MyClass->special_pets;      # Toby

    MySubClass->pets;           # Fido, Max, Spot, Toby
    MyClass->pet_color(Toby); # tan

    MySubClass->special_pet_color(Toby => gold);

    MyClass->pet_color(Toby);         # tan
    MyClass->special_pet_color(Toby); # tan

    MySubClass->pet_color(Toby);         # gold
    MySubClass->special_pet_color(Toby); # gold

    MySubClass->inherit_pet_color(Toby);

    MySubClass->pet_color(Toby);         # tan
    MySubClass->special_pet_color(Toby); # tan

    MyClass->delete_pet_color(Max);

    MyClass->pets;    # Fido, Spot, Toby
    MySubClass->pets; # Fido, Spot, Toby

    MyClass->special_pet_color(Max => mauve);

    MyClass->pets;    # Fido, Max, Spot, Toby
    MySubClass->pets; # Fido, Max, Spot, Toby

    MyClass->special_pets;    # Max, Toby
    MySubClass->special_pets; # Max, Toby

    MySubClass->delete_special_pet_color(Max);

    MyClass->pets;    # Fido, Max, Spot, Toby
    MySubClass->pets; # Fido, Max, Spot, Toby

    MyClass->special_pets;    # Max, Toby
    MySubClass->special_pets; # Toby



AUTHOR

John C. Siracusa (siracusa@gmail.com)

LICENSE

Copyright (c) 2010 by John C. Siracusa. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 ROSE::CLASS::MAKEMETHODS::GENERIC (3) 2013-10-04

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.