// -*- c++ -*- #ifndef _GLIBMM_MISCUTILS_H #define _GLIBMM_MISCUTILS_H /* $Id$ */ /* Copyright (C) 2002 The gtkmm Development Team * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Library General Public * License as published by the Free Software Foundation; either * version 2 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Library General Public License for more details. * * You should have received a copy of the GNU Library General Public * License along with this library; if not, write to the Free * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ #include #include namespace Glib { /** @defgroup MiscUtils Miscellaneous Utility Functions * Miscellaneous Utility Functions -- a selection of portable utility functions. * @{ */ /** Gets a human-readable name for the application, * as set by Glib::set_application_name(). * This name should be localized if possible, and is intended for display to * the user. Contrast with Glib::get_prgname(), which gets a non-localized * name. If Glib::set_application_name() has not been called, returns the * result of Glib::get_prgname() (which may be empty if Glib::set_prgname() * has also not been called). * * @return Human-readable application name. May return "". */ Glib::ustring get_application_name(); /** Sets a human-readable name for the application. * This name should be localized if possible, and is intended for display to * the user. Contrast with Glib::set_prgname(), which sets a non-localized * name. Glib::set_prgname() will be called automatically by * gtk_init(), but Glib::set_application_name() will not. * * Note that for thread safety reasons, this function can only be called once. * * The application name will be used in contexts such as error messages, * or when displaying an application's name in the task list. * * @param application_name Localized name of the application. */ void set_application_name(const Glib::ustring& application_name); /** Gets the name of the program. * If you are using GDK or GTK+ the program name is set in gdk_init(), * which is called by gtk_init(). The program name is found by taking * the last component of argv[0]. * @return The name of the program. */ std::string get_prgname(); /** Sets the name of the program. * @param prgname The name of the program. */ void set_prgname(const std::string& prgname); /** Returns the value of an environment variable. The name and value * are in the GLib file name encoding. On Unix, this means the actual * bytes which might or might not be in some consistent character set * and encoding. On Windows, it is in UTF-8. On Windows, in case the * environment variable's value contains references to other * environment variables, they are expanded. * * @param variable The environment variable to get. * @retval found true Whether the environment variable has been found. * @return The value of the environment variable, or "" if not found. */ std::string getenv(const std::string& variable, bool& found); /** Returns the value of an environment variable. The name and value * are in the GLib file name encoding. On Unix, this means the actual * bytes which might or might not be in some consistent character set * and encoding. On Windows, it is in UTF-8. On Windows, in case the * environment variable's value contains references to other * environment variables, they are expanded. * * @param variable The environment variable to get. * @return The value of the environment variable, or "" if not found. */ std::string getenv(const std::string& variable); /** Sets an environment variable. Both the variable's name and value * should be in the GLib file name encoding. On Unix, this means that * they can be any sequence of bytes. On Windows, they should be in * UTF-8. * * Note that on some systems, when variables are overwritten, the memory * used for the previous variables and its value isn't reclaimed. * * @param variable The environment variable to set. It must not contain '='. * @param value The value to which the variable should be set. * @param overwrite Whether to change the variable if it already exists. * @result false if the environment variable couldn't be set. */ bool setenv(const std::string& variable, const std::string& value, bool overwrite = true); /** Removes an environment variable from the environment. * * Note that on some systems, when variables are overwritten, the memory * used for the previous variables and its value isn't reclaimed. * Furthermore, this function can't be guaranteed to operate in a * threadsafe way. * * @param variable: the environment variable to remove. It must not contain '='. **/ void unsetenv(const std::string& variable); /** Gets the user name of the current user. * @return The name of the current user. */ std::string get_user_name(); /** Gets the real name of the user. * This usually comes from the user's entry in the passwd file. * @return The user's real name. */ std::string get_real_name(); /** Gets the current user's home directory. * @return The current user's home directory. */ std::string get_home_dir(); /** Gets the directory to use for temporary files. * This is found from inspecting the environment variables TMPDIR, * TMP, and TEMP in that order. If none of those are defined * "/tmp" is returned on UNIX and "C:\\" on Windows. * @return The directory to use for temporary files. */ std::string get_tmp_dir(); /** Gets the current directory. * @return The current directory. */ std::string get_current_dir(); /** Returns @c true if the given @a filename is an absolute file name, i.e.\ it * contains a full path from the root directory such as "/usr/local" * on UNIX or "C:\\windows" on Windows systems. * @param filename A file name. * @return Whether @a filename is an absolute path. */ bool path_is_absolute(const std::string& filename); /** Returns the remaining part of @a filename after the root component, * i.e.\ after the "/" on UNIX or "C:\\" on Windows. * If @a filename is not an absolute path, "" will be returned. * @param filename A file name. * @return The file name without the root component, or "". */ std::string path_skip_root(const std::string& filename); /** Gets the name of the file without any leading directory components. * @param filename The name of the file. * @return The name of the file without any leading directory components. */ std::string path_get_basename(const std::string& filename); /** Gets the directory components of a file name. * If the file name has no directory components "." is returned. * @param filename The name of the file. * @return The directory components of the file. */ std::string path_get_dirname(const std::string& filename); /** Creates a filename from a series of elements using the correct * separator for filenames. * This function behaves identically to Glib::build_path(G_DIR_SEPARATOR_S, * elements). No attempt is made to force the resulting filename to be an * absolute path. If the first element is a relative path, the result will * be a relative path. * @param elements A container holding the elements of the path to build. * Any STL compatible container type is accepted. * @return The resulting path. */ std::string build_filename(const Glib::ArrayHandle& elements); /** Creates a filename from two elements using the correct separator for filenames. * No attempt is made to force the resulting filename to be an absolute path. * If the first element is a relative path, the result will be a relative path. * @param elem1 First path element. * @param elem2 Second path element. * @return The resulting path. */ std::string build_filename(const std::string& elem1, const std::string& elem2); /** Creates a path from a series of elements using @a separator as the * separator between elements. * * At the boundary between two elements, any trailing occurrences of * @a separator in the first element, or leading occurrences of @a separator * in the second element are removed and exactly one copy of the separator is * inserted. * * Empty elements are ignored. * * The number of leading copies of the separator on the result is * the same as the number of leading copies of the separator on * the first non-empty element. * * The number of trailing copies of the separator on the result is the same * as the number of trailing copies of the separator on the last non-empty * element. (Determination of the number of trailing copies is done without * stripping leading copies, so if the separator is "ABA", * "ABABA" has 1 trailing copy.) * * However, if there is only a single non-empty element, and there * are no characters in that element not part of the leading or * trailing separators, then the result is exactly the original value * of that element. * * Other than for determination of the number of leading and trailing * copies of the separator, elements consisting only of copies * of the separator are ignored. * * @param separator A string used to separate the elements of the path. * @param elements A container holding the elements of the path to build. * Any STL compatible container type is accepted. * @return The resulting path. */ std::string build_path(const std::string& separator, const Glib::ArrayHandle& elements); /** Locates the first executable named @a program in the user's path, in the * same way that execvp() would locate it. * Returns a string with the absolute path name, or "" if the program * is not found in the path. If @a program is already an absolute path, * returns a copy of @a program if @a program exists and is executable, and * "" otherwise. * * On Windows, if @a program does not have a file type suffix, tries to append * the suffixes in the PATHEXT environment variable (if that doesn't * exist, the suffixes .com, .exe, and .bat) in turn, and then look for the * resulting file name in the same way as CreateProcess() would. This means * first in the directory where the program was loaded from, then in the * current directory, then in the Windows 32-bit system directory, then in the * Windows directory, and finally in the directories in the PATH * environment variable. If the program is found, the return value contains * the full name including the type suffix. * * @param program A program name. * @return An absolute path, or "". */ std::string find_program_in_path(const std::string& program); /** @} group MiscUtils */ } // namespace Glib #endif /* _GLIBMM_FILEUTILS_H */