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