EWS::variables -- variables variable class.
use EWS::variables;
$variables = new EWS::variables(-debug => 0, -io=>$baseIO);
# program executed with arguements: -d -t text -v 2
print "switch d: " . $variables->d, "\n"; print "switch t: " . $variables->t, "\n"; print "switch v: " . $variables->v, "\n";
$variables->alias('t', 'text');
print "switch text: " . $variables->text, "\n";
$variables->readonly('t',0);
$variables->text('New text');
print "switch text: " . $variables->text, "\n";
# access environment variables $home = $variables->ENV_HOME; $ostype = $variables->ENV_OSTYPE;
# create a read-write variable and set to 0.
$variables->create('interrupt', 0, 0);
print "interrupt: " . $variables->interrupt, "\n";
print "interrupt: " . $variables->interrupt(22), "\n";
# access variable hash %variables = $variables->variableHash; $variables = $variables->variableHashRef;
EWS::variables provides object-oriented access to contained objects (variables). Variable-named attributes (i.e. - attribute methods with the same name as a contained variable) provide direct access to contained variables.
Variables may be created as read-write (can be changed) or read-only (unable to be changed).
alias declarations allow virtual variables (aliases) to be substituted for actual variables. Alias-named attributes (i.e. - attribute methods with the same name as an alias) provide indirect access to contained variables.
alias names are maintained in a separate structure from the variable hash and, therefore, can not be accessed using the variableHash structure. Additional attributes are provided to access the aliasHash structure.
Application command-line switches and environment variables are automatically parsed into the variableHash upon object creation (new). Command-line switch names are added without modification (e.g. the switch -d is added as the variable d). Environment variables have ENV_ prepended to the environment variable (e.g. - the environment varable HOME is added as the variable ENV_HOME).
Additional variables must be explictly created. Care must be taken to avoid name conflicts. Creation of a unique namespace by prepending variable names with a namespace name (e.g. - ENV for environment variables) is a simple form of conflict prevention.
Because EWS::variables uses the perl AUTOLOAD mechanism to resolve variable/alias attribute accesses, multiple instances of EWS::variables can become confused. It is better to use EWS::variables as a base class or a single class object and provide a mechanism for namespace exclusivity.
$variables = new EWS::variables(%parameters);
Enter:
%parameters = parameter hash (see below).
Exit:
returns a blessed reference to a new variables object.
parameters are of the form:
-arg => value
acceptable values are:
-debug => 1 = debug messages
-exclusive => 1 = new creates new objects,
0 = new creates shared object (default)
-io => baseIO object
Create a link to a variable in the variable hash.
Enter:
$variable = name of variable to be aliased.
$alias = alias name.
Exit:
none.
Note:
if $variable does not exist, it is created
read-write and value undefined.
Change the declared file type, if possible. Currently, this will only work to convert SCALAR to ARRAY or ARRAY to SCALAR.
Enter:
$variable = name of variable to be coerced.
$targettype = type of variable to be created (SCALAR or ARRAY)
Exit:
1 if successful
0 if unable to coerce.
NOTE: Coercing an ARRAY to SCALAR will result in the first element
of the array being assigned to the new scalar. All other elements
will be discarded!
Create a variable in the variable hash.
Enter:
$variable = name of variable to create.
$type = variable type ==> SCALAR, ARRAY or HASH
Exit:
1 if successful
0 if error (e.g. duplicate entry)
Delete a variable from the variable hash.
Enter:
$variable = name of variable to delete.
Exit:
none.
Return the alias hash.
Enter:
none.
Exit:
%aliasHash
undef if does not exist
Return a reference to the alias hash.
Enter:
none.
Exit:
\%aliasHash
undef if does not exist
Get/set the array element value.
Enter:
$variable = name of array.
$index = array element.
$value = optional value to set.
Exit:
$value if successful
undef if error or $value = undef
Return a reference to the requested array.
Enter:
$variable = name of array.
Exit:
$ref = reference to the array (in scalar mode),
@array = array copy (in list mode).
undef if array does not exist.
Set callback attribute method for the specified variable. This callback will be used for both virtual (alias) and actual variables.
Enter:
$variable = name of variable/alias.
$callback = pointer to attribute method to invoke for this $variable.
Exit:
1 if successful
undef if variable not defined.
Get/set the $key, $value in the specified hash.
Enter:
$variable = name of hash.
$key = name of hash key.
$value = value to set.
Exit:
$value if $variable{$key} exists
undef if error or $value is undef
Return a reference to the requested hash.
Enter:
$variable = name of hash.
Exit:
$ref = reference to the hash.
undef if hash does not exist.
Pop the value off of the specified array.
Enter:
$variable = name of array to 'pop'.
Exit:
$value if successful
undef if error or $value is undefined.
Push the value on to the specified array.
Enter:
$variable = name of array to 'push' on.
$value = value to push.
Exit:
1 if successful,
0 if error
Return the readonly status of the specified variable.
Enter:
$variable = variable to return status of.
$status = 1=read-only, 0=read-write.
Exit:
$status = read-only state (1=read-only, 0=read-write)
undef if not defined.
Ref returns the type of variable stored in $variable.
Enter:
$variable = name of variable to type.
Exit:
'SCALAR', 'ARRAY' or 'HASH'
undef if does not exist or invalid
Return the number of items in the specified array.
Enter:
$variable = name of array.
Exit:
$size = number of items in array
undef if not an array variable.
Shift the first value off of the specified array.
Enter:
$variable = name of array to 'shift'.
Exit:
$value if successful
undef if error or $value is undefined.
Get/set variable value.
Enter:
$variable = name of variable.
if the variable is an array, the next field will be the array index,
followed by the optional value to set.
if the variable is a hash, the next field will be the hash key,
followed by the optional value to set.
if the variable is a scalar, the next field will be the optional value to set.
Exit:
$value = current variable value.
undef if variable does not exist or value is undefined, or index/key is missing.
Return 0 if variable does NOT exist, otherwise return 1 for SCALAR, 2 for ARRAY and 3 for HASH.
Enter:
$variable = name of variable or alias to check.
Exit:
1, 2, or 3 if variable (or alias) exists
0 if doesn't exist
Return the variable hash.
Enter:
none.
Exit:
%variableHash
undef if does not exist
Return a reference to the variable hash.
Enter:
none.
Exit:
\%variableHash
undef if does not exist
The AUTOLOAD method is called whenever an unresolved attribute method is referenced. If the attribute method name is the same as a defined variable or alias, the value is updated, if supplied, and the current value of the variable is returned.
Enter:
method name = variable/alias to set/fetch.
Exit:
undef if not variable/alias
variable value if variable/alias
_loadEnvironment loads the current environment into the variable hash.
Environment variables are accessed by prefixing their names with ENV_ (e.g. the environment variable HOME would accessed by the name ENV_HOME).
Enter:
none.
Exit:
none.
_parseCommandArguements parses the program arguements into the variables hash.
Command line arguements assumed to be in form:
-arg1 -arg2 value2 -arg3 value3
Enter:
none.
Exit:
none.
Jay Wheeler (jaywheeler@geocities.com), EarthWalk Software.
http://www.geocities.com/jaywheeler.geo
EWS::variables is copyright © 2002. EarthWalk Software.
This module is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
This module is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this script; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA, or from the Free Software Foundation web page at
http://www.fsf.org/licenses/lgpl.txt