|
libFAUDES
Sections
Index
|
cfl_tokenreader.hGo 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