Contains (persistent) module configuration info
The function Configuration() returns the class object of the Configuration class.
The Configuration class provides a means of bundling together all the data associated with configurable aspects of modules. As well, the class provides mechanisms for persistent storage of its instances via serialization and diskfile storage. As an adjunct to the persistence mechanism, the Configuration class has methods for handling the anticipatable event that the Configuration class is updated, which would cause the library version to differ from previously stored persistent instances.
The canonical method of accessing an instance of the Configuration class is via the Library Cfg() function (See the "Life Cycle" section of this page, and the Cfg() function documentation).
Each instance of the Configuration class contains a member :version that is used to indicate the currentness of the (possibly persistent) instance. The methods :uptoDate(), :verUpdate() and :antiquated() utilize the :version instance data member for comparison with the class :C_version data member
The Configuration instance member :savedCfg is always initialized as false; by definition, at time of creation an instance has not been read from persistent storage. The only action that can change the value of :savedCfg is reading back a serialized instance with the :fromDisk() method. The :toDisk() does not modify the value of :savedCfg (however, an instance serialized by :toDisk() will not normally become a runtime instance except when instantiated with :fromDisk()).
The Configuration class supports introspection via the standard data members :_data and :_methods.
The class data associated with persistence and versioning is declared in the parent class Persistent. See its documentation for details on those data members.
A Configuration instance comes into existence immediately upon its assignment with the Configuration():new() method. No seperate :create() method is required to request system resources.
A Configuration instance is destroyed when its variable falls out of its declaration scope. In principle, the variable containing a Configuration instance can be declared LOCAL to a function, and the exit condition of the controlling function will preform all necessary destruction of the instance.
However, in practical use, each module will access a single STATIC instance of the Configuration class via the Cfg() function. The instance managed by the Cfg() function is self-initializing and will de-serialize itself from diskfile if one is available. In other words, the Cfg() function can be treated as a globally available and persistent Configuration instance.
While the Cfg() function's Configuration instance will de-serialize itself from diskfile automatically, it will only be serialized with calls to the :toDisk() method. When changes are made to Configuration data that the programmers desires to be persistent, it is necessary to "commit" the changes with the :toDisk() method.
The instance data associated with persistence and versioning is declared in the parent class Persistent. See its documentation for details on those data members.
Since XBase++ does not allow redefinition of self, the methods :fromDisk() and :verUpdate() return the modified Configuration instance, but do not update the existing instance in-place.
Two data members, however, will be given Library/Class default values rather than the values existing in the calling instance. These are :version, which is not changed because all version-specific structure is updated in the returned instance; and :ColorScheme, which reinitialized under the (paranoid) assumption that the Class ColorScheme might have changed structure also.
Since XBase++ does not allow redefinition of self, the methods :fromDisk() and :verUpdate() return the modified Configuration instance, but do not update the existing instance in-place.
? Cfg():className() // Result: "Configuration"
// Check a configuration value
IF Cfg():GrayBar
DrawGraBox(22, 0, 23, 79, "FLAT_PALE_BIGTEXT", cTitle)
ENDIF
// Set, serialize, and save a configuration value
Cfg():GrayBar := .T.
Cfg():toDisk()
// Operate on instance via variable name
oCfg := Cfg()
oCfg:GrayBar := .F.
oCfg:toDisk("Temp.CFG")
// Read a serialized instance from a diskfile
oCfg := Configuration():new():fromDisk("MyFile.CFG")
// Check what is out-of-date in the restored instance
MsgBox( oCfg:antiquated() )
// Update the configuration to match current class definition
oCfg := oCfg:verUpdate()
Source file is Configuration.prg