cfl_token.hGo to the documentation of this file.00001 /** @file cfl_token.h @brief Class Token */ 00002 00003 /* FAU Dscrete 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 #ifndef FAUDES_TOKEN_H 00024 00025 #include "cfl_definitions.h" 00026 #include "cfl_helper.h" 00027 #include <string> 00028 #include <iostream> 00029 #include <fstream> 00030 #include <assert.h> 00031 00032 namespace faudes { 00033 00034 /** 00035 * Tokens model atomic data for stream IO. 00036 * 00037 * A Token models a string or numeric datum that can be read from a 00038 * or written to a C++ stream. The class itself implements the representation of 00039 * the data including its type. For section handling and actual file processing 00040 * see TokenReader and TokenWriter. 00041 * 00042 * @param mType 00043 * faudes::TokenType of the Token 00044 * @param mStringValue 00045 * Token value as C++-type std::string 00046 * @param mOptionValue 00047 * Token value as interpreted option token 00048 * @param mIntegerValue 00049 * Token value as C++-type integer, faudes typedef Int 00050 * @param mFloatValue 00051 * Token value of C++-type double, faudes typedef Float 00052 * 00053 * @ingroup TokenIO 00054 */ 00055 00056 class Token { 00057 public: 00058 00059 friend class TokenWriter; 00060 friend class TokenReader; 00061 00062 /** 00063 * Empty constructor, constructs None token 00064 */ 00065 Token(void); 00066 00067 /** 00068 * Copy constructor 00069 */ 00070 Token(const Token& rToken); 00071 00072 00073 /** 00074 * Token destructor 00075 */ 00076 ~Token(void); 00077 00078 /** Assignment operator */ 00079 Token& operator= (const Token& rOther); 00080 00081 /** 00082 * Token types: 00083 */ 00084 enum TokenType { 00085 None= 0x000, ///< Invalid/empty token 00086 Begin= 0x001, ///< <label> (begin of section) 00087 End= 0x002, ///< <\\label> (end of section) 00088 String= 0x004, ///< any string, space separated or quoted 00089 Option= 0x008, ///< +xyZ+ (option string, may not contain a "+") 00090 Integer= 0x010, ///< 1234 (non-negative integer) 00091 Integer16=0x020, ///< 0x12fff ("0x" makes a number Integer16) 00092 Boolean= 0x040, ///< True/False 00093 Number= 0x080, ///< -12.34 ("-" or "." turns an integer to a number) 00094 Binary= 0x100, ///< =ABhlkjj= (base64 encoded binary data) 00095 Cdata= 0x200 ///< <![CDATA[ ... ]]> markup 00096 }; 00097 00098 00099 /** 00100 * Initialize None token 00101 * 00102 */ 00103 void SetNone(void); 00104 00105 /** 00106 * Initialize as String token 00107 * 00108 * @param rName 00109 * String to fill the Token 00110 */ 00111 void SetString(const std::string& rName); 00112 00113 /** 00114 * Initialize as Begin token 00115 * 00116 * @param rName 00117 * Title of section to fill the Token 00118 */ 00119 void SetBegin(const std::string& rName); 00120 00121 /** 00122 * Initialize as End token 00123 * 00124 * @param rName 00125 * Title of section to fill the Token 00126 */ 00127 void SetEnd(const std::string& rName); 00128 00129 /** 00130 * Initialize as empty-tag token 00131 * 00132 * @param rName 00133 * Title of section to fill the Token 00134 */ 00135 void SetEmpty(const std::string& rName); 00136 00137 /** 00138 * Initialize as Option token 00139 * 00140 * @param rName 00141 * Option to fill the Token 00142 */ 00143 void SetOption(const std::string& rName); 00144 00145 /** 00146 * Initialize as Integer token 00147 * 00148 * @param number 00149 * Number to fill the Token 00150 */ 00151 void SetInteger(const Int number); 00152 00153 /** 00154 * Initialize as Integer16 token 00155 * 00156 * @param number 00157 * Number to fill the Token 00158 */ 00159 void SetInteger16(const Int number); 00160 00161 /** 00162 * Initialize as Boolean token 00163 * 00164 * @param number 00165 * Number to fill the Token 00166 */ 00167 void SetBoolean(const Int number); 00168 00169 /** 00170 * Initialize as Float token 00171 * 00172 * @param number 00173 * Number to fill the Token 00174 */ 00175 void SetFloat(const Float number); 00176 00177 /** 00178 * Initialize Binary token. 00179 * This method allocates a copy of the data. 00180 * For writing only, you may use the TokenWriter interface 00181 * to avoid the local copy. 00182 * 00183 * @param data 00184 * Reference to raw data record 00185 * @param len 00186 * Number of bytes in record 00187 */ 00188 void SetBinary(const char* data, std::size_t len); 00189 00190 00191 /** 00192 * Clear End type (resolve empty section) 00193 * 00194 */ 00195 void ClrEnd(void); 00196 00197 /** 00198 * Get integer value of a numeric token 00199 * 00200 * @return 00201 * Token's integer value 00202 */ 00203 Int IntegerValue(void) const; 00204 00205 /** 00206 * Get float value of a numeric token 00207 * 00208 * @return 00209 * Token float value 00210 */ 00211 Float FloatValue(void) const; 00212 00213 /** 00214 * Get string value of a name token 00215 * 00216 * @return 00217 * Token's string value 00218 */ 00219 const std::string& StringValue(void) const; 00220 00221 /** 00222 * Get option value of a name token 00223 * 00224 * @return 00225 * Token's option value 00226 */ 00227 const std::string& OptionValue(void) const; 00228 00229 /** 00230 * Get token Type 00231 * 00232 * This method is for backward compatibility only. It returns 00233 * a token type with only oe bit set to indicate the 00234 * type as in libfaudes up to version 2.17. To test 00235 * for possible token interpretations, use the 2.17 interface 00236 * IsInteger(), IsString() etc. 00237 * @return 00238 * Type of token 00239 */ 00240 TokenType Type(void) const; 00241 00242 /** 00243 * Test token Type 00244 * 00245 * @return 00246 * True on match 00247 */ 00248 bool IsNone(void) const; 00249 00250 /** 00251 * Test token Type 00252 * 00253 * @return 00254 * True on match 00255 */ 00256 bool IsInteger(void) const; 00257 00258 /** 00259 * Test token Type 00260 * 00261 * @return 00262 * True on match 00263 */ 00264 bool IsInteger16(void) const; 00265 00266 /** 00267 * Test token Type 00268 * 00269 * @return 00270 * True on match 00271 */ 00272 bool IsBoolean(void) const; 00273 00274 /** 00275 * Test token Type 00276 * 00277 * @return 00278 * True on match 00279 */ 00280 bool IsFloat(void) const; 00281 00282 /** 00283 * Test token Type 00284 * 00285 * @return 00286 * True on match 00287 */ 00288 bool IsOption(void) const; 00289 00290 /** 00291 * Test token Type 00292 * 00293 * @return 00294 * True on match 00295 */ 00296 bool IsString(void) const; 00297 00298 /** 00299 * Test token Type 00300 * 00301 * @return 00302 * True on match 00303 */ 00304 bool IsBinary(void) const; 00305 00306 /** 00307 * Test token Type 00308 * 00309 * @return 00310 * True on match 00311 */ 00312 bool IsBegin(void) const; 00313 00314 /** 00315 * Test token Type 00316 * 00317 * @param tag 00318 * Section tag to test for 00319 * @return 00320 * True on match 00321 */ 00322 bool IsBegin(const std::string& tag) const; 00323 00324 /** 00325 * Test token Type 00326 * 00327 * @return 00328 * True on match 00329 */ 00330 bool IsEnd(void) const; 00331 00332 /** 00333 * Test token Type 00334 * 00335 * @param tag 00336 * Section tag to test for 00337 * @return 00338 * True on match 00339 */ 00340 bool IsEnd(const std::string& tag) const; 00341 00342 /** 00343 * Test token Type 00344 * 00345 * @return 00346 * True on match 00347 */ 00348 bool IsEmpty(void) const; 00349 00350 /** 00351 * Clear all attributes. 00352 * 00353 */ 00354 void ClearAttributes(); 00355 00356 /** 00357 * Clear attribute. 00358 * 00359 * @param name 00360 * Attribute name 00361 */ 00362 void ClrAttribute(const std::string& name); 00363 00364 /** 00365 * Insert named attribute, no type. 00366 * Note: only begin tags can have attributes. 00367 * 00368 * @param name 00369 * Attribute name 00370 * @param value 00371 * Attribute value 00372 */ 00373 void InsAttribute(const std::string& name, const std::string& value); 00374 00375 /** 00376 * Insert named attribute with string value. 00377 * Note: only begin tags can have attributes. 00378 * 00379 * @param name 00380 * Attribute name 00381 * @param value 00382 * Attribute value 00383 */ 00384 void InsAttributeString(const std::string& name, const std::string& value); 00385 00386 /** 00387 * Insert named attribute with integer value. 00388 * Note: only begin tags can have attributes. 00389 * 00390 * @param name 00391 * Attribute name 00392 * @param value 00393 * Attribute value 00394 */ 00395 void InsAttributeInteger(const std::string& name, Int value); 00396 00397 /** 00398 * Insert named attribute with integer value. 00399 * Note: only begin tags can have attributes. 00400 * 00401 * @param name 00402 * Attribute name 00403 * @param value 00404 * Attribute value 00405 */ 00406 void InsAttributeInteger16(const std::string& name, Int value); 00407 00408 /** 00409 * Insert named attribute with boolean value. 00410 * Note: only begin tags can have attributes. 00411 * 00412 * @param name 00413 * Attribute name 00414 * @param value 00415 * Attribute value 00416 */ 00417 void InsAttributeBoolean(const std::string& name, Int value); 00418 00419 /** 00420 * Insert named attribute with integer value. 00421 * Note: only begin tags can have attributes. 00422 * 00423 * @param name 00424 * Attribute name 00425 * @param value 00426 * Attribute value 00427 */ 00428 void InsAttributeFloat(const std::string& name, Float value); 00429 00430 /** 00431 * Test attibute existence. 00432 * 00433 * @param name 00434 * Attribute name 00435 * @return 00436 * True is attribute exists and matches type. 00437 */ 00438 bool ExistsAttributeString(const std::string& name); 00439 00440 /** 00441 * Test attibute existence. 00442 * 00443 * @param name 00444 * Attribute name 00445 * @return 00446 * True is attribute exists and matches type. 00447 */ 00448 bool ExistsAttributeInteger(const std::string& name); 00449 00450 /** 00451 * Test attibute existence. 00452 * 00453 * @param name 00454 * Attribute name 00455 * @return 00456 * True is attribute exists and matches type. 00457 */ 00458 bool ExistsAttributeFloat(const std::string& name); 00459 00460 /** 00461 * Access attribute value 00462 * 00463 * @param name 00464 * Attribute name 00465 * @return 00466 * String value of specified attribute 00467 */ 00468 const std::string& AttributeStringValue(const std::string& name); 00469 00470 /** 00471 * Access attribute value 00472 * 00473 * @param name 00474 * Attribute name 00475 * @return 00476 * Integer value of specified attribute (return 0 if it does not exist) 00477 */ 00478 Int AttributeIntegerValue(const std::string& name); 00479 00480 00481 /** 00482 * Access attribute value 00483 * 00484 * @param name 00485 * Attribute name 00486 * @return 00487 * String value of specified attribute 00488 */ 00489 Float AttributeFloatValue(const std::string& name); 00490 00491 00492 /** 00493 * Read Token from input stream 00494 * 00495 * @param pStream 00496 * Pointer to std::ifstream 00497 * @exception Exception 00498 * - ios exceptions (eg file io error) 00499 * @return 00500 * line count 00501 */ 00502 int Read(std::istream* pStream); 00503 00504 /** 00505 * Write Token to output stream 00506 * 00507 * @param pStream 00508 * Pointer to ostream 00509 * @exception Exception 00510 * - ios exceptions (eg file io error,) 00511 */ 00512 void Write(std::ostream* pStream) const; 00513 00514 00515 /** Write specified binary data as base64 string to output stream 00516 * 00517 * @param pStream 00518 * Reference to std::ostream 00519 * @param len 00520 * Number of bytes to write 00521 * @param pData 00522 * Data to write 00523 */ 00524 static void WriteBinary(std::ostream* pStream, const char* pData, std::size_t len); 00525 00526 /** Write a std::string value to an output stream. 00527 * 00528 * This method writes a string verbatim, i.e. incl all control characters. 00529 * It is enclosed by a marker which defaults to "__VERBATIM__". If the string 00530 * contains the marker, a variation is used. 00531 * 00532 * @param pStream 00533 * Reference to std::ostream 00534 * @param rString 00535 * String to write 00536 */ 00537 static void WriteVerbatim(std::ostream* pStream, const std::string& rString); 00538 00539 /** Write a std::string value to an output stream. 00540 * 00541 * This method replace critical characters by their XML entities and 00542 * streams the resulting string. No whitespace etc added. 00543 * 00544 * @param pStream 00545 * Reference to std::ostream 00546 * @param outstr 00547 * String to stream 00548 * @return 00549 * Number of characters written. 00550 */ 00551 static int WriteEscapedString(std::ostream* pStream, const std::string& outstr); 00552 00553 00554 /** Read a std::string value from an input file stream. 00555 * 00556 * Read an XML escaped string until and excl. the specified stop character. 00557 * 00558 * @param pStream 00559 * Reference to std::istream 00560 * @param stop 00561 * Stop character 00562 * @param rString 00563 * Reference to result. 00564 * 00565 * @return 00566 * Line count or -1 for error 00567 */ 00568 static int ReadEscapedString(std::istream* pStream, char stop, std::string& rString); 00569 00570 /** Read chracter data from an input file stream. 00571 * 00572 * Reads the stream untion the next "<" character. 00573 * The plain character data is returned, no enteties substituted etc. 00574 * 00575 * @param pStream 00576 * Reference to std::istream 00577 * @param rString 00578 * Reference to result. 00579 * 00580 * @return 00581 * Line count or -1 for error 00582 */ 00583 static int ReadCharacterData(std::istream* pStream, std::string& rString); 00584 00585 /** 00586 * Pretty print string representation 00587 * 00588 * Convenience functio for inspection/debugging 00589 * 00590 * @return 00591 * Printable string representation 00592 * 00593 */ 00594 std::string Str(void) const; 00595 00596 00597 private: 00598 00599 /** Token type */ 00600 int mType; 00601 00602 /** Token std::string value (for any token type) */ 00603 std::string mStringValue; 00604 00605 /** Token std::string value (if token is of type Option) */ 00606 std::string mOptionValue; 00607 00608 /** Token integer value (if Token is of type Integer or Integer16) */ 00609 Int mIntegerValue; 00610 00611 /** Token float value (if Token is of type Float or Integer) */ 00612 Float mFloatValue; 00613 00614 /** When read from stream, record preceeding space */ 00615 bool mPreceedingSpace; 00616 00617 /** When read from stream, record preceeding space */ 00618 bool mPreceedingNewline; 00619 00620 /** Attribute value */ 00621 class AttributeValue { 00622 public: 00623 AttributeValue(void) {mType=None;} 00624 std::string mStringValue; 00625 Int mIntegerValue; 00626 Float mFloatValue; 00627 int mType; 00628 unsigned int mSort; 00629 }; 00630 00631 /** Attribute value map */ 00632 std::map<std::string, AttributeValue> mAttributes; 00633 00634 /** Attribute sort index (for nice output only) */ 00635 int mAttributeCount; 00636 00637 /** Convenience typedef */ 00638 typedef std::map<std::string, AttributeValue>::iterator aiterator; 00639 typedef std::map<std::string, AttributeValue>::const_iterator caiterator; 00640 00641 /** Interpret attribute value from string */ 00642 void InterpretAttribute(aiterator ait); 00643 00644 /** Interpret string a s number */ 00645 bool InterpretNumber(const std::string& numstr, int& type, Int& ival, Float& fval); 00646 00647 /** Interpret string a s number */ 00648 bool InterpretNumber(void); 00649 00650 /** Write a std::string value to an output stream. 00651 * 00652 * This method writes the string enclosed by a the specified 00653 * delimiter, typically '"' or ' '. Relevant XML entities are 00654 * replaced by references, e.g. &lt; && etc. A 00655 * single white space is added as a sepqrqtor. 00656 * 00657 * @param pStream 00658 * Reference to std::ostream 00659 * @param delim 00660 * Delimiter 00661 */ 00662 void WriteString(std::ostream* pStream, const std::string& delim) const; 00663 00664 /** Write my binary data as base64 string to output stream 00665 * 00666 * @param pStream 00667 * Reference to std::ostream 00668 */ 00669 void WriteBinary(std::ostream* pStream) const; 00670 00671 /** Read a std::string value from an input file stream. 00672 * 00673 * This method assumes that the string was written in the format 00674 * of WriteString, i.e. enclosed by single stop characters. However, 00675 * for practical reasons, it is assumed that the first stop character has 00676 * been allready read . 00677 * 00678 * @param pStream 00679 * Reference to std::istream 00680 * @param stop 00681 * Stop character 00682 * 00683 * @return 00684 * Line count or -1 for error 00685 */ 00686 int ReadString(std::istream* pStream, char stop); 00687 00688 /** Read and interpret attribute definitions of begin tags from an input file stream. 00689 * 00690 * 00691 * @param pStream 00692 * Reference to std::istream 00693 * 00694 * @return 00695 * Line count or -1 for error 00696 */ 00697 int ReadAttributes(std::istream* pStream); 00698 00699 /** Read and interpret markup an input file stream. 00700 * 00701 * This method will identify begin and end tags. Any other XML 00702 * markup is meant to be gracefully ignored be ignored. 00703 * 00704 * @param pStream 00705 * Reference to std::istream 00706 * 00707 * @return 00708 * Line count or -1 for error 00709 */ 00710 int ReadMarkup(std::istream* pStream); 00711 00712 /** Read a std::string value from an input file stream. 00713 * 00714 * This method assumes that the string was written in the format 00715 * of WriteVerbatim, i.e. enclosed by a start and stop markers 00716 * "__VERBATIM__" or variations thereof. However, for practical reasons, 00717 * it is assumed that the first character "_" has been read allready. 00718 * Note: verbatim sections are in general *NOT* XML compliant. 00719 * 00720 * @param pStream 00721 * Reference to std::istream 00722 * 00723 * @return 00724 * Line count or -1 for error 00725 */ 00726 int ReadVerbatim(std::istream* pStream); 00727 00728 /** 00729 * Read a base64 binary string from an input file stream 00730 * 00731 * @param pStream 00732 * Reference to std::istream 00733 * 00734 * @return 00735 * Line count or -1 for error 00736 */ 00737 int ReadBinary(std::istream* pStream); 00738 00739 /** 00740 * Read (ignore) spaces and comments in an input file stream 00741 * 00742 * @param pStream 00743 * Reference to std::istream 00744 * 00745 * @return 00746 * Number of lines read 00747 */ 00748 int ReadSpace(std::istream* pStream); 00749 }; 00750 00751 } // namespace faudes 00752 00753 #define FAUDES_TOKEN_H 00754 #endif 00755 00756 libFAUDES 2.23h --- 2014.04.03 --- c++ api documentaion by doxygen |