Rose::...ds::Set(3pm)

📦

version 0.860 · 4 versions

0.860 · debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
0.860 · fedora 43
0.860 · ubuntu jammy
0.860 · fedora 44

, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Rose::...ds::Set(3pm) 💖

okay bestie, welcome to the manual page for Rose::Class::MakeMethods::Set, straight outta the User Contributed Perl Documentation, section 3pm. she's a method maker, she's iconic, and she's about to hand you a whole family of class methods for managing sets. let's go 🫶

✨ NAME ✨

Rose::Class::MakeMethods::Set — create class methods to manage sets. periodt. 👑

🌸 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 💅

so Rose::Class::MakeMethods::Set is a method maker, and she inherits from Rose::Object::MakeMethods — like, it's giving nepo baby but in a good way, because the interface is genuinely nice. if you wanna learn about that interface, go read the Rose::Object::MakeMethods docs, bestie, that's where the tea is. 🍓

the method types that this module provides are all described below. and here's the vibe check that matters most: every single one of these methods works only with classes, not objects. not objects. none of them. classes only. write that down. ✨

🦋 METHODS TYPES 🦋

`inheritable_set`

creates a whole family of class methods for managing an inheritable set of items, and each item can have an optional value attached to it. 🎀 every item has to be a string — or at least it has to stringify into a unique string value — because internally the set is stored in a hash. no cap, that's just how she's built.

here's the part that lowkey trips people up: the set is inherited by subclasses, but the second a subclass accesses or manipulates the set in any way, it immediately gets its own private copy of the set — copied as it existed in the superclass at the exact moment of that access or manipulation. and which superclass does it copy from? the closest one ("least super") that has ever accessed or manipulated this set. 👀

these rules probably sound kinda wacky, but it might help to know why this family of methods exists at all: it was made for the Rose::HTML::Objects family of modules, to manage the set of required HTML attributes (plus their optional default values) for all the different HTML tags. so, y'know, it was built for a job. 💁♀️

Options

add_implies — a method name, or a reference to a list of method names, that gets called whenever an item is added to the set. every added attribute gets passed as an argument to each method in the add_implies list. 🫶
add_method — the name of the class method that adds a single item to the set. defaults to the method name with the prefix add_ tacked on the front.
adds_method — the name of the class method that adds one or more items to the set. defaults to add_method with an s added to the end. slay.
clear_method — the name of the class method that clears out the contents of the set. defaults to plural_name with a clear_ prefix added.
delete_implies — a method name, or a reference to a list of method names, that gets called whenever an item is removed from the set. every deleted attribute gets passed as an argument to each method in the delete_implies list.
delete_method — the name of the class method that removes a single item from the set. defaults to the method name with the prefix delete_ added.
deletes_method — the name of the class method that removes 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 holding the set of items when you call it in scalar context, and a shallow copy of that hash when you call it in list context. defaults to plural_name with _hash added to the end.
interface — picks the interface. and honestly? this one is kind of pointless, because there is literally 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. but if you call it with any arguments at all, the set gets cleared first with a call to clear_method, and then it gets repopulated by passing all of those arguments to a call to adds_method. the method name defaults to plural_name.
plural_name — the plural name of the items, which is used to construct the default names for a bunch of the other methods. defaults to the method name with an s added.
test_method — the name of the class method that tests whether an item exists 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 shows them all in action. ⭐

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'};

bestie, look at that # Careful! comment up there. that hash you get from valid_names_hash in scalar context is the actual hash used for set storage. do NOT go deleting keys out of it directly — use delete_valid_name() instead. that's the whole point. 🙈

`inherited_set`

creates a family of class methods for managing an inherited set of items. same deal as before: every item has to be a string, or has to stringify into a unique string value, because a hash is what stores the set internally. 🧚

so what even is an inherited set? it's the union of the sets of all the superclasses, minus any items that have been explicitly deleted in the current class. simple as that. 💜

Options

add_implies — a method name, or a 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 the internal cache for the set, or generate it if it doesn't exist yet. 👑 this one should be treated as a private method, but she's listed here anyway because she 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 a 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 class method that yeets one or more items out of the set 💅 defaults to plural_name with delete_ slapped on the front, periodt.
hash_method — the class method that hands you a hash (in list context) or a ref to a hash (in scalar context) holding the whole set. key exists = item exists, that's the whole vibe. defaults to plural_name with _hash tacked on the end.
inherit_method — the class method that says "okay bestie, this inherited value we previously deleted? it's inherited again now." defaults to the method name with inherit_ glued to the front. 🦋
inherits_method — same energy but for multiple inherited values coming back to being inherited. defaults to the inherit_method name with an s added at the end. slay.
interface — picks the interface. ngl this one's kind of pointless since there's literally only one interface rn. defaults to all, obviously. 💀
list_method — the class method that gives you a ref to a sorted list of items in scalar context, or just a sorted list in list context. but wait — if you call it with any arguments, the set gets cleared via a call to clear_method first, then it gets repopulated by passing all the args to a call to adds_method. name defaults to plural_name. 🔥
plural_name — the plural name of the items, and it's the blueprint that builds the default names for a bunch of the other methods. defaults to the method name with an s added.
test_method — the class method that checks whether an item exists in the set. defaults to the method name with the prefix is_ in front of it. ✨

🌸 Interfaces 🌸

all — creates the entire family of methods described above, the whole friend group. the example below shows you how they all hang out together. 👑

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

bestie listen 💛 that delete $h->{'C'}? it does nothing to the set. $h is not a reference to the actual hash used for set storage. the manpage said it, so I'm saying it. no cap. 🙈

👑 AUTHOR 👑

John C. Siracusa (siracusa@gmail.com)

💖 LICENSE 💖

and that's a wrap on the whole page, bestie 🫶 this was shipped with perl v5.34.0 back on 2022-05-28, and the page itself is Rose::...ds::Set(3pm) — go make some sets, you absolute icon. 💅✨🌈

📦 where this page comes from

debian bookworm: librose-object-perl 0.860-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
debian trixie: librose-object-perl 0.860-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu noble: librose-object-perl 0.860-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu resolute: librose-object-perl 0.860-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu stonking: librose-object-perl 0.860-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms