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

FreeBSD Manual Pages

  
 
  

home | help
Rose::Class::MakeMethoUserSContributed Perl DoRose::Class::MakeMethods::Set(3)

NAME
       Rose::Class::MakeMethods::Set - Create class methods to manage sets.

SYNOPSIS
	 package MyClass;

	 use Rose::Class::MakeMethods::Set
	 (
	   inheritable_set =>
	   [
	     required_name =>
	     {
	       add_implies => 'add_valid_name',
	       test_method => 'name_is_required',
	     },
	   ],

	   inherited_set =>
	   [
	     valid_name	=>
	     {
	       test_method => 'name_is_valid',
	     },
	   ],
	 );

	 ...

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

	 MyClass->add_valid_names('A', 'B', 'C');
	 MyClass->add_required_name('D');

	 $v1 = join(',', MyClass->valid_names);	      #	'A,B,C,D';
	 $r1 = join(',', MyClass->required_names);    #	'D'

	 $v2 = join(',', MySubClass->valid_names);    #	'A,B,C,D';
	 $r2 = join(',', MySubClass->required_names); #	'D'

	 MySubClass->add_required_names('X', 'Y');

	 $v2 = join(',', MySubClass->valid_names);    #	'A,B,C,D,X,Y';
	 $r2 = join(',', MySubClass->required_names); #	'D,X,Y'

	 MySubClass->delete_valid_names('B', 'X');

	 $v1 = join(',', MyClass->valid_names);	      #	'A,B,C,D';
	 $r1 = join(',', MyClass->required_names);    #	'D'

	 $v2 = join(',', MySubClass->valid_names);    #	'A,C,D,Y';
	 $r2 = join(',', MySubClass->required_names); #	'D,X,Y'

	 MySubClass->delete_required_name('D');

	 $v1 = join(',', MyClass->valid_names);	      #	'A,B,C,D';
	 $r1 = join(',', MyClass->required_names);    #	'D'

	 $v2 = join(',', MySubClass->valid_names);    #	'A,C,D,Y';
	 $r2 = join(',', MySubClass->required_names); #	'X,Y'

DESCRIPTION
       Rose::Class::MakeMethods::Set 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
       inheritable_set
	   Create a family of class methods for	managing an inheritable	set of
	   items, each with an optional	associated value.  Each	item must be a
	   string, or must stringify to	a unique string	value, since a hash is
	   used	internally to store the	set.

	   The set is inherited	by subclasses, but any subclass	that accesses
	   or manipulates the set in any way will immediately get its own
	   private copy	of the set as it exists	in the superclass at the time
	   of the access or manipulation.  The superclass from which the set
	   is copied is	the closest ("least super") class that has ever
	   accessed or manipulated this	set.

	   These may sound like	wacky rules, but it may	help to	know that this
	   family of methods was created for use in the	Rose::HTML::Objects
	   family of modules to	manage the set of required HTML	attributes
	   (and	their optional default values) for various HTML	tags.

	   Options
	       "add_implies"
		   A method name, or reference to a list of method names, to
		   call	when an	item is	added to the set.  Each	added
		   attribute is	passed as an argument to each method in	the
		   "add_implies" list.

	       "add_method"
		   The name of the class method	used to	add a single item to
		   the set. Defaults to	the method name	with the prefix	"add_"
		   added.

	       "adds_method"
		   The name of the class method	used to	add one	or more	items
		   to the set. Defaults	to "add_method"	with "s" added to the
		   end.

	       "clear_method"
		   The name of the class method	used to	clear the contents of
		   the set. 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 an	item is	removed	from the set.  Each deleted
		   attribute is	passed as an argument to each method in	the
		   "delete_implies" list.

	       "delete_method"
		   The name of the class method	used to	remove a single	item
		   from	the set. Defaults to the method	name with the prefix
		   "delete_" added.

	       "deletes_method"
		   The name of the class method	used to	remove one or more
		   items from the set. Defaults	to "plural_name" with a
		   "delete_" prefix added.

	       "hash_method"
		   The name of the class method	that returns a reference to
		   the actual hash that	contains the set of items in scalar
		   context, and	a shallow copy of the hash in list context.
		   Defaults to "plural_name" with "_hash" added	to the end.

	       "interface"
		   Choose the interface.  This is kind of pointless since
		   there is only one interface right now.  Defaults to "all",
		   obviously.

	       "list_method"
		   The name of the class method	that returns a reference to a
		   sorted list of items	in scalar context, or a	sorted list in
		   list	context.  If called with any arguments,	the set	is
		   cleared with	a call to "clear_method", then the set is
		   repopulated by passing all of the arguments to a call to
		   "adds_method".  The method name defaults to "plural_name".

	       "plural_name"
		   The plural name of the items, used to construct the default
		   names for some other	methods.  Defaults to the method name
		   with	"s" added.

	       "test_method"
		   The name of the class method	that tests for the existence
		   of an item in the set.  Defaults to the method name with
		   the prefix "is_" added.

	       "value_method"
		   The name of the class method	used to	get and	set the
		   (optional) value associated with each item in the set.
		   Defaults to the method name with "_value" added to the end.

	   Interfaces
	       "all"
		   Creates the entire family of	methods	described above.  The
		   example below illustrates their use.

	   Example:

	       package MyClass;

	       use Rose::Class::MakeMethods::Set
	       (
		 inheritable_set =>
		 [
		   valid_name =>
		   {
		     test_method    => 'name_is_valid',
		     delete_implies => 'delete_required_name',
		   },

		   required_name =>
		   {
		     add_implies => 'add_valid_name',
		     test_method => 'name_is_required',
		   },
		 ],
	       );

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

	       MyClass->add_valid_names('A', 'B', 'C');
	       MyClass->add_required_name('D');

	       $v1 = join(',', MyClass->valid_names);	    # 'A,B,C,D';
	       $r1 = join(',', MyClass->required_names);    # 'D'

	       $v2 = join(',', MySubClass->valid_names);    # 'A,B,C,D';
	       $r2 = join(',', MySubClass->required_names); # 'D'

	       MySubClass->add_required_names('X', 'Y');

	       $v2 = join(',', MySubClass->valid_names);    # 'A,B,C,D,X,Y';
	       $r2 = join(',', MySubClass->required_names); # 'D,X,Y'

	       MySubClass->delete_valid_names('B', 'X');

	       $v1 = join(',', MyClass->valid_names);	    # 'A,B,C,D';
	       $r1 = join(',', MyClass->required_names);    # 'D'

	       $v2 = join(',', MySubClass->valid_names);    # 'A,C,D,Y';
	       $r2 = join(',', MySubClass->required_names); # 'D,Y'

	       MySubClass->delete_required_name('D');

	       $v1 = join(',', MyClass->valid_names);	    # 'A,B,C,D';
	       $r1 = join(',', MyClass->required_names);    # 'D'

	       $v2 = join(',', MySubClass->valid_names);    # 'A,C,D,Y';
	       $r2 = join(',', MySubClass->required_names); # 'Y'

	       MyClass->name_is_required('D');	  # true
	       MySubClass->name_is_required('D'); # false

	       $h = MyClass->valid_names_hash;

	       # Careful!  This	is the actual hash used	for set	storage!
	       # You should use	delete_valid_name() instead!
	       delete $h->{'C'};

	       MySubClass->required_name_value(Y => 'xval');

	       print MySubClass->required_name_value('Y'); # 'xval'

	       %r = MySubClass->required_names_hash;

	       print $r{'Y'}; #	'xval'

	       # Okay: %r is a (shallow) copy, not the actual hash
	       delete $r{'Y'};

       inherited_set
	   Create a family of class methods for	managing an inherited set of
	   items. Each item must be a string, or must stringify	to a unique
	   string value, since a hash is used internally to store the set.

	   An inherited	set is made up of the union of the sets	of all
	   superclasses, minus any items 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 an	item is	added to the set.  Each	added
		   attribute is	passed as an argument to each method in	the
		   "add_implies" list.

	       "add_method"
		   The name of the class method	used to	add a single item to
		   the set. Defaults to	the method name	with the prefix	"add_"
		   added.

	       "adds_method"
		   The name of the class method	used to	add one	or more	items
		   to the set. Defaults	to "add_method"	with "s" added to the
		   end.

	       "cache_method"
		   The name of the class method	used to	retrieve (or generate,
		   if it doesn't exist)	the internal cache for the set.	 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 set. 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 an	item is	removed	from the set.  Each deleted
		   attribute is	passed as an argument to each method in	the
		   "delete_implies" list.

	       "delete_method"
		   The name of the class method	used to	remove a single	item
		   from	the set. Defaults to the method	name with the prefix
		   "delete_" added.

	       "deletes_method"
		   The name of the class method	used to	remove one or more
		   items from the set. Defaults	to "plural_name" with a
		   "delete_" prefix added.

	       "hash_method"
		   The name of the class method	that returns a hash (in	list
		   context) or a reference to a	hash (in scalar	context) that
		   contains the	set of items. The existence of a key in	the
		   hash	indicates its existence	in the set. Defaults to
		   "plural_name" with "_hash" added to the end.

	       "inherit_method"
		   The name of the class method	used to	indicate that an
		   inherited value that	was previously deleted from the	set
		   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 values that were previously deleted from the
		   set should return to	being inherited.  Defaults to the
		   "inherit_method" name with "s" added	to the end.

	       "interface"
		   Choose the interface.  This is kind of pointless since
		   there is only one interface right now.  Defaults to "all",
		   obviously.

	       "list_method"
		   The name of the class method	that returns a reference to a
		   sorted list of items	in scalar context, or a	sorted list in
		   list	context.  If called with any arguments,	the set	is
		   cleared with	a call to "clear_method", then the set is
		   repopulated by passing all of the arguments to a call to
		   "adds_method".  The method name defaults to "plural_name".

	       "plural_name"
		   The plural name of the items, used to construct the default
		   names for some other	methods.  Defaults to the method name
		   with	"s" added.

	       "test_method"
		   The name of the class method	that tests for the existence
		   of an item in the set.  Defaults to the method name with
		   the prefix "is_" added.

	   Interfaces
	       "all"
		   Creates the entire family of	methods	described above.  The
		   example below illustrates their use.

	   Example:

	       package MyClass;

	       use Rose::Class::MakeMethods::Set
	       (
		 inherited_set =>
		 [
		   valid_name =>
		   {
		     test_method     =>	'name_is_valid',
		     delete_implies  =>	'delete_required_name',
		     inherit_implies =>	'inherit_required_name',
		   },

		   required_name =>
		   {
		     add_implies => 'add_valid_name',
		     test_method => 'name_is_required',
		   },
		 ],
	       );
	       ...

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

	       MyClass->add_valid_names('A', 'B', 'C');
	       MyClass->add_required_name('D');

	       $v1 = join(',', MyClass->valid_names);	    # 'A,B,C,D';
	       $r1 = join(',', MyClass->required_names);    # 'D'

	       $v2 = join(',', MySubClass->valid_names);    # 'A,B,C,D';
	       $r2 = join(',', MySubClass->required_names); # 'D'

	       MyClass->add_required_names('X',	'Y');

	       $v2 = join(',', MySubClass->valid_names);    # 'A,B,C,D,X,Y';
	       $r2 = join(',', MySubClass->required_names); # 'D,X,Y'

	       MySubClass->delete_valid_names('B', 'X');

	       $v1 = join(',', MyClass->valid_names);	    # 'A,B,C,D,X,Y';
	       $r1 = join(',', MyClass->required_names);    # 'D,X,Y'

	       $v2 = join(',', MySubClass->valid_names);    # 'A,C,D,Y';
	       $r2 = join(',', MySubClass->required_names); # 'D,Y'

	       MySubClass->delete_required_name('D');

	       $v1 = join(',', MyClass->valid_names);	    # 'A,B,C,D,X,Y';
	       $r1 = join(',', MyClass->required_names);    # 'D,X,Y'

	       $v2 = join(',', MySubClass->valid_names);    # 'A,C,D,Y';
	       $r2 = join(',', MySubClass->required_names); # 'Y'

	       MySubClass->inherit_required_name('D');

	       $v1 = join(',', MyClass->valid_names);	    # 'A,B,C,D,X,Y';
	       $r1 = join(',', MyClass->required_names);    # 'D,X,Y'

	       $v2 = join(',', MySubClass->valid_names);    # 'A,C,D,Y';
	       $r2 = join(',', MySubClass->required_names); # 'D,Y'

	       MySubClass->delete_valid_name('D');

	       $v1 = join(',', MyClass->valid_names);	    # 'A,B,C,D,X,Y';
	       $r1 = join(',', MyClass->required_names);    # 'D,X,Y'

	       $v2 = join(',', MySubClass->valid_names);    # 'A,C,Y';
	       $r2 = join(',', MySubClass->required_names); # 'Y'

	       MySubClass->inherit_valid_name('D');

	       $v1 = join(',', MyClass->valid_names);	    # 'A,B,C,D,X,Y';
	       $r1 = join(',', MyClass->required_names);    # 'D,X,Y'

	       $v2 = join(',', MySubClass->valid_names);    # 'A,C,D,Y';
	       $r2 = join(',', MySubClass->required_names); # 'D,Y'

	       MyClass->delete_valid_name('D');

	       $v1 = join(',', MyClass->valid_names);	    # 'A,B,C,X,Y';
	       $r1 = join(',', MyClass->required_names);    # 'X,Y'

	       $v2 = join(',', MySubClass->valid_names);    # 'A,C,Y';
	       $r2 = join(',', MySubClass->required_names); # 'Y'

	       MySubClass->add_required_name('D');

	       $v1 = join(',', MyClass->valid_names);	    # 'A,B,C,X,Y';
	       $r1 = join(',', MyClass->required_names);    # 'X,Y'

	       $v2 = join(',', MySubClass->valid_names);    # 'A,C,D,Y';
	       $r2 = join(',', MySubClass->required_names); # 'D,Y'

	       $h = MyClass->valid_names_hash;

	       # This has no affect on the set.	 $h is not a reference to the
	       # actual	hash used for set storage.
	       delete $h->{'C'};

	       $v1 = join(',', MyClass->valid_names);	    # 'A,B,C,X,Y';
	       $r1 = join(',', MyClass->required_names);    # 'X,Y'

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			  2010-10-17  Rose::Class::MakeMethods::Set(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::Set&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help