BALL::INIFile Class Reference
[General Purpose File Formats]

#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.
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 & line )

Append a line to the last section.

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::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 ( Position pos )

Return an iterator to a section at a given position.

Returns:

SectionIterator

iterator to the section

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

Return an iterator to a section with a given name.

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 SectionIterator & it ) const

Test if the given SectionIterator is valid for this instance.

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

Test if the given LineIterator is valid for this instance.

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.

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: