YGP::INIFile Class Reference

Class to handle the information of an INI-file (containing the settings of an application). More...

List of all members.

Public Member Functions

 INIFile (const char *filename) throw (YGP::FileError)
virtual ~INIFile ()
void addSection (const INISection &section)
INISectionaddSection (const char *section)
void addEntity (const Entity &obj, const char *section)
void addEntity (const Entity &obj, INISection &section)
int read () throw (YGP::ParseError)
void open () throw (YGP::FileError)
XifstreamgetFile ()

Protected Member Functions

virtual int foundSection (const char *section, unsigned int)
const INISectionfindSection (const char *name) const
const INISectionfindSection (const std::string &name) const
void overwrite () throw (YGP::ParseError, YGP::FileError)
static void writeSectionHeader (std::ostream &stream, const char *section)
static void write (std::ostream &stream, const char *section, const Entity &obj)


Detailed Description

Class to handle the information of an INI-file (containing the settings of an application).

Technically this works by binding names (strings) to the addresses of variables (in attributes). Whenever a key matching those names is found, the apropiate value of the key is (tried to) assigned to the variable.

This attributes are grouped into sections (every attribute principally belongs to a section. And a section ends with the start of a new section.). The result is an OS/2- and Windoze-like INI-file with the following syntax:

   [Section1]
   Key1=Value1
   Key2=2

   [Section2]
   Key3=03012000
   

The INI-file can also contain some comments. They must be on separate lines, start with a semi-colon (;) and go til the end of the line.

There are some predefined macros to make the generation of the data-structure to parse an INI-file easier. They must be used in that (top-down) order.

Note:
This macro defines a variable (of type INISection) called name.

Note:
This macro defines a variable (of type YGP::Attribute<type>) called name_.

Note:
This macro defines a variable (of type YGP::Attribute<type>) called name_.

Note:
This macro defines a variable (of type YGP::MetaEnumAttribute) called name_.

Note:
This macro defines a variable (of type YGP::MetaEnumAttribute) called name_.

To parse the INI-file above use the following commands:

      int Key1;
      std::string attr2;
      ADate Key3;

      INIFILE ("Test.ini");
      INISECTION (Section1);
      INIATTR (Section1, int, Key1);
      INIATTR2 (Section1, std::string, attr2, Key2);
      INISECTION (Section2);
      INIATTR (Section2, ADate, Key3);
   

Constructor & Destructor Documentation

YGP::INIFile::INIFile ( const char *  filename  )  throw (YGP::FileError)

Constructor; The parameter filename specifies the file to parse for initialization-information.

If this file does not exist, an exception is thrown.

Parameters:
filename Name of the INI file
Exceptions:
YGP::FileError If file couldn't be open a text describing the error
Remarks:
filename must be an ASCIIZ-string

YGP::INIFile::~INIFile (  )  [virtual]

Destructor.


Member Function Documentation

void YGP::INIFile::addEntity ( const Entity obj,
INISection section 
)

Adds all the attributes of the Entity to the passed section.

Parameters:
obj Object whose attributes should be added
section Section where to add the attributes

void YGP::INIFile::addEntity ( const Entity obj,
const char *  section 
) [inline]

Adds all attributes of an entity to the specified section.

INISection * YGP::INIFile::addSection ( const char *  section  ) 

Adds a section to parse to the INI-file; does nothing if section already exists.

Parameters:
section Name of the section
Returns:
INISection* Pointer to new (or existing) section

void YGP::INIFile::addSection ( const INISection section  ) 

Adds the passed section to the list of sections to parse.

Parameters:
section Specification of the section

const INISection * YGP::INIFile::findSection ( const char *  name  )  const [protected]

Searches the entries of the INI-file-object for a section with the passed name.

If a matching entry is found, a pointer to it is returned; else NULL.

Parameters:
name Name of section to find
Returns:
Section* Pointer to section or NULL (if not found)

int YGP::INIFile::foundSection ( const char *  section,
unsigned  int 
) [protected, virtual]

Callback if a section-header (to be exact: an identifier after the start-of-section character open bracket ([)) is found.

The default action is to check, if the section matches (case-sensitive!) the passed parameter. If yes, its attributes are parsed.

Parameters:
section Name of found section
int Unused length of the section name
Returns:
int PARSE_OK, if name of section is OK, else ParseObject::PARSE_CB_ABORT.

Xifstream& YGP::INIFile::getFile (  )  [inline]

Returns the stream the data is parsed from.

void YGP::INIFile::open (  )  throw (YGP::FileError)

Opens the file for reading.

If this file does not exist, an exception is thrown.

Exceptions:
YGP::FileError If file couldn't be open a text describing the error

void YGP::INIFile::overwrite (  )  throw (YGP::ParseError, YGP::FileError)

Overwrites the INI-file with the set values.

Remarks:
The stored sections/attributes of this INI-file are changed; so they can't be reused!
Exceptions:
YGP::FileError in case file-access fails somehow
  • YGP::ParseError in case of failing to parse the file (before overwriting it)

int YGP::INIFile::read (  )  throw (YGP::ParseError)

Tries to read the INI-file from the file.

First the section header is parsed. If the name of the section from the file is found in the list of sections, those sections are parsed. This step is repeated, until the end of the file is reached or a line is found which is neither a section-header, nor an attribute. The function returns ParseObject::PARSE_OK, if EOF is reached; else a non-zero value is returned or - depending on the error - an exception is thrown.

Returns:
int Status of reading: <0 hard error; 0 OK, >0 soft error
Exceptions:
YGP::ParseError With a message describing error in case of an invalid value

void YGP::INIFile::write ( std::ostream &  stream,
const char *  section,
const Entity obj 
) [static]

Writes an entity to the INI-file.

Every attribute of the object is written as "name=value".

Parameters:
stream File to write to
section Name of the section for all attributes in the object
obj Object to write
Remarks:
There is no error-handling; failures are silently ignored!

static void YGP::INIFile::writeSectionHeader ( std::ostream &  stream,
const char *  section 
) [inline, static]

Writes a header for the section to the passed stream.


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

YGP Version 0.9.31 - Generated on Wed Nov 18 11:25:27 2009 by doxygen 1.5.8