Parameter::Group - Class to handle groups of parameters - either other sub-groups and/or variables.
use Parameter::Group;
# create instance
my $g=Parameter::Group->new();
# create a Parameter-object
my $v=Parameter::Variable->new();
# add a Parameter-object to the group
$g->add($v);
# create a variable object and add it to the group instance
$g=addVariable("myvariable","somevalue",".*");
# create a sub-group-object and add it to the group instance
$g->addGroup("mygroup");
# add variable to subgroup
$g->get("mygroup")->addVariable("somename","othervalue");
# add variable after another named variable
$g->addVariableAfter("myvariable","newvariablename","value");
# add variable before another named variable
$g->addVariableBefore("newvariablename","myvarname","a_value");
# make a variable required and public
$g->addVariable("mypublicvariable","somevalue",1,0);
# create a group and tell it to quote its content parameters (sub-groups and/or variables)
$g->addGroup("myquotedgroup",undef,1);
# remove a named parameter
$g->remove("mypublicvariable");
# enumerate objects (sub-groups and variables)
my $e=$g->enum();
# get next parameter
while (my $par=$g->getNextParameter()) {
print "Parameter value is: $par\n";
}
# enumerate objects
my $pars=$g->enumObjects();
# enumerate unique objects
my $uni=$g->enumUniqueObjects();
# enumerate required objects
my $r=$g->enumRequiredObjects();
# enumerate private objects
$p=$g->enumPrivateObjects();
# get a specific named object
my $o=$g->get("objectname");
# check if an object exists (sub-groups or variables)
if ($g->exists("objectname")) {}
# get if group is to have no space between parameters or not?
my $ns=$g->noSpace();
# get all parameters in group as a string
my $s=$g->toString();
# get number of objects in group (sub-groups and/or variables)
my $c=$g->count();Class to handle groups of parameters, either other sub-groups and/or variables.
This class is a sub-class of the Parameter-class. Usually when using the Parameter-class one only instantiates a Parameter::Group-class.
A parameter-group can contain both other sub-groups as well as parameters. It does not allow the creation or addition of groups or variables that have the same name as other groups and variables already added. This is to ensure unique naming in the entire parameter-group, so that one can use the objects by referring to them by name (ie. parameter-name). One can circumvent this requirement in several ways, but we admonish the user to adhere to a group- and parameter unique use.
When addressing Parameter-objects in this class, you can refer to them or get them by using the get()-method. It works hierarchically and will recurse into sub-groups to find the group or variable that you are looking for. Also methods that take parameter-name as an option will recurse to find the object if not otherwise stated. The expection is sub-groups where they will not recurse up the group-tree, only down the group-tree.
An overview of concepts:
Object A Parameter-object that can be added to a group. It can be either a Parameter::Group or Parameter::Variable-class type.
Parameter An item returned as a single entity to the user of the Parameter-class. It can consist of one or more Parameter::Variable-instances. The Parameter::Group-class decides if a collection of variables and/or sub-groups are to be returned as one parameter. Basically anything organized under a sub-group of the main-parameter-group will be returned as one parameter for that sub-group.
Group A collection of sub-groups and/or variables. It has certain attributes that can be set on it, such as if it is to be escaped, quoted and/or have no space between its parameters.
Variable A named value that can be set in a group. It has certain attributes that can be set on it, such as if it is to be escaped, quoted, be private or not and so on. Please see the Parameter::Variable-class documentation for more info on the Parameter::Variable-type.
The method is inherited from the parent Parameter-class, but in addition sets some internal settings that are unique to the Parameter::Group-class.
This method returns an instantiated class upon success. Please refer to the documentation of the Parameter-class for more information.
Adds a parameter object to the group.
Accepts the following input in this order:
object Reference to the Parameter-class object to add (either Parameter::Group or Parameter::Variable-class).
parname Parameter name of where to add this object. If none given it will be added to the end of all current objects in the Parameter::Group-instance. This parameter is used together with the before/after-parameter to exactly signify where to add the object.
beforeafter Sets if to add the object before or after given parameter name (see the parname- option to add(). If none given it defaults to after. The method only accepts 0 (=before) or 1 (=after).
This method returns 1 upon success, 0 upon failure. Please check the error()-method for more information upon failure.
Attempt to remove named parameter.
Accepts the following input: name. This is the name of the parameter to attempt to locate and remove.
This method returns 1 upon success, 0 upon failure. Please check the error()-method for more information upon failure.
Please note that all instances of a named parameter is removed when invoking this method.
Adds a sub-group object to the group at the end of current objects.
Accepts the following parameters in this order:
name Name of parameter to add.
escape Escape the parameters in this group or not? 1 means true, 0 means false. Default is 0.
quote Quote the parameters in this group or not? 1 means true, 0 means false. Default is 0.
nospace Sets if the parameters in this group are to have no space between them or not? 1 means true, 0 means false. It defaults to 0 and does not remove all spacing between the parameters. In some instances groups of parameters needs to have their space removed and render them together.
parname Sets the name of the parameter where this group is to be added and it is used together with the beforeafter-option. It defaults to blank which means it is added to the end of all the current group-objects.
beforeafter Sets if the parameter is to be added before or after the name given in the "parname"-option. 0 means before, 1 means after. This option defaults to after.
Upon success this method returns the group-instance it created and undef upon failure. Please check the error()-method for more information upon failure.
Adds a sub-group in this group after the given parameter name.
This method is a wrapper for the addGroup-method for ease of use.
Accepts the following parameters in this order:
aftername The parameter-name to add the group after.
name Name of the group to add.
escape Sets if the contents of this Parameter::Group is to be escaped or not? Defaults to 0. Accepts 1 for true, 0 for false.
quote Sets if the contents of this Parameter::Group is to be quoted or not? Defaults to 0. Accepts 1 for true, 0 for false.
nospace Sets if the group is to have no space between parameters in the group. Defaults to 0. Accepts 0 for false, 1 for true.
Returns the instance of the class-created upon success, undef upon failure. Please check the error()-method for more information.
Adds a sub-group in this group before the given parameter name.
This method is a wrapper for the addGroup-method for ease of use. It also works similarly to the addGroupAfter()-method. Check the documentation for that method for more information.
Adds a variable in this group.
If the variable name exists already, that Parameter::Variable-object is added to the group. Variables can be used several places, but all variables should still have unique names.
Accepts the following options in this order:
name Name of variable to add. Must be unique.
value Value of variable that is to be added.
regex Regex of value that is added on variable. This regex is meant to be used when adding values on the parameter, although no checking is enforce in this class. It is up to the user of the class to enforce checking.
required Sets if the variable is required or not to have a value. 0 means false, 1 means true. Defaults to 0. This option is ignored if variable already exists.
private Sets if the variable is to be private or not. 0 means false, 1 means true. Defaults to 1. All variables are private if not otherwise stated. The privacy of the variable is not enforces by this class, but have to be enforced by the user of the Parameter-classes. Private here is meant that the normal user of an application is not allowed to change its value (protected). This option is ignored if variable already exists and that variable object is added.
escape Sets if the variable is to have its value escaped or not. 0 means false, 1 means true. Defaults to 0. Please note that if the group using the variable is set to be escaped, it will override the setting here. This option is ignored if variable already exists and that variable object is added.
preescape Sets if the variable is to have its value preescaped or not. 0 means false, 1 means true. Defaults to 1.
sandbox Sets if the variable value is to be sandboxed or not. 0 means false, 1 means true. Defaults to 0. This option is ignored if variable already exists and that variable object is added.
parname Sets parameter name of where to insert the variable. Defaults to blank which means to insert the variable at the end of the group.
beforeafter Sets if the variable is to be added before or after name set in parname. 0 means before, 1 means after. Defaults to after. If parname and beforeafter is undefined the variable will be appended to the group.
Upon success returns 1, 0 on failure. Please check the error()-method for more information upon failure.
Adds a variable after the given parameter name.
This is a wrapper around the addVariable()-method. It accepts options in the following order: parname (name of parameter after which to add this variable), name (variable name), value (value of variable), regex, required, private, escape, quote, sandbox and preescape. Please see the addVariable()-method for more information about the options.
Please note that if given variable name already exists, that Parameter::Variable-instance is added. If it doesn't exist, it will be created and then added.
Returns 1 upon success, 0 upon failure. Please see the error()-method for more information upon failure.
Adds a variable before the given parameter name.
This is a wrapper around the addVariable()-method. It accepts options in the following order: parname (name of parameter before which to add this variable), name (variable name), value (value of variable), regex, required, private, escape, quote, sandbox and preescape. Please see the addVariable()-method for more information about the options.
Please note that if given variable name already exists, that Parameter::Variable-instance is added. If it doesn't exist, it will be created and then added.
Returns 1 upon success, 0 upon failure. Please see the error()-method for more information upon failure.
Returns the number of Parameter-objects in the group.
No input accepted.
Enumerate the objects that the group-instance contains.
Accepts no input.
Returns a LIST-reference of Parameter-classes
Enumerate the object names of the group.
Please note that object names enumerated can be repeated (for Parameter::Variable-objects) and show the actual order of the Parameter-group.
Returns a reference to a LIST of object names. Please note that the list can be empty.
Enumerate the private objects of the group.
This returns the unique, private objects in the group and its sub-groups.
No input is accepted.
Returns a LIST-reference of object names.
Enumerate the required objects of the group.
This returns the unique and required objects of the group and its sub-groups.
No input is accepted.
Returns a LIST-reference of object names.
Enumerate the unique objects of the group.
This returns the unique object names of the group and its sub-groups.
No input is accepted.
Returns a LIST-reference of the object names.
Checks if a given object name exists in group or its sub-groups.
Accepts one input: object name.
Returns 1 if it exists, 0 if it does not.
Get a names object-instance.
Accepts one input: object name.
Returns the object-instance if the object exists in the top group or its sub-groups, undef upon failure. This method will go to the top-most parent-group and start asking for the object there while recursing down the possible groups in the Parameter-tree. It will return the first match from the top-down.
Please check error()-method upon failure.
Get the first object in the group.
Accepts no input.
Returns the object instance of the first object in the group.
Get the first parameter of the group-instance, if any.
Accepts no input.
Returns the value of the first parameter if any. Undef if no value exists.
Gets the next object in the group.
Accepts no input.
Gets the next object in the group after a call to getFirst(), resetGetNext() or getNext().
Returns an object-reference upon success, undef if there are no more objects.
Returns the next parameters value in the group.
Accepts no input.
Gets the next parameters value in the group or its sub-groups after a call to getFirstParameter(), resetgetNextParameter() or getNextParameter().
Returns a value upon success, undef if there are no more parameter values to fetch.
Get the location of a named object within group or sub-group.
Accepts one input:
name Name of object to get location of.
Returns a LIST-reference. The list reference can be empty if the named object could not be found.
The LIST-reference structure is as follows:
[GROUP-NAME,POSITION]GROUP-NAME is the name of the first group or sub-group that contains the object (variables may exist in several places). POSITION is the first numbered position within GROUP-NAME that the object exists.
Get or set if group is to have no space between its parameters.
Accepts only one input: nospace. Nospace sets if the group is to have no space or not. 1 means true (no space), 0 means false. It defaults to 0 (parameters are to have space between them).
If no input is given, the method returns the current noSpace-setting of the group. Setting the noSpace setting returns the setting after it has been set.
Reset to get the next group object.
Accepts no input.
Resets the fetching of group objects by the method getNext().
Returns 1.
Resets the getting of next parameter value and starts at the beginning of the parameter list.
Accepts no input.
Always returns 1.
Convert all the group- and sub-group parameters into a string.
Accepts no input.
Returns the rendered groups parameters and their values as a string.
Hey! The above document had some coding errors, which are explained below:
=cut found outside a pod block. Skipping to next block.