view release on metacpan or  search on metacpan

Framework.pod  view on Meta::CPAN

the file is not found in any of those locations, we look in the home directorry of the user executing
the process (this is determined via $ENV{'HOME'}). Using this precendenc allowes a great deal of
flexibility ... just remember to keep tour config file names unique! ;-)

=item	configNamespace

IF the file you are loading DOES NOT specify it's own configNamespace, you can specify one explicity
in the function call using this parameter. This should be a string you would like to use for the 
configNamespace-less file you are loading.

=item	Parent

you may specify a parent namespace under which to nest the configNamespace of the file you are
loading. For instance. If I have an application called 'Daleks' which has a config file with a
configNamespace of 'Dalek' and a user preferences file which specifies the configNamespace
'usersDalekConfig', then I might do something like:


$object->LoadCondfig(
	File	=> "usersDalekConfig.xml",
	Parent	=> "Dalek"
);

this would load the user-specific config file UNDER the 'Dalek' configNamespace, so that I could 
access the user-specific data thusly

$object->{'Dalek'}->{'usersDalekConfig'}->{'someKey'};

=item	Crypt

LoadConfig has the capability to decrypt and load config files encrypted via one of the CBC compliant
Crypt::* modules. This option specifies the Crypt::* subclass that you would like to use to decrypt
the specified config file (presuming it is encrypted). For instance, if you wanted to load 
the file "mySecretConfig.xml" which was encrypted using the Crypt::Rijndael module you would do
something like:

$object->LoadConfig(
	File	=> "mySecretConfig.xml",
	Crypt	=> "Rijndael",
	Key		=> $mySecretKey
) || die $object->{'errstr'};

NOTE: this option defaults to the Crypt::* subclass specified when the module was built, if not
explicitly defined either at this function call or at object instantiation.

=item	Key

(see Crypt option above). This is the passphrase to be used to decrypt the configuration file using
the Crypt::* subclass specified on the 'Crypt' option.

NOTE: this option defaults to the passphrase specified when the module was built, if not
explicitly defined either at this function call or at object instantiation.

=back



=head1	WriteConfig 

This will write the data under some configNamespace in the object to the file it was loaded out of, 
or alternately to a different specified file. Encrypted data is handled transparently.

$object->WriteConfig(configNamespace => "usersDalekConfig.xml") || die $object->{'errstr'};

=head2	options

=over

=item	configNamespace (required)

This should be a string indicating the configNamespace that you want to dump back into the spcified
file. Obviously, the configNamespace that you specify must already exist in the current object.

=item	File

This is the file that you want to write the data contained in the specified 'configNamespace' back
out to. If this option is not specified explicitly, then the file from which the specified 
configNamespace was loaded is used. The same file location precidence that is used in LoadConfig
is maintained here. That if the file as specified is not writeable, then we look first under
v_root/config_loc, then v_root/config_loc/ApplicationFrameworks/$object->{'program'} and lastly
in the user's home directory.

=item	Encrypt

if set to a non-zero value, this will cause the file which is being written out to be encrypted with
either the specified Key and Crypt or the default options given when the module was built.
NOTE: setting this option is not necessary if you are writing data back to a file which was encrypted
when you originally loaded it, this option is only necesary if you are encrypting a file which was
not previously encrypted, or if you are creating a new encrypted file.

=item	Crypt

This should be the CBC compliant Crypt::* subclass that you would like to use encrypt the data.
If not specified, this option defaults to the value givne when the module was built. For more 
information, see ReadConfig.

=item	Key

This should be a string contining the passphrase you want to use to encrypt the data with the
specified CBC compliant Crypt::* subclass. For more information, see ReadConfig.

=back



=head1	LoadXMLConfig

This function will load any specified file in the Data::DumpXML DTD. If a binary file is specified
it is presumed to be encrypted. Encrypted files are decrypted using either a specified Crypt::*
module and passphrase, or the default options specified when the module was built. Data is returned
via a hash reference, and is NOT loaded directly into the object.

$data = $object->LoadXMLConfig(File => "path/to/some/file.xml") || die $object->{'errstr'};

This is the backend to LoadConfig which handles inserting config data into the object under the
correct configNamespace, and also handles child configs and nested namespaces. If you just want to
get some raw data out of a file in the Data::DumpXML dtd, which might possibly be encrypted using 
a Crypt::* module which is CBC compliant, then this is the method you're looking for.

=head2	options