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

libFAUDES 2.28a --- 2016.09.13 --- c++ api documentaion by doxygen