1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
<section id="bbv2.reference.modules.path">
<title>path</title>
<indexterm>
<primary>path</primary>
</indexterm>
<para>
Performs various path manipulations. Paths are always in a 'normalized'
representation. In it, a path may be either:
<itemizedlist>
<listitem><para><code>'.'</code>, or</para></listitem>
<listitem>
<para>
<code>['/'] [ ( '..' '/' )* (token '/')* token ]</code>
</para>
</listitem>
</itemizedlist>
In plain english, a path can be rooted, <code>'..'</code>
elements are allowed only at the beginning, and it never
ends in slash, except for the path consisting of slash only.
</para>
<orderedlist>
<listitem id="bbv2.reference.modules.path.make">
<indexterm zone="bbv2.reference.modules.path.make">
<primary>make</primary>
<secondary>path</secondary>
</indexterm>
<code language="jam">rule make ( native )</code>
<para>Converts the native path into normalized form.</para>
</listitem>
<listitem id="bbv2.reference.modules.path.native">
<indexterm zone="bbv2.reference.modules.path.native">
<primary>native</primary>
</indexterm>
<code language="jam">rule native ( path )</code>
<para>Builds the native representation of the path.</para>
</listitem>
<listitem id="bbv2.reference.modules.path.is-rooted">
<indexterm zone="bbv2.reference.modules.path.is-rooted">
<primary>is-rooted</primary>
</indexterm>
<code language="jam">rule is-rooted ( path )</code>
<para>Tests if a path is rooted.</para>
</listitem>
<listitem id="bbv2.reference.modules.path.has-parent">
<indexterm zone="bbv2.reference.modules.path.has-parent">
<primary>has-parent</primary>
</indexterm>
<code language="jam">rule has-parent ( path )</code>
<para>Tests if a path has a parent.</para>
</listitem>
<listitem id="bbv2.reference.modules.path.basename">
<indexterm zone="bbv2.reference.modules.path.basename">
<primary>basename</primary>
</indexterm>
<code language="jam">rule basename ( path )</code>
<para>Returns the path without any directory components.</para>
</listitem>
<listitem id="bbv2.reference.modules.path.parent">
<indexterm zone="bbv2.reference.modules.path.parent">
<primary>parent</primary>
</indexterm>
<code language="jam">rule parent ( path )</code>
<para>Returns the parent directory of the path. If no parent exists, an error is issued.</para>
</listitem>
<listitem id="bbv2.reference.modules.path.reverse">
<indexterm zone="bbv2.reference.modules.path.reverse">
<primary>reverse</primary>
</indexterm>
<code language="jam">rule reverse ( path )</code>
<para>
Returns <code language="jam">path2</code> such that
<code language="jam">[ join path path2 ] = "."</code>.
The path may not contain <code language="jam">".."</code>
element or be rooted.
</para>
</listitem>
<listitem id="bbv2.reference.modules.path.join">
<indexterm zone="bbv2.reference.modules.path.join">
<primary>join</primary>
</indexterm>
<code language="jam">rule join ( elements + )</code>
<para>
Concatenates the passed path elements. Generates an error if any
element other than the first one is rooted. Skips any empty or
undefined path elements.
</para>
</listitem>
<listitem id="bbv2.reference.modules.path.root">
<indexterm zone="bbv2.reference.modules.path.root">
<primary>root</primary>
</indexterm>
<code language="jam">rule root ( path root )</code>
<para>
If <code language="jam">path</code> is relative, it is rooted at
<code language="jam">root</code>. Otherwise, it is unchanged.
</para>
</listitem>
<listitem id="bbv2.reference.modules.path.pwd">
<indexterm zone="bbv2.reference.modules.path.pwd">
<primary>pwd</primary>
</indexterm>
<code language="jam">rule pwd ( )</code>
<para>Returns the current working directory.</para>
</listitem>
<listitem id="bbv2.reference.modules.path.glob">
<indexterm zone="bbv2.reference.modules.path.glob">
<primary>glob</primary>
</indexterm>
<code language="jam">rule glob ( dirs * : patterns + : exclude-patterns * )</code>
<para>
Returns the list of files matching the given pattern in the specified
directory. Both directories and patterns are supplied as portable paths. Each
pattern should be a non-absolute path, and can't contain "." or ".." elements.
Each slash separated element of a pattern can contain the following special
characters:
<itemizedlist>
<listitem>
<para>'?' matches any character</para>
</listitem>
<listitem>
<para>'*' matches an arbitrary number of characters</para>
</listitem>
</itemizedlist>
A file $(d)/e1/e2/e3 (where 'd' is in $(dirs)) matches the pattern p1/p2/p3 if and
only if e1 matches p1, e2 matches p2 and so on.
For example:
<programlisting language="jam">
[ glob . : *.cpp ]
[ glob . : */build/Jamfile ]
</programlisting>
</para>
</listitem>
<listitem id="bbv2.reference.modules.path.glob-tree">
<indexterm zone="bbv2.reference.modules.path.glob-tree">
<primary>glob-tree</primary>
</indexterm>
<code language="jam">rule glob-tree ( roots * : patterns + : exclude-patterns * )</code>
<para>
Recursive version of <link linkend="bbv2.reference.modules.path.glob">glob</link>.
Builds the glob of files while also searching in
the subdirectories of the given roots. An optional set of exclusion patterns
will filter out the matching entries from the result. The exclusions also
apply to the subdirectory scanning, such that directories that match the
exclusion patterns will not be searched.
</para>
</listitem>
<listitem id="bbv2.reference.modules.path.exists">
<indexterm zone="bbv2.reference.modules.path.exists">
<primary>exists</primary>
</indexterm>
<code language="jam">rule exists ( file )</code>
<para>Returns true if the specified file exists.</para>
</listitem>
<listitem id="bbv2.reference.modules.path.all-parents">
<indexterm zone="bbv2.reference.modules.path.all-parents">
<primary>all-parents</primary>
</indexterm>
<code language="jam">rule all-parents ( path : upper_limit ? : cwd ? )</code>
<para>
Find out the absolute name of path and return the list of all the parents,
starting with the immediate one. Parents are returned as relative names. If
<code language="jam">upper_limit</code> is specified, directories above it
will be pruned.
</para>
</listitem>
<listitem id="bbv2.reference.modules.path.glob-in-parents">
<indexterm zone="bbv2.reference.modules.path.glob-in-parents">
<primary>glob-in-parents</primary>
</indexterm>
<code language="jam">rule glob-in-parents ( dir : patterns + : upper-limit ? )</code>
<para>
Search for <code language="jam">patterns</code> in parent directories
of <code language="jam">dir</code>, up to and including
<code language="jam">upper_limit</code>, if it is specified, or
till the filesystem root otherwise.
</para>
</listitem>
<listitem id="bbv2.reference.modules.path.relative">
<indexterm zone="bbv2.reference.modules.path.relative">
<primary>relative</primary>
</indexterm>
<code language="jam">rule relative ( child parent : no-error ? )</code>
<para>
Assuming <code language="jam">child</code> is a subdirectory of
<code language="jam">parent</code>, return the relative path from
<code language="jam">parent</code> to <code language="jam">child</code>.
</para>
</listitem>
<listitem id="bbv2.reference.modules.path.relative-to">
<indexterm zone="bbv2.reference.modules.path.relative-to">
<primary>relative-to</primary>
</indexterm>
<code language="jam">rule relative-to ( path1 path2 )</code>
<para>Returns the minimal path to path2 that is relative path1.</para>
</listitem>
<listitem id="bbv2.reference.modules.path.programs-path">
<indexterm zone="bbv2.reference.modules.path.programs-path">
<primary>programs-path</primary>
</indexterm>
<code language="jam">rule programs-path ( )</code>
<para>
Returns the list of paths which are used by the operating system for
looking up programs.
</para>
</listitem>
<listitem id="bbv2.reference.modules.path.mkdirs">
<indexterm zone="bbv2.reference.modules.path.mkdirs">
<primary>mkdirs</primary>
</indexterm>
<code language="jam">rule makedirs ( path )</code>
<para>
Creates a directory and all parent directories that do not
already exist.
</para>
</listitem>
</orderedlist>
</section>
|
