libFAUDES

Sections

Index

cfl_tokenreader.h

Go to the documentation of this file.
00001 /** @file cfl_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 "cfl_definitions.h"
00029 #include "cfl_exception.h"
00030 #include "cfl_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    * This function searches for the specified section on the current level, 
00161    * it skips any sections on levels below, and it will wrap to the begin 
00162    * of the current section. In the case of success, it returns true, else
00163    * false. In contrast to other token i/o methodes, this method will not throw
00164    * any execptions.
00165    *
00166    * @param rLabel
00167    *   Token label to specify section
00168    *
00169    * @return
00170    *   True if sectiob exists
00171    *
00172    */
00173   bool ExistsBegin(const std::string& rLabel);
00174 
00175   /**
00176    * Open a section by specified label. This function searches
00177    * for the section on this level, it skips any sections on levels
00178    * below this level, and it will wrap to the begin of the current 
00179    * section. In the case of success, the matching begin token is the 
00180    * last token read. After processing the section, a matching ReadEnd(label) 
00181    * must be called.
00182    *
00183    * @param rLabel
00184    *   Token label to specify section
00185    *
00186    * @exception Exception
00187    *   Section begin label not found (id 51)
00188    *
00189    */
00190   void ReadBegin(const std::string& rLabel);
00191 
00192   /**
00193    * Close the current section by matching the previous ReadBegin(). 
00194    * Reads all tokens up to and including end of current section.
00195    *
00196    * @param rLabel
00197    *   Token label to specify section
00198    *
00199    * @exception Exception
00200    *   Section end label not found (id 51)
00201    *
00202    */
00203   void ReadEnd(const std::string& rLabel);
00204 
00205   /**
00206    * Open a section by specified label. This function searches
00207    * for the section on this level and any descending level. However, this
00208    * funtion will not rewind to the beginning of the current section
00209    * (this may change in a future revision). In the case of success, the 
00210    * matching begin token is the last token read. After processing the
00211    * section, a matching SeekEnd(label) must be called.
00212    *
00213    * @param rLabel
00214    *   Label to specify section
00215    *
00216    * @exception Exception
00217    *   Section begin not found (id 51)
00218    *
00219    */
00220   void SeekBegin(const std::string& rLabel);
00221 
00222   /**
00223    * Close the current section by matching the previous SeekBegin(). 
00224    * Reads all tokens up to the level when SeekBegin() was called. 
00225    *
00226    * @param rLabel
00227    *   Token label to specify section
00228    *
00229    * @exception Exception
00230    *   Section end label not found (id 51)
00231    *   Previous level not found/ unmachted call (id 52)
00232    *
00233    */
00234   void SeekEnd(const std::string& rLabel);
00235 
00236   /**
00237    * Peek a token and check whether it ends the specified section.
00238    * This function is meant for scanning a section with a while- construct.
00239    * \code
00240    * SeekBegin("MySec"); 
00241    * while(!Eos("MySec")) { 
00242    *   ... 
00243    * }; 
00244    * SeekEnd("MySec");
00245    * \endcode
00246    *
00247    * @param rLabel
00248    *   Token label to specify section
00249    *
00250    * @exception Exception
00251    *   Unexpected eof (id 51)
00252    *
00253    * @return
00254    *   True at end of section
00255    */
00256   bool Eos(const std::string& rLabel);
00257 
00258   /**
00259    * Read integer  token
00260    *      
00261    * @exception Exception
00262    *   Token mismatch (id 50)
00263    *
00264    * @return
00265    *   value of index token
00266    */
00267   long int ReadInteger(void);
00268 
00269   /**
00270    * Read float token
00271    *      
00272    * @exception Exception
00273    *   Token mismatch (id 50)
00274    *
00275    * @return
00276    *   value of index token
00277    */
00278   double ReadFloat(void);
00279 
00280   /**
00281    * Read string token
00282    *      
00283    * @exception Exception
00284    *   Token mismatch (id 50)
00285    *
00286    * @return
00287    *   value of name token
00288    */
00289   const std::string& ReadString(void);
00290 
00291   /**
00292    * Read option token
00293    *      
00294    * @exception Exception
00295    *   Token mismatch (id 50)
00296    *
00297    * @return
00298    *   value of name token
00299    */
00300   const std::string& ReadOption(void);
00301 
00302   /**
00303    * Read binary token. You can access the binary array
00304    * via StringValue();
00305    *      
00306    * @return
00307    *   Binary data as std::string
00308    * @exception Exception
00309    *   Token mismatch (id 50)
00310    *
00311    */
00312   const std::string& ReadBinary(void);
00313 
00314 
00315   /** Operator for get */
00316   bool operator >> (Token& token) {
00317     return Get(token);
00318   }
00319 
00320   /**
00321    * Return number of lines read
00322    * 
00323    * @return
00324    *   Number of lines read
00325    */ 
00326   int Line(void) const;
00327 
00328   /**
00329    * Return "filename:line"
00330    */
00331   std::string FileLine(void) const;
00332 
00333  private:
00334   /** input mode */
00335   Mode mMode;
00336 
00337   /** istream object pointer */
00338   std::istream* mpStream;
00339 
00340   /** actual stream object, file input  */
00341   std::ifstream mFStream;
00342 
00343   /** actual stream object on heap, string input  */
00344   std::istringstream* mpSStream;
00345 
00346   /** Filename */
00347   std::string mFileName;
00348 
00349   /** Line counter */
00350   int mLineCount;
00351 
00352   /** file position */
00353   long int mFilePos;
00354 
00355   /** Level (of nested sections)*/
00356   int mLevel;
00357 
00358   /** file positions of sections */
00359   std::vector<long int> mLevelPos;
00360 
00361   /** file line of sections */
00362   std::vector<long int> mLevelLine;
00363 
00364   /** level of recent seek */
00365   std::vector<int> mSeekLevel;
00366 
00367   /** recent string buffer */
00368   std::string mLastString;
00369 
00370   /** validity of peek buffer */
00371   bool mHasPeekToken;
00372 
00373   /** peek buffer */
00374   Token mPeekToken;
00375 };
00376 
00377 } // namespace faudes
00378 
00379 #define FAUDES_TOKENREADER_H
00380 #endif 

libFAUDES 2.16b --- 2010-9-8 --- c++ source docu by doxygen 1.6.3