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

libFAUDES 2.22k --- 2013.04.02 --- c++ source docu by doxygen