Adapter type between class IniFile and class Configuration. INI-Files contents usually is fed in with bootstrapping an application and optionally be written out when an application ends (to populate empty INI-files or add new variables to existing ones). For this, an instance of this type is to be locally created each time. In other words, no instance of this type needs to be kept in memory during the life-span of an application.
- See also
- Chapter 7.3 Built-in Class IniFileFeeder of the Programmer's Manual of camp ALib Variables.
- Exceptions
-
Definition at line 19 of file inifilefeeder.inl.
◆ configuration
The configuration to work with. Set with construction.
Definition at line 24 of file inifilefeeder.inl.
◆ DefaultCommentPrefix
String alib::variables::IniFileFeeder::DefaultCommentPrefix =A_CHAR("# ") |
The prefix that is used for comment lines of sections or variables that have been added 'in code' (variables that have not been read from the file). Comments that were read from the file preserve their prefix. If comments including one of the valid prefixes are added to a variable or section 'in code', such prefix is preserved.
Definition at line 51 of file inifilefeeder.inl.
◆ iniFile
IniFile* alib::variables::IniFileFeeder::iniFile = nullptr |
|
protected |
◆ LineWidth
int alib::variables::IniFileFeeder::LineWidth = 100 |
◆ priority
Priority alib::variables::IniFileFeeder::priority |
|
protected |
The priority to use to define variables. Set with construction.
Definition at line 27 of file inifilefeeder.inl.
◆ IniFileFeeder()
alib::variables::IniFileFeeder::IniFileFeeder |
( |
Configuration & | pConfiguration, |
|
|
Priority | pPriority = Priority::ConfigFile ) |
|
inline |
◆ ~IniFileFeeder()
virtual alib::variables::IniFileFeeder::~IniFileFeeder |
( |
| ) |
|
|
inlinevirtual |
◆ AddResourcedSectionComments()
int alib::variables::IniFileFeeder::AddResourcedSectionComments |
( |
ResourcePool & | resourcePool, |
|
|
const NString & | resourceCategory, |
|
|
const NString & | resourceNamePrefix ) |
This is a utility function that reads section comments from externalized string resources.
All sections of the underlying INI-file are processed, but resourced comments are only added in the case that a section's comment string is nulled
. This is not the case if a section was read from from an INI-file, as even if no comments are given, the field is empty, but not nulled. In other words, only sections that have been programmatically added during the run of software are changed
This approach allows a user to remove the comments, without the software restoring them.
The resource names are assembled from given resourceNamePrefix and the section name The resource strings found are processed using method Paragraphs.AddMarked. This allows using text macros like '@HL' to format the text.
- See also
- Field LineWidth, which is respected when formatting comment lines.
- Parameters
-
resourcePool | The resource pool to use. |
resourceCategory | The category of the resourced comments. |
resourceNamePrefix | A prefix of the resource name. |
- Returns
- The number of section comments written. This is useful to detect if the INI-file needs to be written.
Definition at line 269 of file inifilefeeder.cpp.
◆ Export() [1/2]
bool alib::variables::IniFileFeeder::Export |
( |
const String & | path | ) |
|
|
inline |
Creates a variable cursor with the given cfg and path and passes it to overloaded method Export(const Variable&).
- Parameters
-
path | The path of the variable to export. |
- Returns
true
if the variable either did not exist yet in the INI-file or if it existed and the write-back mechanism was in place. false
otherwise.
Definition at line 189 of file inifilefeeder.inl.
◆ Export() [2/2]
bool alib::variables::IniFileFeeder::Export |
( |
const Variable & | var | ) |
|
Writes the given variable to the internal INI-file. If an INI-file was previously loaded, only those variables which are not existing in the INI-file are written. This method can thus be used to "populate" an empty INI-file with variables and their resourced or hard-coded default values and this way present all configurable options to an end-user.
Furthermore, a user can specify the word "writeback" (respectively what is resourced with to token "CFGIniWB"
) to force overwriting the INI-file contents with the current value of the variable.
- Parameters
-
var | The variable to export. |
- Returns
true
if the variable either did not exist yet in the INI-file or if it existed and the write-back mechanism was in place. false
otherwise.
Definition at line 182 of file inifilefeeder.cpp.
◆ ExportEnd() [1/2]
void alib::variables::IniFileFeeder::ExportEnd |
( |
| ) |
|
|
inline |
Closes and deletes the internal iniFile instance without writing an opened INI-file.
Definition at line 150 of file inifilefeeder.inl.
◆ ExportEnd() [2/2]
void alib::variables::IniFileFeeder::ExportEnd |
( |
const system::Path & | path | ) |
|
|
inline |
Writes the contents of the internal iniFile instance created with ExportStart into an (optionally) different file and then deletes the instance.
- Parameters
-
path | The file path for writing. |
Definition at line 155 of file inifilefeeder.inl.
◆ ExportStart()
Creates the internal iniFile instance.
- Parameters
-
path | The filepath to the INI-file. |
- Returns
- A pointer to the (otherwise internal) IniFile object that was opened. Use with caution. Could be used for example to detect the fact that the INI-file was empty or not found.
Definition at line 132 of file inifilefeeder.inl.
◆ ExportSubTree() [1/2]
int alib::variables::IniFileFeeder::ExportSubTree |
( |
Configuration::Cursor | cursor, |
|
|
bool | directChildrenOnly = false ) |
Writes all variables below the given StringTree::Cursor of the Configuration into the iniFile, previously created with ExportStart. If an INI-file was previously loaded, only those variables which are not existing in the INI-file are written. This method can thus be used to "populate" an empty INI-file with default values and this way present all configurable options to an end-user.
Furthermore, a user can specify the word "writeback" (respectively what is resourced with to token "CFGIniWB"
) to force overwriting the INI-file contents with the current value of the variable.
- Parameters
-
cursor | A cursor into the configuration's StringTree. |
directChildrenOnly | If true , only the direct children of this cursor are written as variables. Defaults to false . |
- Returns
- The number of variables exported. A negative value on error.
Definition at line 229 of file inifilefeeder.cpp.
◆ ExportSubTree() [2/2]
int alib::variables::IniFileFeeder::ExportSubTree |
( |
const String & | path, |
|
|
bool | directChildrenOnly = false ) |
|
inline |
Invokes ExportSubTree(Configuration::Cursor, bool) by creating a cursor from the given path
- Parameters
-
path | The path to the subtree (or single variable) to use. |
directChildrenOnly | If true , only the direct children of this path are written as variables. Defaults to false . |
- Returns
- The number of variables exported. A negative value on error.
Definition at line 227 of file inifilefeeder.inl.
◆ GetIniFile()
IniFile & alib::variables::IniFileFeeder::GetIniFile |
( |
| ) |
|
|
inline |
Allows access to the internal INI-file object created with either method ImportStart or ExportStart. In debug-compilations, this method asserts that an INI-file was opened. In release-compilations, a non-existing INI-file leads to undefined behavior.
- Returns
- The currently opened INI-File.
Definition at line 309 of file inifilefeeder.inl.
◆ ImportAll()
int alib::variables::IniFileFeeder::ImportAll |
( |
| ) |
|
Imports all entries found INI-file into the configuration. Variables which are already declared and have a lower priority definition, will be set with the value found. Otherwise, a preset string is set for the variable.
- Returns
- The number of variables imported.
Definition at line 161 of file inifilefeeder.cpp.
◆ ImportEnd()
void alib::variables::IniFileFeeder::ImportEnd |
( |
| ) |
|
|
inline |
◆ ImportSection() [1/2]
int alib::variables::IniFileFeeder::ImportSection |
( |
const String & | sectionName | ) |
|
Imports all entries in the section named sectionName in the underlying INI-file into the configuration.
- Parameters
-
sectionName | The name of the section to import. |
- Returns
- The number of variables imported.
Definition at line 143 of file inifilefeeder.cpp.
◆ ImportSection() [2/2]
int alib::variables::IniFileFeeder::ImportSection |
( |
const String & | sectionName, |
|
|
const String & | typeName ) |
Imports all entries in the section named sectionName in the underlying INI-file into the configuration. This special version of the method accepts parameter typeName and hence declares the variables in case they have not been declared, yet.
- Note
- This method is useful to load a section of variables of the same type with a) avoiding to set preset string and b) with the advantage that a using code may use Variable::Try to find the variable already.
This method may be used for example with camp ALib Expressions to declare nested expressions to an StandardRepository.
- Parameters
-
sectionName | The name of the section to import. |
typeName | The type of the variable to declare. |
- Returns
- The number of variables imported.
Definition at line 74 of file inifilefeeder.cpp.
◆ importSection()
◆ ImportStart()
Creates the internal iniFile instance.
- Parameters
-
path | The filepath to the INI-file. |
- Returns
- A pointer to the (otherwise internal) IniFile object that was opened. Use with caution. Could be used for example to detect the fact that the INI-file was empty or not found.
Definition at line 114 of file inifilefeeder.inl.
◆ SearchEntry() [1/2]
Searches the entry of the internal INI-file that represents the given variable determined by parameter path
- Parameters
-
path | The path of the variable to search in the INI-file. |
- Returns
- The section and entry if found. If not found, the second member of the pair is emtpy.
Definition at line 46 of file inifilefeeder.cpp.
◆ SearchEntry() [2/2]
Searches the entry of the internal INI-file that represents the given variable
- Parameters
-
variable | The variable to search in the INI-file. |
- Returns
- The section and entry if found. If not found, the second member of the pair is emtpy.
Definition at line 63 of file inifilefeeder.cpp.
◆ SetWriteBackFlag() [1/2]
bool alib::variables::IniFileFeeder::SetWriteBackFlag |
( |
const String & | path | ) |
|
This method may be used to set the writeback flag of an entry in the associated INI-file. The flag is only set if the entry was programmaticaly created (usually with one of the Export-methods of this class) and if it was not present in the INI-file before.
- See also
- Chapter 7.5 Writing Session Information of the Programmer's Manual of module ALib Variables.
- Parameters
-
path | The path of the variable to export. |
- Returns
true
if the variable did exist and was newly added to the INI-file, false
otherwise.
Definition at line 303 of file inifilefeeder.cpp.
◆ SetWriteBackFlag() [2/2]
bool alib::variables::IniFileFeeder::SetWriteBackFlag |
( |
const Variable & | var | ) |
|
The documentation for this class was generated from the following files: