CMake/Source/kwsys/SystemTools.hxx.in

/*=========================================================================

  Program:   KWSys - Kitware System Library
  Module:    $RCSfile$
  Language:  C++
  Date:      $Date$
  Version:   $Revision$

  Copyright (c) 2002 Kitware, Inc., Insight Consortium.  All rights reserved.
  See http://www.cmake.org/HTML/Copyright.html for details.

     This software is distributed WITHOUT ANY WARRANTY; without even 
     the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
     PURPOSE.  See the above copyright notices for more information.

=========================================================================*/
#ifndef @KWSYS_NAMESPACE@_SystemTools_hxx
#define @KWSYS_NAMESPACE@_SystemTools_hxx

#include <@KWSYS_NAMESPACE@/StandardIncludes.hxx>

#include <string>
#include <vector>

namespace @KWSYS_NAMESPACE@
{

/** \class SystemTools
 * \brief A collection of useful platform-independent system functions.
 */
class SystemTools
{
public:
  /**
   * Replace symbols in str that are not valid in C identifiers as
   * defined by the 1999 standard, ie. anything except [A-Za-z0-9_].
   * They are replaced with `_' and if the first character is a digit
   * then an underscore is prepended.  Note that this can produce
   * identifiers that the standard reserves (_[A-Z].* and __.*).
   */
  static kwsys_std::string MakeCindentifier(const char* s);
  
  /**
   * Make a new directory if it is not there.  This function
   * can make a full path even if none of the directories existed
   * prior to calling this function.  
   */
  static bool MakeDirectory(const char* path);

  /**
   * Get current time as a double. On certain platforms this will
   * return higher resolution than seconds:
   * (1) gettimeofday() -- resolution in microseconds
   * (2) ftime() -- resolution in milliseconds
   * (3) time() -- resolution in seconds
   */
  static double GetTime();

  /**
   * Replace replace all occurances of the string in
   * the source string.
   */
  static void ReplaceString(kwsys_std::string& source,
                            const char* replace,
                            const char* with);

  /**
   * Read a registry value
   */
  static bool ReadRegistryValue(const char *key, kwsys_std::string &value);

  /**
   * Write a registry value
   */
  static bool WriteRegistryValue(const char *key, const char *value);

  /**
   * Delete a registry value
   */
  static bool DeleteRegistryValue(const char *key);

  /**
   * Look for and replace registry values in a string
   */
  static void ExpandRegistryValues(kwsys_std::string& source);

  /**
   * Return a capitalized string (i.e the first letter is uppercased,
   * all other are lowercased).
   */
  static kwsys_std::string Capitalized(const kwsys_std::string&);
  
  /**
   * Return a lower case string
   */
  static kwsys_std::string LowerCase(const kwsys_std::string&);
  
  /**
   * Return a lower case string
   */
  static kwsys_std::string UpperCase(const kwsys_std::string&);
  
  /**
   * Replace Windows file system slashes with Unix-style slashes.
   */
  static void ConvertToUnixSlashes(kwsys_std::string& path);
  
  /**
   * Platform independent escape spaces, unix uses backslash,
   * windows double quotes the string.
   */
  static kwsys_std::string EscapeSpaces(const char* str);

  /** Escape quotes in a string.  */
  static kwsys_std::string EscapeQuotes(const char* str);

  /**
   * For windows this calles ConvertToWindowsOutputPath and for unix
   * it calls ConvertToUnixOutputPath
   */
  static kwsys_std::string ConvertToOutputPath(const char*);
  
  /** Return true if a file exists in the current directory.  */
  static bool FileExists(const char* filename);
  
  /**
   *  Add the paths from the environment variable PATH to the 
   *  string vector passed in.
   */
  static void GetPath(kwsys_std::vector<kwsys_std::string>& path);

  /**
   *  Get the file extension (including ".") needed for an executable
   *  on the current platform ("" for unix, ".exe" for Windows).
   */
  static const char* GetExecutableExtension();

  /**
   * Copy the source file to the destination file only
   * if the two files differ.  
   */
  static bool CopyFileIfDifferent(const char* source,
                                  const char* destination);
  
  ///! Compare the contents of two files.  Return true if different.
  static bool FilesDiffer(const char* source,
                          const char* destination);
  
  ///! return true if the two files are the same file
  static bool SameFile(const char* file1, const char* file2);

  ///! Copy a file.
  static bool CopyFileAlways(const char* source, const char* destination);
  
  ///! Remove a file.
  static bool RemoveFile(const char* source);
  
  ///! Find a file in the system PATH, with optional extra paths.
  static kwsys_std::string FindFile(const char* name,
                              const kwsys_std::vector<kwsys_std::string>& path= kwsys_std::vector<kwsys_std::string>());

  ///! Find an executable in the system PATH, with optional extra paths.
  static kwsys_std::string FindProgram(const char* name,
                                 const kwsys_std::vector<kwsys_std::string>& path = kwsys_std::vector<kwsys_std::string>(),
                                 bool no_system_path = false);

  ///! Find a library in the system PATH, with optional extra paths.
  static kwsys_std::string FindLibrary(const char* name,
                                 const kwsys_std::vector<kwsys_std::string>& path);
  
  ///! return true if the file is a directory.
  static bool FileIsDirectory(const char* name);
  static void Glob(const char *directory, const char *regexp,
                   kwsys_std::vector<kwsys_std::string>& files);
  static void GlobDirs(const char *fullPath, kwsys_std::vector<kwsys_std::string>& files);

  /**
   * Try to find a list of files that match the "simple" globbing
   * expression. At this point in time the globbing expressions have
   * to be in form: /directory/partial_file_name*. The * character has
   * to be at the end of the string and it does not support ?
   * []... The optional argument type specifies what kind of files you
   * want to find. 0 means all files, -1 means directories, 1 means
   * files only. This method returns true if search was succesfull.
   */
  static bool SimpleGlob(const kwsys_std::string& glob, kwsys_std::vector<kwsys_std::string>& files, 
                         int type = 0);
  
  static kwsys_std::string GetCurrentWorkingDirectory();
  
  /**
   * Given the path to a program executable, get the directory part of
   * the path with the file stripped off.  If there is no directory
   * part, the empty string is returned.
   */
  static kwsys_std::string GetProgramPath(const char*);
  static bool SplitProgramPath(const char* in_name, 
                               kwsys_std::string& dir, 
                               kwsys_std::string& file,
                               bool errorReport = true);
  
  /**
   * Given a path to a file or directory, convert it to a full path.
   * This collapses away relative paths relative to the cwd argument
   * (which defaults to the current working directory).  The full path
   * is returned.
   */
  static kwsys_std::string CollapseFullPath(const char* in_relative);
  static kwsys_std::string CollapseFullPath(const char* in_relative,
                                      const char* in_base);
  
  ///! return path of a full filename (no trailing slashes).
  static kwsys_std::string GetFilenamePath(const kwsys_std::string&);

  
  ///! return file name of a full filename (i.e. file name without path).
  static kwsys_std::string GetFilenameName(const kwsys_std::string&);
  
  ///! Split a program from its arguments and handle spaces in the paths.
  static void SplitProgramFromArgs(const char* path, 
                                   kwsys_std::string& program, kwsys_std::string& args);
  
  ///! return file extension of a full filename (dot included).
  static kwsys_std::string GetFilenameExtension(const kwsys_std::string&);
  
  ///! return file name without extension of a full filename.
  static kwsys_std::string GetFilenameWithoutExtension(const kwsys_std::string&);
  
  ///! return file name without its last (shortest) extension.
  static kwsys_std::string GetFilenameWithoutLastExtension(const kwsys_std::string&);
  
  /** Return whether the path represents a full path (not relative).  */
  static bool FileIsFullPath(const char*);
  
  static long int ModifiedTime(const char* filename);

  ///! for windows return the short path for the given path, unix just a pass through
  static bool GetShortPath(const char* path, kwsys_std::string& result);
  
  ///! change directory the the directory specified
  static int ChangeDirectory(const char* dir);

  /** Split a string on its newlines into multiple lines.  Returns
      false only if the last line stored had no newline.  */
  static bool Split(const char* s, kwsys_std::vector<kwsys_std::string>& l);
  
  static kwsys_std::string GetCurrentDateTime(const char* format);

  /** Get the result of strerror(errno).  */
  static kwsys_std::string GetLastSystemError();
  
  /** When building DEBUG with MSVC, this enables a hook that prevents
   * error dialogs from popping up if the program is being run from
   * DART.
   */
  static void EnableMSVCDebugHook();

  /**
   * Read line from file. Make sure to get everything. Due to a buggy stream
   * library on the HP and another on Mac OSX, we need this very carefully
   * written version of getline. Returns true if any data were read before the
   * end-of-file was reached.
   */
  static bool GetLineFromStream(kwsys_std::istream& istr, kwsys_std::string& line);
  
protected:
  // these two functions can be called from ConvertToOutputPath
  /**
   * Convert the path to a string that can be used in a unix makefile.
   * double slashes are removed, and spaces are escaped.
   */
  static kwsys_std::string ConvertToUnixOutputPath(const char*);
  
  /**
   * Convert the path to string that can be used in a windows project or
   * makefile.   Double slashes are removed if they are not at the start of
   * the string, the slashes are converted to windows style backslashes, and
   * if there are spaces in the string it is double quoted.
   */
  static kwsys_std::string ConvertToWindowsOutputPath(const char*);
};

} // namespace @KWSYS_NAMESPACE@

#endif