LLVM  4.0.0
Path.h
Go to the documentation of this file.
1 //===- llvm/Support/Path.h - Path Operating System Concept ------*- C++ -*-===//
2 //
3 // The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 //
10 // This file declares the llvm::sys::path namespace. It is designed after
11 // TR2/boost filesystem (v3), but modified to remove exception handling and the
12 // path class.
13 //
14 //===----------------------------------------------------------------------===//
15 
16 #ifndef LLVM_SUPPORT_PATH_H
17 #define LLVM_SUPPORT_PATH_H
18 
19 #include "llvm/ADT/Twine.h"
20 #include "llvm/Support/DataTypes.h"
21 #include <iterator>
22 
23 namespace llvm {
24 namespace sys {
25 namespace path {
26 
27 /// @name Lexical Component Iterator
28 /// @{
29 
30 /// @brief Path iterator.
31 ///
32 /// This is an input iterator that iterates over the individual components in
33 /// \a path. The traversal order is as follows:
34 /// * The root-name element, if present.
35 /// * The root-directory element, if present.
36 /// * Each successive filename element, if present.
37 /// * Dot, if one or more trailing non-root slash characters are present.
38 /// Traversing backwards is possible with \a reverse_iterator
39 ///
40 /// Iteration examples. Each component is separated by ',':
41 /// @code
42 /// / => /
43 /// /foo => /,foo
44 /// foo/ => foo,.
45 /// /foo/bar => /,foo,bar
46 /// ../ => ..,.
47 /// C:\foo\bar => C:,/,foo,bar
48 /// @endcode
50  : public std::iterator<std::input_iterator_tag, const StringRef> {
51  StringRef Path; ///< The entire path.
52  StringRef Component; ///< The current component. Not necessarily in Path.
53  size_t Position; ///< The iterators current position within Path.
54 
55  // An end iterator has Position = Path.size() + 1.
56  friend const_iterator begin(StringRef path);
57  friend const_iterator end(StringRef path);
58 
59 public:
60  reference operator*() const { return Component; }
61  pointer operator->() const { return &Component; }
62  const_iterator &operator++(); // preincrement
63  bool operator==(const const_iterator &RHS) const;
64  bool operator!=(const const_iterator &RHS) const { return !(*this == RHS); }
65 
66  /// @brief Difference in bytes between this and RHS.
67  ptrdiff_t operator-(const const_iterator &RHS) const;
68 };
69 
70 /// @brief Reverse path iterator.
71 ///
72 /// This is an input iterator that iterates over the individual components in
73 /// \a path in reverse order. The traversal order is exactly reversed from that
74 /// of \a const_iterator
76  : public std::iterator<std::input_iterator_tag, const StringRef> {
77  StringRef Path; ///< The entire path.
78  StringRef Component; ///< The current component. Not necessarily in Path.
79  size_t Position; ///< The iterators current position within Path.
80 
81  friend reverse_iterator rbegin(StringRef path);
82  friend reverse_iterator rend(StringRef path);
83 
84 public:
85  reference operator*() const { return Component; }
86  pointer operator->() const { return &Component; }
87  reverse_iterator &operator++(); // preincrement
88  bool operator==(const reverse_iterator &RHS) const;
89  bool operator!=(const reverse_iterator &RHS) const { return !(*this == RHS); }
90 
91  /// @brief Difference in bytes between this and RHS.
92  ptrdiff_t operator-(const reverse_iterator &RHS) const;
93 };
94 
95 /// @brief Get begin iterator over \a path.
96 /// @param path Input path.
97 /// @returns Iterator initialized with the first component of \a path.
98 const_iterator begin(StringRef path);
99 
100 /// @brief Get end iterator over \a path.
101 /// @param path Input path.
102 /// @returns Iterator initialized to the end of \a path.
103 const_iterator end(StringRef path);
104 
105 /// @brief Get reverse begin iterator over \a path.
106 /// @param path Input path.
107 /// @returns Iterator initialized with the first reverse component of \a path.
108 reverse_iterator rbegin(StringRef path);
109 
110 /// @brief Get reverse end iterator over \a path.
111 /// @param path Input path.
112 /// @returns Iterator initialized to the reverse end of \a path.
113 reverse_iterator rend(StringRef path);
114 
115 /// @}
116 /// @name Lexical Modifiers
117 /// @{
118 
119 /// @brief Remove the last component from \a path unless it is the root dir.
120 ///
121 /// @code
122 /// directory/filename.cpp => directory/
123 /// directory/ => directory
124 /// filename.cpp => <empty>
125 /// / => /
126 /// @endcode
127 ///
128 /// @param path A path that is modified to not have a file component.
130 
131 /// @brief Replace the file extension of \a path with \a extension.
132 ///
133 /// @code
134 /// ./filename.cpp => ./filename.extension
135 /// ./filename => ./filename.extension
136 /// ./ => ./.extension
137 /// @endcode
138 ///
139 /// @param path A path that has its extension replaced with \a extension.
140 /// @param extension The extension to be added. It may be empty. It may also
141 /// optionally start with a '.', if it does not, one will be
142 /// prepended.
144 
145 /// @brief Replace matching path prefix with another path.
146 ///
147 /// @code
148 /// /foo, /old, /new => /foo
149 /// /old/foo, /old, /new => /new/foo
150 /// /foo, <empty>, /new => /new/foo
151 /// /old/foo, /old, <empty> => /foo
152 /// @endcode
153 ///
154 /// @param Path If \a Path starts with \a OldPrefix modify to instead
155 /// start with \a NewPrefix.
156 /// @param OldPrefix The path prefix to strip from \a Path.
157 /// @param NewPrefix The path prefix to replace \a NewPrefix with.
159  const StringRef &OldPrefix,
160  const StringRef &NewPrefix);
161 
162 /// @brief Append to path.
163 ///
164 /// @code
165 /// /foo + bar/f => /foo/bar/f
166 /// /foo/ + bar/f => /foo/bar/f
167 /// foo + bar/f => foo/bar/f
168 /// @endcode
169 ///
170 /// @param path Set to \a path + \a component.
171 /// @param a The component to be appended to \a path.
172 void append(SmallVectorImpl<char> &path, const Twine &a,
173  const Twine &b = "",
174  const Twine &c = "",
175  const Twine &d = "");
176 
177 /// @brief Append to path.
178 ///
179 /// @code
180 /// /foo + [bar,f] => /foo/bar/f
181 /// /foo/ + [bar,f] => /foo/bar/f
182 /// foo + [bar,f] => foo/bar/f
183 /// @endcode
184 ///
185 /// @param path Set to \a path + [\a begin, \a end).
186 /// @param begin Start of components to append.
187 /// @param end One past the end of components to append.
188 void append(SmallVectorImpl<char> &path,
189  const_iterator begin, const_iterator end);
190 
191 /// @}
192 /// @name Transforms (or some other better name)
193 /// @{
194 
195 /// Convert path to the native form. This is used to give paths to users and
196 /// operating system calls in the platform's normal way. For example, on Windows
197 /// all '/' are converted to '\'.
198 ///
199 /// @param path A path that is transformed to native format.
200 /// @param result Holds the result of the transformation.
201 void native(const Twine &path, SmallVectorImpl<char> &result);
202 
203 /// Convert path to the native form in place. This is used to give paths to
204 /// users and operating system calls in the platform's normal way. For example,
205 /// on Windows all '/' are converted to '\'.
206 ///
207 /// @param path A path that is transformed to native format.
208 void native(SmallVectorImpl<char> &path);
209 
210 /// @brief Replaces backslashes with slashes if Windows.
211 ///
212 /// @param path processed path
213 /// @result The result of replacing backslashes with forward slashes if Windows.
214 /// On Unix, this function is a no-op because backslashes are valid path
215 /// chracters.
216 std::string convert_to_slash(StringRef path);
217 
218 /// @}
219 /// @name Lexical Observers
220 /// @{
221 
222 /// @brief Get root name.
223 ///
224 /// @code
225 /// //net/hello => //net
226 /// c:/hello => c: (on Windows, on other platforms nothing)
227 /// /hello => <empty>
228 /// @endcode
229 ///
230 /// @param path Input path.
231 /// @result The root name of \a path if it has one, otherwise "".
233 
234 /// @brief Get root directory.
235 ///
236 /// @code
237 /// /goo/hello => /
238 /// c:/hello => /
239 /// d/file.txt => <empty>
240 /// @endcode
241 ///
242 /// @param path Input path.
243 /// @result The root directory of \a path if it has one, otherwise
244 /// "".
246 
247 /// @brief Get root path.
248 ///
249 /// Equivalent to root_name + root_directory.
250 ///
251 /// @param path Input path.
252 /// @result The root path of \a path if it has one, otherwise "".
254 
255 /// @brief Get relative path.
256 ///
257 /// @code
258 /// C:\hello\world => hello\world
259 /// foo/bar => foo/bar
260 /// /foo/bar => foo/bar
261 /// @endcode
262 ///
263 /// @param path Input path.
264 /// @result The path starting after root_path if one exists, otherwise "".
266 
267 /// @brief Get parent path.
268 ///
269 /// @code
270 /// / => <empty>
271 /// /foo => /
272 /// foo/../bar => foo/..
273 /// @endcode
274 ///
275 /// @param path Input path.
276 /// @result The parent path of \a path if one exists, otherwise "".
278 
279 /// @brief Get filename.
280 ///
281 /// @code
282 /// /foo.txt => foo.txt
283 /// . => .
284 /// .. => ..
285 /// / => /
286 /// @endcode
287 ///
288 /// @param path Input path.
289 /// @result The filename part of \a path. This is defined as the last component
290 /// of \a path.
292 
293 /// @brief Get stem.
294 ///
295 /// If filename contains a dot but not solely one or two dots, result is the
296 /// substring of filename ending at (but not including) the last dot. Otherwise
297 /// it is filename.
298 ///
299 /// @code
300 /// /foo/bar.txt => bar
301 /// /foo/bar => bar
302 /// /foo/.txt => <empty>
303 /// /foo/. => .
304 /// /foo/.. => ..
305 /// @endcode
306 ///
307 /// @param path Input path.
308 /// @result The stem of \a path.
309 StringRef stem(StringRef path);
310 
311 /// @brief Get extension.
312 ///
313 /// If filename contains a dot but not solely one or two dots, result is the
314 /// substring of filename starting at (and including) the last dot, and ending
315 /// at the end of \a path. Otherwise "".
316 ///
317 /// @code
318 /// /foo/bar.txt => .txt
319 /// /foo/bar => <empty>
320 /// /foo/.txt => .txt
321 /// @endcode
322 ///
323 /// @param path Input path.
324 /// @result The extension of \a path.
326 
327 /// @brief Check whether the given char is a path separator on the host OS.
328 ///
329 /// @param value a character
330 /// @result true if \a value is a path separator character on the host OS
331 bool is_separator(char value);
332 
333 /// @brief Return the preferred separator for this platform.
334 ///
335 /// @result StringRef of the preferred separator, null-terminated.
337 
338 /// @brief Get the typical temporary directory for the system, e.g.,
339 /// "/var/tmp" or "C:/TEMP"
340 ///
341 /// @param erasedOnReboot Whether to favor a path that is erased on reboot
342 /// rather than one that potentially persists longer. This parameter will be
343 /// ignored if the user or system has set the typical environment variable
344 /// (e.g., TEMP on Windows, TMPDIR on *nix) to specify a temporary directory.
345 ///
346 /// @param result Holds the resulting path name.
347 void system_temp_directory(bool erasedOnReboot, SmallVectorImpl<char> &result);
348 
349 /// @brief Get the user's home directory.
350 ///
351 /// @param result Holds the resulting path name.
352 /// @result True if a home directory is set, false otherwise.
354 
355 /// @brief Get the user's cache directory.
356 ///
357 /// Expect the resulting path to be a directory shared with other
358 /// applications/services used by the user. Params \p Path1 to \p Path3 can be
359 /// used to append additional directory names to the resulting path. Recommended
360 /// pattern is <user_cache_directory>/<vendor>/<application>.
361 ///
362 /// @param Result Holds the resulting path.
363 /// @param Path1 Additional path to be appended to the user's cache directory
364 /// path. "" can be used to append nothing.
365 /// @param Path2 Second additional path to be appended.
366 /// @param Path3 Third additional path to be appended.
367 /// @result True if a cache directory path is set, false otherwise.
368 bool user_cache_directory(SmallVectorImpl<char> &Result, const Twine &Path1,
369  const Twine &Path2 = "", const Twine &Path3 = "");
370 
371 /// @brief Has root name?
372 ///
373 /// root_name != ""
374 ///
375 /// @param path Input path.
376 /// @result True if the path has a root name, false otherwise.
377 bool has_root_name(const Twine &path);
378 
379 /// @brief Has root directory?
380 ///
381 /// root_directory != ""
382 ///
383 /// @param path Input path.
384 /// @result True if the path has a root directory, false otherwise.
385 bool has_root_directory(const Twine &path);
386 
387 /// @brief Has root path?
388 ///
389 /// root_path != ""
390 ///
391 /// @param path Input path.
392 /// @result True if the path has a root path, false otherwise.
393 bool has_root_path(const Twine &path);
394 
395 /// @brief Has relative path?
396 ///
397 /// relative_path != ""
398 ///
399 /// @param path Input path.
400 /// @result True if the path has a relative path, false otherwise.
401 bool has_relative_path(const Twine &path);
402 
403 /// @brief Has parent path?
404 ///
405 /// parent_path != ""
406 ///
407 /// @param path Input path.
408 /// @result True if the path has a parent path, false otherwise.
409 bool has_parent_path(const Twine &path);
410 
411 /// @brief Has filename?
412 ///
413 /// filename != ""
414 ///
415 /// @param path Input path.
416 /// @result True if the path has a filename, false otherwise.
417 bool has_filename(const Twine &path);
418 
419 /// @brief Has stem?
420 ///
421 /// stem != ""
422 ///
423 /// @param path Input path.
424 /// @result True if the path has a stem, false otherwise.
425 bool has_stem(const Twine &path);
426 
427 /// @brief Has extension?
428 ///
429 /// extension != ""
430 ///
431 /// @param path Input path.
432 /// @result True if the path has a extension, false otherwise.
433 bool has_extension(const Twine &path);
434 
435 /// @brief Is path absolute?
436 ///
437 /// @param path Input path.
438 /// @result True if the path is absolute, false if it is not.
439 bool is_absolute(const Twine &path);
440 
441 /// @brief Is path relative?
442 ///
443 /// @param path Input path.
444 /// @result True if the path is relative, false if it is not.
445 bool is_relative(const Twine &path);
446 
447 /// @brief Remove redundant leading "./" pieces and consecutive separators.
448 ///
449 /// @param path Input path.
450 /// @result The cleaned-up \a path.
452 
453 /// @brief In-place remove any './' and optionally '../' components from a path.
454 ///
455 /// @param path processed path
456 /// @param remove_dot_dot specify if '../' (except for leading "../") should be
457 /// removed
458 /// @result True if path was changed
459 bool remove_dots(SmallVectorImpl<char> &path, bool remove_dot_dot = false);
460 
461 } // end namespace path
462 } // end namespace sys
463 } // end namespace llvm
464 
465 #endif
const_iterator end(StringRef path)
Get end iterator over path.
Definition: Path.cpp:241
friend reverse_iterator rbegin(StringRef path)
Get reverse begin iterator over path.
Definition: Path.cpp:309
StringRef root_name(StringRef path)
Get root name.
Definition: Path.cpp:392
StringRef stem(StringRef path)
Get stem.
Definition: Path.cpp:588
friend reverse_iterator rend(StringRef path)
Get reverse end iterator over path.
Definition: Path.cpp:316
bool is_relative(const Twine &path)
Is path relative?
Definition: Path.cpp:700
void replace_extension(SmallVectorImpl< char > &path, const Twine &extension)
Replace the file extension of path with extension.
Definition: Path.cpp:507
bool has_stem(const Twine &path)
Has stem?
Definition: Path.cpp:672
StringRef root_directory(StringRef path)
Get root directory.
Definition: Path.cpp:414
bool operator==(const reverse_iterator &RHS) const
Definition: Path.cpp:351
const_iterator begin(StringRef path)
Get begin iterator over path.
Definition: Path.cpp:233
bool operator!=(const reverse_iterator &RHS) const
Definition: Path.h:89
bool has_root_directory(const Twine &path)
Has root directory?
Definition: Path.cpp:637
bool operator==(const const_iterator &RHS) const
Definition: Path.cpp:301
void append(SmallVectorImpl< char > &path, const Twine &a, const Twine &b="", const Twine &c="", const Twine &d="")
Append to path.
Definition: Path.cpp:448
void native(const Twine &path, SmallVectorImpl< char > &result)
Convert path to the native form.
Definition: Path.cpp:548
void remove_filename(SmallVectorImpl< char > &path)
Remove the last component from path unless it is the root dir.
Definition: Path.cpp:501
Twine - A lightweight data structure for efficiently representing the concatenation of temporary valu...
Definition: Twine.h:81
pointer operator->() const
Definition: Path.h:61
bool is_absolute(const Twine &path)
Is path absolute?
Definition: Path.cpp:686
StringRef extension(StringRef path)
Get extension.
Definition: Path.cpp:601
bool operator!=(const const_iterator &RHS) const
Definition: Path.h:64
bool is_separator(char value)
Check whether the given char is a path separator on the host OS.
Definition: Path.cpp:614
StringRef root_path(StringRef path)
Get root path.
Definition: Path.cpp:360
bool has_relative_path(const Twine &path)
Has relative path?
Definition: Path.cpp:651
bool remove_dots(SmallVectorImpl< char > &path, bool remove_dot_dot=false)
In-place remove any '.
Definition: Path.cpp:738
StringRef filename(StringRef path)
Get filename.
Definition: Path.cpp:584
friend const_iterator end(StringRef path)
Get end iterator over path.
Definition: Path.cpp:241
bool has_filename(const Twine &path)
Has filename?
Definition: Path.cpp:658
pointer operator->() const
Definition: Path.h:86
reference operator*() const
Definition: Path.h:60
reverse_iterator & operator++()
Definition: Path.cpp:324
bool user_cache_directory(SmallVectorImpl< char > &Result, const Twine &Path1, const Twine &Path2="", const Twine &Path3="")
Get the user's cache directory.
Definition: Path.cpp:1184
const_iterator & operator++()
Definition: Path.cpp:248
void replace_path_prefix(SmallVectorImpl< char > &Path, const StringRef &OldPrefix, const StringRef &NewPrefix)
Replace matching path prefix with another path.
Definition: Path.cpp:525
ptrdiff_t operator-(const const_iterator &RHS) const
Difference in bytes between this and RHS.
Definition: Path.cpp:305
StringRef remove_leading_dotslash(StringRef path)
Remove redundant leading "./" pieces and consecutive separators.
Definition: Path.cpp:702
StringRef relative_path(StringRef path)
Get relative path.
Definition: Path.cpp:443
friend const_iterator begin(StringRef path)
Get begin iterator over path.
Definition: Path.cpp:233
ptrdiff_t operator-(const reverse_iterator &RHS) const
Difference in bytes between this and RHS.
Definition: Path.cpp:356
StringRef parent_path(StringRef path)
Get parent path.
Definition: Path.cpp:493
StringRef get_separator()
Return the preferred separator for this platform.
Definition: Path.cpp:626
Path iterator.
Definition: Path.h:49
Reverse path iterator.
Definition: Path.h:75
reverse_iterator rbegin(StringRef path)
Get reverse begin iterator over path.
Definition: Path.cpp:309
bool has_root_path(const Twine &path)
Has root path?
Definition: Path.cpp:644
bool has_root_name(const Twine &path)
Has root name?
Definition: Path.cpp:630
reverse_iterator rend(StringRef path)
Get reverse end iterator over path.
Definition: Path.cpp:316
void system_temp_directory(bool erasedOnReboot, SmallVectorImpl< char > &result)
Get the typical temporary directory for the system, e.g., "/var/tmp" or "C:/TEMP".
bool home_directory(SmallVectorImpl< char > &result)
Get the user's home directory.
bool has_extension(const Twine &path)
Has extension?
Definition: Path.cpp:679
reference operator*() const
Definition: Path.h:85
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:47
std::string convert_to_slash(StringRef path)
Replaces backslashes with slashes if Windows.
Definition: Path.cpp:574
bool has_parent_path(const Twine &path)
Has parent path?
Definition: Path.cpp:665