/**
* Acedia's `Feature`s store their configuration in separate classes
* derived from this one. They allow to provide `Feature`s with several config
* presets and, potentially, swap them on-the-fly.
* To create a new config object for a `Feature` use following template:
*
* ```unrealscript
* class <FEATURE_NAME> extends FeatureConfig
* perobjectconfig
* config(<FEATURE_CONFIG>);
*
* // ...
*
* defaultproperties
* {
* configName = "<FEATURE_CONFIG>"
* }
* ```
*
* For each `Feature` you need to define a new child class, along with
* implementing it's `FromData()`, `ToData()` and `DefaultIt()` methods.
* You will also need to implement `Feature`'s `SwapConfig()` method that take
* an instance of `FeatureConfig` as a parameter. Other than that you should
* avoid directly using objects of this class.
* Copyright 2021 Anton Tarasenko
*------------------------------------------------------------------------------
* This file is part of Acedia.
*
* Acedia is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, version 3 of the License, or
* (at your option) any later version.
*
* Acedia 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 General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with Acedia. If not, see <https://www.gnu.org/licenses/>.
*/
class FeatureConfig extends AcediaObject
dependson(AssociativeArray)
abstract;
// Name of the config object that was marked as "auto enabled".
// `none` iff none are set to be auto-enabled.
// Only it's default value is ever used.
var private Text autoEnabledConfig;
// All config of a particular class only get loaded once per session
// (unless new one is created) and then accessed through this collection.
// Only it's default value is ever used.
var private AssociativeArray existingConfigs;
// Stores name of the config where settings are to be stored.
// Must correspond to value in `config(...)` modifier in class definition.
var protected string configName;
// Setting that tells Acedia whether or not to enable feature,
// corresponding to this config during initialization.
// Only one version of any specific class should have this flag set to
// `true`. Otherwise any config with this flag will be picked as "auto enabled"
// and log warning will be given.
// Only it's default value is ever used.
var private config bool autoEnable;
var private LoggerAPI.Definition warningMultipleFeaturesAutoEnabled;
/* These methods must be overloaded to store and load all the config
* variables inside an `AssociativeArray` collection. How exactly to store
* them is up to each `Feature` to decide, as long as it allows conversion into
* JSON (see `JSONAPI.IsCompatible()` for details). Note, however, that boxes
* can value boxes and references should be considered interchangeable.
* For example, even if you always save `int` value as a `IntRef` in
* `ToData()` method, it might be stored as `IntBox` in `FromData()` call.
* And vice versa.
* NOTE: DO NOT use `P()`, `C()`, `F()` or `T()` methods for keys or
* values in collections you return. All keys and values will be automatically
* deallocated when necessary, so these methods for creating `Text` values are
* not suitable.
*/
protected function AssociativeArray ToData() { return none; }
protected function FromData(AssociativeArray source) {}
/**
* This method must be overloaded to setup default values for all config
* variables. You should use it instead of the `defaultproperties` block.
*/
protected function DefaultIt() {}
/**
* This loads all of the `FeatureConfig`'s settings objects into internal
* arrays. Must be called before any other methods.
*/
public static final function Initialize()
{
local int i;
local Text nextName;
local FeatureConfig nextConfig;
local array<string> names;
if (default.existingConfigs != none) {
return;
}
default.autoEnabledConfig = none;
default.existingConfigs = __().collections.EmptyAssociativeArray();
names = GetPerObjectNames( default.configName, string(default.class.name),
MaxInt);
for (i = 0; i < names.length; i += 1)
{
if (names[i] == "") {
continue;
}
nextName = __().text.FromString(names[i]);
nextConfig = new(none, nextName.ToPlainString()) default.class;
default.existingConfigs.SetItem(nextName.LowerCopy(), nextConfig);
if (nextConfig.autoEnable)
{
if (default.autoEnabledConfig == none)
{
default.autoEnabledConfig = nextName;
continue;
}
else
{
__().logger
.Auto(default.warningMultipleFeaturesAutoEnabled)
.ArgClass(default.class)
.Arg(default.autoEnabledConfig.Copy());
}
}
nextName.FreeSelf();
}
}
/**
* Returns name of the config object that is configured to be used for
* auto-enabled `Feature`.
*
* @return Name of the config object (case-insensitive), configured to be used
* for auto-enabled `Feature`. `none` if either class of the caller config
* object was not initialized or no config object was set to be used
* as auto-enabled.
*/
public static function Text GetAutoEnabledConfig()
{
if (default.autoEnabledConfig != none) {
return default.autoEnabledConfig.Copy();
}
return none;
}
/**
* Sets (by name) config object to be used when it's corresponding `Feature`
* is auto-enabled.
*
* @param autoEnabledConfigName Name (case-insensitive) of the config to
* be used when it's corresponding `Feature` is auto-enabled.
* Passing `none` or name of non-existing config will prevent it's
* `Feature` in question from being auto-enabled at all.
* @return `true` iff some config was set to be used when it's `Feature` is
* auto-enabled, even if the same config was already configured to be used.
*/
public static function bool SetAutoEnabledConfig(Text autoEnabledConfigName)
{
local Iter I;
local bool wasAutoEnabled;
local bool enabledConfig;
local Text nextConfigName;
local FeatureConfig nextConfig;
if (default.existingConfigs == none) {
return false;
}
I = default.existingConfigs.Iterate();
for (I = default.existingConfigs.Iterate(); !I.HasFinished(); I.Next(true))
{
nextConfigName = Text(I.GetKey());
nextConfig = FeatureConfig(I.Get());
wasAutoEnabled = nextConfig.autoEnable;
if (nextConfigName.Compare(autoEnabledConfigName, SCASE_INSENSITIVE))
{
default.autoEnabledConfig = autoEnabledConfigName.LowerCopy();
nextConfig.autoEnable = true;
enabledConfig = true;
}
else {
nextConfig.autoEnable = false;
}
if (wasAutoEnabled != nextConfig.autoEnable) {
nextConfig.SaveConfig();
}
}
return enabledConfig;
}
/**
* Returns array containing names of all available config objects.
*
* @return Array with names of all available config objects.
*/
public static function array<Text> AvailableConfigs()
{
local array<Text> emptyResult;
if (default.existingConfigs != none) {
return default.existingConfigs.CopyTextKeys();
}
return emptyResult;
}
/**
* Returns `FeatureConfig` of caller class with name `name`.
*
* @param name Name of the config object, whos settings data is to
* be loaded. Case-insensitive.
* @return `FeatureConfig` of caller class with name `name`.
*/
public final static function FeatureConfig GetConfigInstance(Text name)
{
local FeatureConfig requiredConfig;
if (default.existingConfigs == none) {
return none;
}
if (name != none) {
name = name.LowerCopy();
}
requiredConfig = FeatureConfig(default.existingConfigs.GetItem(name));
__().memory.Free(name);
return requiredConfig;
}
/**
* Loads Acedia's representation of settings data of a particular config
* object, given by the `name`.
*
* @param name Name of the config object, whos settings data is to
* be loaded.
* @return Settings data of a particular config object, given by the `name`.
* Expected to be in format that allows for JSON serialization
* (see `JSONAPI.IsCompatible()` for details).
* For correctly implemented config objects should only return `none` if
* their class was not yet initialized (see `self.Initialize()` method).
*/
public final static function AssociativeArray LoadData(Text name)
{
local AssociativeArray result;
local FeatureConfig requiredConfig;
requiredConfig = GetConfigInstance(name);
if (requiredConfig != none) {
result = requiredConfig.ToData();
}
return result;
}
/**
* Saves Acedia's representation of settings data (`data`) for a particular
* config object, given by the `name`.
*
* @param name Name of the config object, whos settings data is to
* be modified.
* @param data New data for config variables. Expected to be in format that
* allows for JSON deserialization (see `JSONAPI.IsCompatible()` for
* details).
*/
public final static function SaveData(Text name, AssociativeArray data)
{
local FeatureConfig requiredConfig;
if (name != none) {
name = name.LowerCopy();
}
if (default.existingConfigs != none) {
requiredConfig = FeatureConfig(default.existingConfigs.GetItem(name));
}
if (requiredConfig != none)
{
requiredConfig.FromData(data);
requiredConfig.SaveConfig();
}
__().memory.Free(name);
}
/**
* Creates a brand new config object with a given name.
*
* Fails if config object with that name already exists.
* Names are case-insensitive.
*
* @param name Name of the new config object.
* @return `true` iff new config object was created.
*/
public final static function bool NewConfig(Text name)
{
local FeatureConfig oldConfig, newConfig;
if (name == none) return false;
if (default.existingConfigs == none) return false;
oldConfig = FeatureConfig(default.existingConfigs.GetItem(name));
if (oldConfig != none) return false;
newConfig = new(none, name.ToPlainString()) default.class;
newConfig.DefaultIt();
newConfig.SaveConfig();
default.existingConfigs.SetItem(name.LowerCopy(), newConfig);
return true;
}
/**
* Deletes config object with a given name.
* Names are case-insensitive.
*
* If given config object exists, this method cannot fail.
*
* @param name Name of the config object to delete.
*/
public final static function DeleteConfig(Text name)
{
local AssociativeArray.Entry entry;
if (default.existingConfigs == none) {
return;
}
entry = default.existingConfigs.TakeEntry(name);
if (entry.value != none) {
entry.value.ClearConfig();
}
__().memory.Free(entry.value);
__().memory.Free(entry.key);
}
defaultproperties
{
usesObjectPool = false
autoEnable = false
warningMultipleFeaturesAutoEnabled = (l=LOG_Warning,m="Multiple configs for `%1` were marked as \"auto enabled\". This is likely caused by an erroneous config. \"%2\" config will be used.")
}
