#include <BALL/FORMAT/INIFile.h>

Classes
class	IteratorTraits_
	Interface for the LineIterator. More...

class	Section

Public Types
enum	{ MAX_LINE_LENGTH = 1048576 }

typedef std::list< Section > ::iterator	SectionIterator

typedef IteratorTraits_	LineIterator

Public Member Functions
bool	apply (UnaryProcessor< LineIterator > &processor)

void	setDuplicateKeyCheck (bool mode)

bool	duplicateKeyCheckEnabled () const

std::list< String >	getContent () const

bool	setContent (const std::list< String > &lines)

Constructors and Destructors
	INIFile ()

	INIFile (const String &filename)

virtual	~INIFile ()

void	clear ()

File I/O and related
bool	read ()

bool	write ()

const String &	getFilename () const

void	setFilename (const String &filename)

Debugging and Diagnostics
bool	isValid () const

Methods for line-wise access.
The INIFile can be accessed line-wise (ignoring the section structure). Each line can be accessed via its index (starting with 0) by getLine and modified by setLine . The index has to be less than the value returned by getNumberOfLines .
LineIterator	getLine (Size line_number)

Methods for access with an iterator.
The INIFile may be also accessed with an LineIterator.
bool	setLine (LineIterator line_it, const String &line)

bool	deleteLine (LineIterator line_it)

bool	insertLine (LineIterator line_it, const String &line)

Methods for access per section.
bool	appendLine (const String &section_name, const String &line)

bool	appendLine (const String &line)
	Append a line to the last section. More...

Size	getNumberOfLines () const

bool	hasSection (const String &section_name) const

SectionIterator	getSection (const String &section_name)

SectionIterator	getSection (Position pos)

Size	getNumberOfSections () const

LineIterator	getSectionFirstLine (const String &section_name)

LineIterator	getSectionLastLine (const String &section_name)

Size	getSectionLength (const String &section_name) const

bool	deleteSection (const String &section)

bool	appendSection (const String &section)

Methods to access single entries
bool	hasEntry (const String &section, const String &key) const

String	getValue (const String &section, const String &key) const

bool	setValue (const String &section, const String &key, const String &value)

bool	insertValue (const String &section, const String &key, const String &value)

const INIFile &	operator= (const INIFile &file)

Predicates
bool	operator== (const INIFile &inifile) const

bool	isValid (const LineIterator &it) const

bool	isValid (const SectionIterator &it) const

Static Public Attributes
static const String	UNDEFINED

static const String	HEADER

Protected Attributes
bool	check_duplicate_keys_

bool	valid_

String	filename_

std::list< Section >	sections_

StringHashMap< SectionIterator >	section_index_

Detailed Description

INIFile. This class provides support to read and evaluate the contents of Windows-style INI files.

Definition at line 28 of file INIFile.h.

Member Typedef Documentation

typedef IteratorTraits_ BALL::INIFile::LineIterator

An iterator for the lines in an INIFile. With a LineIterator it is easy to iterate over all lines in an instance of INIFile.

Definition at line 91 of file INIFile.h.

typedef std::list<Section>::iterator BALL::INIFile::SectionIterator

Definition at line 85 of file INIFile.h.

Member Enumeration Documentation

anonymous enum

Enum for constants

Enumerator
MAX_LINE_LENGTH	Maximum line length for each entry (1048576)

Definition at line 34 of file INIFile.h.

Constructor & Destructor Documentation

BALL::INIFile::INIFile ( )

Default constructor. The state of valid_ is set to false. An instance is valid if it is read or written successfully.

BALL::INIFile::INIFile ( const String & filename )

Constructor with filename The file is not opend.

virtual BALL::INIFile::~INIFile ( )

virtual

Destructor.

Member Function Documentation

bool BALL::INIFile::appendLine	(	const String &	section_name,
		const String &	line
	)

Append a line to a section. To add a line to the HEADER use INIFile::HEADER as section_name. If the given section does not exists, false is returned. Lines starting with "[" cannot be added (to prevent problems with section headers). If checking for duplicate keys is enabled and line contains a key, the section already contains, the method aborts and returns false, use setValue() instead. If an empty string is given as value for section_name, the last section is used.

Parameters

section_name	the section to add the line
line	the line to be added

See also: setDuplicateKeyCheck

Returns: true, if line could be added

bool BALL::INIFile::appendLine ( const String & line )

Append a line to the last section.

bool BALL::INIFile::appendSection ( const String & section )

Append a section. If the given section does already exists, false is returned.

bool BALL::INIFile::apply ( UnaryProcessor< LineIterator > & processor )

Apply a processor to all lines of the file.

void BALL::INIFile::clear ( )

Clear the internal datastructures. Clear frees all allocated memory but retains the filename set for the INIFile object.

bool BALL::INIFile::deleteLine ( LineIterator line_it )

Delete a line. If the line does not exists, false is returned. Section headers can not be removed with this method. If the line contains a key, it will be removed.

Parameters

line_number the line to delete

bool BALL::INIFile::deleteSection ( const String & section )

Delete a section. If the given section does not exist, false is returned. If you remove the header, all lines of the header are removed, but the header itself still remains as section in the instance.

bool BALL::INIFile::duplicateKeyCheckEnabled ( ) const

Get checking mode for duplicate keys

std::list<String> BALL::INIFile::getContent ( ) const

const String& BALL::INIFile::getFilename ( ) const

Returns the current filename.

LineIterator BALL::INIFile::getLine ( Size line_number )

Return the contents of the specified line. If the line_number given is not valid (less than 0 or greater/equal to the number returned by getNumberOfLines ) a non-valid iterator is returned. Use of this method is not recommended, because in the worst case, it could be O(n).

Parameters

line_number,first line starts with 0

Returns: LineIterator to the specified line

Size BALL::INIFile::getNumberOfLines ( ) const

Return number of lines.

Size BALL::INIFile::getNumberOfSections ( ) const

Count all sections. The HEADER is not counted!

SectionIterator BALL::INIFile::getSection ( const String & section_name )

Return an iterator to a section with a given name.

Returns

SectionIterator

iterator to the section

SectionIterator BALL::INIFile::getSection ( Position pos )

Return an iterator to a section at a given position.

Returns

SectionIterator

iterator to the section

LineIterator BALL::INIFile::getSectionFirstLine ( const String & section_name )

Returns an iterator to the first line of a section. The first line of a section is the line with the section name (in square brackets).

Returns

LineIterator

iterator to the first line of the section
unvalid iterator, if section does not exist

Parameters

section_name the name of the section to be found

LineIterator BALL::INIFile::getSectionLastLine ( const String & section_name )

Returns an iterator to the last line of a section.

Returns

LineIterator

iterator to the last line of the section
unvalid iterator, if section does not exist

Parameters

section_name the name of the section to be found

Size BALL::INIFile::getSectionLength ( const String & section_name ) const

Returns the number of lines in a section.

Returns

Size

the number of lines, or
INVALID_SIZE if the section could not be found

Parameters

section_name the name of the section to be found

String BALL::INIFile::getValue	(	const String &	section,
		const String &	key
	)		const

Query the value corresponding to a given key. If no value exists for the given key, or either the section or the key are not defined, UNDEFINED is returned.

Parameters

section	the section name to look in for the key
key	a key in the section

Returns

String

the value corresponding to the key in section
or UNDEFINED

bool BALL::INIFile::hasEntry	(	const String &	section,
		const String &	key
	)		const

Check whether the given section contains a certain key.

Returns

bool

true if the key could be found in the section,
false if either key or section didn't exist

Parameters

section	the section to look in for the key
key	the key to look for

bool BALL::INIFile::hasSection ( const String & section_name ) const

Queries for a certain section.

Parameters

section_name the name of the section (without square brackets)

Returns

bool

true if the section exists (is hashed!)
false if the section could not be found

bool BALL::INIFile::insertLine	(	LineIterator	line_it,
		const String &	line
	)

Add a line after a given iterator. Lines starting with "[" cannot be added (to prevent problems with section headers). If the line contains a key and the section already contains this key the method aborts and returns false, use setValue() instead.

Parameters

line_it	the iterator to insert after
line	the line to be added

Returns: true, if line could be added

bool BALL::INIFile::insertValue	(	const String &	section,
		const String &	key,
		const String &	value
	)

Insert a new value in a given section If the key exists already or the sections doesnt exist, nothing happens.

Parameters

section	the section to insert the key
key	the key to insert
value	the new value

Returns

bool

true if the value was inserted
false if key or section do not exist

bool BALL::INIFile::isValid ( ) const

Returns the current state of the instance of INIFile. An instance is valid if it is read or writen succesfully.

bool BALL::INIFile::isValid ( const LineIterator & it ) const

Test if the given LineIterator is valid for this instance.

bool BALL::INIFile::isValid ( const SectionIterator & it ) const

Test if the given SectionIterator is valid for this instance.

const INIFile& BALL::INIFile::operator= ( const INIFile & file )

bool BALL::INIFile::operator== ( const INIFile & inifile ) const

Equality operator. Two instances are equal if they have the same sections with the same lines.

bool BALL::INIFile::read ( )

Open a file and read its contents. This method destroys all existing data in memory and then tries to open the file specified by setFilename. If the file could not be opened, the method returns false, leaving the INIFile instance in invalid state (as returned by isValid ).

: If the file could be opened, the whole file is read into an internal buffer and the different sections are interpreted. Then, internal datastructures for fast access to the stored data are build (Hashtable containing the sections).

: Lines starting with '!', ';', or '#' are treated as comment lines and stored, but not interpreted. Key-names and values are trimmed. If a line starts with "[", but no closing bracket occurs, false is returned.

Returns

bool

true if the file could be opened and read
false otherwise

bool BALL::INIFile::setContent ( const std::list< String > & lines )

void BALL::INIFile::setDuplicateKeyCheck ( bool mode )

Set checking for duplicate keys mode

void BALL::INIFile::setFilename ( const String & filename )

Sets a new filename. The state of valid_ is set to false.

bool BALL::INIFile::setLine	(	LineIterator	line_it,
		const String &	line
	)

Change the contents of a line. Replaces the line given by line_it by the text in line. Section lines cannot be changed with this method. If the line contains a key, the old key is deleted and the new (if any) is set. If the line starts with "[" the method aborts.

Parameters

line_it	iterator to the line to change
line	new content of the line

bool BALL::INIFile::setValue	(	const String &	section,
		const String &	key,
		const String &	value
	)

Change the value corresponding to a given key. Replaces the value of an existing key in an existing section. If the key or the new value is a empty string nothing is changed.

Parameters

section	the section to look in for the key
key	the key to look for
value	the new value

Returns

bool

true if the value was changed
false if key or section do not exist

bool BALL::INIFile::write ( )

Writes the buffer contents to a file. If the file could not be written, valid_ is set to false, ow true.

Returns

bool

true if the file could be succesfully written
false otherwise

Member Data Documentation

bool BALL::INIFile::check_duplicate_keys_

protected

Definition at line 424 of file INIFile.h.

String BALL::INIFile::filename_

protected

Definition at line 428 of file INIFile.h.

const String BALL::INIFile::HEADER

static

Name of the HEADER section: $ "\#HEADER!" $

Definition at line 101 of file INIFile.h.

StringHashMap<SectionIterator> BALL::INIFile::section_index_

protected

Definition at line 434 of file INIFile.h.

std::list<Section> BALL::INIFile::sections_

protected

Definition at line 431 of file INIFile.h.

const String BALL::INIFile::UNDEFINED

static

Return type for undefined keys "[UNDEFINED!]"

Definition at line 96 of file INIFile.h.

bool BALL::INIFile::valid_

protected

Definition at line 426 of file INIFile.h.

Classes

Public Types

Public Member Functions

Static Public Attributes

Protected Attributes

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation