cfl_token.h
Go to the documentation of this file.
1 /** @file cfl_token.h @brief Class Token */
2 
3 /* FAU Dscrete 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 #ifndef FAUDES_TOKEN_H
24 
25 #include "cfl_definitions.h"
26 #include "cfl_helper.h"
27 #include <string>
28 #include <iostream>
29 #include <fstream>
30 #include <assert.h>
31 
32 namespace faudes {
33 
34 /**
35  * Tokens model atomic data for stream IO.
36  *
37  * A Token models a string or numeric datum that can be read from a
38  * or written to a C++ stream. The class itself implements the representation of
39  * the data including its type. For section handling and actual file processing
40  * see TokenReader and TokenWriter.
41  *
42  * @param mType
43  * faudes::TokenType of the Token
44  * @param mStringValue
45  * Token value as C++-type std::string
46  * @param mOptionValue
47  * Token value as interpreted option token
48  * @param mIntegerValue
49  * Token value as C++-type integer, faudes typedef Int
50  * @param mFloatValue
51  * Token value of C++-type double, faudes typedef Float
52  *
53  * @ingroup TokenIO
54  */
55 
56 class Token {
57 public:
58 
59  friend class TokenWriter;
60  friend class TokenReader;
61 
62  /**
63  * Empty constructor, constructs None token
64  */
65  Token(void);
66 
67  /**
68  * Copy constructor
69  */
70  Token(const Token& rToken);
71 
72 
73  /**
74  * Token destructor
75  */
76  ~Token(void);
77 
78  /** Assignment operator */
79  Token& operator= (const Token& rOther);
80 
81  /**
82  * Token types:
83  */
84  enum TokenType {
85  None= 0x000, ///< Invalid/empty token
86  Begin= 0x001, ///< <label> (begin of section)
87  End= 0x002, ///< <\\label> (end of section)
88  String= 0x004, ///< any string, space separated or quoted
89  Option= 0x008, ///< +xyZ+ (option string, may not contain a "+")
90  Integer= 0x010, ///< 1234 (non-negative integer)
91  Integer16=0x020, ///< 0x12fff ("0x" makes a number Integer16)
92  Boolean= 0x040, ///< True/False
93  Number= 0x080, ///< -12.34 ("-" or "." turns an integer to a number)
94  Binary= 0x100, ///< =ABhlkjj= (base64 encoded binary data)
95  Cdata= 0x200 ///< <![CDATA[ ... ]]> markup
96  };
97 
98 
99  /**
100  * Initialize None token
101  *
102  */
103  void SetNone(void);
104 
105  /**
106  * Initialize as String token
107  *
108  * @param rName
109  * String to fill the Token
110  */
111  void SetString(const std::string& rName);
112 
113  /**
114  * Initialize as Begin token
115  *
116  * @param rName
117  * Title of section to fill the Token
118  */
119  void SetBegin(const std::string& rName);
120 
121  /**
122  * Initialize as End token
123  *
124  * @param rName
125  * Title of section to fill the Token
126  */
127  void SetEnd(const std::string& rName);
128 
129  /**
130  * Initialize as empty-tag token
131  *
132  * @param rName
133  * Title of section to fill the Token
134  */
135  void SetEmpty(const std::string& rName);
136 
137  /**
138  * Initialize as Option token
139  *
140  * @param rName
141  * Option to fill the Token
142  */
143  void SetOption(const std::string& rName);
144 
145  /**
146  * Initialize as Integer token
147  *
148  * @param number
149  * Number to fill the Token
150  */
151  void SetInteger(const Int number);
152 
153  /**
154  * Initialize as Integer16 token
155  *
156  * @param number
157  * Number to fill the Token
158  */
159  void SetInteger16(const Int number);
160 
161  /**
162  * Initialize as Boolean token
163  *
164  * @param number
165  * Number to fill the Token
166  */
167  void SetBoolean(const Int number);
168 
169  /**
170  * Initialize as Float token
171  *
172  * @param number
173  * Number to fill the Token
174  */
175  void SetFloat(const Float number);
176 
177  /**
178  * Initialize Binary token.
179  * This method allocates a copy of the data.
180  * For writing only, you may use the TokenWriter interface
181  * to avoid the local copy.
182  *
183  * @param data
184  * Reference to raw data record
185  * @param len
186  * Number of bytes in record
187  */
188  void SetBinary(const char* data, std::size_t len);
189 
190 
191  /**
192  * Clear End type (resolve empty section)
193  *
194  */
195  void ClrEnd(void);
196 
197  /**
198  * Get integer value of a numeric token
199  *
200  * @return
201  * Token's integer value
202  */
203  Int IntegerValue(void) const;
204 
205  /**
206  * Get float value of a numeric token
207  *
208  * @return
209  * Token float value
210  */
211  Float FloatValue(void) const;
212 
213  /**
214  * Get string value of a name token
215  *
216  * @return
217  * Token's string value
218  */
219  const std::string& StringValue(void) const;
220 
221  /**
222  * Get option value of a name token
223  *
224  * @return
225  * Token's option value
226  */
227  const std::string& OptionValue(void) const;
228 
229  /**
230  * Get token Type
231  *
232  * This method is for backward compatibility only. It returns
233  * a token type with only oe bit set to indicate the
234  * type as in libfaudes up to version 2.17. To test
235  * for possible token interpretations, use the 2.17 interface
236  * IsInteger(), IsString() etc.
237  * @return
238  * Type of token
239  */
240  TokenType Type(void) const;
241 
242  /**
243  * Test token Type
244  *
245  * @return
246  * True on match
247  */
248  bool IsNone(void) const;
249 
250  /**
251  * Test token Type
252  *
253  * @return
254  * True on match
255  */
256  bool IsInteger(void) const;
257 
258  /**
259  * Test token Type
260  *
261  * @return
262  * True on match
263  */
264  bool IsInteger16(void) const;
265 
266  /**
267  * Test token Type
268  *
269  * @return
270  * True on match
271  */
272  bool IsBoolean(void) const;
273 
274  /**
275  * Test token Type
276  *
277  * @return
278  * True on match
279  */
280  bool IsFloat(void) const;
281 
282  /**
283  * Test token Type
284  *
285  * @return
286  * True on match
287  */
288  bool IsOption(void) const;
289 
290  /**
291  * Test token Type
292  *
293  * @return
294  * True on match
295  */
296  bool IsString(void) const;
297 
298  /**
299  * Test token Type
300  *
301  * @return
302  * True on match
303  */
304  bool IsBinary(void) const;
305 
306  /**
307  * Test token Type
308  *
309  * @return
310  * True on match
311  */
312  bool IsBegin(void) const;
313 
314  /**
315  * Test token Type
316  *
317  * @param tag
318  * Section tag to test for
319  * @return
320  * True on match
321  */
322  bool IsBegin(const std::string& tag) const;
323 
324  /**
325  * Test token Type
326  *
327  * @return
328  * True on match
329  */
330  bool IsEnd(void) const;
331 
332  /**
333  * Test token Type
334  *
335  * @param tag
336  * Section tag to test for
337  * @return
338  * True on match
339  */
340  bool IsEnd(const std::string& tag) const;
341 
342  /**
343  * Test token Type
344  *
345  * @return
346  * True on match
347  */
348  bool IsEmpty(void) const;
349 
350  /**
351  * Clear all attributes.
352  *
353  */
354  void ClearAttributes();
355 
356  /**
357  * Clear attribute.
358  *
359  * @param name
360  * Attribute name
361  */
362  void ClrAttribute(const std::string& name);
363 
364  /**
365  * Insert named attribute, no type.
366  * Note: only begin tags can have attributes.
367  *
368  * @param name
369  * Attribute name
370  * @param value
371  * Attribute value
372  */
373  void InsAttribute(const std::string& name, const std::string& value);
374 
375  /**
376  * Insert named attribute with string value.
377  * Note: only begin tags can have attributes.
378  *
379  * @param name
380  * Attribute name
381  * @param value
382  * Attribute value
383  */
384  void InsAttributeString(const std::string& name, const std::string& value);
385 
386  /**
387  * Insert named attribute with integer value.
388  * Note: only begin tags can have attributes.
389  *
390  * @param name
391  * Attribute name
392  * @param value
393  * Attribute value
394  */
395  void InsAttributeInteger(const std::string& name, Int value);
396 
397  /**
398  * Insert named attribute with integer value.
399  * Note: only begin tags can have attributes.
400  *
401  * @param name
402  * Attribute name
403  * @param value
404  * Attribute value
405  */
406  void InsAttributeInteger16(const std::string& name, Int value);
407 
408  /**
409  * Insert named attribute with boolean value.
410  * Note: only begin tags can have attributes.
411  *
412  * @param name
413  * Attribute name
414  * @param value
415  * Attribute value
416  */
417  void InsAttributeBoolean(const std::string& name, Int value);
418 
419  /**
420  * Insert named attribute with integer value.
421  * Note: only begin tags can have attributes.
422  *
423  * @param name
424  * Attribute name
425  * @param value
426  * Attribute value
427  */
428  void InsAttributeFloat(const std::string& name, Float value);
429 
430  /**
431  * Test attibute existence.
432  *
433  * @param name
434  * Attribute name
435  * @return
436  * True is attribute exists and matches type.
437  */
438  bool ExistsAttributeString(const std::string& name);
439 
440  /**
441  * Test attibute existence.
442  *
443  * @param name
444  * Attribute name
445  * @return
446  * True is attribute exists and matches type.
447  */
448  bool ExistsAttributeInteger(const std::string& name);
449 
450  /**
451  * Test attibute existence.
452  *
453  * @param name
454  * Attribute name
455  * @return
456  * True is attribute exists and matches type.
457  */
458  bool ExistsAttributeFloat(const std::string& name);
459 
460  /**
461  * Access attribute value
462  *
463  * @param name
464  * Attribute name
465  * @return
466  * String value of specified attribute
467  */
468  const std::string& AttributeStringValue(const std::string& name);
469 
470  /**
471  * Access attribute value
472  *
473  * @param name
474  * Attribute name
475  * @return
476  * Integer value of specified attribute (return 0 if it does not exist)
477  */
478  Int AttributeIntegerValue(const std::string& name);
479 
480 
481  /**
482  * Access attribute value
483  *
484  * @param name
485  * Attribute name
486  * @return
487  * String value of specified attribute
488  */
489  Float AttributeFloatValue(const std::string& name);
490 
491 
492  /**
493  * Read Token from input stream
494  *
495  * @param pStream
496  * Pointer to std::ifstream
497  * @exception Exception
498  * - ios exceptions (eg file io error)
499  * @return
500  * line count
501  */
502  int Read(std::istream* pStream);
503 
504  /**
505  * Write Token to output stream
506  *
507  * @param pStream
508  * Pointer to ostream
509  * @exception Exception
510  * - ios exceptions (eg file io error,)
511  */
512  void Write(std::ostream* pStream) const;
513 
514 
515  /** Write specified binary data as base64 string to output stream
516  *
517  * @param pStream
518  * Reference to std::ostream
519  * @param len
520  * Number of bytes to write
521  * @param pData
522  * Data to write
523  */
524  static void WriteBinary(std::ostream* pStream, const char* pData, std::size_t len);
525 
526  /** Write a std::string value to an output stream.
527  *
528  * This method writes a string verbatim, i.e. incl all control characters.
529  * It is enclosed by a marker which defaults to "__VERBATIM__". If the string
530  * contains the marker, a variation is used.
531  *
532  * @param pStream
533  * Reference to std::ostream
534  * @param rString
535  * String to write
536  */
537  static void WriteVerbatim(std::ostream* pStream, const std::string& rString);
538 
539  /** Write a std::string value to an output stream.
540  *
541  * This method replace critical characters by their XML entities and
542  * streams the resulting string. No whitespace etc added.
543  *
544  * @param pStream
545  * Reference to std::ostream
546  * @param outstr
547  * String to stream
548  * @return
549  * Number of characters written.
550  */
551  static int WriteEscapedString(std::ostream* pStream, const std::string& outstr);
552 
553 
554  /** Read a std::string value from an input file stream.
555  *
556  * Read an XML escaped string until and excl. the specified stop character.
557  *
558  * @param pStream
559  * Reference to std::istream
560  * @param stop
561  * Stop character
562  * @param rString
563  * Reference to result.
564  *
565  * @return
566  * Line count or -1 for error
567  */
568  static int ReadEscapedString(std::istream* pStream, char stop, std::string& rString);
569 
570  /** Read chracter data from an input file stream.
571  *
572  * Reads the stream untion the next "<" character.
573  * The plain character data is returned, no enteties substituted etc.
574  *
575  * @param pStream
576  * Reference to std::istream
577  * @param rString
578  * Reference to result.
579  *
580  * @return
581  * Line count or -1 for error
582  */
583  static int ReadCharacterData(std::istream* pStream, std::string& rString);
584 
585  /**
586  * Pretty print string representation
587  *
588  * Convenience functio for inspection/debugging
589  *
590  * @return
591  * Printable string representation
592  *
593  */
594  std::string Str(void) const;
595 
596 
597 private:
598 
599  /** Token type */
600  int mType;
601 
602  /** Token std::string value (for any token type) */
603  std::string mStringValue;
604 
605  /** Token std::string value (if token is of type Option) */
606  std::string mOptionValue;
607 
608  /** Token integer value (if Token is of type Integer or Integer16) */
610 
611  /** Token float value (if Token is of type Float or Integer) */
613 
614  /** When read from stream, record preceeding space */
616 
617  /** When read from stream, record preceeding space */
619 
620  /** Attribute value */
622  public:
624  std::string mStringValue;
627  int mType;
628  unsigned int mSort;
629  };
630 
631  /** Attribute value map */
632  std::map<std::string, AttributeValue> mAttributes;
633 
634  /** Attribute sort index (for nice output only) */
636 
637  /** Convenience typedef */
638  typedef std::map<std::string, AttributeValue>::iterator aiterator;
639  typedef std::map<std::string, AttributeValue>::const_iterator caiterator;
640 
641  /** Interpret attribute value from string */
642  void InterpretAttribute(aiterator ait);
643 
644  /** Interpret string a s number */
645  bool InterpretNumber(const std::string& numstr, int& type, Int& ival, Float& fval);
646 
647  /** Interpret string a s number */
648  bool InterpretNumber(void);
649 
650  /** Write a std::string value to an output stream.
651  *
652  * This method writes the string enclosed by a the specified
653  * delimiter, typically '"' or ' '. Relevant XML entities are
654  * replaced by references, e.g. &amp;lt; &amp;&amp; etc. A
655  * single white space is added as a sepqrqtor.
656  *
657  * @param pStream
658  * Reference to std::ostream
659  * @param delim
660  * Delimiter
661  */
662  void WriteString(std::ostream* pStream, const std::string& delim) const;
663 
664  /** Write my binary data as base64 string to output stream
665  *
666  * @param pStream
667  * Reference to std::ostream
668  */
669  void WriteBinary(std::ostream* pStream) const;
670 
671  /** Read a std::string value from an input file stream.
672  *
673  * This method assumes that the string was written in the format
674  * of WriteString, i.e. enclosed by single stop characters. However,
675  * for practical reasons, it is assumed that the first stop character has
676  * been allready read .
677  *
678  * @param pStream
679  * Reference to std::istream
680  * @param stop
681  * Stop character
682  *
683  * @return
684  * Line count or -1 for error
685  */
686  int ReadString(std::istream* pStream, char stop);
687 
688  /** Read and interpret attribute definitions of begin tags from an input file stream.
689  *
690  *
691  * @param pStream
692  * Reference to std::istream
693  *
694  * @return
695  * Line count or -1 for error
696  */
697  int ReadAttributes(std::istream* pStream);
698 
699  /** Read and interpret markup an input file stream.
700  *
701  * This method will identify begin and end tags. Any other XML
702  * markup is meant to be gracefully ignored be ignored.
703  *
704  * @param pStream
705  * Reference to std::istream
706  *
707  * @return
708  * Line count or -1 for error
709  */
710  int ReadMarkup(std::istream* pStream);
711 
712  /** Read a std::string value from an input file stream.
713  *
714  * This method assumes that the string was written in the format
715  * of WriteVerbatim, i.e. enclosed by a start and stop markers
716  * "__VERBATIM__" or variations thereof. However, for practical reasons,
717  * it is assumed that the first character "_" has been read allready.
718  * Note: verbatim sections are in general *NOT* XML compliant.
719  *
720  * @param pStream
721  * Reference to std::istream
722  *
723  * @return
724  * Line count or -1 for error
725  */
726  int ReadVerbatim(std::istream* pStream);
727 
728  /**
729  * Read a base64 binary string from an input file stream
730  *
731  * @param pStream
732  * Reference to std::istream
733  *
734  * @return
735  * Line count or -1 for error
736  */
737  int ReadBinary(std::istream* pStream);
738 
739  /**
740  * Read (ignore) spaces and comments in an input file stream
741  *
742  * @param pStream
743  * Reference to std::istream
744  *
745  * @return
746  * Number of lines read
747  */
748  int ReadSpace(std::istream* pStream);
749 };
750 
751 } // namespace faudes
752 
753 #define FAUDES_TOKEN_H
754 #endif
755 
756 

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