Commit | Line | Data |
---|---|---|
a218eb12 MW |
1 | .\" -*-nroff-*- |
2 | .ie t \{\ | |
3 | . ds o \(bu | |
4 | . if \n(.g .fam P | |
5 | .\} | |
6 | .el \{\ | |
7 | . ds o o | |
8 | .\} | |
9 | .de hP | |
10 | .IP | |
11 | \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c | |
12 | .. | |
13 | .de VS | |
14 | .sp 1 | |
15 | .RS | |
16 | .nf | |
17 | .ft B | |
18 | .. | |
19 | .de VE | |
20 | .ft R | |
21 | .fi | |
22 | .RE | |
23 | .sp 1 | |
24 | .. | |
25 | .TH extract-profile 1 "3 May 2015" "distorted.org.uk key management" | |
26 | .SH NAME | |
27 | extract-profile \- determine configuration using inheritance and substitution | |
28 | .SH SYNOPSIS | |
29 | .B extract-profile | |
30 | .I section | |
31 | .IR file | directory ... | |
32 | .SH DESCRIPTION | |
33 | The | |
34 | .B extract-profile | |
35 | utility reads a number of | |
36 | .BR .ini -style | |
37 | configuration files from the named | |
38 | .IR file s | |
39 | and | |
40 | .IR directori es, | |
41 | combines the sections according to inheritance rules (described below), | |
42 | performs substitutions on the values, | |
43 | and writes the resulting effective contents of the named | |
44 | .I section | |
45 | to standard output. | |
46 | .PP | |
47 | A | |
48 | .I directory | |
49 | named on the command line | |
50 | causes files within to be examined: | |
51 | specifically, each file whose name consists only of | |
52 | upper- and lowercase letters, | |
53 | digits, | |
54 | underscores | |
55 | .RB (` _ '), | |
56 | and | |
57 | hyphens | |
58 | .RB (` \- ') | |
59 | will be processed; | |
60 | other files are ignored, | |
61 | as are objects in the | |
62 | .I directory | |
63 | which aren't files | |
64 | (so, in particular, directories are not processed recursively). | |
65 | The files within a directory are processed | |
66 | in ascending lexicographic order. | |
67 | It may be useful to prefix filenames with numbers | |
68 | in order to ensure that they're read in the correct order. | |
69 | .SS Command-line options | |
70 | The following options are recognized. | |
71 | .TP | |
72 | .B \-h, \-\-help | |
73 | Print an overview | |
74 | of the options and commands | |
75 | to standard output | |
76 | and exit successfully. | |
77 | .TP | |
78 | .B \-\-version | |
79 | Print the version number | |
80 | of the | |
81 | .B distorted-keys | |
82 | package | |
83 | to standard output | |
84 | and exit successfully. | |
85 | .SS Configuration data model | |
86 | A | |
87 | .I property | |
88 | has a | |
89 | .I name | |
90 | and a | |
91 | .IR value . | |
92 | A property's name must consist only of | |
93 | upper- and lowercase letters, | |
94 | digits, | |
95 | underscores | |
96 | .RB (` _ '), | |
97 | and | |
98 | percent signs | |
99 | .RB (` % '). | |
100 | A property is | |
101 | .I internal | |
102 | if its name contains | |
103 | a percent sign; | |
104 | otherwise it is | |
105 | .IR external . | |
106 | .PP | |
107 | A | |
108 | .I direct section | |
109 | has a name, | |
110 | an | |
111 | .I inclusion list | |
112 | of other sections, | |
113 | and a collection of | |
114 | .I direct properties | |
115 | with distinct names. | |
116 | .PP | |
117 | There is a special section | |
118 | named | |
119 | .B @GLOBAL | |
120 | which is implicitly included by every other section. | |
121 | .SS Configuration syntax | |
122 | Configuration files are line-oriented. | |
123 | Leading and trailing whitespace is always ignored. | |
124 | There is no line-continuation syntax. | |
125 | There are four kinds of lines. | |
126 | .hP \*o | |
127 | .IR "Blank lines" , | |
128 | consisting only of whitespace, | |
129 | are ignored. | |
130 | .hP \*o | |
131 | .IR Comments , | |
132 | beginning with | |
133 | hash | |
134 | .RB (` # ') | |
135 | or | |
136 | semicolon | |
137 | .RB (` ; '), | |
138 | are also ignored. | |
139 | .hP \*o | |
140 | .IR "Section headings" , | |
141 | consisting of a name | |
142 | surrounded by square brackets | |
143 | .RB (` [ ... ] '), | |
144 | cause the following assignments, | |
145 | as far as the next section heading | |
146 | or the end of the file, | |
147 | to define or override properties in the named section. | |
148 | .hP \*o | |
149 | .IR Assignments , | |
150 | of the form | |
151 | .I name | |
152 | .B = | |
153 | .I value | |
154 | or | |
155 | .I name | |
156 | .B : | |
157 | .IR value , | |
158 | define (or override) direct properties | |
159 | or pseudoproperties | |
160 | in the current section. | |
161 | Spaces around the | |
162 | .RB ` = ' | |
163 | or | |
164 | .RB ` : ' | |
165 | are optional and, if present, ignored. | |
166 | Hyphens | |
167 | .RB (` - ') | |
168 | in the | |
169 | .I name | |
170 | are converted to | |
171 | underscores | |
172 | .RB (` _ '). | |
173 | Assignments preceding the first section header in a file | |
174 | apply to the special section | |
175 | .BR @GLOBAL . | |
176 | .PP | |
177 | The same property | |
178 | or pseudoproperty | |
179 | may be defined multiple times in a section: | |
180 | only the last definition is significant; | |
181 | earlier definitions are silently ignored. | |
182 | .PP | |
183 | Pseudoproperties have names beginning with an at sign | |
184 | .RB (` @ '). | |
185 | The following pseudoproperties are recognized. | |
186 | .TP | |
187 | .B @include | |
188 | The value is a list of section names separated by whitespace. | |
189 | The current section's inclusion list is set to | |
190 | the corresponding named sections. | |
191 | .PP | |
192 | Sections may be defined in any order. | |
193 | The same section may be defined more than once: | |
194 | the effect is the same as a single section containing | |
195 | all of the assignments of the individual sections | |
196 | in the same order. | |
197 | .SS Inheritance | |
198 | The | |
199 | .I inferiors | |
200 | of a section | |
201 | .I S | |
202 | are the sections in | |
203 | .IR S 's | |
204 | inclusion list, | |
205 | together with their inferiors. | |
206 | It is an error if a section is its own inferior. | |
207 | (Consequently, it is an error if | |
208 | .B @GLOBAL | |
209 | has a non-empty inclusion list.) | |
210 | If | |
211 | .I T | |
212 | is an inferior of | |
213 | .I S | |
214 | then | |
215 | .I S | |
216 | is a | |
217 | .I superior | |
218 | of | |
219 | .IR T . | |
220 | .PP | |
221 | A section | |
222 | .I S | |
223 | has an | |
224 | .I effective property | |
225 | named | |
226 | .I P | |
227 | if either | |
228 | .I S | |
229 | has a direct property named | |
230 | .IR P , | |
231 | or any inferior of | |
232 | .I S | |
233 | has a direct property named | |
234 | .IR P . | |
235 | .PP | |
236 | If | |
237 | .I S | |
238 | has an effective property named | |
239 | .I P | |
240 | then | |
241 | .IR P 's | |
242 | .I defining set | |
243 | consists of those sections out of | |
244 | .I S | |
245 | and its inferiors | |
246 | which have a direct property named | |
247 | .IR P . | |
248 | The | |
249 | .I reduced defining set | |
250 | for | |
251 | .I P | |
252 | consists of those sections in the | |
253 | .I defining set | |
254 | of | |
255 | .I P | |
256 | which have no superiors in the defining set. | |
257 | .PP | |
258 | If all of the sections in the reduced defining set for | |
259 | .I P | |
260 | assign the same value to | |
261 | .I P | |
262 | then that is the | |
263 | .I effective value | |
264 | for | |
265 | .I P | |
266 | in | |
267 | .IR S ; | |
268 | otherwise the configuration is erroneous. | |
269 | .PP | |
270 | Note that, | |
271 | according to these rules, | |
272 | if | |
273 | .I S | |
274 | has a direct property | |
275 | .I P | |
276 | then | |
277 | .I S | |
278 | has an effective property | |
279 | .I P | |
280 | with the same value. | |
281 | .SS Output | |
282 | The | |
283 | .B extract-profile | |
284 | program's output consists of assignments | |
285 | .IB name = value | |
286 | for the effective properties of the named | |
287 | .IR section , | |
288 | one per line, | |
289 | in an arbitrary order. | |
290 | .SH AUTHOR | |
291 | Mark Wooding, <mdw@distorted.org.uk> | |
292 | .SH SEE ALSO | |
293 | .BR distorted-keys (7). |