libFAUDES

Sections

Index

tokenreader.h

Go to the documentation of this file.
00001 /** @file tokenreader.h @brief Class TokenReader */
00002 
00003 /* FAU Discrete Event Systems Library (libfaudes)
00004 
00005 Copyright (C) 2006  Bernd Opitz
00006 Exclusive copyright is granted to Klaus Schmidt
00007 
00008 This library is free software; you can redistribute it and/or
00009 modify it under the terms of the GNU Lesser General Public
00010 License as published by the Free Software Foundation; either
00011 version 2.1 of the License, or (at your option) any later version.
00012 
00013 This library is distributed in the hope that it will be useful,
00014 but WITHOUT ANY WARRANTY; without even the implied warranty of
00015 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00016 Lesser General Public License for more details.
00017 
00018 You should have received a copy of the GNU Lesser General Public
00019 License along with this library; if not, write to the Free Software
00020 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA */
00021 
00022 
00023 
00024 #ifndef FAUDES_TOKENREADER_H
00025 
00026 #include <vector>
00027 
00028 #include "definitions.h"
00029 #include "exception.h"
00030 #include "token.h"
00031 
00032 namespace faudes {
00033 
00034 /**
00035  * A TokenReader reads sequential tokens from a file or string. It can get or peek
00036  * the next token and it will track line numbers for informative diagnosis output.
00037  *
00038  * The class also implements nested sections. That is, you may search for a
00039  * (sub-)section within the current section and, hence, implement file formats that 
00040  * do not insist in a particular ordering of the sections (e.g. a Generator
00041  * consists of states, transitions and events, no matter in which order).
00042  *
00043  * Convenience functions are provided to read a token of a particular type and
00044  * throws faudes::Exception on token mismatch. You may catch the exception 
00045  * as follows:
00046  * \code 
00047  * try {
00048  *   some tokenreader operations
00049  * }
00050  * catch (faudes::Exception& ex) {
00051  *   cerr << "Error reading file (details: " << ex.What() << ")" << endl;
00052  * }
00053  * \endcode
00054  * Note that in addition to the documented execeptions all TokenReader functions 
00055  * do pass on faudes ios errors from the Token class.
00056  * 
00057  */
00058 
00059 class TokenReader {
00060 public:
00061 
00062   /**
00063    * Mode of operation: read from file, stdin or string
00064    */
00065   enum Mode {File, Stdin, String};
00066 
00067   /**
00068    * TokenReader constructor
00069    *
00070    * @param mode
00071    *   select source: File, Stdin or String
00072    * @param rInString
00073    *   string to read from or filename
00074    *
00075    * @exception Exception
00076    *   - faudes::Exception ios error opening file (id 1)
00077    *   - faudes::Exception invalid mode (Stdin not implemented) (id 1)
00078    */
00079   TokenReader(Mode mode, const std::string& rInString="");
00080 
00081   /**
00082    * Creates a TokenReader for reading complete file.
00083    *
00084    * @param rFilename
00085    *   File to read
00086    *
00087    * @exception Exception
00088    *   - faudes::Exception ios error opening file (id 1)
00089    */
00090   TokenReader(const std::string& rFilename);
00091 
00092 
00093   /**
00094    * Destruct
00095    */
00096   ~TokenReader(void);
00097 
00098   /**
00099    * Get state of TokenReader stream
00100    *
00101    * @return
00102    *   std::stream.good()
00103    */
00104   bool good(void) const;
00105 
00106   /**
00107    * Get the filename.
00108    * Return dummy values for console or string mode.
00109    * 
00110    * @return 
00111    *   Filename
00112    */
00113   std::string FileName(void) const;
00114 
00115   /**
00116    * Get file mode.
00117    * 
00118    * @return 
00119    *   Mode
00120    */
00121   Mode SourceMode(void) const { return mMode;};
00122 
00123   /**
00124    * Peek next token. False indicates eof.
00125    *
00126    * @param token
00127    *   Reference to token
00128    * 
00129    * @exception Exception
00130    *   - faudes::Exception ios error reading file (id 1)
00131    *
00132    * @return
00133    *   True for a valid token, false for eof
00134    */
00135   bool Peek(Token& token);
00136 
00137   /**
00138    * Get next token. False indicates eof.
00139    *
00140    * @param token
00141    *   Reference to token
00142    * 
00143    * @exception Exception
00144    *   faudes exception ios (id 1)
00145    *
00146    * @return
00147    *   True for a valid token, false for eof
00148    */
00149   bool Get(Token& token);
00150 
00151   /**
00152    * Rewind stream (must be a seekable stream)
00153    *
00154    * @exception Exception
00155    *   - faudes::Exception ios error reading file (id 1)
00156    */
00157   void Rewind(void);
00158 
00159   /**
00160    * Open a section by specified label. This function searches
00161    * for the section on this level, it skips any sections on levels
00162    * below this level, and it will wrap to the begin of the current 
00163    * section. In the case of success, the matching begin token is the 
00164    * last token read. After processing the section, a matching ReadEnd(label) 
00165    * must be called.
00166    *
00167    * @param rLabel
00168    *   Token label to specify section
00169    *
00170    * @exception Exception
00171    *   Section begin label not found (id 51)
00172    *
00173    */
00174   void ReadBegin(const std::string& rLabel);
00175 
00176   /**
00177    * Close the current section by matching the previous ReadBegin(). 
00178    * Reads all tokens up to and including end of current section.
00179    *
00180    * @param rLabel
00181    *   Token label to specify section
00182    *
00183    * @exception Exception
00184    *   Section end label not found (id 51)
00185    *
00186    */
00187   void ReadEnd(const std::string& rLabel);
00188 
00189   /**
00190    * Open a section by specified label. This function searches
00191    * for the section on this level and any descending level. However, this
00192    * funtion will not rewind to the beginning of the current section
00193    * (this may change in a future revision). In the case of success, the 
00194    * matching begin token is the last token read. After processing the
00195    * section, a matching SeekEnd(label) must be called.
00196    *
00197    * @param rLabel
00198    *   Label to specify section
00199    *
00200    * @exception Exception
00201    *   Section begin not found (id 51)
00202    *
00203    */
00204   void SeekBegin(const std::string& rLabel);
00205 
00206   /**
00207    * Close the current section by matching the previous SeekBegin(). 
00208    * Reads all tokens up to the level when SeekBegin() was called. 
00209    *
00210    * @param rLabel
00211    *   Token label to specify section
00212    *
00213    * @exception Exception
00214    *   Section end label not found (id 51)
00215    *   Previous level not found/ unmachted call (id 52)
00216    *
00217    */
00218   void SeekEnd(const std::string& rLabel);
00219 
00220   /**
00221    * Peek a token and check whether it ends the specified section.
00222    * This function is meant for scanning a section with a while- construct.
00223    * \code
00224    * SeekBegin("MySec"); 
00225    * while(!Eos("MySec")) { 
00226    *   ... 
00227    * }; 
00228    * SeekEnd("MySec");
00229    * \endcode
00230    *
00231    * @param rLabel
00232    *   Token label to specify section
00233    *
00234    * @exception Exception
00235    *   Unexpected eof (id 51)
00236    *
00237    * @return
00238    *   True at end of section
00239    */
00240   bool Eos(const std::string& rLabel);
00241 
00242   /**
00243    * Read integer  token
00244    *      
00245    * @exception Exception
00246    *   Token mismatch (id 50)
00247    *
00248    * @return
00249    *   value of index token
00250    */
00251   long int ReadInteger(void);
00252 
00253   /**
00254    * Read float token
00255    *      
00256    * @exception Exception
00257    *   Token mismatch (id 50)
00258    *
00259    * @return
00260    *   value of index token
00261    */
00262   double ReadFloat(void);
00263 
00264   /**
00265    * Read string token
00266    *      
00267    * @exception Exception
00268    *   Token mismatch (id 50)
00269    *
00270    * @return
00271    *   value of name token
00272    */
00273   const std::string& ReadString(void);
00274 
00275   /**
00276    * Read option token
00277    *      
00278    * @exception Exception
00279    *   Token mismatch (id 50)
00280    *
00281    * @return
00282    *   value of name token
00283    */
00284   const std::string& ReadOption(void);
00285 
00286   /**
00287    * Read binary token. You can access the binary array
00288    * via StringValue();
00289    *      
00290    * @return
00291    *   Binary data as std::string
00292    * @exception Exception
00293    *   Token mismatch (id 50)
00294    *
00295    */
00296   const std::string& ReadBinary(void);
00297 
00298 
00299   /** Operator for get */
00300   bool operator >> (Token& token) {
00301     return Get(token);
00302   }
00303 
00304   /**
00305    * Return number of lines read
00306    * 
00307    * @return
00308    *   Number of lines read
00309    */ 
00310   int Line(void) const;
00311 
00312   /**
00313    * Return "filename:line"
00314    */
00315   std::string FileLine(void) const;
00316 
00317  private:
00318   /** input mode */
00319   Mode mMode;
00320 
00321   /** istream object pointer */
00322   std::istream* mpStream;
00323 
00324   /** actual stream object, file input  */
00325   std::ifstream mFStream;
00326 
00327   /** actual stream object on heap, string input  */
00328   std::istringstream* mpSStream;
00329 
00330   /** Filename */
00331   std::string mFileName;
00332 
00333   /** Line counter */
00334   int mLineCount;
00335 
00336   /** file position */
00337   long int mFilePos;
00338 
00339   /** Level (of nested sections)*/
00340   int mLevel;
00341 
00342   /** file positions of sections */
00343   std::vector<long int> mLevelPos;
00344 
00345   /** file line of sections */
00346   std::vector<long int> mLevelLine;
00347 
00348   /** level of recent seek */
00349   std::vector<int> mSeekLevel;
00350 
00351   /** recent string buffer */
00352   std::string mLastString;
00353 
00354   /** validity of peek buffer */
00355   bool mHasPeekToken;
00356 
00357   /** peek buffer */
00358   Token mPeekToken;
00359 };
00360 
00361 } // namespace faudes
00362 
00363 #define FAUDES_TOKENREADER_H
00364 #endif 

libFAUDES 2.14g --- 2009-12-3 --- c++ source docu by doxygen 1.5.6