cfl_tokenreader.h
Go to the documentation of this file.
1 /** @file cfl_tokenreader.h @brief Class TokenReader */
2 
3 /* FAU Discrete Event Systems Library (libfaudes)
4 
5 Copyright (C) 2006 Bernd Opitz
6 Exclusive copyright is granted to Klaus Schmidt
7 
8 This library is free software; you can redistribute it and/or
9 modify it under the terms of the GNU Lesser General Public
10 License as published by the Free Software Foundation; either
11 version 2.1 of the License, or (at your option) any later version.
12 
13 This library is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 Lesser General Public License for more details.
17 
18 You should have received a copy of the GNU Lesser General Public
19 License along with this library; if not, write to the Free Software
20 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
21 
22 
23 
24 #ifndef FAUDES_TOKENREADER_H
25 
26 #include <vector>
27 
28 #include "cfl_definitions.h"
29 #include "cfl_exception.h"
30 #include "cfl_token.h"
31 
32 namespace faudes {
33 
34 /**
35  * A TokenReader reads sequential tokens from a file or string. It can get or peek
36  * the next token and it will track line numbers for informative diagnosis output.
37  *
38  * The class also implements nested sections. That is, you may search for a
39  * (sub-)section within the current section and, hence, implement file formats that
40  * do not insist in a particular ordering of the sections (e.g. a Generator
41  * consists of states, transitions and events, no matter in which order).
42  *
43  * Convenience functions are provided to read a token of a particular type and
44  * throws faudes::Exception on token mismatch. You may catch the exception
45  * as follows:
46  * \code
47  * try {
48  * some tokenreader operations
49  * }
50  * catch (faudes::Exception& ex) {
51  * cerr << "Error reading file (details: " << ex.What() << ")" << endl;
52  * }
53  * \endcode
54  * Note that in addition to the documented execeptions all TokenReader functions
55  * do pass on faudes ios errors from the Token class.
56  *
57  * @ingroup TokenIO
58  */
59 
60 class TokenReader {
61 public:
62 
63  /**
64  * Mode of operation: read from file, stdin or string
65  */
66  enum Mode {File, Stdin, String};
67 
68  /**
69  * TokenReader constructor
70  *
71  * @param mode
72  * select source: File, Stdin or String
73  * @param rInString
74  * string to read from or filename
75  *
76  * @exception Exception
77  * - faudes::Exception ios error opening file (id 1)
78  * - faudes::Exception invalid mode (Stdin not implemented) (id 1)
79  */
80  TokenReader(Mode mode, const std::string& rInString="");
81 
82  /**
83  * Creates a TokenReader for reading a file.
84  *
85  * @param rFilename
86  * File to read
87  *
88  * @exception Exception
89  * - faudes::Exception ios error opening file (id 1)
90  */
91  TokenReader(const std::string& rFilename);
92 
93 
94  /**
95  * Destruct
96  */
97  ~TokenReader(void);
98 
99  /**
100  * Access C++ stream
101  *
102  */
103  std::istream* Streamp(void);
104 
105  /**
106  * Get state of TokenReader stream
107  *
108  * @return
109  * std::stream.good()
110  */
111  bool Good(void) const;
112 
113  /**
114  * Get the filename.
115  * Returns dummy values for console or string mode.
116  *
117  * @return
118  * Filename
119  */
120  std::string FileName(void) const;
121 
122  /**
123  * Get file mode.
124  *
125  * @return
126  * Mode
127  */
128  Mode SourceMode(void) const { return mMode;};
129 
130  /**
131  * Peek next token. False indicates eof.
132  *
133  * @param token
134  * Reference to token
135  *
136  * @exception Exception
137  * - faudes::Exception ios error reading file (id 1)
138  *
139  * @return
140  * True for a valid token, false for eof
141  */
142  bool Peek(Token& token);
143 
144  /**
145  * Get next token. False indicates eof.
146  *
147  * @param token
148  * Reference to token
149  *
150  * @exception Exception
151  * faudes exception ios (id 1)
152  *
153  * @return
154  * True for a valid token, false for eof
155  */
156  bool Get(Token& token);
157 
158  /**
159  * Rewind stream (must be a seekable stream)
160  *
161  * @exception Exception
162  * - faudes::Exception ios error reading file (id 1)
163  */
164  void Rewind(void);
165 
166  /**
167  * This function searches for the specified section on the current level,
168  * it skips any sections on levels below, and it will wrap to the begin
169  * of the current section. In the case of success, it returns true, else
170  * false. In contrast to other token i/o methodes, this method will not throw
171  * any execptions.
172  *
173  * @param rLabel
174  * Token label to specify section
175  *
176  * @return
177  * True if sectiob exists
178  *
179  */
180  bool ExistsBegin(const std::string& rLabel);
181 
182  /**
183  * Open a section by specified label. This function searches
184  * for the section on this level, it skips any sections on levels
185  * below this level, and it will wrap to the begin of the current
186  * section. In the case of success, the matching begin token is the
187  * last token read. After processing the section, a matching ReadEnd(label)
188  * must be called.
189  *
190  * @param rLabel
191  * Token label to specify section
192  *
193  * @exception Exception
194  * Section begin label not found (id 51)
195  *
196  */
197  void ReadBegin(const std::string& rLabel);
198 
199  /**
200  * Open a section by specified label.
201  *
202  * This version ReadBegin(const std::string&) will return the actual
203  * begin tag in its second argument.
204  *
205  * @param rLabel
206  * Token label to specify section
207  * @param rToken
208  * Begin tag as found in token stream.
209  *
210  * @exception Exception
211  * Section begin label not found (id 51)
212  *
213  */
214  void ReadBegin(const std::string& rLabel, Token& rToken);
215 
216  /**
217  * Close the current section by matching the previous ReadBegin().
218  * Reads all tokens up to and including end of current section.
219  *
220  * @param rLabel
221  * Token label to specify section
222  *
223  * @exception Exception
224  * Section end label not found (id 51)
225  *
226  */
227  void ReadEnd(const std::string& rLabel);
228 
229  /**
230  * Find specified begin label.
231  * This function searches
232  * for the section on this level and any descending level.
233  * It does not read the specified section tag, but stops just
234  * one token before.
235  *
236  * Technical note:
237  * Former versions of libFAUDES also read the actual begin token and
238  * required a matching call of SeekEnd(). As of version 2.18a, this is not
239  * supported anymore. The previous behaviour was rarely needed and can be
240  * mimiqued by an ordinary ReadEnd() with a subsequent Recover(level).
241  *
242  * @param rLabel
243  * Label to specify section
244  *
245  * @exception Exception
246  * Section begin not found (id 51)
247  *
248  */
249  void SeekBegin(const std::string& rLabel);
250 
251  /**
252  * Find specified begin label.
253  *
254  * This version SeekBegin(const std::string&) will return the actual
255  * begin tag in its second argument.
256  *
257  * @param rLabel
258  * Token label to specify section
259  * @param rToken
260  * Begin tag as found in token stream.
261  *
262  * @exception Exception
263  * Section begin label not found (id 51)
264  *
265  */
266  void SeekBegin(const std::string& rLabel, Token& rToken);
267 
268  /**
269  * Peek a token and check whether it ends the specified section.
270  * This function is meant for scanning a section with a while- construct.
271  * \code
272  * SeekBegin("MySec");
273  * while(!Eos("MySec")) {
274  * ...
275  * };
276  * SeekEnd("MySec");
277  * \endcode
278  *
279  * @param rLabel
280  * Token label to specify section
281  *
282  * @exception Exception
283  * Unexpected eof (id 51)
284  *
285  * @return
286  * True at end of section
287  */
288  bool Eos(const std::string& rLabel);
289 
290  /**
291  * Read integer token
292  *
293  * @exception Exception
294  * Token mismatch (id 50)
295  *
296  * @return
297  * value of index token
298  */
299  long int ReadInteger(void);
300 
301  /**
302  * Read float token
303  *
304  * @exception Exception
305  * Token mismatch (id 50)
306  *
307  * @return
308  * value of index token
309  */
310  double ReadFloat(void);
311 
312  /**
313  * Read string token
314  *
315  * @exception Exception
316  * Token mismatch (id 50)
317  *
318  * @return
319  * value of name token
320  */
321  const std::string& ReadString(void);
322 
323  /**
324  * Read option token
325  *
326  * @exception Exception
327  * Token mismatch (id 50)
328  *
329  * @return
330  * value of name token
331  */
332  const std::string& ReadOption(void);
333 
334  /**
335  * Read binary token. You can access the binary array
336  * via StringValue();
337  *
338  * @return
339  * Binary data as std::string
340  * @exception Exception
341  * Token mismatch (id 50)
342  *
343  */
344  const std::string& ReadBinary(void);
345 
346 
347  /**
348  * Read plain text
349  *
350  * Read all text until and excluding the next markup.
351  * This method interprets known enteties and swallows
352  * beginning and ending white space. Effetively, ot is used
353  * to read ASCII compatible text.
354  *
355  * @exception Exception
356  * Stream mismatch (id 50)
357  *
358  * @return
359  * Text read.
360  */
361  const std::string& ReadText(void);
362 
363 
364  /**
365  * Read plain text
366  *
367  * Read all text until and excluding the next markup.
368  * This method does no interpretation whatever. It can be used
369  * to implement carbon copy of text sections.
370  *
371  * @exception Exception
372  * Stream mismatch (id 50)
373  *
374  * @return
375  * Text read.
376  */
377  const std::string& ReadCharacterData(void);
378 
379  /**
380  * Read XML section
381  *
382  * Reads the current section, including all character data and markup,
383  * until and excluding the matching end tag. This method does no interpretation whatever.
384  * the result is a string that represents
385  * the respective section in XML format.
386  *
387  * @exception Exception
388  * Stream mismatch (id 50)
389  * @return
390  * Text read.
391  */
392  const std::string& ReadSection(void);
393 
394 
395  /** Operator for get */
396  bool operator >> (Token& token) {
397  return Get(token);
398  }
399 
400  /**
401  * Return number of lines read
402  *
403  * @return
404  * Number of lines read
405  */
406  int Line(void) const;
407 
408  /**
409  * Return current level of section nesting
410  *
411  * @return
412  * Number of lines read
413  */
414  int Level(void) const { return mLevel;};
415 
416  /**
417  * Recover to specified section nesting
418  *
419  * The current implementation will mess up the Seek-stack. Thus,
420  * Recover() only works when no Seekbegin() was used.
421  *
422  * @return
423  * True on success
424  */
425  bool Recover(int level);
426 
427  /**
428  * Return "filename:line"
429  */
430  std::string FileLine(void) const;
431 
432  private:
433 
434  /** input mode */
436 
437  /** istream object pointer */
438  std::istream* mpStream;
439 
440  /** actual stream object, file input */
441  std::ifstream mFStream;
442 
443  /** actual stream object on heap, string input */
444  std::istringstream* mpSStream;
445 
446  /** Filename */
447  std::string mFileName;
448 
449  /** Line counter */
451 
452  /** file position */
453  long int mFilePos;
454 
455  /** Level (of nested sections)*/
456  int mLevel;
457 
458  /** label of sections */
459  std::vector<std::string> mLevelLabel;
460 
461  /** file positions of sections */
462  std::vector<long int> mLevelPos;
463 
464  /** file line of sections */
465  std::vector<long int> mLevelLine;
466 
467  /** level of recent seek */
468  std::vector<int> mSeekLevel;
469 
470  /** recent string buffer */
471  std::string mLastString;
472 
473  /** peek buffer */
475 };
476 
477 } // namespace faudes
478 
479 #define FAUDES_TOKENREADER_H
480 #endif

libFAUDES 2.24g --- 2014.09.15 --- c++ api documentaion by doxygen