libFAUDES

Sections

Index

cfl_token.h

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

libFAUDES 2.18b --- 2010-12-17 --- c++ source docu by doxygen 1.6.3