cfl_token.h

Go 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. &amp;lt; &amp;&amp; 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