Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Rose::Class::MakeMethoUserGContributed PerRose::Class::MakeMethods::Generic(3)

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

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
       scalar
	   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"

       inheritable_boolean
	   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

       inheritable_scalar
	   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'

       hash
	   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

       inheritable_hash
	   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 they're 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	}

       inherited_hash
	   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.

perl v5.24.1			  2013-10-Rose::Class::MakeMethods::Generic(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS TYPES | AUTHOR | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Rose::Class::MakeMethods::Generic&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help