Rose::Object::MakeMethUser:Contributed PRose::Object::MakeMethods::Generic(3p)



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
       Rose::Object::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 hash-
       based objects.

METHODS TYPES
       scalar
           Create get/set methods for scalar attributes.

           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 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 an object
                   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 method
                   specified by the "init_method" option is called and the
                   attribute is set to the return value of that method.

           Example:

               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.  For each argument
           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.

           Options
               "default"
                   Determines the default value of the attribute.  This option
                   is only applicable when using the "get_set" interface.

               "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 attribute.  Again, the only thing that
                   matters about the return value of this method is whether or
                   not is is true or false.  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 boolean
                   object attribute. When called with an argument, the value
                   of the attribute is set to true if the argument evaluates
                   to true, false (but defined) otherwise.  The current value
                   of the attribute is returned.

                   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 generated the method.

               "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 is set based on the boolean value of the return
                   value of that method.

           Example:

               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.

           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 hash attribute.    This method should
                   return a reference to a hash, and is only applicable when
                   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"
                   If 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.

                   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 stored by
                   the object 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 stored by the object in scalar
                   context.

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

               "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 is initialized to an empty
                   hash before proceeding as usual.

               "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
                   stored by the object 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 stored by
                   the object 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 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.

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

           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) 2006 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.12.2                      2009-1Rose::Object::MakeMethods::Generic(3p)
