Class
Class
Mode
Enabled
| CleanCode Perl Libraries |
| Home | Perl | Java | PowerShell | C# | SQL | Index | Tools | Download | What's New |
| Multi-Lingual Library | Maintainability | ||||||||||||
|
Perl | |
Java | |
JavaScript | |
Certified Class |
|
Testable Class |
|
Standalone Mode |
|
Diagnostic Enabled |
Data::ParamMap - Manages a collection of parameters and their associated tooltips.
use Data::ParamMap;
# create a new object with a constant argument list.
$paramMap = Data::ParamMap->new({"arg1"=>"tooltip1", "arg2"=>"tooltip2",...});
# add parameters for classes used by this class
# so displaying a usage summary will show all parameters
$paramMap->putAll($Data::Diagnostic::paramMap);
# pass to InputOptions to validate arguments automatically...
$settings = Data::InputOptions->new($args, undef, undef, $paramMap);
# ... or check manually (for specific or pattern-matched argument)
if (!$paramMap->containsKey($argName)) ...
# print list of params and tooltips with specified indent
if ($badArgs) { print STDERR $paramMap->toString(" "); }
# print list of params and tooltips with no indent
print STDERR $paramMap;
Perl5.005
This class extends a standard hash with some handy features for managing program configuration parameters. Typically, you will have a known, constant set of parameters that your program will use. Create a simple constant list of these parameters, wherein each one is associated with a "tooltip"--a short text fragment describing the purpose of the parameter. Most command-line oriented programs have a standard "usage" summary, listing all of the parameters (or options) and the purpose of each. Using a ParamMap you can do this with trivial code. Here's a sample list of parameters for a program, followed by a constructor for our object:
$paramList = {
"sourcePath" => "root of source xml tree",
"targetPath" => "root of target xml tree",
"enable" => "do processing if true; just report if false",
"help" => "show this list"
};
$paramMap = Data::ParamMap->new($paramList);
If you then have a routine that displays a usage summary, all you have to do is print the ParamMap, as in:
sub usage {
print STDERR "usage: program-x\n\n";
print STDERR $paramMap->toString();
}
The output of the above method would simply be:
usage: program-x
sourcePath -- root of source xml tree
targetPath -- root of target xml tree
enable -- do processing if true; just report if false
help -- show this list
But let's say your program uses another module, such as CleanCode's Diagnostic module, and you allow the user to specify command-line input parameters that may also be used by this included module. But then the above usage() method is not really complete, as it does not show the parameters used by the other module(s). As long the included modules also use a ParamMap, you only need one line of code to merge the two lists:
$paramMap->putAll(Data::Diagnostic::paramMap);
Then when you print the paramMap, it will list not only your parameters, but those of the Diagnostic module (in this example). But this merged list is not just for a usage() method. It also comes into play when you want to validate the argument list passed to your program. When you call the containsKey() method to see whether an argument passed in is one that you are expecting, the method will now check against your local list plus the lists from the included modules you have merged via the putAll() method. (While you are certainly free to do manual validation of the argument list, the CleanCode InputOptions module will do it for you by just passing in your top-level paramMap.)
Finally, a ParamMap is not limited to an enumerated set of parameters. You may use regular expressions in your parameters to match a class of names. Like many things, this has advantages and disadvantages. You gain flexibility in what you can accept, but then you lose the ability to do strict validation. (Some regular expressions would match an infinite number of strings, and clearly you wouldn't be expecting all of them.) This flexibility is very handy in the case, for instance, where the allowable parameters depends upon things that happen at runtime. The Diagnostic module, for example, allows each loaded class to have its own diagnostic level parameter, where the name is classname_DIAG. But when you, as a developer, use the Diagnostic module, you don't want to concern yourself with all the other CleanCode modules loaded along with the Diagnostic module. Further, you may even use dynamic class loading, where you couldn't know which modules in advance even if you wanted to. So the Diagnostic module includes this in its ParamMap:
{ ".*_DIAG" => "diagnostic level for any class" },
Then your argument list may contain DIAGNOSTIC_DIAG, FOOBAR_DIAG, or any other diagnostic level, and they will all pass validation.
Current version of this class.
PACKAGE->new(paramList)
Creates a ParamMap object initialized with the specified paramList.
paramList - hash reference specifying each parameter name and a description of its use. The parameter name may either be a simple string or a regular-expression.
a newly created object
OBJ->containsKey(key)
Determines if the specified key matches an element of the ParamMap either as a specific string or as a regular expression.
key - string; paramenter name to check for match
OBJ->putAll(newMap)
Merges the new map with the current map. Elements in the new map which are already in the current map are not changed. Any such conflicts are reported in an UnsupportedOperationException.
newMap - map to merge with the current map.
OBJ->toString(indent)
Converts the object to a string representation with the specified indent on each line. If an indent is not specified, lines will not be indented. One parameter name and description are listed on each line in the format parameter -- description.
indent - optional; string; text used for indentation
A standalone test class to exercise the ParamMap class. Runs through a series of tests, indicating what is expected (roughly). You can work with the ParamMap class in isolation to get a feel for what it does, using the inner class Data::ParamMap::Test. Invoke the class as a main program, calling the function main from the command-line as in:
perl -mData::ParamMap -e "Data::ParamMap::Test::main"None
Michael Sorens
$Revision: 8 $ $Date: 2006-12-19 21:13:43 -0800 (Tue, 19 Dec 2006) $
CleanCode 0.9
Hey! The above document had some coding errors, which are explained below:
=back doesn't take any parameters, but you said =back -- end of CONSTRUCTOR section
=back doesn't take any parameters, but you said =back -- end of METHOD section
| Home | Perl | Java | PowerShell | C# | SQL | Index | Tools | Download | What's New |
| CleanCode Perl Libraries | Copyright © 2001-2013 Michael Sorens - Revised 2013.06.30 |