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, preumably
00293  * using the convenience macro FAUDES_WRITE_CONSOLE(). The default gConsoleOut
00294  * provides redirection to a named file by gConsoleOut.ToFile("filename"). libFAUDES 
00295  * Applications can use this construct in deriving a specialised class from ConsoleOut to
00296  * grab and inspect all console output.
00297  */
00298 class ConsoleOut {
00299 public:
00300   /** Write a std::string message */
00301   void Write(const std::string& message);
00302   /** Retrieve buffer to write on */
00303   std::ostream& Buffer(void);
00304   /** Flush buffer to output, optional progress estimate */
00305   void Flush(long int cntnow=0, long int cntdone=0);
00306   /** Redirect to file */
00307   void ToFile(const std::string& filename);
00308   /** Query filename */
00309   const std::string& Filename(void) { return mFilename;}; 
00310   /** acess static instance */
00311   static ConsoleOut* G(void);
00312   /** Redirect */
00313   void Redirect(ConsoleOut* out);
00314   /** Mute */
00315   void Mute(bool on) {mMute=on;};
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(long int cntnow, long int cntdone, const std::string& message);
00323 private:
00324   /** Private line buffer */
00325   std::ostringstream mLineBuffer;
00326   /** Private output stream */
00327   std::ofstream* pStream;
00328   /** Private record file name */
00329   std::string mFilename;
00330   /** Mute flag */
00331   bool mMute;
00332   /** Private static instance */
00333   static ConsoleOut* spInstance;
00334 };
00335 
00336  
00337 /**
00338  * Globale console out object and reference
00339  */
00340 extern ConsoleOut gConsoleOut;
00341 extern ConsoleOut gpConsoleOut;
00342 
00343 
00344 /**
00345  * Debugging counter. Counts items as specified by the type string and reports
00346  * sums on exit. You must define the macro FAUDES_DEBUG_CODE to get a report.
00347  *
00348  * Technical note: we use the somewhat winded static member construct to
00349  * guerantee that our member variables have been constructed befor actual
00350  * counting occurs. This is neccessary since some faudes types might have a
00351  * static instance and, hence, may be consructed rather early. 
00352  *
00353  */
00354 class ObjectCount {
00355  public:
00356   static void Inc(const std::string& rTypeName);
00357   static void Dec(const std::string& rTypeName);
00358   static void Init(void);
00359   static std::map< std::string, long int >* mspMax;
00360   static std::map< std::string, long int >* mspCount;
00361  private:
00362   static bool msDone;
00363   ObjectCount(void);
00364 };
00365 
00366 
00367 /**
00368  * Test Protocol. 
00369  * Sets the filename for the test protocol by 
00370  * - removing any path specififucation,
00371  * - replacing "." by "_",
00372  * - appending ".prot", and finaly
00373  * - prepending "tmp_".
00374  * The function returns the filename except for the
00375  * "tmp_" prefix. The latter is considered the nominal
00376  * protocol output (aka reference protocol).
00377  * 
00378  * Note: only the first invocation of this functions actually sets
00379  * the protocol file. Further invocations are ignored, but can be
00380  * used to query the reference protocol.
00381  * 
00382  * @param rSource
00383  *   Source file to protocol
00384  * @return
00385  *   Filename with nominal protocol.
00386  *
00387  */
00388 std::string TestProtocol(const std::string& rSource);  
00389 
00390 
00391 /**
00392  * Test Protocol. 
00393  * This function dumps the specified data to the protocol file for
00394  * the purpose of later comparison with a refernce value.
00395  * If the protocol file has not been set up, this
00396  * function does nothing; see also TestProtocol(const std::string&.  
00397  * 
00398  * @param rMessage
00399  *   Informal identifyer of the test
00400  * @param rData
00401  *   Formal result of the test case
00402  * @param core
00403  *   Whether to record full token io or statistics only.
00404  *
00405  */
00406 void TestProtocol(const std::string& rMessage, const Type& rData, bool core=false); 
00407 
00408 /**
00409  * Test Protocol. 
00410  * Specialized version for boolean test data. 
00411  * See also TestProtocol(const std::string&, const Type&, bool);
00412  * 
00413  * @param rMessage
00414  *   Informal identifyer of the test
00415  * @param data
00416  *   Test data
00417  *
00418  */
00419 void TestProtocol(const std::string& rMessage, bool data); 
00420 
00421 /**
00422  * Test Protocol. 
00423  * Specialized version for integer test data. 
00424  * See also TestProtocol(const std::string&, const Type&, bool);
00425  * 
00426  * @param rMessage
00427  *   Informal identifyer of the test
00428  * @param data
00429  *   Test data
00430  *
00431  */
00432 void TestProtocol(const std::string& rMessage, long int data); 
00433 
00434 
00435 /**
00436  * Test Protocol. 
00437  * Specialized version for string data. 
00438  * See also TestProtocol(const std::string&, const Type&, bool);
00439  * 
00440  * @param rMessage
00441  *   Informal identifyer of the test
00442  * @param data
00443  *   Test data
00444  *
00445  */
00446  void TestProtocol(const std::string& rMessage, const std::string& data); 
00447 
00448 
00449 /**
00450  * Test Protocol. 
00451  * Perform a comparison of the recent protocol file and the
00452  * corresponding reference. Returns true if the test passes.
00453  *
00454  * Note: this function closes the current protocol.
00455  *
00456  * @return 
00457  *    True <=> test past
00458  */
00459 bool TestProtocol(void);
00460 
00461 
00462 /** Test protocol record macro */
00463 #define FAUDES_TEST_DUMP(mes,dat) { std::stringstream sstr; sstr << \
00464   mes << " [at " << __FILE__ << ":" << __LINE__ << "]" ; \
00465   TestProtocol(__FILE__); TestProtocol(sstr.str(),dat); }
00466 
00467 /** Test protocol diff macro */
00468 #define FAUDES_TEST_DIFF() { if(!TestProtocol()) { \
00469     FAUDES_WRITE_CONSOLE("FAUDES_TEST_DIFF: sensed test case error in " << __FILE__); exit(1);} }
00470 
00471 
00472 /** Algorithm loop callback 
00473  *
00474  * Set a callback function for libFAUDES algorithms. Applications
00475  * are meant to use this interface to terminate an algorithm on user
00476  * request. libFAUDES algorithms are meant to throw an execption when
00477  * the callback function returns true. See also void LoopCallback(void).
00478  *
00479  * @param pBreakFnct
00480  *
00481  */
00482  void LoopCallback(bool (*pBreakFnct)(void));
00483 
00484  /** Algorithm loop callback
00485   *
00486   * Calls the loop callback function and throws an exception if it
00487   * returns true. 
00488   *
00489   * @exception
00490   *   Break on appliation request (id 110)
00491   *
00492   */
00493  void LoopCallback(void);
00494 
00495 
00496 
00497 } // namespace faudes
00498 
00499 
00500 #endif
00501 

libFAUDES 2.20d --- 2011.04.26 --- c++ source docu by doxygen