libs/glibmm2/glib/glibmm/miscutils.h

   1 // -*- c++ -*-
   2 #ifndef _GLIBMM_MISCUTILS_H
   3 #define _GLIBMM_MISCUTILS_H
   4
   5 /* $Id: miscutils.h 428 2007-07-29 12:43:29Z murrayc $ */
   6
   7 /* Copyright (C) 2002 The gtkmm Development Team
   8  *
   9  * This library is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Library General Public
  11  * License as published by the Free Software Foundation; either
  12  * version 2 of the License, or (at your option) any later version.
  13  *
  14  * This library is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Library General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Library General Public
  20  * License along with this library; if not, write to the Free
  21  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  22  */
  23
  24 #include <glibmm/arrayhandle.h>
  25 #include <glibmm/ustring.h>
  26
  27
  28 namespace Glib
  29 {
  30
  31 /** @defgroup MiscUtils Miscellaneous Utility Functions
  32  * Miscellaneous Utility Functions -- a selection of portable utility functions.
  33  * @{
  34  */
  35
  36 /** Gets a human-readable name for the application,
  37  * as set by Glib::set_application_name().
  38  * This name should be localized if possible, and is intended for display to
  39  * the user.  Contrast with Glib::get_prgname(), which gets a non-localized
  40  * name. If Glib::set_application_name() has not been called, returns the
  41  * result of Glib::get_prgname() (which may be empty if Glib::set_prgname()
  42  * has also not been called).
  43  *
  44  * @return Human-readable application name. May return <tt>""</tt>.
  45  */
  46 Glib::ustring get_application_name();
  47
  48 /** Sets a human-readable name for the application.
  49  * This name should be localized if possible, and is intended for display to
  50  * the user.  Contrast with Glib::set_prgname(), which sets a non-localized
  51  * name.  Glib::set_prgname() will be called automatically by
  52  * <tt>gtk_init()</tt>, but Glib::set_application_name() will not.
  53  *
  54  * Note that for thread safety reasons, this function can only be called once.
  55  *
  56  * The application name will be used in contexts such as error messages,
  57  * or when displaying an application's name in the task list.
  58  *
  59  * @param application_name Localized name of the application.
  60  */
  61 void set_application_name(const Glib::ustring& application_name);
  62
  63 /** Gets the name of the program.
  64  * If you are using GDK or GTK+ the program name is set in <tt>gdk_init()</tt>,
  65  * which is called by <tt>gtk_init()</tt>.  The program name is found by taking
  66  * the last component of <tt>argv[0]</tt>.
  67  * @return The name of the program.
  68  */
  69 std::string get_prgname();
  70
  71 /** Sets the name of the program.
  72  * @param prgname The name of the program.
  73  */
  74 void set_prgname(const std::string& prgname);
  75
  76 /** Returns the value of an environment variable. The name and value
  77  * are in the GLib file name encoding. On Unix, this means the actual
  78  * bytes which might or might not be in some consistent character set
  79  * and encoding. On Windows, it is in UTF-8. On Windows, in case the
  80  * environment variable's value contains references to other
  81  * environment variables, they are expanded.
  82  *
  83  * @param variable The environment variable to get.
  84  * @retval found <tt>true</tt> Whether the environment variable has been found.
  85  * @return The value of the environment variable, or <tt>""</tt> if not found.
  86  */
  87 std::string getenv(const std::string& variable, bool& found);
  88
  89 /** Returns the value of an environment variable. The name and value
  90  * are in the GLib file name encoding. On Unix, this means the actual
  91  * bytes which might or might not be in some consistent character set
  92  * and encoding. On Windows, it is in UTF-8. On Windows, in case the
  93  * environment variable's value contains references to other
  94  * environment variables, they are expanded.
  95  *
  96  * @param variable The environment variable to get.
  97  * @return The value of the environment variable, or <tt>""</tt> if not found.
  98  */
  99 std::string getenv(const std::string& variable);
 100
 101
 102 /** Sets an environment variable. Both the variable's name and value
 103  * should be in the GLib file name encoding. On Unix, this means that
 104  * they can be any sequence of bytes. On Windows, they should be in
 105  * UTF-8.
 106  *
 107  * Note that on some systems, when variables are overwritten, the memory
 108  * used for the previous variables and its value isn't reclaimed.
 109  *
 110  * @param variable The environment variable to set. It must not contain '='.
 111  * @param value  The value to which the variable should be set.
 112  * @param overwrite Whether to change the variable if it already exists.
 113  * @result false if the environment variable couldn't be set.
 114  */
 115 bool setenv(const std::string& variable, const std::string& value, bool overwrite = true);
 116
 117 /** Removes an environment variable from the environment.
 118  *
 119  * Note that on some systems, when variables are overwritten, the memory
 120  * used for the previous variables and its value isn't reclaimed.
 121  * Furthermore, this function can't be guaranteed to operate in a
 122  * threadsafe way.
 123  *
 124  * @param variable: the environment variable to remove. It  must not contain '='.
 125  **/
 126 void unsetenv(const std::string& variable);
 127
 128 /** Gets the user name of the current user.
 129  * @return The name of the current user.
 130  */
 131 std::string get_user_name();
 132
 133 /** Gets the real name of the user.
 134  * This usually comes from the user's entry in the <tt>passwd</tt> file.
 135  * @return The user's real name.
 136  */
 137 std::string get_real_name();
 138
 139 /** Gets the current user's home directory.
 140  * @return The current user's home directory or an empty string if not defined.
 141  */
 142 std::string get_home_dir();
 143
 144 /** Gets the directory to use for temporary files.
 145  * This is found from inspecting the environment variables <tt>TMPDIR</tt>,
 146  * <tt>TMP</tt>, and <tt>TEMP</tt> in that order.  If none of those are defined
 147  * <tt>"/tmp"</tt> is returned on UNIX and <tt>"C:\\"</tt> on Windows.
 148  * @return The directory to use for temporary files.
 149  */
 150 std::string get_tmp_dir();
 151
 152 /** Gets the current directory.
 153  * @return The current directory.
 154  */
 155 std::string get_current_dir();
 156
 157 //TODO: We could create a C++ enum to wrap the C GUserDirectory enum,
 158 //but we would have to either be very careful, or define the enum
 159 //values in terms of the C enums anyway.
 160 /** Returns the full path of a special directory using its logical id.
 161  *
 162  * On Unix this is done using the XDG special user directories.
 163  *
 164  * Depending on the platform, the user might be able to change the path
 165  * of the special directory without requiring the session to restart; GLib
 166  * will not reflect any change once the special directories are loaded.
 167  *
 168  * Return value: the path to the specified special directory.
 169  * @param directory Te logical id of special directory
 170  *
 171  * @newin2p14
 172  */
 173 std::string get_user_special_dir(GUserDirectory directory);
 174
 175 /** Returns a base directory in which to access application data such as icons
 176  * that is customized for a particular user.
 177  *
 178  * On UNIX platforms this is determined using the mechanisms described in the
 179  * XDG Base Directory Specification
 180  *
 181  * @newin2p14
 182  */
 183 std::string get_user_data_dir();
 184
 185 /** Returns a base directory in which to store user-specific application
 186  * configuration information such as user preferences and settings.
 187  *
 188  * On UNIX platforms this is determined using the mechanisms described in the
 189  * XDG Base Directory Specification
 190  *
 191  * @newin2p14
 192  */
 193 std::string get_user_config_dir();
 194
 195 /** Returns a base directory in which to store non-essential, cached data
 196  * specific to particular user.
 197  *
 198  * On UNIX platforms this is determined using the mechanisms described in the
 199  * XDG Base Directory Specification
 200  *
 201  * @newin2p14
 202  */
 203 std::string get_user_cache_dir();
 204
 205 /** Returns @c true if the given @a filename is an absolute file name, i.e.\ it
 206  * contains a full path from the root directory such as <tt>"/usr/local"</tt>
 207  * on UNIX or <tt>"C:\\windows"</tt> on Windows systems.
 208  * @param filename A file name.
 209  * @return Whether @a filename is an absolute path.
 210  */
 211 bool path_is_absolute(const std::string& filename);
 212
 213 /** Returns the remaining part of @a filename after the root component,
 214  * i.e.\ after the <tt>"/"</tt> on UNIX or <tt>"C:\\"</tt> on Windows.
 215  * If @a filename is not an absolute path, <tt>""</tt> will be returned.
 216  * @param filename A file name.
 217  * @return The file name without the root component, or <tt>""</tt>.
 218  */
 219 std::string path_skip_root(const std::string& filename);
 220
 221 /** Gets the name of the file without any leading directory components.
 222  * @param filename The name of the file.
 223  * @return The name of the file without any leading directory components.
 224  */
 225 std::string path_get_basename(const std::string& filename);
 226
 227 /** Gets the directory components of a file name.
 228  * If the file name has no directory components <tt>"."</tt> is returned.
 229  * @param filename The name of the file.
 230  * @return The directory components of the file.
 231  */
 232 std::string path_get_dirname(const std::string& filename);
 233
 234 /** Creates a filename from a series of elements using the correct
 235  * separator for filenames.
 236  * This function behaves identically to Glib::build_path(G_DIR_SEPARATOR_S,
 237  * elements).  No attempt is made to force the resulting filename to be an
 238  * absolute path.  If the first element is a relative path, the result will
 239  * be a relative path.
 240  * @param elements A container holding the elements of the path to build.
 241  *   Any STL compatible container type is accepted.
 242  * @return The resulting path.
 243  */
 244 std::string build_filename(const Glib::ArrayHandle<std::string>& elements);
 245
 246 /** Creates a filename from two elements using the correct separator for filenames.
 247  * No attempt is made to force the resulting filename to be an absolute path.
 248  * If the first element is a relative path, the result will be a relative path.
 249  * @param elem1 First path element.
 250  * @param elem2 Second path element.
 251  * @return The resulting path.
 252  */
 253 std::string build_filename(const std::string& elem1, const std::string& elem2);
 254
 255 /** Creates a path from a series of elements using @a separator as the
 256  * separator between elements.
 257  *
 258  * At the boundary between two elements, any trailing occurrences of
 259  * @a separator in the first element, or leading occurrences of @a separator
 260  * in the second element are removed and exactly one copy of the separator is
 261  * inserted.
 262  *
 263  * Empty elements are ignored.
 264  *
 265  * The number of leading copies of the separator on the result is
 266  * the same as the number of leading copies of the separator on
 267  * the first non-empty element.
 268  *
 269  * The number of trailing copies of the separator on the result is the same
 270  * as the number of trailing copies of the separator on the last non-empty
 271  * element. (Determination of the number of trailing copies is done without
 272  * stripping leading copies, so if the separator is <tt>"ABA"</tt>,
 273  * <tt>"ABABA"</tt> has 1 trailing copy.)
 274  *
 275  * However, if there is only a single non-empty element, and there
 276  * are no characters in that element not part of the leading or
 277  * trailing separators, then the result is exactly the original value
 278  * of that element.
 279  *
 280  * Other than for determination of the number of leading and trailing
 281  * copies of the separator, elements consisting only of copies
 282  * of the separator are ignored.
 283  *
 284  * @param separator A string used to separate the elements of the path.
 285  * @param elements A container holding the elements of the path to build.
 286  *   Any STL compatible container type is accepted.
 287  * @return The resulting path.
 288  */
 289 std::string build_path(const std::string& separator,
 290                        const Glib::ArrayHandle<std::string>& elements);
 291
 292 /** Locates the first executable named @a program in the user's path, in the
 293  * same way that <tt>execvp()</tt> would locate it.
 294  * Returns a string with the absolute path name, or <tt>""</tt> if the program
 295  * is not found in the path.  If @a program is already an absolute path,
 296  * returns a copy of @a program if @a program exists and is executable, and
 297  * <tt>""</tt> otherwise.
 298  *
 299  * On Windows, if @a program does not have a file type suffix, tries to append
 300  * the suffixes in the <tt>PATHEXT</tt> environment variable (if that doesn't
 301  * exist, the suffixes .com, .exe, and .bat) in turn, and then look for the
 302  * resulting file name in the same way as CreateProcess() would.  This means
 303  * first in the directory where the program was loaded from, then in the
 304  * current directory, then in the Windows 32-bit system directory, then in the
 305  * Windows directory, and finally in the directories in the <tt>PATH</tt>
 306  * environment variable.  If the program is found, the return value contains
 307  * the full name including the type suffix.
 308  *
 309  * @param program A program name.
 310  * @return An absolute path, or <tt>""</tt>.
 311  */
 312 std::string find_program_in_path(const std::string& program);
 313
 314 /** @} group MiscUtils */
 315
 316 } // namespace Glib
 317
 318
 319 #endif /* _GLIBMM_FILEUTILS_H */
 320