About
User Reference
C++ API
luafaudes
Developer
Links
libFAUDES online
libFAUDES

Sections

Index

cfl_helper.h

Go to the documentation of this file.
00001 /** @file cfl_helper.h   Helper functions */
00002 
00003 /* FAU Discrete Event Systems Library (libfaudes)
00004 
00005    Copyright (C) 2006  Bernd Opitz
00006    Copyright (C) 2008-2010 Thomas Moor
00007    Exclusive copyright is granted to Klaus Schmidt
00008 
00009    This library is free software; you can redistribute it and/or
00010    modify it under the terms of the GNU Lesser General Public
00011    License as published by the Free Software Foundation; either
00012    version 2.1 of the License, or (at your option) any later version.
00013 
00014    This library is distributed in the hope that it will be useful,
00015    but WITHOUT ANY WARRANTY; without even the implied warranty of
00016    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00017    Lesser General Public License for more details.
00018 
00019    You should have received a copy of the GNU Lesser General Public
00020    License along with this library; if not, write to the Free Software
00021    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA */
00022 
00023 
00024 #ifndef FAUDES_HELPER_H
00025 #define FAUDES_HELPER_H
00026 
00027 #include <cstdlib>
00028 #include <cstring>
00029 #include <limits>
00030 #include <string>
00031 #include <iostream>
00032 #include <sstream>
00033 #include <fstream>
00034 #include <iomanip>
00035 #include <map>
00036 #include <set>
00037 
00038 
00039 #include "cfl_definitions.h"
00040 #include "cfl_exception.h"
00041 
00042 namespace faudes {
00043 
00044 // forward
00045 class Type;
00046 
00047 /**
00048  * integer to string
00049  * 
00050  * @param number
00051  *   integer
00052  *
00053  * @return
00054  *   string
00055  */
00056 std::string ToStringInteger(long int number);
00057 
00058 
00059 /**
00060  * integer to string base 16
00061  * 
00062  * @param number
00063  *   integer
00064  *
00065  * @return
00066  *   string
00067  */
00068 std::string ToStringInteger16(long int number);
00069 
00070 /**
00071  * float to string 
00072  * 
00073  * @param number
00074  *   double
00075  *
00076  * @return
00077  *   string
00078  */
00079 std::string ToStringFloat(double number);
00080 
00081 
00082 /**
00083  * Fill string with spaces up to a given length if length of the string
00084  * is smaller than given length parameter.
00085  *
00086  * @param rString
00087  *   string
00088  * @param len
00089  *   Minimum number of charakters in string
00090  *
00091  * @return
00092  *   Expanded string
00093  */
00094 std::string ExpandString(const std::string& rString, unsigned int len);
00095 
00096 /**
00097  * Limit length of string, return head and tail of string
00098  *
00099  * @param rString
00100  *   string
00101  * @param len
00102  *   Maximum number of charakters in string (approx)
00103  *
00104  * @return
00105  *   Collapsed string
00106  */
00107  std::string CollapsString(const std::string& rString, unsigned int len= FD_MAXCONTAINERNAME);
00108 
00109 
00110 /**
00111  * Convert a string to Idx
00112  *
00113  * @param rString
00114  *   string to convert
00115  *
00116  * @return 
00117  *   Idx
00118  *
00119  * @exception
00120  *   Idx overflow (id 600)
00121  */
00122 Idx ToIdx(const std::string& rString);
00123 
00124 /**
00125  * Substitute in string
00126  *
00127  * @param rString
00128  *   Source string to substitute
00129  * @param rFrom
00130  *   String to match
00131  * @param rTo
00132  *   Replacement to fill in 
00133  * @return 
00134  *   Result string
00135  *
00136  */
00137 std::string StringSubstitute(const std::string& rString,const std::string& rFrom,const std::string& rTo);
00138    
00139 
00140 
00141 /**
00142  * Return FAUDES_VERSION as std::string
00143  *
00144  * @return 
00145  *   std::string with FAUDES_VERSION
00146  */
00147 std::string FDVersionString();
00148 
00149 /**
00150  * Return FAUDES_PLUGINS as std::string
00151  *
00152  * @return 
00153  *   std::string with FAUDES_VERSION
00154  */
00155 std::string FDPluginsString();
00156 
00157 /**
00158  * Return contributors as std::string
00159  *
00160  * @return 
00161  *   std::string 
00162  */
00163 std::string FDContributorsString();
00164 
00165 
00166 /**
00167  * Convenience function: process dot file
00168  * to graphics output.  If no output format is given,
00169  * try to guess from filename extension. 
00170  *
00171  * @param rDotFile
00172  *   name of dot file
00173  * @param rOutFile
00174  *   name of graphics file 
00175  * @param rOutFormat
00176  *   graphics format eg "png", "jpg"
00177  * @param rDotExec
00178  *   path/name of executable
00179  *
00180  * @exception Exception
00181  *   - error in systemcall (id 3)
00182  *   - unkown format (id 3)
00183  *
00184  */
00185 void ProcessDot(const std::string& rDotFile, const std::string& rOutFile, 
00186   const std::string& rOutFormat = "", const std::string& rDotExec = "dot");
00187 
00188 
00189 /**
00190  * Create a temp file, length 0
00191  *
00192  * @return
00193  *   Name of temp file
00194  */
00195 std::string CreateTempFile(void);
00196 
00197 
00198 /**
00199  * Delete a file
00200  *
00201  * @param rFileName
00202  *   Name of file to delete
00203  */
00204 bool RemoveFile(const std::string& rFileName);
00205 
00206 /**
00207  * Std dir-separator.
00208  * @return
00209  *   Separator as one-char string
00210  */
00211 const std::string& DirSeparator(void);
00212 
00213 /**
00214  * Extract directory from full path.
00215  *
00216  * @param rFullPath
00217  *   Full name of file eg "/home/friend/data/generator.gen"
00218  * @return
00219  *   Directory eg "/home/friend/data"
00220  */
00221 std::string ExtractDirectory(const std::string& rFullPath);
00222 
00223 /**
00224  * Extract file name from full path.
00225  *
00226  * @param rFullName
00227  *   Full path of file eg "/home/friend/data/generator.gen"
00228  * @return
00229  *   Filename "generator.gen"
00230  */
00231 std::string ExtractFilename(const std::string& rFullName);
00232 
00233 /**
00234  * Extract file name from full path. This version also
00235  * remove the last suffix.
00236  *
00237  * @param rFullName
00238  *   Full path of file eg "/home/friend/data/generator.gen"
00239  * @return
00240  *   Filename "generator"
00241  */
00242 std::string ExtractBasename(const std::string& rFullName);
00243 
00244 /**
00245  * Extract file name from full path. This version also
00246  * remove the last suffix.
00247  *
00248  * @param rFullName
00249  *   Full path of file eg "/home/friend/data/generator.gen"
00250  * @return
00251  *   Extension "gen"
00252  */
00253 std::string ExtractExtension(const std::string& rFullName);
00254 
00255 /**
00256  * Construct full path from directory and filename.
00257  *
00258  * @param rDirectory
00259  *   Directory eg "/home/friend/data"
00260  * @param rFileName
00261  *   File eg "generator.gen"
00262  * @return
00263  *   Path eg "/home/friend/data/generator.gen"
00264  */
00265 std::string PrependDirectory(const std::string& rDirectory, const std::string& rFileName);
00266 
00267 /**
00268  * Test existence of file
00269  *
00270  * @param rFilename
00271  *   Name of file to test
00272  * @return
00273  *   True <> can open file for reading
00274  */
00275 bool FileExists(const std::string& rFilename);
00276 
00277 
00278 /**
00279  * Read the contents of the specified directors.
00280  *
00281  * @param rDirectory
00282  *   Directory eg "/home/friend/data"
00283  * @return
00284  *   List of files, e.g. "gen1.gen gen2.gen data subdir"
00285  */
00286 std::set< std::string > ReadDirectory(const std::string& rDirectory);
00287 
00288 /**
00289  * Console Out
00290  *
00291  * All console out messages (errors, progress report etc) are
00292  * meant to use the global ConsoleOut instance gConsoleOut, presumably
00293  * using the convenience macro FAUDES_WRITE_CONSOLE(). The default ConsoleOut::G()
00294  * provides optional redirection to a named file by 
00295  * G()->ConsoleOut.ToFile("filename"). 
00296  * 
00297  * libFAUDES applications can use this construct to grab all
00298  * console output by 1) deriving a specialised class from ConsoleOut and 2) 
00299  * redirection by ConsoleOut::G()->Redirect(derived_class_instance).
00300  */
00301 class ConsoleOut {
00302 public:
00303   /** Acess static instance */
00304   static ConsoleOut* G(void);
00305   /** Write a std::string message (optional progress report) */
00306   virtual void Write(const std::string& message,long int cntnow=0, long int cntdone=0);
00307   /** Redirect to file */
00308   void ToFile(const std::string& filename);
00309   /** Query filename */
00310   const std::string& Filename(void) { return mFilename;}; 
00311   /** Redirect */
00312   void Redirect(ConsoleOut* out);
00313   /** Mute */
00314   void Mute(bool on) {mMute=on;};
00315   bool Mute() { return mMute;};
00316 protected:
00317   /** Constructor */
00318   ConsoleOut(void);
00319   /** Destructor */
00320   virtual ~ConsoleOut(void);
00321   /** Writing hook. Re-implement this function in order to grab all output */
00322   virtual void DoWrite(const std::string& message,long int cntnow=0, long int cntdone=0);
00323 private:
00324   /** Private output stream */
00325   std::ofstream* pStream;
00326   /** Private record file name */
00327   std::string mFilename;
00328   /** Mute flag */
00329   bool mMute;
00330   /** Redirect */
00331   ConsoleOut* pInstance;
00332   /** Private static instance */
00333   static ConsoleOut* smpInstance;
00334 };
00335 
00336  
00337 /**
00338  * Debugging counter. Counts items as specified by the type string and reports
00339  * sums on exit. You must define the macro FAUDES_DEBUG_CODE to get a report.
00340  *
00341  * Technical note: we use the somewhat winded static member construct to
00342  * guerantee that our member variables have been constructed befor actual
00343  * counting occurs. This is neccessary since some faudes types might have a
00344  * static instance and, hence, may be consructed rather early. 
00345  *
00346  */
00347 class ObjectCount {
00348  public:
00349   static void Inc(const std::string& rTypeName);
00350   static void Dec(const std::string& rTypeName);
00351   static void Init(void);
00352   static std::map< std::string, long int >* mspMax;
00353   static std::map< std::string, long int >* mspCount;
00354  private:
00355   static bool msDone;
00356   ObjectCount(void);
00357 };
00358 
00359 
00360 /**
00361  * Test Protocol. 
00362  * Sets the filename for the test protocol by 
00363  * - removing any path specififucation,
00364  * - replacing "." by "_",
00365  * - appending ".prot", and finaly
00366  * - prepending "tmp_".
00367  * The function returns the filename except for the
00368  * "tmp_" prefix. The latter is considered the nominal
00369  * protocol output (aka reference protocol).
00370  * 
00371  * Note: only the first invocation of this functions actually sets
00372  * the protocol file. Further invocations are ignored, but can be
00373  * used to query the reference protocol.
00374  * 
00375  * @param rSource
00376  *   Source file to protocol
00377  * @return
00378  *   Filename with nominal protocol.
00379  *
00380  */
00381 std::string TestProtocol(const std::string& rSource);  
00382 
00383 
00384 /**
00385  * Test Protocol. 
00386  * This function dumps the specified data to the protocol file for
00387  * the purpose of later comparison with a refernce value.
00388  * If the protocol file has not been set up, this
00389  * function does nothing; see also TestProtocol(const std::string&.  
00390  * 
00391  * @param rMessage
00392  *   Informal identifyer of the test
00393  * @param rData
00394  *   Formal result of the test case
00395  * @param core
00396  *   Whether to record full token io or statistics only.
00397  *
00398  */
00399 void TestProtocol(const std::string& rMessage, const Type& rData, bool core=false); 
00400 
00401 /**
00402  * Test Protocol. 
00403  * Specialized version for boolean test data. 
00404  * See also TestProtocol(const std::string&, const Type&, bool);
00405  * 
00406  * @param rMessage
00407  *   Informal identifyer of the test
00408  * @param data
00409  *   Test data
00410  *
00411  */
00412 void TestProtocol(const std::string& rMessage, bool data); 
00413 
00414 /**
00415  * Test Protocol. 
00416  * Specialized version for integer test data. 
00417  * See also TestProtocol(const std::string&, const Type&, bool);
00418  * 
00419  * @param rMessage
00420  *   Informal identifyer of the test
00421  * @param data
00422  *   Test data
00423  *
00424  */
00425 void TestProtocol(const std::string& rMessage, long int data); 
00426 
00427 
00428 /**
00429  * Test Protocol. 
00430  * Specialized version for string data. 
00431  * See also TestProtocol(const std::string&, const Type&, bool);
00432  * 
00433  * @param rMessage
00434  *   Informal identifyer of the test
00435  * @param data
00436  *   Test data
00437  *
00438  */
00439  void TestProtocol(const std::string& rMessage, const std::string& data); 
00440 
00441 
00442 /**
00443  * Test Protocol. 
00444  * Perform a comparison of the recent protocol file and the
00445  * corresponding reference. Returns true if the test passes.
00446  *
00447  * Note: this function closes the current protocol.
00448  *
00449  * @return 
00450  *    True <=> test past
00451  */
00452 bool TestProtocol(void);
00453 
00454 
00455 /** Test protocol record macro */
00456 #define FAUDES_TEST_DUMP(mes,dat) { std::stringstream sstr; sstr << \
00457   mes << " [at " << __FILE__ << ":" << __LINE__ << "]" ; \
00458   TestProtocol(__FILE__); TestProtocol(sstr.str(),dat); }
00459 
00460 /** Test protocol diff macro */
00461 #define FAUDES_TEST_DIFF() { if(!TestProtocol()) { \
00462     FAUDES_WRITE_CONSOLE("FAUDES_TEST_DIFF: sensed test case error in " << __FILE__); exit(1);} }
00463 
00464 
00465 /** Algorithm loop callback 
00466  *
00467  * Set a callback function for libFAUDES algorithms. Applications
00468  * are meant to use this interface to terminate an algorithm on user
00469  * request. libFAUDES algorithms are meant to throw an execption when
00470  * the callback function returns true. See also void LoopCallback(void).
00471  *
00472  * @param pBreakFnct
00473  *
00474  */
00475  void LoopCallback(bool (*pBreakFnct)(void));
00476 
00477  /** Algorithm loop callback
00478   *
00479   * Calls the loop callback function and throws an exception if it
00480   * returns true. 
00481   *
00482   * @exception
00483   *   Break on appliation request (id 110)
00484   *
00485   */
00486  void LoopCallback(void);
00487 
00488 
00489 
00490 } // namespace faudes
00491 
00492 
00493 #endif
00494 

libFAUDES 2.20s --- 2011.10.12 --- c++ source docu by doxygen