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