src/support/environment.h

   1 // -*- C++ -*-
   2 /**
   3  * \file environment.h
   4  * This file is part of LyX, the document processor.
   5  * Licence details can be found in the file COPYING.
   6  *
   7  * \author Angus Leeming
   8  *
   9  * Full author contact details are available in file CREDITS.
  10  */
  11
  12 #ifndef LYX_ENVIRONMENT_H
  13 #define LYX_ENVIRONMENT_H
  14
  15 #include <string>
  16 #include <vector>
  17
  18 namespace lyx {
  19 namespace support {
  20
  21 /// @returns true if the environment variable @c name exists.
  22 bool hasEnv(std::string const & name);
  23
  24 /// @returns the contents of the environment variable @c name encoded in utf8.
  25 std::string const getEnv(std::string const & name);
  26
  27 /** @returns the contents of the environment variable @c name,
  28  *  split into path elements using the OS-dependent separator token
  29  *  and encoded in utf8.
  30  *  Each element is then passed through os::internal_path() to
  31  *  guarantee that it is in the form of a unix-style path.
  32  *  If the environment variable is not set, then the function returns
  33  *  an empty vector.
  34  */
  35 std::vector<std::string> const getEnvPath(std::string const & name);
  36
  37 /** Set the contents of the environment variable @c name to @c value.
  38  *  \p value is encoded in utf8.
  39  *  @returns true if the variable was set successfully.
  40  */
  41 bool setEnv(std::string const & name, std::string const & value);
  42
  43 /** Set the contents of the environment variable @c name
  44  *  using the paths stored in the @c env vector (encoded in utf8).
  45  *  Each element is passed through os::external_path().
  46  *  Multiple elements are concatenated into a single string using
  47  *  os::path_separator().
  48  */
  49 void setEnvPath(std::string const & name, std::vector<std::string> const & env);
  50
  51 /** Prepend a list of paths to that returned by the environment variable.
  52  *  Identical paths occurring later in the list are removed.
  53  *  @param name the name of the environment variable (encoded in utf8).
  54  *  @prefix the list of paths in OS-native syntax (encoded in utf8).
  55  *  Eg "/foo/bar:/usr/bin:/usr/local/bin" on *nix,
  56  *     "C:\foo\bar;C:\windows" on Windows.
  57  */
  58 void prependEnvPath(std::string const & name, std::string const & prefix);
  59
  60 /** Remove the variable @c name from the environment.
  61  *  @returns true if the variable was unset successfully.
  62  */
  63 bool unsetEnv(std::string const & name);
  64
  65
  66 /** Utility class to change temporarily an environment variable. The
  67  * variable is reset to its original state when the dummy EnvChanger
  68  * variable is deleted.
  69  */
  70 class EnvChanger {
  71 public:
  72         ///
  73         EnvChanger(std::string const & name, std::string const & value)
  74         : name_(name), set_(hasEnv(name)), value_(getEnv(name))
  75         {
  76                         setEnv(name, value);
  77         }
  78         ///
  79         ~EnvChanger()
  80         {
  81                 if (set_)
  82                         setEnv(name_, value_);
  83                 else
  84                         unsetEnv(name_);
  85         }
  86
  87 private:
  88         /// the name of the variable
  89         std::string name_;
  90         /// was the variable set?
  91         bool set_;
  92         ///
  93         std::string value_;
  94 };
  95
  96 } // namespace support
  97 } // namespace lyx
  98
  99 #endif // LYX_ENVIRONMENT_H