HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
pathUtils.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_BASE_TF_PATH_UTILS_H
25 #define PXR_BASE_TF_PATH_UTILS_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/base/tf/api.h"
30 #include <string>
31 #include <vector>
32 
34 
35 /// \file tf/pathUtils.h
36 /// \ingroup group_tf_Path
37 /// Definitions of basic path utilities in tf.
38 ///
39 /// These are utilities that operate on paths (represented by strings as
40 /// something like: "/chars/Buzz/Torso".
41 
42 /// Returns the canonical path of the specified filename, eliminating any
43 /// symbolic links encountered in the path.
44 ///
45 /// This is a wrapper to realpath(3), which caters for situations where the
46 /// real realpath() would return a NULL string, such as the case where the
47 /// path is really just a program name. The memory allocated by realpath is
48 /// managed internally.
49 ///
50 /// If \a allowInaccessibleSuffix is true, then this function will only invoke
51 /// realpath on the longest accessible prefix of \a path, and then append the
52 /// inaccessible suffix.
53 ///
54 /// If \a error is provided, it is set to the error reason should an error
55 /// occur while computing the real path. If no error occurs, the string is
56 /// cleared.
57 TF_API
59  bool allowInaccessibleSuffix = false,
60  std::string* error = 0);
61 
62 /// Normalizes the specified path, eliminating double slashes, etc.
63 ///
64 /// This canonicalizes paths, removing any double slashes, and eliminiating
65 /// '.', and '..' components of the path. This emulates the behavior of
66 /// os.path.normpath in Python.
67 ///
68 /// On Windows, all backslashes are converted to forward slashes and drive
69 /// specifiers (e.g., "C:") are lower-cased. If \p stripDriveSpecifier
70 /// is \c true, these drive specifiers are removed from the path.
71 TF_API
73  bool stripDriveSpecifier = false);
74 
75 /// Return the index delimiting the longest accessible prefix of \a path.
76 ///
77 /// The returned value is safe to use to split the string via it's generalized
78 /// copy constructor. If the entire path is accessible, return the length of
79 /// the input string. If none of the path is accessible, return 0. Otherwise
80 /// the index points to the path separator that delimits the existing prefix
81 /// from the non-existing suffix.
82 ///
83 /// Examples: suppose the paths /, /usr, and /usr/anim exist, but no other
84 /// paths exist.
85 ///
86 /// TfFindLongestAccessiblePrefix('/usr/anim') -> 9
87 /// TfFindLongestAccessiblePrefix('/usr/anim/foo') -> 9
88 /// TfFindLongestAccessiblePrefix('/foo/bar') -> 0
89 ///
90 /// If an error occurs, and the \a error string is not null, it is set to the
91 /// reason for the error. If the error string is set, the returned index is
92 /// the path separator before the element at which the error occurred.
93 TF_API
94 std::string::size_type
96 
97 /// Returns the canonical absolute path of the specified filename.
98 ///
99 /// This makes the specified path absolute, by prepending the current working
100 /// directory. If the path is already absolute, it is returned unmodified.
101 /// This function differs from TfRealPath in that the path may point to a
102 /// symlink, or not exist at all, and still result in an absolute path, rather
103 /// than an empty string.
104 TF_API
106 
107 /// Returns the extension for a file path
108 ///
109 /// If \p path is a directory path, an empty path, or a dotfile path, return
110 /// the empty string. Otherwise return \p path 's dot-separated extension as
111 /// a string(dot not included).
112 ///
113 /// Examples:
114 ///
115 /// TfGetExtension('/foo/bar') -> ''
116 /// TfGetExtension('/foo/bar/foo.baz') -> 'baz'
117 /// TfGetExtension('/foo.bar/foo.baz') -> 'baz'
118 /// TfGetExtension('/foo/bar/foo.101.baz') -> 'baz'
119 /// TfGetExtension('/foo/bar/.foo.baz') -> 'baz'
120 /// TfGetExtension('/foo/bar/.foo') -> ''
121 TF_API
123 
124 /// Returns the value of a symbolic link. Returns the empty string on
125 /// error or if path is not a symbolic link.
126 TF_API
128 
129 /// Return true if and only if a path is relative (not absolute).
130 TF_API
131 bool TfIsRelativePath(std::string const& path);
132 
133 /// Expands one or more shell glob patterns.
134 ///
135 /// This is a wrapper to glob(3), which manages the C structures necessary to
136 /// glob a pattern, returning a std::vector of results. If no flags are
137 /// specified, the GLOB_MARK and GLOB_NOCHECK flags are set by default.
138 /// GLOB_MARK marks directories which match the glob pattern with a trailing
139 /// slash. GLOB_NOCHECK returns any unexpanded patterns in the result.
140 TF_API
141 std::vector<std::string> TfGlob(std::vector<std::string> const& paths,
142  unsigned int flags=ARCH_GLOB_DEFAULT);
143 
144 /// Expands a shell glob pattern.
145 ///
146 /// This form of Glob calls TfGlob. For efficiency reasons, if expanding more
147 /// than one pattern, use the vector form. As with the vector form of TfGlob,
148 /// if flags is not set, the default glob flags are GLOB_MARK and
149 /// GLOB_NOCHECK.
150 TF_API
151 std::vector<std::string> TfGlob(std::string const& path,
152  unsigned int flags=ARCH_GLOB_DEFAULT);
153 
155 
156 #endif /* PXR_BASE_TF_PATH_UTILS_H */
#define TF_API
Definition: api.h:40
GLenum GLsizei GLsizei GLsizei GLsizei GLbitfield flags
Definition: glew.h:2864
TF_API std::string TfNormPath(std::string const &path, bool stripDriveSpecifier=false)
TF_API std::string TfRealPath(std::string const &path, bool allowInaccessibleSuffix=false, std::string *error=0)
#define ARCH_GLOB_DEFAULT
Definition: fileSystem.h:87
TF_API std::string TfReadLink(std::string const &path)
TF_API bool TfIsRelativePath(std::string const &path)
Return true if and only if a path is relative (not absolute).
GLsizei const GLchar *const * path
Definition: glew.h:6461
GLsizei const GLchar *const * string
Definition: glew.h:1844
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
TF_API std::string TfAbsPath(std::string const &path)
TF_API std::string::size_type TfFindLongestAccessiblePrefix(std::string const &path, std::string *error=0)
TF_API std::vector< std::string > TfGlob(std::vector< std::string > const &paths, unsigned int flags=ARCH_GLOB_DEFAULT)
TF_API std::string TfGetExtension(std::string const &path)
GLenum const void * paths
Definition: glew.h:13589