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  * @ingroup TokenIO
00058  */
00059 
00060 class TokenReader {
00061 public:
00062 
00063   /**
00064    * Mode of operation: read from file, stdin or string
00065    */
00066   enum Mode {File, Stdin, String};
00067 
00068   /**
00069    * TokenReader constructor
00070    *
00071    * @param mode
00072    *   select source: File, Stdin or String
00073    * @param rInString
00074    *   string to read from or filename
00075    *
00076    * @exception Exception
00077    *   - faudes::Exception ios error opening file (id 1)
00078    *   - faudes::Exception invalid mode (Stdin not implemented) (id 1)
00079    */
00080   TokenReader(Mode mode, const std::string& rInString="");
00081 
00082   /**
00083    * Creates a TokenReader for reading complete file.
00084    *
00085    * @param rFilename
00086    *   File to read
00087    *
00088    * @exception Exception
00089    *   - faudes::Exception ios error opening file (id 1)
00090    */
00091   TokenReader(const std::string& rFilename);
00092 
00093 
00094   /**
00095    * Destruct
00096    */
00097   ~TokenReader(void);
00098 
00099   /**
00100    * Get state of TokenReader stream
00101    *
00102    * @return
00103    *   std::stream.good()
00104    */
00105   bool Good(void) const;
00106 
00107   /**
00108    * Get the filename.
00109    * Return dummy values for console or string mode.
00110    * 
00111    * @return 
00112    *   Filename
00113    */
00114   std::string FileName(void) const;
00115 
00116   /**
00117    * Get file mode.
00118    * 
00119    * @return 
00120    *   Mode
00121    */
00122   Mode SourceMode(void) const { return mMode;};
00123 
00124   /**
00125    * Peek next token. False indicates eof.
00126    *
00127    * @param token
00128    *   Reference to token
00129    * 
00130    * @exception Exception
00131    *   - faudes::Exception ios error reading file (id 1)
00132    *
00133    * @return
00134    *   True for a valid token, false for eof
00135    */
00136   bool Peek(Token& token);
00137 
00138   /**
00139    * Get next token. False indicates eof.
00140    *
00141    * @param token
00142    *   Reference to token
00143    * 
00144    * @exception Exception
00145    *   faudes exception ios (id 1)
00146    *
00147    * @return
00148    *   True for a valid token, false for eof
00149    */
00150   bool Get(Token& token);
00151 
00152   /**
00153    * Rewind stream (must be a seekable stream)
00154    *
00155    * @exception Exception
00156    *   - faudes::Exception ios error reading file (id 1)
00157    */
00158   void Rewind(void);
00159 
00160   /**
00161    * This function searches for the specified section on the current level, 
00162    * it skips any sections on levels below, and it will wrap to the begin 
00163    * of the current section. In the case of success, it returns true, else
00164    * false. In contrast to other token i/o methodes, this method will not throw
00165    * any execptions.
00166    *
00167    * @param rLabel
00168    *   Token label to specify section
00169    *
00170    * @return
00171    *   True if sectiob exists
00172    *
00173    */
00174   bool ExistsBegin(const std::string& rLabel);
00175 
00176   /**
00177    * Open a section by specified label. This function searches
00178    * for the section on this level, it skips any sections on levels
00179    * below this level, and it will wrap to the begin of the current 
00180    * section. In the case of success, the matching begin token is the 
00181    * last token read. After processing the section, a matching ReadEnd(label) 
00182    * must be called.
00183    *
00184    * @param rLabel
00185    *   Token label to specify section
00186    *
00187    * @exception Exception
00188    *   Section begin label not found (id 51)
00189    *
00190    */
00191   void ReadBegin(const std::string& rLabel);
00192 
00193   /**
00194    * Open a section by specified label. 
00195    *
00196    * This version ReadBegin(const std::string&) will return the actual
00197    * begin tag in its second argument.
00198    *
00199    * @param rLabel
00200    *   Token label to specify section
00201    * @param rToken
00202    *   Begin tag as found in token stream.
00203    *
00204    * @exception Exception
00205    *   Section begin label not found (id 51)
00206    *
00207    */
00208   void ReadBegin(const std::string& rLabel, Token& rToken);
00209 
00210   /**
00211    * Close the current section by matching the previous ReadBegin(). 
00212    * Reads all tokens up to and including end of current section.
00213    *
00214    * @param rLabel
00215    *   Token label to specify section
00216    *
00217    * @exception Exception
00218    *   Section end label not found (id 51)
00219    *
00220    */
00221   void ReadEnd(const std::string& rLabel);
00222 
00223   /**
00224    * Find specified begin label.
00225    * This function searches
00226    * for the section on this level and any descending level. 
00227    * It does not read the specified section tag, but stops just
00228    * one token before.
00229    *
00230    * Technical note:
00231    * Former versions of libFAUDES also read the actual begin token and
00232    * required a matching call of SeekEnd(). As of version 2.18a, this is not
00233    * supported anymore. The previous behaviour war rarely needed and can be
00234    * mimiqued by an ordinary ReadEnd() with a subsequent Recover(level).
00235    *
00236    * @param rLabel
00237    *   Label to specify section
00238    *
00239    * @exception Exception
00240    *   Section begin not found (id 51)
00241    *
00242    */
00243   void SeekBegin(const std::string& rLabel);
00244 
00245   /**
00246    * Find specified begin label.
00247    *
00248    * This version SeekBegin(const std::string&) will return the actual
00249    * begin tag in its second argument.
00250    *
00251    * @param rLabel
00252    *   Token label to specify section
00253    * @param rToken
00254    *   Begin tag as found in token stream.
00255    *
00256    * @exception Exception
00257    *   Section begin label not found (id 51)
00258    *
00259    */
00260   void SeekBegin(const std::string& rLabel, Token& rToken);
00261 
00262   /**
00263    * Peek a token and check whether it ends the specified section.
00264    * This function is meant for scanning a section with a while- construct.
00265    * \code
00266    * SeekBegin("MySec"); 
00267    * while(!Eos("MySec")) { 
00268    *   ... 
00269    * }; 
00270    * SeekEnd("MySec");
00271    * \endcode
00272    *
00273    * @param rLabel
00274    *   Token label to specify section
00275    *
00276    * @exception Exception
00277    *   Unexpected eof (id 51)
00278    *
00279    * @return
00280    *   True at end of section
00281    */
00282   bool Eos(const std::string& rLabel);
00283 
00284   /**
00285    * Read integer  token
00286    *      
00287    * @exception Exception
00288    *   Token mismatch (id 50)
00289    *
00290    * @return
00291    *   value of index token
00292    */
00293   long int ReadInteger(void);
00294 
00295   /**
00296    * Read float token
00297    *      
00298    * @exception Exception
00299    *   Token mismatch (id 50)
00300    *
00301    * @return
00302    *   value of index token
00303    */
00304   double ReadFloat(void);
00305 
00306   /**
00307    * Read string token
00308    *      
00309    * @exception Exception
00310    *   Token mismatch (id 50)
00311    *
00312    * @return
00313    *   value of name token
00314    */
00315   const std::string& ReadString(void);
00316 
00317   /**
00318    * Read option token
00319    *      
00320    * @exception Exception
00321    *   Token mismatch (id 50)
00322    *
00323    * @return
00324    *   value of name token
00325    */
00326   const std::string& ReadOption(void);
00327 
00328   /**
00329    * Read binary token. You can access the binary array
00330    * via StringValue();
00331    *      
00332    * @return
00333    *   Binary data as std::string
00334    * @exception Exception
00335    *   Token mismatch (id 50)
00336    *
00337    */
00338   const std::string& ReadBinary(void);
00339 
00340 
00341   /**
00342    * Read plain text
00343    *      
00344    * Read all text until and excluding the next markup.
00345    *
00346    * @exception Exception
00347    *   Stream mismatch (id 50)
00348    *
00349    * @return
00350    *   Text read.
00351    */
00352   const std::string& ReadText(void);
00353 
00354 
00355   /** Operator for get */
00356   bool operator >> (Token& token) {
00357     return Get(token);
00358   }
00359 
00360   /**
00361    * Return number of lines read
00362    * 
00363    * @return
00364    *   Number of lines read
00365    */ 
00366   int Line(void) const;
00367 
00368   /**
00369    * Return current level of section nesting
00370    * 
00371    * @return
00372    *   Number of lines read
00373    */ 
00374   int Level(void) const { return mLevel;};
00375 
00376   /**
00377    * Recover to specified section nesting
00378    *
00379    * The current implementation will mess up the Seek-stack. Thus,
00380    * Recover() only works when no Seekbegin() was used.
00381    * 
00382    * @return
00383    *   True on success
00384    */ 
00385   bool Recover(int level);
00386 
00387   /**
00388    * Return "filename:line"
00389    */
00390   std::string FileLine(void) const;
00391 
00392  private:
00393 
00394   /** input mode */
00395   Mode mMode;
00396 
00397   /** istream object pointer */
00398   std::istream* mpStream;
00399 
00400   /** actual stream object, file input  */
00401   std::ifstream mFStream;
00402 
00403   /** actual stream object on heap, string input  */
00404   std::istringstream* mpSStream;
00405 
00406   /** Filename */
00407   std::string mFileName;
00408 
00409   /** Line counter */
00410   int mLineCount;
00411 
00412   /** file position */
00413   long int mFilePos;
00414 
00415   /** Level (of nested sections)*/
00416   int mLevel;
00417 
00418   /** file positions of sections */
00419   std::vector<long int> mLevelPos;
00420 
00421   /** file line of sections */
00422   std::vector<long int> mLevelLine;
00423 
00424   /** level of recent seek */
00425   std::vector<int> mSeekLevel;
00426 
00427   /** recent string buffer */
00428   std::string mLastString;
00429 
00430   /** validity of peek buffer */
00431   bool mHasPeekToken;
00432 
00433   /** peek buffer */
00434   Token mPeekToken;
00435 };
00436 
00437 } // namespace faudes
00438 
00439 #define FAUDES_TOKENREADER_H
00440 #endif 

libFAUDES 2.18b --- 2010-12-17 --- c++ source docu by doxygen 1.6.3