Description:

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 Configuration.

Exceptions

alib::config::Exceptions::ErrorWritingFile

Definition at line 26 of file inifilefeeder.hpp.

#include <inifilefeeder.hpp>

Collaboration diagram for IniFileFeeder:

[legend]

Public Field Index:
String	DefaultCommentPrefix =A_CHAR("# ")

int	LineWidth = 100

Public Method Index:
	IniFileFeeder (Configuration &pConfiguration, Priority pPriority=Priority::ConfigFile)

virtual	~IniFileFeeder ()

ALIB_API int	AddResourcedSectionComments (ResourcePool &resourcePool, const NString &resourceCategory, const NString &resourceNamePrefix)

bool	Export (const String &path)

ALIB_API bool	Export (const Variable &var)

void	ExportEnd ()
	Closes and deletes the internal iniFile instance without writing an opened INI-file.

void	ExportEnd (const lang::system::Path &path)

IniFile *	ExportStart (const lang::system::Path &path)

ALIB_API int	ExportSubTree (Configuration::Cursor cursor, bool directChildrenOnly=false)

int	ExportSubTree (const String &path, bool directChildrenOnly=false)

IniFile &	GetIniFile ()

ALIB_API int	ImportAll ()

void	ImportEnd ()
	Closes and deletes the internal iniFile instance.

ALIB_API int	ImportSection (const String &sectionName)

ALIB_API int	ImportSection (const String &sectionName, const String &typeName)

IniFile *	ImportStart (const lang::system::Path &path)

ALIB_API std::pair< IniFile::Section , IniFile::Entry >	SearchEntry (const String &path)

ALIB_API std::pair< IniFile::Section , IniFile::Entry >	SearchEntry (const Variable &variable)

ALIB_API bool	SetWriteBackFlag (const String &path)

ALIB_API 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:
ALIB_API int	importSection (IniFile::Section &section)

Field Details:

◆ configuration

Configuration& configuration

protected

The configuration to work with. Set with construction.

Definition at line 31 of file inifilefeeder.hpp.

◆ DefaultCommentPrefix

String 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 58 of file inifilefeeder.hpp.

◆ iniFile

IniFile* iniFile = nullptr

protected

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

Definition at line 37 of file inifilefeeder.hpp.

◆ LineWidth

int LineWidth = 100

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

Definition at line 51 of file inifilefeeder.hpp.

◆ priority

Priority priority

protected

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

Definition at line 34 of file inifilefeeder.hpp.

Constructor(s) / Destructor Details:

◆ IniFileFeeder()

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

inline

Constructor.

Parameters

pConfiguration	Stored in field configuration.
pPriority	Stored in field priority. ConfigFile.

Definition at line 66 of file inifilefeeder.hpp.

◆ ~IniFileFeeder()

virtual ~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 73 of file inifilefeeder.hpp.

Method Details:

◆ AddResourcedSectionComments()

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

Here is the call graph for this function:

◆ Export() [1/2]

bool 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 193 of file inifilefeeder.hpp.

Here is the call graph for this function:

◆ Export() [2/2]

bool 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 "INIWB") 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 167 of file inifilefeeder.cpp.

Here is the call graph for this function:

◆ ExportEnd() [1/2]

void ExportEnd ( )

inline

Closes and deletes the internal iniFile instance without writing an opened INI-file.

Definition at line 154 of file inifilefeeder.hpp.

Here is the call graph for this function:

◆ ExportEnd() [2/2]

void ExportEnd ( const lang::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 159 of file inifilefeeder.hpp.

Here is the call graph for this function:

◆ ExportStart()

IniFile * ExportStart ( const lang::system::Path & path )

inline

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

Here is the call graph for this function:

◆ ExportSubTree() [1/2]

int 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 "INIWB") 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 214 of file inifilefeeder.cpp.

Here is the call graph for this function:

◆ ExportSubTree() [2/2]

int 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 230 of file inifilefeeder.hpp.

Here is the call graph for this function:

◆ GetIniFile()

IniFile & 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 310 of file inifilefeeder.hpp.

◆ ImportAll()

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

Here is the call graph for this function:

◆ ImportEnd()

void ImportEnd ( )

inline

Closes and deletes the internal iniFile instance.

Definition at line 142 of file inifilefeeder.hpp.

◆ ImportSection() [1/2]

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

Here is the call graph for this function:

◆ ImportSection() [2/2]

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

Here is the call graph for this function:

◆ importSection()

int importSection ( IniFile::Section & section )

protected

Implements ImportSection.

Parameters

section The section to import

Returns: The number of variables imported.

Definition at line 97 of file inifilefeeder.cpp.

Here is the call graph for this function:

◆ ImportStart()

IniFile * ImportStart ( const lang::system::Path & path )

inline

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

◆ SearchEntry() [1/2]

std::pair< IniFile::Section *, IniFile::Entry * > 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 31 of file inifilefeeder.cpp.

Here is the call graph for this function:

◆ SearchEntry() [2/2]

std::pair< IniFile::Section *, IniFile::Entry * > 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 48 of file inifilefeeder.cpp.

Here is the call graph for this function:

◆ SetWriteBackFlag() [1/2]

bool 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 Configuration.

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

Here is the call graph for this function:

◆ SetWriteBackFlag() [2/2]

bool SetWriteBackFlag ( const Variable & var )

Invokes overloaded method SetWriteBackFlag(const String& path).

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 299 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

◆ iniFile

◆ LineWidth

◆ priority

Constructor(s) / Destructor Details:

◆ IniFileFeeder()

◆ ~IniFileFeeder()

Method Details:

◆ AddResourcedSectionComments()

◆ 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]