forked from lix-project/lix
config.hh: Add documentation
Provides some general overview on the mechanics of Config/Setting and comments for the public methods of Config.
This commit is contained in:
parent
9df3d8ccd7
commit
fc137d2f00
|
@ -7,6 +7,38 @@
|
|||
|
||||
namespace nix {
|
||||
|
||||
/**
|
||||
* The Config class provides Nix runtime configurations.
|
||||
*
|
||||
* What is a Configuration?
|
||||
* A collection of uniquely named Settings.
|
||||
*
|
||||
* What is a Setting?
|
||||
* Each property that you can set in a configuration corresponds to a
|
||||
* `Setting`. A setting records value and description of a property
|
||||
* with a default and optional aliases.
|
||||
*
|
||||
* A valid configuration consists of settings that are registered to a
|
||||
* `Config` object instance:
|
||||
*
|
||||
* Config config;
|
||||
* Setting<std::string> systemSetting{&config, "x86_64-linux", "system", "the current system"};
|
||||
*
|
||||
* The above creates a `Config` object and registers a setting called "system"
|
||||
* via the variable `systemSetting` with it. The setting defaults to the string
|
||||
* "x86_64-linux", it's description is "the current system". All of the
|
||||
* registered settings can then be accessed as shown below:
|
||||
*
|
||||
* std::map<std::string, Config::SettingInfo> settings;
|
||||
* config.getSettings(settings);
|
||||
* config["system"].description == "the current system"
|
||||
* config["system"].value == "x86_64-linux"
|
||||
*
|
||||
*
|
||||
* The above retrieves all currently known settings from the `Config` object
|
||||
* and adds them to the `settings` map.
|
||||
*/
|
||||
|
||||
class Args;
|
||||
class AbstractSetting;
|
||||
class JSONPlaceholder;
|
||||
|
@ -23,6 +55,10 @@ protected:
|
|||
|
||||
public:
|
||||
|
||||
/**
|
||||
* Sets the value referenced by `name` to `value`. Returns true if the
|
||||
* setting is known, false otherwise.
|
||||
*/
|
||||
virtual bool set(const std::string & name, const std::string & value) = 0;
|
||||
|
||||
struct SettingInfo
|
||||
|
@ -31,19 +67,52 @@ public:
|
|||
std::string description;
|
||||
};
|
||||
|
||||
/**
|
||||
* Adds the currently known settings to the given result map `res`.
|
||||
* - res: map to store settings in
|
||||
* - overridenOnly: when set to true only overridden settings will be added to `res`
|
||||
*/
|
||||
virtual void getSettings(std::map<std::string, SettingInfo> & res, bool overridenOnly = false) = 0;
|
||||
|
||||
/**
|
||||
* Parses the configuration in `contents` and applies it
|
||||
* - contents: configuration contents to be parsed and applied
|
||||
* - path: location of the configuration file
|
||||
*/
|
||||
void applyConfig(const std::string & contents, const std::string & path = "<unknown>");
|
||||
|
||||
/**
|
||||
* Applies a nix configuration file
|
||||
* - path: the location of the config file to apply
|
||||
*/
|
||||
void applyConfigFile(const Path & path);
|
||||
|
||||
/**
|
||||
* Resets the `overridden` flag of all Settings
|
||||
*/
|
||||
virtual void resetOverriden() = 0;
|
||||
|
||||
/**
|
||||
* Outputs all settings to JSON
|
||||
* - out: JSONObject to write the configuration to
|
||||
*/
|
||||
virtual void toJSON(JSONObject & out) = 0;
|
||||
|
||||
/**
|
||||
* Converts settings to `Args` to be used on the command line interface
|
||||
* - args: args to write to
|
||||
* - category: category of the settings
|
||||
*/
|
||||
virtual void convertToArgs(Args & args, const std::string & category) = 0;
|
||||
|
||||
/**
|
||||
* Logs a warning for each unregistered setting
|
||||
*/
|
||||
void warnUnknownSettings();
|
||||
|
||||
/**
|
||||
* Re-applies all previously attempted changes to unknown settings
|
||||
*/
|
||||
void reapplyUnknownSettings();
|
||||
};
|
||||
|
||||
|
|
Loading…
Reference in a new issue