Rose::...eneric(3pm)

🌸 Rose::Object::MakeMethods::Generic 🌸

okay bestie, this is the Rose::...eneric(3pm) page from the User Contributed Perl Documentation and it's literally iconic, so let's get into it 💅✨

---

💖 NAME 💖

Rose::Object::MakeMethods::Generic — Create simple object methods. 🫶

---

🦋 SYNOPSIS 🦋

package MyObject;

use Rose::Object::MakeMethods::Generic
(
  scalar =>
  [
    'power',
    'error',
  ],

  'scalar --get_set_init' => 'name',

  'boolean --get_set_init' => 'is_tall',

  boolean =>
  [
    'is_red',
    'is_happy' => { default => 1 },
  ],

  array =>
  [
    jobs       => {},
    job        => { interface => 'get_set_item', hash_key => 'jobs' },
    clear_jobs => { interface => 'clear', hash_key => 'jobs' },
    reset_jobs => { interface => 'reset', hash_key => 'jobs' },
  ],

  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' },
  ],
);

sub init_name    { 'Fred' }
sub init_is_tall { 1 }
...

$obj = MyObject->new(power => 5);

print $obj->name; # Fred

$obj->do_something or die $obj->error;

$obj->is_tall;        # true
$obj->is_tall(undef); # false (but defined)
$obj->is_tall;        # false (but defined)

$obj->is_red;         # undef
$obj->is_red(1234);   # true
$obj->is_red('');     # false (but defined)
$obj->is_red;         # false (but defined)

$obj->is_happy;       # true

$obj->params(a => 1, b => 2);   # add pairs
$val = $obj->param('b');        # 2
$obj->param_exists('x');        # false

$obj->jobs('butcher', 'baker'); # add values
$obj->job(0 => 'sailor');       # set value
$job = $obj->job(0);            # 'sailor'

---

🌈 DESCRIPTION 🌈

So Rose::Object::MakeMethods::Generic is a method maker that inherits from Rose::Object::MakeMethods. If you wanna know how the whole interface thing works, go read the Rose::Object::MakeMethods docs — that's the lore, bestie, this page assumes you've done your homework 📚✨

The method types that this module hands you are all laid out below. And here's the vibe check: all of these methods work only with hash-based objects. That's the rule, no cap. 💀

---

👑 METHODS TYPES 👑

🍓 scalar

Create get/set methods for scalar attributes. Simple, clean, iconic. ✨

💜 Options

• hash_key — the key inside the hash-based object where this attribute gets stored. If you don't say anything, it just defaults to the name of the method. lowkey convenient.
• init_method — the name of the method to call when initializing the value of an undefined attribute. Heads up: this option only applies when you're using the get_set_init interface. Defaults to the method name with the prefix init_ added onto the front. 🎀
• interface — pick one of the two possible interfaces. Defaults to get_set.

🎀 Interfaces

• get_set — makes a simple get/set accessor method for an object attribute. Call it with an argument and the attribute gets set. Either way, the current value of the attribute is what comes back at you. 💅
• get_set_init — acts just like the get_set interface unless the value of the attribute is undefined. In that case, the method named by the init_method option gets called, and the attribute is set to whatever that method returns. ✨

Example, bestie:

package MyObject;

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

sub init_name { 'Fred' }
...

$obj->power(99);    # returns 99
$obj->name;         # returns "Fred"
$obj->name('Bill'); # returns "Bill"

---

🦋 boolean

Create get/set methods for boolean attributes. Here's the whole entire vibe: for each argument you pass to these methods, the only thing that matters is whether it evaluates to true or false. The return value is either true, false (but defined), or undef if the value has never been set at all. 🙈

💜 Options

• default — determines the default value of the attribute. This one only applies when you're using the get_set interface.
• hash_key — the key inside the hash-based object where this attribute gets stored. Defaults to the name of the method.
• init_method — the name of the method to call when initializing the value of an undefined attribute. Again, the only thing that matters about the return value of this method is whether or not it's true or false. This option only applies when you're using the get_set_init interface. Defaults to the method name with the prefix init_ added. 🎀
• interface — pick one of the two possible interfaces. Defaults to get_set.

🎀 Interfaces

• get_set — makes a simple get/set accessor method for a boolean object attribute. Call it with an argument and the value of the attribute gets set to true if the argument evaluates to true, and false (but defined) otherwise. The current value of the attribute is returned.

And here's a lil ✨performance tea✨: if Class::XSAccessor version 0.14 or later is installed, and the ROSE_OBJECT_NO_CLASS_XSACCESOR environment variable is not set to a true value, then Class::XSAccessor will be used to generate the method. slay.

• get_set_init — behaves like the get_set interface unless the value of the attribute is undefined. In that case, the method specified by the init_method option is called, and the attribute gets set based on the boolean value of whatever that method returns. 🫶

Example time:

package MyObject;

use Rose::Object::MakeMethods::Generic
(
  'boolean --get_set_init' => 'is_tall',

  boolean =>
  [
    'is_red',
    'is_happy' => { default => 1 },
  ],
);

sub init_is_tall { 'blah' }
...

$obj->is_tall;        # returns true
$obj->is_tall(undef); # returns false (but defined)
$obj->is_tall;        # returns false (but defined)

$obj->is_red;         # returns undef
$obj->is_red(1234);   # returns true
$obj->is_red('');     # returns false (but defined)
$obj->is_red;         # returns false (but defined)

$obj->is_happy;       # returns true

---

🌈 hash

Create methods to manipulate hash attributes. This is the one with all the ✨interfaces✨, so buckle up bestie. 🎢

💜 Options

• hash_key — the key inside the hash-based object where this attribute gets stored. Defaults to the name of the method.
• init_method — the name of the method to call when initializing the value of an undefined hash attribute. This method should return a reference to a hash, and it only applies when you're using the get_set_init interface. Defaults to the method name with the prefix init_ added. 🎀
• interface — choose which interface to use. Defaults to get_set.

🎀 Interfaces

• get_set — here's the full rundown, no skips:
  • Called with no arguments: returns a list of key/value pairs in list context, or a reference to the actual hash stored by the object in scalar context.
  • 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 stored by the object in scalar context.
  • Called with one argument, and that argument is a reference to an array: then you get back a list of the hash values for each key in the array.
  • 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.
  • Called with an even number of arguments: they're taken as name/value pairs and added to the hash. It then returns a list of key/value pairs in list context, or a reference to the actual hash stored by the object in scalar context.

⚠️ Passing an odd number of arguments greater than 1 causes a fatal error. Not a vibe. Don't do it. 💀

• get_set_init — behaves like the get_set interface unless the attribute is undefined. In that case, the method specified by the init_method option is called, and the attribute is set to the return value of that method, which should be a reference to a hash. 🫶
• get_set_inited — behaves like the get_set interface unless the attribute is undefined. In that case, it gets initialized to an empty hash before proceeding as usual. ✨
• get_set_all — the "actually let me just replace the whole thing" energy:
  • Called with no arguments: returns a list of key/value pairs in list context, or a reference to the actual hash stored by the object in scalar context.
  • 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 stored by the object in scalar context.
  • Otherwise: the hash gets 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 stored by the object in scalar context. 💅
• get_set_init_all — behaves like the get_set_all interface unless the attribute is undefined. In that case, the method specified by the init_method option is called, and the attribute is set to the return value of that method, which should be a reference to a hash. 🌸
• clear — sets the attribute to an empty hash. just empty. no cap. 💅
• reset — sets the attribute to undef. it's giving "factory reset" but for your hash. 🫶
• delete — deletes the key(s) passed as arguments. if you pass no arguments, that's a fatal error. so bestie, don't do that. 💀
• 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. the rules are the rules. 🙈
• 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, so don't come for me about order. ✨
• names — an alias for the keys interface. same vibe, different name. iconic. 👑
• 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 either. 🌸

✨ Example ✨

package MyObject;

use Rose::Object::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' },
  ],
);
...

$obj = MyObject->new;

$obj->params; # undef

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

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

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

$obj->param_exists('a'); # false

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

$obj->delete_param('c');
$obj->param(f => 7, g => 8);

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

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

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

✨ array ✨

Create methods to manipulate array attributes. yes bestie, arrays. the other kind of list. let's get into it. 🦋

Options

• hash_key — the key inside the hash-based object to use for the storage of this attribute. defaults to the name of the method.
• init_method — the name of the method to call when initializing the value of an undefined array attribute. this method should return a reference to an array. this option is only applicable when using the get_set_init, push, and add interfaces. when using the get_set_init interface, init_method defaults to the method name with the prefix init_ added.
• interface — choose which interface to use. defaults to get_set.

Interfaces

• get_set — if called with no arguments, returns the array contents in list context or a reference to the actual array stored by the object in scalar context. if called with one argument, and that argument is a reference to an array, that array reference is used as the new value for the attribute. returns the array contents in list context or a reference to the actual array stored by the object in scalar context. if called with one argument, and that argument is not a reference to an array, or if called with more than one argument, then the array contents are replaced by the arguments. returns the array contents in list context or a reference to the actual array stored by the object in scalar context.
• get_set_init — behaves like the get_set interface unless the attribute is undefined. in that case, the method specified by the init_method option is called and the attribute is set to the return value of that method, which should be a reference to an array.
• get_set_inited — behaves like the get_set interface unless the attribute is undefined. in that case, it is initialized to an empty array before proceeding as usual.
• get_set_item — if called with one argument, returns the item at that array index. if called with two arguments, sets the item at the array index specified by the first argument to the value specified by the second argument. 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.
• add — an alias for the push interface.
• push — if called with a list or a reference to an array, the contents of the list or referenced array are added to the end of the array. if called with no arguments, a fatal error will occur.
• pop — remove an item from the end of the array and returns it. if an integer argument is passed, then that number of items is removed and returned. otherwise, just one is removed and returned.
• shift — remove an item from the start of the array and returns it. if an integer argument is passed, then that number of items is removed and returned. otherwise, just one is removed and returned.
• unshift — if called with a list or a reference to an array, the contents of the list or referenced array are added to the start of the array. if called with no arguments, a fatal error will occur.
• clear — sets the attribute to an empty array.
• reset — sets the attribute to undef.

✨ Example ✨

package MyObject;

use Rose::Object::MakeMethods::Generic
(
  array =>
  [
    jobs       => {},
    job        => { interface => 'get_set_item',
                    hash_key  => 'jobs' },
    clear_jobs => { interface => 'clear', hash_key => 'jobs' },
    reset_jobs => { interface => 'reset', hash_key => 'jobs' },
  ],
);
...

$obj = MyObject->new;

$jobs = $obj->jobs; # undef

$obj->clear_jobs();
$jobs = $obj->jobs; # ref to empty array

$obj->jobs('butcher', 'baker'); # add values
$vals = join(',', $obj->jobs);  # 'butcher,baker'

$obj->jobs([ 'candlestick', 'maker' ]); # replace values

$vals = join(',', $obj->jobs); # 'candlestick,maker'

$job = $obj->job(0);      # 'candlestick'
$obj->job(0 => 'sailor'); # set value
$job = $obj->job(0);      # 'sailor'

$obj->reset_jobs;
$jobs = $obj->jobs; # undef

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

---

and that's the tea ☕ — this page is from perl v5.34.0, dated 2022-05-28, and it's Rose::...eneric(3pm). bye bestie, go slay those objects 💖