1<!-- Generated with Stardoc: http://skydoc.bazel.build --> 2 3Skylib module containing file path manipulation functions. 4 5NOTE: The functions in this module currently only support paths with Unix-style 6path separators (forward slash, "/"); they do not handle Windows-style paths 7with backslash separators or drive letters. 8 9 10<a id="#paths.basename"></a> 11 12## paths.basename 13 14<pre> 15paths.basename(<a href="#paths.basename-p">p</a>) 16</pre> 17 18Returns the basename (i.e., the file portion) of a path. 19 20Note that if `p` ends with a slash, this function returns an empty string. 21This matches the behavior of Python's `os.path.basename`, but differs from 22the Unix `basename` command (which would return the path segment preceding 23the final slash). 24 25 26**PARAMETERS** 27 28 29| Name | Description | Default Value | 30| :------------- | :------------- | :------------- | 31| <a id="paths.basename-p"></a>p | The path whose basename should be returned. | none | 32 33**RETURNS** 34 35The basename of the path, which includes the extension. 36 37 38<a id="#paths.dirname"></a> 39 40## paths.dirname 41 42<pre> 43paths.dirname(<a href="#paths.dirname-p">p</a>) 44</pre> 45 46Returns the dirname of a path. 47 48The dirname is the portion of `p` up to but not including the file portion 49(i.e., the basename). Any slashes immediately preceding the basename are not 50included, unless omitting them would make the dirname empty. 51 52 53**PARAMETERS** 54 55 56| Name | Description | Default Value | 57| :------------- | :------------- | :------------- | 58| <a id="paths.dirname-p"></a>p | The path whose dirname should be returned. | none | 59 60**RETURNS** 61 62The dirname of the path. 63 64 65<a id="#paths.is_absolute"></a> 66 67## paths.is_absolute 68 69<pre> 70paths.is_absolute(<a href="#paths.is_absolute-path">path</a>) 71</pre> 72 73Returns `True` if `path` is an absolute path. 74 75**PARAMETERS** 76 77 78| Name | Description | Default Value | 79| :------------- | :------------- | :------------- | 80| <a id="paths.is_absolute-path"></a>path | A path (which is a string). | none | 81 82**RETURNS** 83 84`True` if `path` is an absolute path. 85 86 87<a id="#paths.join"></a> 88 89## paths.join 90 91<pre> 92paths.join(<a href="#paths.join-path">path</a>, <a href="#paths.join-others">others</a>) 93</pre> 94 95Joins one or more path components intelligently. 96 97This function mimics the behavior of Python's `os.path.join` function on POSIX 98platform. It returns the concatenation of `path` and any members of `others`, 99inserting directory separators before each component except the first. The 100separator is not inserted if the path up until that point is either empty or 101already ends in a separator. 102 103If any component is an absolute path, all previous components are discarded. 104 105 106**PARAMETERS** 107 108 109| Name | Description | Default Value | 110| :------------- | :------------- | :------------- | 111| <a id="paths.join-path"></a>path | A path segment. | none | 112| <a id="paths.join-others"></a>others | Additional path segments. | none | 113 114**RETURNS** 115 116A string containing the joined paths. 117 118 119<a id="#paths.normalize"></a> 120 121## paths.normalize 122 123<pre> 124paths.normalize(<a href="#paths.normalize-path">path</a>) 125</pre> 126 127Normalizes a path, eliminating double slashes and other redundant segments. 128 129This function mimics the behavior of Python's `os.path.normpath` function on 130POSIX platforms; specifically: 131 132- If the entire path is empty, "." is returned. 133- All "." segments are removed, unless the path consists solely of a single 134 "." segment. 135- Trailing slashes are removed, unless the path consists solely of slashes. 136- ".." segments are removed as long as there are corresponding segments 137 earlier in the path to remove; otherwise, they are retained as leading ".." 138 segments. 139- Single and double leading slashes are preserved, but three or more leading 140 slashes are collapsed into a single leading slash. 141- Multiple adjacent internal slashes are collapsed into a single slash. 142 143 144**PARAMETERS** 145 146 147| Name | Description | Default Value | 148| :------------- | :------------- | :------------- | 149| <a id="paths.normalize-path"></a>path | A path. | none | 150 151**RETURNS** 152 153The normalized path. 154 155 156<a id="#paths.relativize"></a> 157 158## paths.relativize 159 160<pre> 161paths.relativize(<a href="#paths.relativize-path">path</a>, <a href="#paths.relativize-start">start</a>) 162</pre> 163 164Returns the portion of `path` that is relative to `start`. 165 166Because we do not have access to the underlying file system, this 167implementation differs slightly from Python's `os.path.relpath` in that it 168will fail if `path` is not beneath `start` (rather than use parent segments to 169walk up to the common file system root). 170 171Relativizing paths that start with parent directory references only works if 172the path both start with the same initial parent references. 173 174 175**PARAMETERS** 176 177 178| Name | Description | Default Value | 179| :------------- | :------------- | :------------- | 180| <a id="paths.relativize-path"></a>path | The path to relativize. | none | 181| <a id="paths.relativize-start"></a>start | The ancestor path against which to relativize. | none | 182 183**RETURNS** 184 185The portion of `path` that is relative to `start`. 186 187 188<a id="#paths.replace_extension"></a> 189 190## paths.replace_extension 191 192<pre> 193paths.replace_extension(<a href="#paths.replace_extension-p">p</a>, <a href="#paths.replace_extension-new_extension">new_extension</a>) 194</pre> 195 196Replaces the extension of the file at the end of a path. 197 198If the path has no extension, the new extension is added to it. 199 200 201**PARAMETERS** 202 203 204| Name | Description | Default Value | 205| :------------- | :------------- | :------------- | 206| <a id="paths.replace_extension-p"></a>p | The path whose extension should be replaced. | none | 207| <a id="paths.replace_extension-new_extension"></a>new_extension | The new extension for the file. The new extension should begin with a dot if you want the new filename to have one. | none | 208 209**RETURNS** 210 211The path with the extension replaced (or added, if it did not have one). 212 213 214<a id="#paths.split_extension"></a> 215 216## paths.split_extension 217 218<pre> 219paths.split_extension(<a href="#paths.split_extension-p">p</a>) 220</pre> 221 222Splits the path `p` into a tuple containing the root and extension. 223 224Leading periods on the basename are ignored, so 225`path.split_extension(".bashrc")` returns `(".bashrc", "")`. 226 227 228**PARAMETERS** 229 230 231| Name | Description | Default Value | 232| :------------- | :------------- | :------------- | 233| <a id="paths.split_extension-p"></a>p | The path whose root and extension should be split. | none | 234 235**RETURNS** 236 237A tuple `(root, ext)` such that the root is the path without the file 238extension, and `ext` is the file extension (which, if non-empty, contains 239the leading dot). The returned tuple always satisfies the relationship 240`root + ext == p`. 241 242 243