Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Changeset 9881 in orxonox.OLD for trunk/src/lib


Ignore:
Timestamp:
Oct 10, 2006, 4:23:28 PM (18 years ago)
Author:
bensch
Message:

many doxygen tags

Location:
trunk/src/lib/parser/ini_parser
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/lib/parser/ini_parser/ini_parser.cc

    r9880 r9881  
    2121#include "ini_parser.h"
    2222
    23 #if HAVE_CONFIG_H
    24 #include <config.h>
    25 #endif
    26 
    2723#include <cassert>
    2824#include <algorithm>
    2925
    30 #ifdef DEBUG_LEVEL
    31  #include "../../../lib/util/debug.h"
    32 #else
    33  #define PRINTF(x) printf
    34  #define PRINT(x) printf
    35 #endif
     26#define PARSELINELENGHT     1024       //!< how many chars to read at once
    3627
    3728
    … …  
    3930/// INI-PARSER NODE ///
    4031/// /// /// /// /// ///
     32/**
     33 * @brief Constructs a Node
     34 * @param name The name of the Node
     35 * @param comment The comment of the Node.
     36 */
    4137IniParser::Node::Node(const std::string& name, const std::string& comment)
    4238{
    … …  
    4844/// INI-PARSER ENTRY ///
    4945/// /// /// /// /// ////
     46/**
     47 * @brief Constructs a new Entry
     48 * @param name the Name of the Entry
     49 * @param value The name of the Value
     50 * @param comment The Comment used for the Entry
     51 */
    5052IniParser::Entry::Entry(const std::string& name, const std::string& value, const std::string& comment)
    5153    : IniParser::Node(name, comment), _value(value)
    5254{}
    5355
     56/**
     57 * @brief Displays some nice debug info.
     58 */
    5459void IniParser::Entry::debug() const
    5560{
    … …  
    6166/// INI-PARSER SECTION  ///
    6267/// /// /// /// /// /// ///
     68/**
     69 * @brief constructs a new Section
     70 * @param sectionName The name of the Section
     71 * @param comment The Comment for this section
     72 */
    6373IniParser::Section::Section(const std::string& sectionName, const std::string& comment)
    6474    : IniParser::Node(sectionName, comment)
    6575{}
    6676
     77/**
     78 * @brief Adds a new Entry to this Section
     79 * @param entryName The name of the Entry
     80 * @param value The Value of the Section
     81 * @param comment The Comment
     82 * @returns Reference to the Entry added.
     83 * @see IniParser::Entry::Entry
     84 */
    6785IniParser::Entry& IniParser::Section::addEntry(const std::string& entryName, const std::string& value, const std::string& comment)
    6886{
    … …  
    7694}
    7795
     96/**
     97 * @brief edits an Entry's Value
     98 * @param entryName The Entry to edit
     99 * @param value The Value to change
     100 * @param createMissing If the Entry is missing it is created if true.
     101 * @return true on success.
     102 */
    78103bool IniParser::Section::editEntry(const std::string& entryName, const std::string& value, bool createMissing)
    79104{
    … …  
    93118}
    94119
     120/**
     121 * @param entryName The name of the entry to search for
     122 * @param defaultValue The returned value, if the entry is not found
     123 * @return The Value of the Entry, or defaultValue, if not found.
     124 */
    95125const std::string& IniParser::Section::getValue(const std::string& entryName, const std::string& defaultValue) const
    96126{
    … …  
    102132}
    103133
     134/**
     135 * @brief sets a Comment to an Entry
     136 * @param entryName The Name of the Entry to set the comment to.
     137 * @param comment the Comment.
     138 * @return true on success (entry found and setup).
     139 */
    104140bool IniParser::Section::setEntryComment(const std::string& entryName, const std::string& comment)
    105141{
    … …  
    113149}
    114150
     151/**
     152 * @brief retrieves a Comment of an Entry
     153 * @param entryName The Entry to get the comment of.
     154 * @return The Comment, or "" if the Entry was not found.
     155 */
    115156const std::string& IniParser::Section::getEntryComment(const std::string& entryName) const
    116157{
    … …  
    124165
    125166
     167/**
     168 * @brief retrieves a pointer to an Entry
     169 * @param entryName The Name of the Entry.
     170 * @return the located Entry or NULL!
     171 * @note beware of NULL!
     172 */
    126173IniParser::Entry* IniParser::Section::getEntry(const std::string& entryName)
    127174{
    … …  
    133180}
    134181
     182/**
     183 * @brief retrieves an Iterator to an Entry called entryName within this section
     184 * @param entryName the name of the Entry
     185 * @return The iterator to the position, or end();
     186 * @see Section::end();
     187 */
    135188IniParser::Entry::const_iterator IniParser::Section::getEntryIt(const std::string& entryName) const
    136189{
    … …  
    138191}
    139192
     193/**
     194 * @brief clears the Section's entries (flushes them)
     195 */
    140196void IniParser::Section::clear()
    141197{
    … …  
    143199}
    144200
     201/**
     202 * @brief print out some debug info
     203 */
    145204void IniParser::Section::debug() const
    146205{
    … …  
    155214/// INI-PARSER DOCUMENT ///
    156215/// /// /// /// /// /// ///
     216/**
     217 * @brief Constructs a new Document
     218 * @param fileName The Name of the Document.
     219 * @param comment Some Comment
     220 */
    157221IniParser::Document::Document(const std::string& fileName, const std::string& comment)
    158222    : IniParser::Node(fileName, comment)
    159223{}
    160224
     225/**
     226 * @brief Adds a new Section to the Document
     227 * @param sectionName The Name of the Section to add
     228 * @param comment A comment for the section.
     229 * @return A Reference to the newly added section.
     230 */
    161231IniParser::Section& IniParser::Document::addSection(const std::string& sectionName, const std::string& comment)
    162232{
    … …  
    171241}
    172242
     243/**
     244 * @brief removes a Section from the Document.
     245 * @param sectionName The section to remove
     246 * @return true on success (section was found).
     247 */
    173248bool IniParser::Document::removeSection(const std::string& sectionName)
    174249{
    … …  
    183258}
    184259
     260/**
     261 * @brief Sets a comment to a section
     262 * @param sectionName The name of the section
     263 * @param comment The Comment.
     264 * @return True on success (section was found).
     265 */
    185266bool IniParser::Document::setSectionComment(const std::string& sectionName, const std::string& comment)
    186267{
    … …  
    197278
    198279
     280/**
     281 * @brief Queries for a Section within the document returning a Pointer to it
     282 * @param sectionName The Section to search for.
     283 * @return A pointer to the section, of NULL if not found.
     284 * @brief beware of the NULL-pointer!
     285 */
    199286IniParser::Section* IniParser::Document::getSection(const std::string& sectionName)
    200287{
    … …  
    208295}
    209296
     297/**
     298 * @brief Queries for a Section within the document returning a Pointer to it
     299 * @param sectionName The Section to search for.
     300 * @return An iterator to the Section, or end()
     301 * @see Section::end().
     302 */
    210303IniParser::Section::const_iterator IniParser::Document::getSectionIt(const std::string& sectionName) const
    211304{
    … …  
    214307}
    215308
     309/**
     310 * @brief adds a new Entry to a designated section.
     311 * @param sectionName The name of the Section
     312 * @param entryName The Name of the Entry to add
     313 * @param value The Value to set for the entry
     314 * @param comment optionally a comment.
     315 * @return true on success (always true)
     316 *
     317 * @note the section will also be created on the go, if it did not exists so far!
     318 */
    216319bool IniParser::Document::addEntry(const std::string& sectionName, const std::string& entryName, const std::string& value, const std::string& comment)
    217320{
    … …  
    229332}
    230333
     334/**
     335 * @brief edits an Entry, and possibly creating it.
     336 * @param sectionName The Section's name to edit the entry in.
     337 * @param entryName The Name of the Entry to edit the value from
     338 * @param value The new value for the Entry.
     339 * @param createMissing if true, the Entry, (and the section) will be created.
     340 * @return true on success, false otherwise.
     341 */
    231342bool IniParser::Document::editEntry(const std::string& sectionName, const std::string& entryName, const std::string& value, bool createMissing)
    232343{
    … …  
    248359}
    249360
     361/**
     362 * @brief Retrieve a value from an Entry.
     363 * @param sectionName The Name of the Section the enrty is in
     364 * @param entryName The Name of the entry
     365 * @param defaultValue A default value, if the entry is not found
     366 * @return A string containing the value, or defaultValue, if the Section->Entry was not found.
     367 */
    250368const std::string& IniParser::Document::getValue(const std::string& sectionName, const std::string& entryName, const std::string& defaultValue) const
    251369{
    … …  
    257375}
    258376
     377/**
     378 * @brief Sets a Comment to an Entry.
     379 * @param sectionName The name of the Section.
     380 * @param entryName The name of the Entry.
     381 * @param comment The comment to set to this Entry
     382 * @return true on success (Section->Entry found).
     383 */
    259384bool IniParser::Document::setEntryComment(const std::string& sectionName, const std::string& entryName, const std::string& comment)
    260385{
    … …  
    267392}
    268393
     394/**
     395 * @brief retrieved the comment of an Entry.
     396 * @param sectionName The section.
     397 * @param entryName The Entry to get the comment from
     398 * @return the Comment of the Entry.
     399 */
    269400const std::string& IniParser::Document::getEntryComment(const std::string& sectionName, const std::string& entryName) const
    270401{
    … …  
    276407}
    277408
     409/**
     410 * @brief clears all sections.
     411 */
    278412void IniParser::Document::clear()
    279413{
    … …  
    281415}
    282416
     417/**
     418 * @brief Print some nice debug output.
     419 */
    283420void IniParser::Document::debug() const
    284421{
    … …  
    334471  if( (stream = fopen (fileName.c_str(), "r")) == NULL)
    335472  {
    336     PRINTF(1)("IniParser could not open %s for reading\n", fileName.c_str());
     473    printf("ERROR:: IniParser could not open %s for reading\n", fileName.c_str());
    337474    return false;
    338475  }
    … …  
    393530        if (currentSection == NULL)
    394531        {
    395           PRINTF(2)("Not in a Section yet for %s\n", lineBegin);
     532          printf("WARNING:: Not in a Section yet for %s\n", lineBegin);
    396533          lineCount++;
    397534          continue;
    … …  
    427564
    428565/**
    429  * @brief opens a file and writes to it
    430  * @param fileName: path and name of the new file to write to
     566 * @brief opens a file and writes to it.
     567 * @param fileName: path and name of the new file to write to. If empty the internal value is used.
    431568 * @return true on success false otherwise
    432569 */
    433570bool IniParser::writeFile(const std::string& fileName) const
    434571{
     572  std::string parseFile;
    435573  FILE*    stream;           //!< The stream we use to read the file.
    436574  if( fileName.empty())
    437     return false;
    438 
    439   if( (stream = fopen (fileName.c_str(), "w")) == NULL)
    440   {
    441     PRINTF(1)("IniParser could not open %s for writing\n", fileName.c_str());
     575    parseFile = _fileName;
     576  else
     577    parseFile = fileName;
     578
     579  if( (stream = fopen (parseFile.c_str(), "w")) == NULL)
     580  {
     581    printf("ERROR:: IniParser could not open %s for writing\n", parseFile.c_str());
    442582    return false;
    443583  }
    … …  
    551691void IniParser::debug() const
    552692{
    553   PRINT(0)("Iniparser '%s' - debug\n", this->_fileName.c_str());
     693  printf("Iniparser '%s' - debug\n", this->_fileName.c_str());
    554694  if (!this->_document.comment().empty())
    555     PRINT(0)("FileComment:\n '%s'\n\n", this->_document.comment().c_str());
     695    printf("FileComment:\n '%s'\n\n", this->_document.comment().c_str());
    556696
    557697  if (!this->_document.sections().empty())
    558698    this->_document.debug();
    559699  else
    560     PRINTF(0)("no Sections Defined in this ini-file (%s).\n", _fileName.c_str());
    561 }
    562 
    563 
    564 /**
    565  * takes lines together to form one NodeComment, ereasing the commentList
     700    printf("no Sections Defined in this ini-file (%s).\n", _fileName.c_str());
     701}
     702
     703
     704/**
     705 * @brief takes lines together to form one NodeComment, ereasing the commentList
     706 * @param node the Node to apply the Comment to.
     707 * @param comments the CommentList to append.
    566708 */
    567709void IniParser::setNodeComment(Node* node, std::list<std::string>* comments)

  • trunk/src/lib/parser/ini_parser/ini_parser.h

    r9880 r9881  
    88#ifndef _INI_PARSER_H
    99#define _INI_PARSER_H
    10 
    11 #define PARSELINELENGHT     512       //!< how many chars to read at once
    1210
    1311#include <string>
    … …  
    2220public:
    2321  ////////////////////////////////////
    24   /// A Node for a Ini-Node. The base of all INI-elements.
     22  /// A class for a Ini-Node. The base of all INI-elements.
    2523  class Node
    2624  {
    2725  public:
    2826    Node(const std::string& name, const std::string& comment = "");
     27    //! Simple destructor
    2928    virtual ~Node() {};
     29    /** @returns the name of the Node */
    3030    const std::string& name() const  { return _name; };
     31    /** @returns the Comment of the Node */
    3132    const std::string& comment() const  { return _comment; };
     33    /** @param name the name to set for this node */
    3234    void setName(const std::string& name) { this->_name = name; };
     35    /** @param comment the Comment to set for this node */
    3336    void setComment(const std::string& comment) { this->_comment = comment; };
    3437
     38    /** @param name the name to compare against this nodes name @returns true on match */
    3539    bool operator==(const std::string& name) const { return _name == name; };
    36     bool operator==(const Node& node) const { return this->_name == node._name; };
    37 
     40
     41    /** @brief displays some debug information about the node */
    3842    virtual void debug() const = 0;
    3943
    … …  
    4852  public:
    4953    Entry(const std::string& name, const std::string& value = "", const std::string& comment = "");
     54    /** @returns the Value of the Entry */
    5055    const std::string& value() const { return _value; };
     56    /** @param value sets the value of the Entry */
    5157    void setValue (const std::string& value) { _value = value; };
    5258
    … …  
    5460
    5561  public:
    56     typedef std::list<Entry>                    list;
    57     typedef list::iterator                      iterator;
    58     typedef list::const_iterator                const_iterator;
    59 
    60   private:
    61     std::string         _value;    //!< value of a given Entry
     62    typedef std::list<Entry>       list;           //!< A Type definition for lists of Entries.
     63    typedef list::iterator         iterator;       //!< A Type definition for iterators of Entries.
     64    typedef list::const_iterator   const_iterator; //!< A Type definition for constant iterators of Entries.
     65
     66  private:
     67    std::string                    _value;         //!< value of a given Entry
    6268  };
    6369
    … …  
    7581    const std::string& getEntryComment(const std::string& entryName) const;
    7682
     83    /** @returns the List of Entries */
    7784    const Entry::list& entries() const { return _entries; }
    7885    Entry* getEntry(const std::string& entryName);
    7986
    8087    Entry::const_iterator getEntryIt(const std::string& entryName) const;
     88    /** @returns an Iterator pointing to the beginning of the entries. */
    8189    Entry::iterator begin() { return _entries.begin(); };
     90    /** @returns a constant Iterator pointing to the beginning of the entries */
    8291    Entry::const_iterator begin() const { return _entries.begin(); };
     92    /** @returns an Iterator pointing to the end of the entries */
    8393    Entry::iterator end() { return _entries.end(); };
     94    /** @returns a constant Iterator pointing to the end of the entries */
    8495    Entry::const_iterator end() const { return _entries.end(); };
    8596
    … …  
    89100
    90101  public:
    91     typedef std::list<Section>                  list;
    92     typedef list::iterator                      iterator;
    93     typedef list::const_iterator                const_iterator;
    94 
    95   private:
    96     Entry::list     _entries;  //!< a list of entries for this section
     102    typedef std::list<Section>      list;            //!< A Type definition for lists of Sections
     103    typedef list::iterator          iterator;        //!< A Type definition for iterators of Sectionlists.
     104    typedef list::const_iterator    const_iterator;  //!< A Type definition for constant iterators of Sectionlists.
     105
     106  private:
     107    Entry::list                     _entries;        //!< a list of entries for this section
    97108  };
    98109
    … …  
    107118    bool setSectionComment(const std::string& sectionName, const std::string& comment);
    108119
     120    /** @returns list of all sections */
    109121    const Section::list& sections() const { return _sections; }
    110122    Section* getSection(const std::string& sectionName);
    111123
    112124    Section::const_iterator getSectionIt(const std::string& sectionName) const;
     125    /** @returns an Iterator poining to the beginning of the Sections List */
    113126    Section::iterator begin() { return _sections.begin(); };
     127    /** @returns a constant Iterator poining to the beginning of the Sections List */
    114128    Section::const_iterator begin() const { return _sections.begin(); };
     129    /** @returns an Iterator poining to the end of the Sections List */
    115130    Section::iterator end() { return _sections.end(); };
     131    /** @returns a constant Iterator poining to the end of the Sections List */
    116132    Section::const_iterator end() const { return _sections.end(); };
    117133
    … …  
    128144
    129145  private:
    130     Section::list            _sections;        //!< a list of all stored Sections of the Parser.
     146    Section::list       _sections;        //!< a list of all stored Sections of the Parser.
    131147  };
    132148
    … …  
    142158  /// Read and Write the File
    143159  bool readFile(const std::string& fileName, bool keepSettings = false);
    144   bool writeFile(const std::string& fileName) const;
     160  bool writeFile(const std::string& fileName = "") const;
    145161
    146162  void setFileComment(const std::string& fileComment);
     163  /** @returns comments for the File. */
    147164  const std::string& getFileComment() const { return this->_document.comment(); };
    148165
    … …  
    150167  Section& addSection(const std::string& sectionName);
    151168  // iterate through sections with these Functions
     169  //! see Section::getSection()
    152170  Section* getSection(const std::string& sectionName) { return this->_document.getSection(sectionName); };
    153171  Section::const_iterator getSectionIt(const std::string& sectionName) const;
    154172
     173  //! see Section::begin()
    155174  Section::iterator begin() { return this->_document.begin(); };
     175  //! see Section::begin()
    156176  Section::const_iterator begin() const { return this->_document.begin(); };
     177    //! see Section::end()
    157178  Section::iterator end() { return this->_document.end(); };
     179    //! see Section::end()
    158180  Section::const_iterator end() const { return this->_document.end(); };
    159181
    … …  
    175197  void setNodeComment(Node* node, std::list<std::string>* comments);
    176198private:
    177   std::string                      _fileName;
    178   Document                         _document;
     199  std::string                      _fileName;        //!< The name of the File that is parsed here.
     200  Document                         _document;        //!< The Document inside of the file.
    179201
    180202  static const std::string         _emptyString;     //!< Just an Empty String that will be returned if nothing else is found.
Note: See TracChangeset for help on using the changeset viewer.