libs/pbd/pbd/search_path.h

   1 /*
   2     Copyright (C) 2007 Tim Mayberry
   3
   4     This program is free software; you can redistribute it and/or modify
   5     it under the terms of the GNU General Public License as published by
   6     the Free Software Foundation; either version 2 of the License, or
   7     (at your option) any later version.
   8
   9     This program is distributed in the hope that it will be useful,
  10     but WITHOUT ANY WARRANTY; without even the implied warranty of
  11     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12     GNU General Public License for more details.
  13
  14     You should have received a copy of the GNU General Public License
  15     along with this program; if not, write to the Free Software
  16     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  17
  18 */
  19
  20 #ifndef PBD_SEARCH_PATH_INCLUDED
  21 #define PBD_SEARCH_PATH_INCLUDED
  22
  23 #include <string>
  24 #include <vector>
  25
  26 #include <pbd/filesystem.h>
  27
  28 namespace PBD {
  29
  30 using std::string;
  31 using std::vector;
  32
  33 /**
  34  * @class The SearchPath class is a helper class for getting a
  35  * vector of paths contained in a search path string where a
  36  * "search path string" contains absolute directory paths
  37  * separated by a colon(:) or a semi-colon(;) on windows.
  38  *
  39  * The SearchPath class does not test whether the paths exist
  40  * or are directories. It is basically just a container.
  41  */
  42 class SearchPath {
  43 public:
  44
  45         typedef std::vector<sys::path>::iterator         iterator;
  46         typedef std::vector<sys::path>::const_iterator   const_iterator;
  47
  48 public:
  49
  50         /**
  51          * Create an empty SearchPath.
  52          */
  53         SearchPath ();
  54
  55         /**
  56          * Initialize SearchPath from a string where the string contains
  57          * one or more absolute paths to directories which are delimited
  58          * by a path separation character. The path delimeter is a
  59          * colon(:) on unix and a semi-colon(;) on windows.
  60          *
  61          * Each path contained in the search path may or may not resolve to
  62          * an existing directory in the filesystem.
  63          *
  64          * @param search_path A path string.
  65          */
  66         SearchPath (const string& search_path);
  67
  68         /**
  69          * Initialize SearchPath from a sys::path.
  70          *
  71          * @param directory_path A directory path.
  72          */
  73         SearchPath (const sys::path& directory_path);
  74
  75         /**
  76          * Initialize SearchPath from a vector of paths that may or may
  77          * not exist.
  78          *
  79          * @param path A path.
  80          */
  81         SearchPath (const vector<sys::path>& paths);
  82
  83         /**
  84          * The copy constructor does what you would expect and copies the
  85          * vector of paths contained by the SearchPath.
  86          */
  87         SearchPath (const SearchPath& search_path);
  88
  89         /**
  90          * Indicate whether there are any directory paths in m_dirs.
  91          *
  92          * If SearchPath is initialized with an empty string as the
  93          * result of for instance the contents of an unset environment
  94          * variable.
  95          *
  96          * @return true if there are any paths in m_paths.
  97          */
  98         operator void* () const { return (void*)!m_dirs.empty(); }
  99
 100         /**
 101          *  @return a read/write iterator that points to the first
 102          *  path in the SearchPath. Iteration is done in ordinary
 103          *  element order.
 104          */
 105         iterator begin () { return m_dirs.begin(); }
 106
 107         /**
 108          *  @return A read-only (constant) iterator that points to the
 109          *  first path in the SearchPath.
 110          */
 111         const_iterator begin () const { return m_dirs.begin(); }
 112
 113         /**
 114          *  @return A read/write iterator that points one past the last
 115          *  path in the SearchPath.
 116          */
 117         iterator end () { return m_dirs.end(); }
 118
 119         /**
 120          *  @return A read-only (constant) iterator that points one past
 121          *  the last path in the SearchPath.
 122          */
 123         const_iterator end () const { return m_dirs.end(); }
 124
 125         /**
 126          * @return a search path string.
 127          *
 128          * The string that is returned contains the platform specific
 129          * path separator.
 130          */
 131         const string to_string () const;
 132
 133         /**
 134          * Assignment of another SearchPath to this.
 135          */
 136         SearchPath& operator= (const SearchPath& spath);
 137
 138         /**
 139          * Add all the directories in path to this.
 140          */
 141         SearchPath& operator+= (const SearchPath& spath);
 142
 143         /**
 144          * Add another directory path to the search path.
 145          */
 146         SearchPath& operator+= (const sys::path& directory_path);
 147
 148         /**
 149          * Concatenate another SearchPath onto this.
 150          */
 151         SearchPath& operator+ (const SearchPath& other);
 152
 153         /**
 154          * Add another path to the search path.
 155          */
 156         SearchPath& operator+ (const sys::path& directory_path);
 157
 158         /**
 159          * Add a sub-directory to each path in the search path.
 160          * @param subdir The directory name, it should not contain
 161          * any path separating tokens.
 162          */
 163         SearchPath& add_subdirectory_to_paths (const string& subdir);
 164
 165         /**
 166          * Add a sub-directory to each path in the search path.
 167          * @see add_subdirectory_to_paths
 168          */
 169         SearchPath& operator/= (const string& subdir);
 170
 171 protected:
 172
 173         void add_directory (const sys::path& directory_path);
 174
 175         void add_directories (const vector<sys::path>& paths);
 176
 177         vector<sys::path> m_dirs;
 178
 179 };
 180
 181 } // namespace PBD
 182
 183 #endif