Description:

Adapter type between class IniFile and class Configuration. INI-file contents usually are 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 created locally 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

alib::variables::Exceptions::ErrorWritingFile

Definition at line 20 of file inifilefeeder.hpp.

#include <inifilefeeder.hpp>

Collaboration diagram for alib::variables::IniFileFeeder:

[legend]

Public Field Index:
String	DefaultCommentPrefix =A_CHAR("# ")
bool	DidNotExistOrWasEmpty =false
int	LineWidth = 100

Public Method Index:
	IniFileFeeder (Configuration &pConfiguration, Priority pPriority=Priority::ConfigFile)
virtual	~IniFileFeeder ()
int	AddResourcedSectionComments (ResourcePool &resourcePool, const NString &resourceCategory, const NString &resourceNamePrefix)
int	AddResourcedSectionComments (resources::ResourceHolder &resourceHolder, const NString &resourceNamePrefix)
bool	Export (const String &path)
bool	Export (const Variable &var)
void	ExportEnd ()
	Closes and deletes the internal iniFile instance without writing an opened INI-file.
void	ExportEnd (const Path &path)
int	ExportStart (const Path &path)
int	ExportSubTree (Configuration::Cursor cursor, bool directChildrenOnly=false)
int	ExportSubTree (const String &path, bool directChildrenOnly=false)
IniFile &	GetIniFile ()
int	ImportAll ()
void	ImportEnd ()
	Closes and deletes the internal iniFile instance.
int	ImportSection (const String &sectionName)
int	ImportSection (const String &sectionName, const String &typeName)
int	ImportStart (const Path &path)
IniFile::Handle	SearchEntry (const String &path)
IniFile::Handle	SearchEntry (const Variable &variable)
bool	SetWriteBackFlag (const String &path)
bool	SetWriteBackFlag (const Variable &var)

Protected Field Index:
Configuration &	configuration
	The configuration to work with. Set with construction.
IniFile *	iniFile = nullptr
	The INI-file. Created with methods ImportStart and ExportStart.
Priority	priority
	The priority to use to define variables. Set with construction.

Protected Method Index:
int	importSection (IniFile::Section &section)

Field Details:

◆ configuration

Configuration& alib::variables::IniFileFeeder::configuration

protected

The configuration to work with. Set with construction.

Definition at line 24 of file inifilefeeder.hpp.

◆ 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 50 of file inifilefeeder.hpp.

◆ DidNotExistOrWasEmpty

bool alib::variables::IniFileFeeder::DidNotExistOrWasEmpty =false

This flag may be read after invoking the method ExportStart, which will try to read the file first. If the file could not be opened or is empty, this flag is set. The flag may be used to decide, for example, if a file-comment or section comments should be generated.

Definition at line 56 of file inifilefeeder.hpp.

◆ iniFile

IniFile* alib::variables::IniFileFeeder::iniFile = nullptr

protected

The INI-file. Created with methods ImportStart and ExportStart.

Definition at line 30 of file inifilefeeder.hpp.

◆ LineWidth

int alib::variables::IniFileFeeder::LineWidth = 100

The desired maximum width of the INI-file. Defaults to 100. This value is used with utility method AddResourcedSectionComments.

Definition at line 43 of file inifilefeeder.hpp.

◆ priority

Priority alib::variables::IniFileFeeder::priority

protected

The priority to use to define variables. Set with construction.

Definition at line 27 of file inifilefeeder.hpp.

Constructor(s) / Destructor Details:

◆ IniFileFeeder()

alib::variables::IniFileFeeder::IniFileFeeder	(	Configuration &	pConfiguration,
		Priority	pPriority = Priority::ConfigFile )

inline

Constructor.

Parameters

pConfiguration	Stored in the field configuration.
pPriority	Stored in the field priority. Defaults to ConfigFile.

Definition at line 65 of file inifilefeeder.hpp.

◆ ~IniFileFeeder()

virtual alib::variables::IniFileFeeder::~IniFileFeeder ( )

inlinevirtual

Virtual destructor. Raises an ALib warning in debug-compilations, if the internal INI-file was not disposed before deletion. Disposal is made with methods ImportEnd and ExportEnd.

Definition at line 72 of file inifilefeeder.hpp.

Method Details:

◆ AddResourcedSectionComments() [1/2]

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 an INI-file, as even if no comments were 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 the method 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 203 of file inifilefeeder.cpp.

Here is the call graph for this function:

◆ AddResourcedSectionComments() [2/2]

int alib::variables::IniFileFeeder::AddResourcedSectionComments	(	resources::ResourceHolder &	resourceHolder,
		const NString &	resourceNamePrefix )

inline

This is a shortcut to the overloaded method, accepting a ResourceHolder instead of parameters resourcePool and resourceCategory.

Parameters

resourceHolder	A container holding a resource pool and a fixed category.
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 316 of file inifilefeeder.hpp.

Here is the call graph for this function:

◆ 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 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 201 of file inifilefeeder.hpp.

Here is the call graph for this function:

◆ 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 126 of file inifilefeeder.cpp.

Here is the call graph for this function:

◆ 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 164 of file inifilefeeder.hpp.

Here is the call graph for this function:

◆ ExportEnd() [2/2]

void alib::variables::IniFileFeeder::ExportEnd ( const 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 169 of file inifilefeeder.hpp.

◆ ExportStart()

int alib::variables::IniFileFeeder::ExportStart ( const Path & path )

inline

Creates the internal iniFile instance.

Parameters

path	The filepath to the INI-file.

Returns: The number of entries read. (The result of method int Read(const CPathString&) .)

Definition at line 138 of file inifilefeeder.hpp.

Here is the call graph for this function:

◆ ExportSubTree() [1/2]

int alib::variables::IniFileFeeder::ExportSubTree	(	Configuration::Cursor	cursor,
		bool	directChildrenOnly = false )

Writes all variables below the given 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 172 of file inifilefeeder.cpp.

Here is the call graph for this function:

◆ 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 237 of file inifilefeeder.hpp.

Here is the call graph for this function:

◆ 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 328 of file inifilefeeder.hpp.

◆ 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 107 of file inifilefeeder.cpp.

Here is the call graph for this function:

◆ ImportEnd()

void alib::variables::IniFileFeeder::ImportEnd ( )

inline

Closes and deletes the internal iniFile instance.

Definition at line 154 of file inifilefeeder.hpp.

◆ 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 92 of file inifilefeeder.cpp.

Here is the call graph for this function:

◆ 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 without declaring it.
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 32 of file inifilefeeder.cpp.

Here is the call graph for this function:

◆ importSection()

int alib::variables::IniFileFeeder::importSection ( IniFile::Section & section )

protected

Implements overloaded methods ImportSection(const String&).

Parameters

section The section to import

Returns: The number of variables imported.

Definition at line 64 of file inifilefeeder.cpp.

Here is the call graph for this function:

◆ ImportStart()

int alib::variables::IniFileFeeder::ImportStart ( const Path & path )

inline

Creates the internal iniFile instance.

Parameters

path	The filepath to the INI-file.

Returns: The number of entries read. (The result of method int Read(const CPathString&) .)

Definition at line 118 of file inifilefeeder.hpp.

◆ SearchEntry() [1/2]

IniFile::Handle alib::variables::IniFileFeeder::SearchEntry ( const String & path )

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 7 of file inifilefeeder.cpp.

Here is the call graph for this function:

◆ SearchEntry() [2/2]

IniFile::Handle alib::variables::IniFileFeeder::SearchEntry ( const Variable & variable )

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 22 of file inifilefeeder.cpp.

Here is the call graph for this function:

◆ 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 programmatically 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 234 of file inifilefeeder.cpp.

Here is the call graph for this function:

◆ SetWriteBackFlag() [2/2]

bool alib::variables::IniFileFeeder::SetWriteBackFlag ( const Variable & var )

Invokes overloaded method SetWriteBackFlag(const String&).

Parameters

var	The variable to modifiy.

Returns: true if the variable did exist and was newly added to the INI-file, false otherwise.

Definition at line 246 of file inifilefeeder.cpp.

Here is the call graph for this function:

The documentation for this class was generated from the following files:

Description:

Public Field Index:

Public Method Index:

Protected Field Index:

Protected Method Index:

Field Details:

◆ configuration

◆ DefaultCommentPrefix

◆ DidNotExistOrWasEmpty

◆ iniFile

◆ LineWidth

◆ priority

Constructor(s) / Destructor Details:

◆ IniFileFeeder()

◆ ~IniFileFeeder()

Method Details:

◆ AddResourcedSectionComments() [1/2]

◆ AddResourcedSectionComments() [2/2]

◆ Export() [1/2]

◆ Export() [2/2]

◆ ExportEnd() [1/2]

◆ ExportEnd() [2/2]

◆ ExportStart()

◆ ExportSubTree() [1/2]

◆ ExportSubTree() [2/2]

◆ GetIniFile()

◆ ImportAll()

◆ ImportEnd()

◆ ImportSection() [1/2]

◆ ImportSection() [2/2]

◆ importSection()

◆ ImportStart()

◆ SearchEntry() [1/2]

◆ SearchEntry() [2/2]

◆ SetWriteBackFlag() [1/2]

◆ SetWriteBackFlag() [2/2]